Expansion in scope of notes

[opoudjis]

Until now, notes have been restricted to being runs of paragraphs, and they can appear attached underneath any other block.

Recent feedback obtained by ISO is that notes and examples should be treated the same, as containing any number of different blocks, including:

• formulas
• paragraphs
• tables (without borders)
• numbered/unnumbered bullet lists and sub-lists
• indented text
• graphics

As it happens, the Asciidoctor format will permit this kind of embedding in its multi-block notes, so notes looking like that will be converted successfully into XML. However there is no provision in the Metanorma grammar for this, and there is no provision in rendering.

Taking account of such notes will generate a lot of work, which must not be underestimated, and it cannot proceed until the following questions are resolved.

• Are heterogeneous notes a characteristic of basicdoc, standoc, or specifically ISO?
• Are embedded notes within tables, terms, admonitions, figures, lists also heterogeneous, or constrained to be paragraphs? (In this instance, Asciidoctor constrains what is possible; but there are good reasons why such structures are undesirable.)
• How are these heterogeneous notes to be rendered visually, so as to make them identifiable as a unit? Note that while HTML rendering in Metanorma visually codes them with a background colour, Word rendering currently uses only font size, and has foregone indentation.
• How are the embedded blocks to be rendered differently? It has been suggested for example that tables are to be rendered without borders.
• How are the embedded blocks to be referenced? One alternative is not to reference them differently from their container, as a note. If they are to be referenced differently, the referencing code may end up complex (Section 823, Note 4, Table 2?)

[opoudjis]

@ronaldtse ?

[ronaldtse]

• Are heterogeneous notes a characteristic of basicdoc, standoc, or specifically ISO?

Let's say basicdoc.

• Are embedded notes within tables, terms, admonitions, figures, lists also heterogeneous, or constrained to be paragraphs? (In this instance, Asciidoctor constrains what is possible; but there are good reasons why such structures are undesirable.)

I wonder what sort of constraints are actually helpful. For example, a table inside a note inside a table seems to be the wrong thing to allow. Maybe we want a restricted set to be available within these specific types of notes.

• How are these heterogeneous notes to be rendered visually, so as to make them identifiable as a unit? Note that while HTML rendering in Metanorma visually codes them with a background colour, Word rendering currently uses only font size, and has foregone indentation.

I think we either do indentation or restrict them within a table to enforce indentation. ISO and IEC Directives, for example, use a "bordered container" to differentiate them against content text.

• How are the embedded blocks to be rendered differently? It has been suggested for example that tables are to be rendered without borders.

This I think depends on the usage of the author. Un-bordered "lists" could usually be implemented as definitions lists instead of needing a table.

• How are the embedded blocks to be referenced? One alternative is not to reference them differently from their container, as a note. If they are to be referenced differently, the referencing code may end up complex (Section 823, Note 4, Table 2?)

I suppose we need a convention on how to name things within a Note. Let me ask the ISO Editor and revert on this.

[ronaldtse]

BTW, NOTEs/EXAMPLEs are not meant to contain everything. The ISO Editor previously stated (which is documented on metanorma.com) that NOTEs/EXAMPLEs can contain:

• formulas
• paragraphs
• tables (without borders)
• numbered/unnumbered bullet lists and sub-lists
• indented text
• graphics

The only restriction is that they shall be purely informative statements of facts, therefore no requirements, recommendations or permissions are allowed (see DP2, 2018, 24.5 and 25.5). They are supposed to provide supplementary information; the documents shall be usable without NOTEs/EXAMPLEs.

[ronaldtse]

@opoudjis from ISO:

Tables and Figures shall be numbered sequentially throughout the document (the numbering restarts within each annex, e.g. Figure/Table A.1, A.2 …) and given concise titles.
There is no such concept of a Figure/Table within a NOTE/EXAMPLE; the numbering of Figures and Tables are independent of their positions in the text. If they are put in-between NOTE/EXAMPLE text, the rules are the same. (But in most cases, Tables/Figures don’t need to be put within a NOTE/EXAMPLE, they can be referenced in the NOTE/EXAMPLE text)

Firstly, again we don’t regard any Tables/Figures to be sub-elements of a NOTE/EXAMPLE; they are numbered independently throughout the document.

=> Tables/Figures should not be sub-elements of NOTE/EXAMPLE.

Each table/figure should be stand-alone and cross-references should be used instead to link them with each other.

=> They are numbered as independent elements within the document. If you want a table/figure in NOTE/EXAMPLE it should be through a reference.

Secondly, please don’t put a table within another table. It is also not encouraged to put a figure within a table. Using complicated structures like this will create immense difficulty when the document goes through XML processing within ISO/CS; the output can be error-prone and the readability undermined.

The following excerpt is from DP2, 29.3:
“A table within a table is not permitted. Subdivision of a table into subsidiary sections with new column headings is not permitted. It is often better to create several tables rather than trying to consolidate too much information into one table. The simpler the presentation, the better.”

=> Tables cannot contain other tables. Figures should not belong to tables.

Each Figure/Table shall be clearly cited in the text so that its context/purpose is clear to the users. When you make a reference to a NOTE/Table/Figure, you just refer to the NOTE/Table/Figure itself; within the NOTE text, you can add citations like “see more details in Table/Figure X.”

=> Table and Figures must ALWAYS be numbered as first level elements: e.g. Table X, Figure X.

[ronaldtse]

From ISO on table borders inside NOTE/EXAMPLEs:

There is no hard rules on the borders. Please style them as you see fit; but again please understand that a table is not a sub-element of a NOTE/EXAMPLE. It can be put in-between NOTE/EXAMPLE text, but it is ultimately the cross-references that create the linkage, not the positioning of the content

[ronaldtse]

@opoudjis this is now actionable.

[opoudjis]

Tables and figures will be permitted within notes and examples in basicdoc. They will be excluded in standoc.

Notes will include: formulas, lists, blockquotes.

[opoudjis]

We allow source code within notes, but we cannot allow it to be captioned, just as we do not when source code is within tables. Adding note to labelled_ancestor(), the list of blocks that do not allow their descendants to have their own caption.

[opoudjis]

Have tested in ISO: the blocks within a note are coloured in HTML as a single block

In Word, lists and blockquotes are in smaller font, formulas and sourcecode are not. None of them are indented.

[opoudjis]

We will indent non-paragraphs contained within notes in Word.

We will try to enforce smaller font in formulas and sourcecode within notes.