Notes format

[RexJaeschke]

From WG4 N0441, “Plan to Make IS 29500 Parts Comply with the ISO Style Guidelines.”

From ISO: Please update all the NOTEs per ISO/IEC Directives, Part 2, 2018, Clause 24. They shall be numbered within each subclause and shall not be put in square brackets. Please understand that even though there’s no need to reference NOTEs within this document, it is possible that other documents would like to refer to a specific NOTE in this document. Numbering them is necessary.

During the teleconference of 2019-09-03 it was clearly stated by ISO staff several times that there is no need to annotate informative text. The absence of words indicating a requirement makes text informative.

The current annotation, “[Note: … end note]”, is one mechanism currently used to indicate text that is informative. The four Parts of 29500 currently contain more than 3,900 such occurrences, none of which are numbered, so cannot possibly be referenced from any document now, and nor are they intended to be. As such, one proposed solution is to remove all occurrences of “[Note: “ (note trailing space) and “ end note]” (note leading space). The same would be done with the alternate informative indicators, “[Rationale: … end rationale]” and “[Guidance: … end guidance]”.

Requiring all these occurrences to be numbered ISO-format notes instead would be a huge (and correspondingly expensive) task with no appreciable value resulting. It would also increase the size of the 6,500-pages of spec, as most notes are sentences in existing paragraphs, and would have to made separate paragraphs. For example, a paragraph containing two separate notes might have to be broken up into five paragraphs: initial normative text, first note, more normative text, second note, and final normative text.

---

*ISO-072 |   | General: NOTEs |   | ed | ISO/IEC Directives, Part 2, 2018, 24.3 Within a given clause or subclause, notes shall be numbered sequentially. The numbering restarts at each new subdivision. A single note in a subdivision does not need to be numbered. ISO/IEC Directives, Part 2, 2018, 29.5.1 A single note in a table shall be preceded by “NOTE”, placed at the beginning of the first line of the text of the note. When several notes occur in the same table, they shall be designated “NOTE 1”, “NOTE 2”, “NOTE 3”, etc. The numbering restarts for each new table. ISO/IEC Directives, Part 2, 2018, 24.5 Notes shall not contain requirements (use of “shall”) or any information considered indispensable for the use of the document, for example instructions (imperative mood), recommendations (use of “should”) or permission (use of “may”). Notes should be written as a statement of fact.

Please either number and style all NOTEs in accordance with the Directives or change them to normal body text. Per earlier communication, it is noted that the plan is to review and update the NOTEs after the DIS ballot. This comment is added as a reminder. |  

[RexJaeschke]

Proposal

Option A

Replace all "[Note: " with "(" and all " end note]” with ")". This is easy and it doesn't interfere with the current paragraph structure (Labeled notes inside paragraphs simply became unlabeled notes.) As notes have no normative text, they have no impact on spec's meaning.

I propose this rather than replacing the delimiters with nothing, as a parenthesized paragraph identifies it as an aside; that is, an FYI/BTW.

We should check with ISO that this approach is acceptable.

Option B

We go the ISO route and make each note a stand-alone paragraph with note number except if it's the only one in that subclause. Clearly this has to be done programmatically, but only one time.

See the Directives Part 2 for specific formatting requirements.

[murata2makoto]

Option C

Update the Typefi settings for automatically introducing note numbers when Typefi generates PDF documents. In my opinion, this is the best approach. But I'm not sure if ISO can do this.

Option D

Write a program for automatically embedding note numbers in STS documents.

This program is very easy to write. The program has to be executed whenever an STS document is created from a DOCX file.

Option E

Write a program for automatically embedding note numbers in DOCX documents.

This program is a bit difficult but is certainly possible. The program has to be executed only once by WG4.

[murata2makoto]

BTW, JATS has note elements. Does the ISO toolchain support them?

[RexJaeschke]

2020-07-08 Teleconference

Rex pushed for his Proposal Option A, as this is easy to implement without needing any tooling. There was a short discussion.

[RexJaeschke]

Now that we're resubmitting out original spec, the programmatic addition of the Example tag and number will have to be done against that Word document.

Murata-san will write the tool to do the numbering.

Regarding inline notes, we'll confirm with ISO that saying "Note, ..." doesn't make something a Note.

[franciscave]

For this specification I favour Option B , for the following reasoning.

So far as I can see, there are no instances where a subclause contains more than one Note, so we won't need to number them. We can simply replace "[Note ... end note]" with "NOTE ...". That way we retain the distinctive nature of the Notes and comply with the Directives without a huge amount of effort. Option A would probably not be acceptable to the ISO editors. Other options may need to be considered in future for Parts 1 and 4, of course.

Where a Note is currently embedded in a paragraph (nine instances), I think we should either break up the paragraphs, so that the Note is in a paragraph on its own, or remove the Note tags, whichever seems most appropriate. Not the end of the world in any of these cases.

All Notes in Part 2 are at most a single paragraph, so I don't foresee any problems with this approach.

[murata2makoto]

@franciscave Agreed.

[RexJaeschke]

For standalone Notes, we'll use Option B. For inline Notes, we'll remove the delimiters and possibly put the text inside parentheses. We'll ask ISO about using the word "Note" at the start of an inline Note.

As there are only 26 Notes, total, it might be easier to make the changes by hand.

[RexJaeschke]

For all standalone Notes, I changed the prefix to "NOTE x" and on a final pass, I will replace the number if they are required; otherwise, I'll remove the " x". I left the in-line Notes as they are pending a reply from ISO w.r.t whether we can use the word "note" in a sentence without requiring it be made a NOTE.

As there are only 26 Notes in total, I'm doing the change manually. We can develop a tool to automate this when we have to revise Parts 1 and 4. (And any new Notes added during maintenance can be numbered "x" with the tool fixing up" the numbers when it is run.)

[RexJaeschke]

From ISO:

Question for ISO: Just because a sentence contains the text “Note, …” does that require that sentence to be set as an ISO-format NOTE?

YC: This is not a requirement; but it is good practice to put additional information intended to assist the understanding or use of the text into NOTEs consistently.

Question for ISO: In the following text, how can the reader tell if the second paragraph is part of the note?

NOTE 2 Path segments are not explicitly represented as folders in the abstract package model, and no directory of folders exists in the abstract package model.

A package implementer is not required to support non-ASCII part names, although doing so is recommended.

YC: Text within a NOTE would be 1-size smaller (Cambria 10) than normal body text (Cambria 11).

Question for ISO: If the second paragraph is not part of the note, how can one write a note containing multiple paragraphs, possibly including figures/tables?

YC: Please just make sure the font size for all the paragraphs within the NOTE is set to 10. For Figures/Tables, they cannot be "included" within a NOTE; but they can be referenced. For example, within the text of a NOTE, citations like “see Table/Figure X” can be added (each Table/Figure shall be clearly cited in the text anyhow). It is ultimately the cross-references that create the linkage, not the positioning of the content.

Notes for SC 34/WG4: We’ll have to reduce the size of all text inside a NOTE to 10 points, and we’ll have to move all captioned elements (such as tables/figures) outside of NOTEs. However, we can keep current in-line “note that” sentences as inline text, but without the NOTE format.

I changed all NOTEs to 10-point Cambria.

No NOTEs contain tables or Figures, so no work was needed to separate these.

As no subclauses have multiple NOTEs, none of the NOTEs have numbers.

[RexJaeschke]

As agreed on the 2020-10-07 WQG4 telcon, I removed the Note delimiters from all embedded Notes, and added an intro "Note that".