Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove clause/section numbering #1023

Closed
zvr opened this issue Aug 6, 2024 · 1 comment · Fixed by #1044
Closed

Remove clause/section numbering #1023

zvr opened this issue Aug 6, 2024 · 1 comment · Fixed by #1044
Assignees
Milestone

Comments

@zvr
Copy link
Member

zvr commented Aug 6, 2024

There should be no numbering on chapter and section headers.

It is automatically added while creating the PDF.

@zvr zvr added this to the 3.0.1 milestone Aug 6, 2024
@bact
Copy link
Collaborator

bact commented Aug 8, 2024

If we still like to make a reference to a specific section (for example, https://spdx.github.io/spdx-spec/v3.0.1-draft/annexes/diffs-from-previous-editions/#A.5 ) an HTML anchor (<a name="..."></a>) or an ID (id="..." property inside the h heading tag) is need to be either added manually or generated automatically to each section.

Generating our own numbering automatically (numbers will not be in source file):

  • Pros: Can be consistency easily, less work, less error; Removing and adding new heading is easy
  • Cons: Not transparent. A human editor who like to make a reference to a section in a chapter needs to generate that chapter first to get an HTML anchor name. Depends on when in the workflow the anchor/id is generated, the anchor validation during the MkDocs build may not work.

Adding anchor manually (numbers will be source file):

  • Pro: Transparent. A human editor can just look at the source file and get immediately the HTML anchor name
  • Cons: Tedious and prone to error; Removing and adding new headings mean re-numbering work

Figure 1
(Figure 1 - source code of https://spdx.github.io/spdx-spec/v3.0.1-draft/annexes/diffs-from-previous-editions/ )

--

Linking directly to sections, using the generated heading ID from MkDocs:

  • MkDocs cannot do the numbering for us, but relying on Markdown convention, it does currently generate ID (id="...") for each heading for us.
  • The link like https://spdx.github.io/spdx-spec/v3.0.1-draft/annexes/diffs-from-previous-editions/#a5-differences-from-v22-and-v21 is a mechanic that made the navigation bar work.
  • This ID is supported by GitHub and other Markdown authoring tools. Some authoring tools can offer a list of heading IDs to choose from when the author type # in the link syntax:
    Screenshot 2024-08-08 at 18 58 32
  • MkDocs generates the ID from the heading name. As few document has multiple headings with the same name (like "Purpose", "Guideline"), the MkDocs generation may not work for these documents if there's no numbering. But there can be a workaround by renaming those headings to be unique.
  • If numbering is to be inserted later and not presented in the source file, the authoring tool will not know the ID a5-differences-from-v22-and-v21, as the ID that can be derived from the source from the authoring tool perspective is differences-from-v22-and-v21 (without a5).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants