speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
https://speced.github.io/bikeshed
Creative Commons Zero v1.0 Universal
1.11k stars 200 forks source link

Lettered/numbered annex or appendix sections #2929

Open leo-barnes opened 1 month ago

leo-barnes commented 1 month ago

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 commented 1 month ago

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

tidoust commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

@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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

@tabatkins

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

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

Ms2ger commented 1 month ago

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".