Lists
General
Metanorma AsciiDoc supports three types of lists:
- Unordered lists
- Ordered lists
- Definition lists
Unordered lists
Unordered lists are bulleted lists, entered using the asterisk (*) symbol. Unordered lists can be nested by prefixing additional asterisks.
The main changes compared to the previous edition are:
* updated normative references;
* deletions:
** deletion of 4.3. [nested list item]
** deletion of 4.4. [nested list item]Ordered lists
Ordered lists are invoked by beginning the line with a dot .. The list items are numbered automatically. The default list uses arabic numbers, but can vary depending on the defined style of the Metanorma flavor.
. First Step
. Second Step
. Third StepDefinition lists
Definition lists pair a term and a description together in a list, separated by two or more colon symbols (:).
Definition lists are often used to define abbreviations, units or symbols.
Definition lists follow the syntax of:
`term:: Definition`stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
stem:[m_D]:: is the mass, in grams, of grains with that defect;
stem:[m_S]:: is the mass, in grams, of the test sample.\stem:[] is used for mathematical formatting, and results in italics. So w is an italic w, w; \m_D is an italic m with a D subscript: mD.Referencing a list item
You can reference a single list item using the internal reference mechanism.
Simply assign an anchor before the list item:
. Ordered list
.. [[id1]] This is the first list item
... [[id2]] This is a list sub-itemList items with more than one paragraph
Metanorma AsciiDoc supports multiple paragraphs within a single list item through list continuation.
.Microsoft Word caveats
- For list items containing multiple paragraphs, Metanorma attempts to format them appropriately by using custom list continuation styles (
ListContLevel1etc.) applied to groups of paragraphs; however, you should check the output document and may need to manually intervene. - In Microsoft Word, each list entry must be a single paragraph. Metanorma is employing a workaround through list continuation styles, and results may be unexpected if the list is edited.
List styling
Unordered list styling
The default styling for unordered lists are bullets. Metanorma does not support other styles for unordered lists.
Ordered list styling
General
The default styling for ordered lists follow the specifications of ISO/IEC DIR 2 and is the same for each output type:
- level 1: a), b), c) (
alphabetic), - level 2: 1), 2), 3) (
arabic), - level 3: i), ii), iii) (
roman), - level 4: A), B), C) (
alphabetic_upper), - level 5: I), II), III) (
roman_upper).
Step lists
In some situations an integer-numbered list is needed for specification of process steps.
In certain flavours (NIST, ITU, OGC), class=steps is used to override the default numbering, and use Arabic numbering as the base instead:
- level 1: 1), 2), 3)
- level 2: a), b), c)
- level 3: i), ii), iii)
- level 4: A), B), C)
- level 5: I), II), III)
Specification of start label
The start attribute can be specified for ordered lists to specify the start label of the ordered list.
This is a historical note that applies to isodoc up to v3.1.12.
The start attribute for ordered lists was only allowed by certain Metanorma flavors, such as BIPM and ISO. This is because of the difficulty of realising the list numbering starting other than at 1 in autonumbered lists in Word HTML. This issue has been addressed isodoc ≥ v3.2.0, and the constraint no longer applies.
Specification of list type
The type attribute can be used to specify the list numbering using values from above. Manually-styled lists are not supported by all flavors.
The accepted values are:
alphabetic- a), b), c)
arabic- 1), 2), 3)
roman- i), ii), iii)
alphabetic_upper- A), B), C)
roman_upper- I), II), III)
[type="alphabetic_upper"]
. First as "A"
. Second as "B"
[type="roman_upper"]
. First as "I"
. Second as "II"This is a historical note that applies to isodoc v1.3.0 to v2.0.2.
The type attribute, with acceptable values listed in the list above, could be used to allow specifying labels of an ordered list isodoc ≥ v1.3.0.
In Word rendering the type attribute is always ignored in favor of ISO/IEC DIR 2 compliant labelling.
As of v2.0.3, the ability to specify the type attribute has been retracted isodoc ≥ v2.0.3, because of the bugs it introduces with list cross-referencing and rendering.
Lists as tables
It is possible to specify that nested lists be rendered as tables metanorma-standoc ≥ v3.3.3.
Under this rendering:
- each level of the nested list is given a separate column
- each branching entry of the list is given its own row
- nested titles of sublists are treated as column headings
To specify table rendering of a list, use the attribute display=table.
[display=table]
.List turned into table
. List 1
+
--
.Second header
.. Sublist 1
*** A
*** B
*** C
.. Sublist 2
--
. List 2
. List 3
.. Sublist 3
... D
... Erenders as
| List turned into table | Second header | |
| 1. List 1 | a. Sublist 1 a | * A * B * C |
| b. Sublist 2 | 2. List 2 | 3. List 3 |
| a. Sublist 3 a | . i. D . ii. E |
To fix the relative widths of the table columns, add the attribute display-directives="colgroup='...'", where ... is a comma-delimited list of column widths, just as are used in the native AsciiDoc attribute cols.
[display=table,display-directives="colgroup='1,2,1'"]Definition list styling
Definition lists are rendered by default horizontally, with the definition in the same line as the term.
In Word output, definition lists are rendered as true tables. Word defines the width of the term column using the auto-width algorithm, and might cause words to break.
To ensure that terms are rendered in a single line in Word, you need to use non-breaking spaces and non-breaking hyphens in HTML escape notation.
- Non-breaking spaces:
\ or\  - Non-breaking hyphens
\‑
Instead of entering:
This is a non-breaking term.Enter:
This\ is\ a\ non\‑breaking\ term.