Various Word Generator issues found when proofing a recent Word version of the spec

[RexJaeschke]

Here are some observations:

1. Page numbering for the front matter needs to be Roman with Clause 1. Scope starting Arabic numbering with 1. This can be fixed manually, if necessary.
2. 6.5.1 JSON-LD context file contains the JSON code "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld" set in red color. Is there a reason to color this? In general, ISO is not a fan of colored text in specs. In any event, their tool might remove the color. Could/should this line simply be set like other kinds of code?
3. Clauses 8–18 each have a subclause X.1 "Profile information" followed immediately by X.1.1.1 "Summary". There is no intervening X.1.1! (I’m guessing this is a Word-generation issue rather than a problem in md.)
4. The style and layout of the Annexes can be set manually. (That will require any links to the existing numbered annexes to be changed to lettered annexes.)
5. 9.2.6.6 (among others) shows a table that spans pages. If possible, select the table property “Repeat as header row at the top of each page.”
6. 23.7.1 has a numbered list inside a number list, both using Arabic digits. According to the ISO Style Guide, “The default order for a numbered list is a), b), c) for the first level; 1), 2), 3) for the second level; i), ii), iii) for the third level; and a), b), c) for the fourth level.” At the very least, we should make one of the levels something other than Arabic. Perhaps the nested level could be alpha or Roman. This can be fixed manually, if necessary.

[goneall]

From the tech call on 14 Oct 2025:

Here are some observations:

1. Page numbering for the front matter needs to be Roman with Clause 1. Scope starting Arabic numbering with 1. This can be fixed manually, if necessary.

This will be done manually

3. 6.5.1 JSON-LD context file contains the JSON code "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld" set in red color. Is there a reason to color this? In general, ISO is not a fan of colored text in specs. In any event, their tool might remove the color. Could/should this line simply be set like other kinds of code?
4. Clauses 8–18 each have a subclause X.1 "Profile information" followed immediately by X.1.1.1 "Summary". There is no intervening X.1.1! (I’m guessing this is a Word-generation issue rather than a problem in md.)

Planned for improvements in the spec parser

6. The style and layout of the Annexes can be set manually. (That will require any links to the existing numbered annexes to be changed to lettered annexes.)

Will be done manually

8. 9.2.6.6 (among others) shows a table that spans pages. If possible, select the table property “Repeat as header row at the top of each page.”

Will be done manually

10. 23.7.1 has a numbered list inside a number list, both using Arabic digits. According to the ISO Style Guide, “The default order for a numbered list is a), b), c) for the first level; 1), 2), 3) for the second level; i), ii), iii) for the third level; and a), b), c) for the fourth level.” At the very least, we should make one of the levels something other than Arabic. Perhaps the nested level could be alpha or Roman. This can be fixed manually, if necessary.

This needs to be updated in the model - need to create a PR in the model repo

[zvr]

translating the sections mentioned:

• "6.5.1 JSON-LD context file..." is in the serializations.md chapter in the spec
• "Clauses 8–18 each" these are the namespace pages
• "23.7.1 has a numbered list inside a number list" is in the pkg-url-specification.md annex in the spec