Example format

[RexJaeschke]

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

From ISO: Please update all the EXAMPLEs per ISO/IEC Directives, Part 2, 2018, Clause 25. 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 EXAMPLEs within this document, it is possible that other documents would like to refer to a specific EXAMPLE 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, “[Example: … end example]”, is one mechanism to indicate text that is informative. The four Parts of 29500 currently contain more than 5, 800 such occurrences, none of which are numbered, so cannot possibly be referenced from any document, and nor are they intended to be.

This construct is used in two distinct situations: as a sentence (possibly inside an existing paragraph) that might otherwise have simply begin “For example, …”; and as a single- or multiline XML (or other) code fragment.

To be investigated further.

Requiring all these occurrences to be numbered ISO-format examples would be a huge (and correspondingly expensive) task with no appreciable value resulting.

---

ISO-071 |   | General: EXAMPLEs |   | ed | ISO/IEC Directives, Part 2, 2018, 25.3 Within a given clause or subclause, examples shall be numbered sequentially. The numbering restarts at each new subdivision. A single example in a subdivision does not need to be numbered. ISO/IEC Directives, Part 2, 2018, 25.5 Examples 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”). Examples should be written as a statement of fact.

Please either number and style all EXAMPLEs in accordance with the Directives or change them to normal body text. Please also note that some EXAMPLEs contain requirements/recommendations/permissions (see comments in the DIS_edit file for the EXAMPLEs in question), which are not allowed; these EXAMPLEs need to be changed to normal body text. Per earlier communication, it is noted that the plan is to review and update the EXAMPLEs after the DIS ballot. This comment is added as a reminder.

[RexJaeschke]

Proposal

We make all stand-alone examples ISO-format EXAMPLES with number except if it's the only one in that subclause. Clearly this has to be done programmatically, but only one time.

For in-line examples, which are really like asides, as in

"... in the physical format. [Example: Some physical formats store parts as individual files in a file system, in which case, it is advantageous to map many part names directly to identical physical file names. end example]"

we set them like Notes.

[murata2makoto]

Just like note numbering, there are three ways to do this programmatically. Typefi settings, STS programming, and OOXML programming. I prefer the first one.

[RexJaeschke]

2020-07-08 Teleconference

Murata pointed out that the converted STS document does not have XML elements dedicated to examples (or notes). He argued that the note element of STS should be used and that example numbers should automatically be generated during the translation to PDF. Francis said that such an enhancement will take a lot of time. Rex added to his proposal “For in-line examples, which are really like asides, … we set them like Notes.” that we’d also add “For example,” to the beginning. We’ll need to check with ISO that just because we use the word “example” does not actually make that sentence an example in terms of requiring special formatting. Rex agreed that some sort of one-time programmatic solution is needed for the stand-alone examples.

[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 examples, we'll confirm with ISO that saying "for example, ..." doesn't make something an Example.

[RexJaeschke]

For all standalone Examples, I changed the prefix to "EXAMPLE 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 Examples as they are pending a reply from ISO w.r.t whether we can use the words "for example" in a sentence without requiring it be made an EXAMPLE NOTE.

As there are only 44 Examples 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 Examples added during maintenance can be numbered "x" with the tool fixing up" the numbers when it is run.)

[Q-Swan]

There are places where the draft FDIS (and previous versions) has end example] but no matching [Example: preceding it

See 7.5.4.4 and 7.5.4.5. Searching for both strings indicates that there are only two instances. They are not in-line examples.

[RexJaeschke]

Thanks, Caroline. All fixed.

[RexJaeschke]

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

YC: This is not a requirement; but it is good practice to put examples illustrating certain concepts into EXAMPLEs consistently.

Question for ISO: In the following text, how can the reader tell if the second paragraph is part of the example or not? EXAMPLE 2 If an abstract package contains a part named "/a", the name of another part in that abstract package must not be "/a" or "/A".

For each part name N and string S, let the result of concatenating N, the forward slash, and S be denoted by N[S]. A part name N1 is said to be derivable from another part name N2 if, for some string S, N1 is equivalent to N2[S].

YC: Text within an EXAMPLE 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 example, how can one write an example containing multiple paragraphs, possibly including figures/tables?

YC: Please just make sure the font size for all the paragraphs within the EXAMPLE is set to 10. For Figures/Tables, they cannot be "included" within an EXAMPLE; but they can be referenced. For example, within the text of an EXAMPLE, 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.

Question for ISO: The following is intended to be one large example: a code block followed by text followed by another code block. How can this be made clear?

EXAMPLE 7 Consider a Relationships part

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <rlsps:Relationships … </rlsps:Relationships>

Given Id="rId6" and Type="http://../relationships/image", Step 2 constructs

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Relationships …

YC: Please just make sure the font size of text in-between code blocks is set to 10.

Further question for ISO: Just be clear, if an example contains one or more paragraphs of text, they must be set in 9-point Cambria. However, if the example also contains one or more code blocks, do they have to be set in 9-point Courier New, rather than 10-point? If not, it seems odd to have two different point sizes in an example.

Notes for SC 34/WG4:

We’ll have to reduce the size of all text inside an EXAMPLE, and we’ll have to move all captioned elements (such as tables/figures) outside of EXAMPLEs. However, we can keep current in-line “for example” sentences as inline text, but without the EXAMPLE format.

I set all stand-along EXAMPLE text in 10-point Cambria, but left code blocks as is, pending a response from ISO.

[RexJaeschke]

As agreed on the 2020-10-07 WQG4 telcon, I removed the Example delimiters from all embedded Examples, and added an intro "For example,". I also numbered the Example where two or more occurred in a subclause.