Lettered/numbered annex or appendix sections

[leo-barnes]

Many MPEG tend to have informative annexes containing examples or similar. The main spec consists of regular numbered sections, which is then followed by a number of lettered annexes. So you might have something like:

1 Introduction
2 Clause about X
2.1 Sub-clause about detail Y of X
2.2 Sub-clause about detail Z of X
Annex A: (Informative) Examples using X
A.1 Introduction
A.2 Example 1
A.2.1 Example 1 details
A.3 Example 2
Annex B: (Normative) Profiles/brands that add restrictions on X
...

It would be great if Bikeshed could add support for something similar. We have noticed that starting a header with "Appendix" removes the numbering, but I would like to keep numbering of annex sub-sections, just have them start with a specific letter.

[leo-barnes]

@tidoust
Or is there already some functionality like this that we could make use of?

[tidoust]

There may be but I'm not aware of any ;)

@tabatkins, FYI, that's another place where ReSpec does things slightly differently. ReSpec would, in this case, produce what's being requested. For example, see the appendices in the Table of Contents or ReSpec's documentation.

[tabatkins]

Okay, so just checking - if a top-level section starts with X: or Word X:, I should number the subsections with X.1, etc.

If the heading started with X:, treat that the same way as a numbered marker, pulled out to the column with the others. Do I do something similar with Appendix D, or just leave it "unnumbered"?

[leo-barnes]

Okay, so just checking - if a top-level section starts with X: or Word X:, I should number the subsections with X.1, etc.

Yep, pretty much.

If the heading started with X:, treat that the same way as a numbered marker, pulled out to the column with the others. Do I do something similar with Appendix D, or just leave it "unnumbered"?

Ideally I would prefer not having to specify the exact letter and have it automatically increment, but that's probably pushing it a bit too far :)

Here's an example from the HEIF spec:

11	Region and region annotation
11.1	Overview
11.2	Common definitions for image sequence or video tracks and for image items
11.2.1	Region geometry structure
...
Annex A (normative)  Storage of externally specified metadata
A.1	General
A.2	Exif
A.2.1	Untimed Exif metadata
A.2.2	Exif metadata in tracks
A.3	XMP metadata
A.4	MPEG-7 metadata
A.5	IPTC-IIM metadata
Annex B (normative)  HEVC Image File Format
B.1	General
B.2	HEVC images and image collections
B.2.1	General
B.2.2	Image data
...
B.3	HEVC image sequences
B.3.1	General
B.3.2	Derivation from ISO/IEC 14496-12 and ISO/IEC 14496-15
...
Annex J (informative)  Examples of image collections
J.1	General
J.2	Single image

[leo-barnes]

@tidoust

@tabatkins, FYI, that's another place where ReSpec does things slightly differently. ReSpec would, in this case, produce what's being requested. For example, see the appendices in the Table of Contents or ReSpec's documentation.

Yeah, that looks pretty much like what I would want to have.

[tabatkins]

Ideally I would prefer not having to specify the exact letter and have it automatically increment, but that's probably pushing it a bit too far :)

I could do this, but it would require recognizing a specific set of keywords (and possibly making that configurable in a metadata). Then /Word\b/ as a prefix could be auto-lettered.

Okay, this all sounds reasonable.

[tabatkins]

Oooh, another question. If I auto-letter, and you have multiple different types of appendixes, should they share one set of letters or each use their own?

That is, say you have "Appendix ...", "Appendix ...", "Annex ...", "Footnote ...". Should those be lettered A, B, C, D, or A, B, A, A?

(I'm thinking A, B, C, D)

[leo-barnes]

@tabatkins

(I'm thinking A, B, C, D)

Agreed, that makes the most sense to me as well.

[Ms2ger]

Btw, wasm does this manually; see e.g. https://www.w3.org/TR/2024/WD-wasm-core-2-20240911/ . Note the missing number for "Change History".