metanorma-iso 2.1.1 → 2.1.2

data/docs/guidance.adoc

@@ -1,487 +0,0 @@
-= Guidance for Authoring
-
-TIP: This guide has been authored for ISO standards, but most of it applies to all Metanorma standards. We indicate where guidance differs for different standards classes.
-
-The Asciidoctor approach to authoring ISO standards (and other related standards under Metanorma) is not https://en.wikipedia.org/wiki/WYSIWYG[WYSIWYG]: you are dealing with a text editor and a console rather than a Word document, and you are authoring something that looks more like HTML than the final product. On the other hand, editing documents with a markup system like Asciidoctor makes it much easier to automate key validation and formatting processes, such as checking for missing document components, autonumbering, and generating output in multiple formats.
-
-The documents you will be authoring will be in the http://asciidoctor.org[Asciidoc] formatting language, so you need to be familiar with that language's markup conventions.
-
-* http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] will be your companion.
-* https://www.metanorma.com/software/metanorma-iso/docs/asciiiso-syntax/[AsciiISO syntax] provides a quick reference for both standard Asciidoctor markup and custom ISO-related features.
-* See also https://github.com/metanorma/metanorma-iso#asciidoctor-model-additions[Additions to markup made for ISO standards] in README Metanorma-ISO.
-
-We have tried to make things easier for you by preparing an https://github.com/metanorma/metanorma-iso/blob/master/spec/examples/rice.adoc[AsciiDoc version] of the ISO Standard exemplar, the https://www.iso.org/publication/PUB100407.html["Rice document"].
-If you use this document as a template for your own ISO standard document, you will find most of the formatting you need illustrated there.
-
-== Output in different languages
-
-Metanorma allows generation of standards in different languages; the language of the document is specified in the `:language:` document attribute (and `:script:`, for languages with more than one script).
-
-For each language, language-specific templated text is specified for the boilerplate, labels and cross-references that are included in document output. Metanorma has predefined templates for English, Chinese (Simplified) and French. You can specify your own language by providing your own http://www.yaml.org/spec/1.2/spec.html[YAML] template file, and linking to it with the `:i18nyaml` document attribute. The YAML template you provide needs to match https://github.com/metanorma/isodoc/blob/master/lib/isodoc/i18n-en.yaml, substituting translations for each of the fields given.
-
-The Chinese (Simplified) template also localises punctuation and spacing, mapping them away from the default Latin punctuation used elsewhere in the gem.
-
-== Validation
-
-All Metanorma XML documents that are generated by the Metanorma tool are validated against a formal schema for the document structure, as well as style rules around content. The gem will generate a sequence of warnings; you should pay attention to them. 
-
-The content warnings come first, and are prefixed with `ISO Style`. They try to impose rules on content taken from http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf[ISO/IEC DIR 2], including restrictions on where requirements may be stated, usage of decimal points, hanging clauses, and subclauses that are the only child of their parent clause. While the error detection is not infallible, they should be reviewed at least once. Where possible, the gem will give the ID or section heading associated with the error. For example:
-
-[source,console]
---
-ISO style: WARNING (Section: ): Footnote may contain requirement: The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.
-ISO style: WARNING (Section: Wire sieve,): possible decimal point: 0.02
-ISO style: invalid technical committee type XYZ
-ISO style: AnnexA-4-1:Preparation of test sample: subsection is only child
---
-
-TIP: Style rules around content are currently only applied to ISO standards. Within ISO, style rules are currently specific to content in English.
-
-The syntax errors come afterwards, and they report the line number and line position of the syntax error in the Metanorma XML document generated by the gem. (For example, the Asciidoctor document `rice.adoc` generates the Metanorma XML file `rice.xml`.) These errors deal with restrictions on what kinds of text can appear where, pointers within the document that are orphaned, and elements that appear in the wrong sequence. Deciphering what has gone wrong with them may take more effort, but the errors they point to are more serious than the style errors, and need to be resolved for the document to be well-formed. The gem will usually (but not always!) generate HTML and Word output despite the presence of those errors.
-
-For example:
-
-[source,console]
---
-value of attribute "date" is invalid; must be an ISO date @ 454:183
-element "review" missing required attribute "from" @ 454:183
-element "subsection" not allowed here; expected the element end-tag or element "admonition", "dl", "example", "figure", "formula", "note", "ol", "p", "quote", "review", "sourcecode", "table" or "ul" @ 467:52
-value of attribute "date" is invalid; must be an ISO date @ 476:233
-IDREF "Annex-A-2" without matching ID @ 315:50
-IDREF "last_conformance_class" without matching ID @ 649:236
-IDREF "Annex-A" without matching ID @ 308:141
---
-
-The tool also validates terms cited from the Internatinal Electrotechnical Vocabulary (IEV) against the online http://www.electropedia.org[IEV Electropedia] entries: if the preferred term does not match the form given in the IEV for that entry, it will issue a warning.
-
-== Document header
-
-The core metadata about the standard comes from the Asciidoctor document header (the list of colon-delimited attributes at the start of the document). The https://github.com/metanorma/metanorma-standoc#document-attributes[metanorma-standoc README] and the README of each standard-specific gem documents what those fields should be. Use the Rice document as a template, and be careful about sticking to the guidelines on populating them.
-
-You will need to use the `:stem:` document attribute in if you have any AsciiMath or MathML to include in the document; otherwise they will not be detected.
-
-The document header, unlike the document proper, cannot deal with HTML entities. If you need to enter non-Ascii characters for a title, or dashes for compound titles, you will need to enter them directly as Unicode (even if your console text editor doesn't like it): e.g. `:title-main-fr: Spécification et méthodes d'essai`, not `:title-main-fr: Sp\écification et m\éthodes d'essai`; `:title-part-en:Information Technology—Security`, not `:title-part-en:Information Technology\—Security`.
-
-== Document sections
-
-Sections are marked off in Asciidoc with titles prefixed by double equal signs, `==`. The gem depends on the titles given to identify the different kinds of sections in the document. As a result, you cannot choose to modify the titles of sections; the `Abstract`, `Introduction`, `Scope`, `Normative References`, `Terms and Definitions`, `Symbols and Abbreviations`, and `Bibliography` need to be titled as such. As an alternative (if the document deviates from that naming structure, or is in a language other than English), the section can be prefixed with a `heading=` attribute, giving the English canonical form of the section name.
-
-[source,asciidoc]
---
-== Normative References
-
-[heading=terms and definitions]
-== Terms, definitions and abbreviations
---
-
-The Foreword of a standard is detected as any text between the document header and the first section header (the "document preamble" in Asciidoctor). The Rice document gives the `.Foreword` title to the preamble, but the gem will supply the "Foreword" title regardless of what title is present.
-
-
-=== Bibliographies
-
-The Normative References and the Bibliography must be preceded by the style attribute `[bibliography]`, so that the references they contain may be recognised as such. 
-
-All bibliographic entries must be given as unordered lists. 
-
-Currently the gem only supports formatted citations, which are given as such in the Asciidoc source. In the future, we expect to integrate the documents with rendering of Relaton-model bibliographies.
-
-==== References to standards
-
-For references to standards with a document identifier, the entry must be preceded by a bibliographic anchor, in triple brackets: this consists of an arbitrary internal identifier (used in citations), followed by the canonical document identifier for the reference as its label. All references under Normative References are expected to have such an identifier. For example:
-
-[source,asciidoc]
---
-* [[[ricepotentialmilling,ISO 6646]]], _Rice -- Determination of the potential milling yield from paddy and from husked rice_
-* [[[ISOGuide73, ISO Guide 73:2009]]], _Risk management -- Vocabulary_
---
-
-[subs="quotes"]
-ISO 6646 in this example would be cited from elsewhere in the document through crossreferences to the `ricepotentialmilling` identifier; e.g. `<< ricepotentialmilling>>` (which will be rendered as `ISO 6646`), `<<``ricepotentialmilling, section 5``>>` (which will be rendered as `ISO 6646, Section 5`), `<<``ricepotentialmilling,section 5: the foregoing discussion``>>` (which will be tagged in the XML representation as Section 5 of ISO 6646, but will be displayed as `the foregoing discussion`.)
-
-[TIP]
-====
-If an ISO reference is in preparation, ISO/IEC DIR 2 dictates that details of the reference status be given as a footnote. In Asciidoc, this is done by giving the date as a double dash, and following the bibliographic anchor with a footnote macro:
-
-[source,asciidoc]
---
-* [[[ISO16634,ISO 16634:--]]] footnote:[Under preparation. (Stage at the time of publication ISO/DIS 16634)], _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_
---
-
-If an ISO reference includes all parts of the standard, that is indicated by appending `(all parts)` after the reference anchor:
-
-[source,asciidoc]
---
-* [[[ISO16634,ISO 16634 (all parts)]]] _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_
---
-====
-
-In informative references, references to standards documents are still given with the same format of bibliographic anchor, and they are cited by their document identifier -- although they are displayed with an incrementing reference number in brackets, for consistency with any bibliographic entries that are not standards documents. (This convention is taken from ISO.) So
-
-[source,asciidoc]
---
-[bibliography]
-== Bibliography 
-
-* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
-...
-* [[[ref11,11]]] Nitrogen-ammonia-protein modified Kjeldahl method -- Titanium oxide and copper sulfate catalyst. _Official Methods and Recommended Practices of the AOCS_ (ed. Firestone, D.E.), AOCS Official Method Ba Ai 4-91, 1997, AOCS Press, Champaign, IL
---
-
-is displayed as:
-
-[quote]
-____
-*Bibliography*
-
-[1] ISO 3696, _Water for analytical laboratory use -- Specification and test methods_
-...
-[11] Nitrogen-ammonia-protein modified Kjeldahl method -- Titanium oxide and copper sulfate catalyst. _Official Methods and Recommended Practices of the AOCS_ (ed. Firestone, D.E.), AOCS Official Method Ba Ai 4-91, 1997, AOCS Press, Champaign, IL
-____
-
-The bracketed reference numbers are expected to be correct and in order: they are not overriden in rendering.
-
-==== Relaton Reference Fetching
-
-The https://github.com/metanorma/relaton[`relaton`] can fetch bibliographic entries for any standards known to have online bibliographic databases (ISO, IEC, IETF, GB). Any bibliographic entry recognised through its document identifier prefix will by default have its bibliographic entry fetched by that gem. The fetched data overrides any content about the item provided in the document, since the online bibliography is treated as the source of truth for that standards document.
-
-==== Cross-References
-
-Normally in Asciidoctor, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference. So a cross-reference `<<ISO7301,the foregoing reference>>` will be rendered as "the foregoing reference", and hyperlinked to the ISO7301 reference.
-
-In Metanorma Asciidoctor cross-references, bibliographic localities (e.g. page numbers, clause numbers) can be added directly after the comma, as part of the cross-reference text: this overrides the normal Asciidoctor treatment of custom text. Bibliographic localities are expressed as a sequence of lowercase locality type, then an equal sign, then the locality value or range of values. The locality can appear in quotations, if it contains special characters (like dashes or commas).
-
-[source,asciidoc]
---
-<<ISO7301,clause=3.1-3.4>>
-
-NOTE: This table is based on <<ISO7301,table=1>>.
-
-Sampling shall be carried out in accordance with <<xxx,section="5-3-1,bis">>
---
-
-Any text after the bibliographic localities is still treated as custom cross-reference text; e.g. `<<ISO7301,clause=5,table=1,the foregoing reference>>`. 
-
-TIP: Custom cross-references should not be used in ISO standards, either for an external reference, or for a section of the current document: ISO/IEC DIR 2 requires any cross-references to be transparent in text. For example, a cross-reference to the anchor `[[tabular]]` on clause 5 should be given as just `<<tabular>>`, without any custom text: it will be automatically rendered as `Clause 5` by the gem.
-
-TIP: ISO clause references in particular will suppress the word "Clause" before a subclause reference, following ISO/IEC DIR 2: `<``<ISO24333,clause=5>``>` will be rendered as _ISO 24333, Clause 5_, but `<``<ISO7301,clause=3.1>``>` will be rendered as _ISO 7301, 3.1_.
-
-
-=== Terms and Definitions
-
-// TODO: This paragraph will be removed when https://github.com/metanorma/metanorma-iso/issues/222 is implemented
-
-The title of a top-level Terms and Definitions clause is populated automatically, overriding the title provided by the user: if it contains a Symbols and Abbreviated Terms subclause, it is titled _Terms, definitions, symbols and abbreviated terms_, otherwise it is titled _Terms and definitions_. A Terms and Definitions clause will be recognised if either title is given, regardless of case. Symbols and Abbreviated Terms subclauses are also automatically titled; other subclauses of Terms and Definitions clauses are not.
-
-If the Terms and Definitions are partly or fully sourced from another standard, that document is named as a `[source=REFERENCE]` attribute to the section. (The attribute needs to be applied to the top-level clause, if there are subclauses.) If there are no terms and definitions defined in this standards document, no terms should be included in the section body (it should be blank). The boilerplate at the start of the section is adjusted to reflect both possibilities; any paragraphs or lists in the Asciidoctor input (which can replicate the expected boilerplate) is stripped in the intermediate XML format.
-
-Terms and Definitions sections follow a strict grammar, which is reflected in their Asciidoctor markup:
-
-* The term is given as a subheading at the appropriate level (three equal signs, unless there are subsections in the Terms and Definition section). The term may be crossreferenced from other terms, in which case it should have an anchor.
-* The term is optionally followed by alternative/admitted terms, which must be marked up in an `+alt:[...]+` macro; deprecated terms, which must be marked up in a `+deprecated:[...]+` macro; and a term domain, which must be marked up in a `+domain:[...]+` macro.
-* The definition of the term is given in a separate paragraph.
-* The definition is optionally followed by examples (paragraphs with an `[example]` style attribute).
-* The definition is then optionally followed by notes (denoted with a `NOTE:` prefix).
-* The definition is then followed by a citation for the term, marked with a `[.source]` role attribute). 
-* The citation is a cross-reference to a normative reference, optionally followed by a comma and a modification if applicable.
-
-For example,
-
-[source,asciidoc]
---
-[[paddy]]
-=== paddy 
-alt:[paddy rice]
-alt:[rough rice]
-deprecated:[cargo rice]
-domain:[rice]
-
-rice retaining its husk after threshing
-
-[example]
-Foreign seeds, husks, bran, sand, dust.
-
-NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking. 
-
-[.source]
-<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated,
-and Note 1 to entry is not included here
---
-
-The requirement that the source of a term be given in a citation also applies when the source is a term bank, such as the http://www.electropedia.org[International Electrotechnical Vocabulary (IEV)]. Formally, IEV references should be cited as `IEC 60050-nnn:20xx`, where `n` is the top-level clause, and `20xx` is the year when that particular specification was published; e.g. `IEC 60050-113:2011, 113-01-07`. For convenience, this gem requires all IEV references to be to a single reference, named `IEV` in the normative references. In rendering the Asciidoctor into Metanorma XML, this reference will be replaced by the various required IEC 60050-nnn:20xx references. (That means that you should not insert your own instances of IEC 60050 references for IEV citations: they will be duplicated by the automatically generated references.)
-
-[source,asciidoc]
---
-[.source]
-<<ievtermbank,clause="103-01-02">>
-
-...
-
-[bibliography]
-* [[[ievtermbank,IEV]]], _IEV: Electropedia_
-// will be excluded from HTML and Word output. Will be replaced by a canonical reference in XML output.
---
-
-Note that, for IEV entries to be validated, the IEV reference must be given as a Clause, and in quotes (otherwise the locality syntax would be interpreted as a range); so `<<ievtermbank,clause="103-01-02">>` for IEV 103-01-02.
-
-Asciidoctor does not permit macros to be nested inside other macros; so the following markup, introducing a stem expression as an admitted term, is illegal. (The use of stem expressions as preferred terms is not a problem, because the macro appears as a header.)
-
-[source,asciidoc]
---
-=== stem:[t_90] 
-alt:[stem:[t_A]]
-
-Time to launch.
---
-
-However, the gem will treat any standalone paragraph in a term section, consisting of just a stem macro, as an admitted term:
-
-[source,asciidoc]
---
-=== stem:[t_90] 
-
-stem:[t_A]
-
-Time to launch.
---
-
-As defined above, all terminal subclauses of a term section are treated as term definitions. Exceptionally, an introductory section can be treated as a subclause instead of a term, by prefixing it with the style attribute `[.nonterm]`:
-
-[source,asciidoc]
---
-== Terms and definitions
-
-[.nonterm]
-=== Introduction
-The following terms have non-normative effect, and should be ignored by the ametrical.
-
-=== Anapaest
-
-metrical foot consisting of a short, a long, and a short
---
-
-=== Symbols and Abbreviations
-
-Symbols and Abbreviations sections are expected to be simple definition lists (http://asciidoctor.org/docs/user-manual/#labeled-list["labelled lists"] in Asciidoctor nomenclature). The gem takes care of sorting the symbol entries in the order prescribed by ISO/IEC DIR 2, provided the symbols are in AsciiMath; sorting MathML entries is not currently supported.
-
-=== Clauses
-
-Blank subclause headings can be given as `=== {blank}`. These are used when you want to give a subclause number for a new subclause, but without an associated header text. So e.g. in the Rice Model document,
-
-[source,asciidoc]
---
-=== Physical and chemical characteristics 
-
-==== {blank}
-
-The mass fraction of moisture, determined in accordance with...
---
-
-renders as 
-
-____
-*4.2. Physical and chemical characteristics*
-
-*4.2.1.*  The mass fraction of moisture, determined in accordance with...
-____
-
-TIP: This notation should not be used to implement paragraph numbering, as required for UNECE: the UNECE gem automatically treats each paragraph as a distinct clause, and automatically numbers it.
-
-Inline subclause headings (e.g. for test methods) are indicated by preceding the heading with the `[%inline-header]` option attribute. So in the Rice Model document,
-
-[source,asciidoc]
---
-[%inline-header]
-==== Sieve, 
-
-with round perforations of diameter 1,4 mm.
---
-
-renders as 
-
-____
-*A.2.1.1. Sieve,* with round perforations of diameter 1,4 mm.
-____
-
-
-Informative clauses are indicated with the attribute `[obligation=informative]`; clauses are normative by default.
-
-=== Annexes
-
-All annexes must be preceded by the style attribute `[appendix]`, in order to be recognised correctly. Like all clauses, annexes are normative by default, an informative annex is indicated with `[appendix,obligation=informative]`.
-
-[TIP]
-====
-In ISO, Appendixes to annexes can occur, although they are not mentioned in ISO/IEC DIR 2; ISO/IEC DIR 1 features them. They are marked up as immediate subsections of annexes, and must be tagged with an option attribute of "appendix":
-
-[source,asciidoc]
---
-[appendix]
-== Annex A
-Text
-
-[%appendix]
-=== Appendix 1
-Text
---
-====
-
-The numbering of annexes and appendices is automatic: do not insert "Annex A" or "Appendix 1" as part of the title. Annex and Appendix titles can be left blank, as with Clauses.
-
-== Text markup
-
-=== Mathematical formatting
-
-Mathematical formatting is done using the `[stem]` macro. Asciidoctor supports http://asciimath.org[AsciiMath] and LaTeX natively (AsciiMath by default); as of this writing Metanorma only supports AsciiMath. AsciiMath is converted to Microsoft Word's OOXML via MathML, using the https://github.com/asciidoctor/asciimath[AsciiMath] Ruby gem; the syntax of the Ruby gem may be at odds with the usual MathJax processor of AsciiMath. (We have found that the Ruby gem insists on numerators being bracketed.)
-
-=== Formulae
-
-Formulae are marked up as `[stem]` blocks. Any explanation of symbols in the formula is given as a "where" paragraph, followed by a definition list. For example:
-
-[source,asciidoc]
---
-[[formulaA-1]]
-[stem]
-++++
-w = (m_D) / (m_s)
-++++
-
-where
-
-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. 
---
-
-=== Figures
-
-Like formulae, figures can be followed by a definition list for the variables used in the figure; the definition list is preceded by `+*Key*+`. For example:
-
-[source,asciidoc]
---
-[[figureC-1]]
-.Typical gelatinization curve
-image::rice_images/rice_image2.png[]
-footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]
-
-*Key*
-
-stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent
-stem:[t]:: cooking time, expressed in minutes
-stem:[t_90]:: time required to gelatinize 90 % of the kernels
-P:: point of the curve corresponding to a cooking time of stem:[t_90]
-
-NOTE: These results are based on a study carried out on three different types of kernel.
---
-
-Subfigures (which appear in ISO) are entered by including images in an Asciidoc example:
-
-[source,asciidoc]
---
-[[figureC-2]]
-.Stages of gelatinization
-====
-.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels)
-image::rice_images/rice_image3_1.png[]
-
-.Intermediate stages: Some fully gelatinized kernels are visible
-image::rice_images/rice_image3_2.png[]
-
-.Final stages: All kernels are fully gelatinized
-image::rice_images/rice_image3_3.png[]
-
-====
---
-
-=== Tables
-
-While Asciidoctor tables are quite powerful for a non-XML markup language, they still have not dealt with the full range of complexity required in Metanorma. Metanorma adds the option of multiple header rows (attribute `headerrows=n`), to deal with the complexity of ISO tables requiring labels, variables, and units to lining up in the header.
-
-Asciidoc allows table cells to have footnotes (which the gem renders inside the table), and notes following the table (which the gem moves inside the table footer.) Table 1 in the Rice document illustrates a large range of table formatting options.
-
-=== Lists
-
-Ordered lists in both HTML and Word have their labels pre-configured, to align with ISO/IEC DIR 2: _a), b), c)_ for the first level, then _1), 2), 3)_ for the second level, then _i), ii), iii)_, then _A), B), C)_, then _I), II), III)_. The `type` attribute for ordered lists in Asciidoctor, which allows the user to specify the label of an ordered list, is ignored.
-
-TIP: The stylesheets for ISO render unordered lists with em-dashes instead of bullets, as preferred by ISO. Ordered lists in Word are rendered with their labels bracketed. (_a)_, _1)_, etc.) 
-
-TIP: Asciidoctor and HTML support multiple paragraphs within a single list item (through https://asciidoctor.org/docs/user-manual/#list-continuation[list continuation]); in HTML output, all the paragraphs within a list item will be aligned. The software attempts to do so with Word output as well, by using custom list continuation styles (`ListContLevel1` etc.); but you should check the output, and may need to manually intervene.
-
-In Word, each list entry must be a single paragraph; if the Asciidoctor contains more than one paragraph for a list item, the subsequent paragraphs will not be preceded by a bullet in Word, but they will also not be indented under the first paragraph of the list item.
-
-=== Footnotes
-
-Asciidoctor supports only single-paragraph footnotes through its footnote macro (which can only contain a single line of text); this reflects a stylistic bias against digressive text by the Asciidoc creator, and will not change. It can be worked around by introducing line breaks into the macro (see https://github.com/asciidoctor/asciidoctor.org/issues/599, http://discuss.asciidoctor.org/footnotes-with-paragraph-breaks-td4130.html).
-
-=== Notes
-
-Notes that are not at the end of a clause are folded into the preceding block, if that block is not delimited (so that the user could not choose to include or exclude a note): that is, notes are folded into a preceding paragraph, list, formula, or figure.
-
-=== Reviewer Notes
-
-We have introduced a mechanism in the gem to annotate arbitrary blocks of text, using Asciidoctor sidebars and anchors for the beginning and end of the annotation; see https://github.com/metanorma/metanorma-standoc#reviewer-notes[discussion in the metanorma-standoc README].
-
-== Cross-references
-
-The guidance given in ISO/IEC DIR 2 for internal cross-references guarantees unambiguous referencing, and it is followed rigorously by Metanorma. In particular, if a formula, example, figure, list, list item or table is cross-referenced outside its (sub)clause, the clause containing the item is always given in the cross-reference, unless the item is being referenced in the same clause. In the case of notes, the containing clause is extended to containing example, figure or table.
-
-So for example, in the Rice model document, formula B.1 is defined in Annex B.6, and is referenced in B.6 and B.7. In the Rice model document published by ISO, both instances are cited as "Formula (B.1)"; but the gem follows ISO/IEC DIR 2 in citing the former as "Formula (B.1)", but the latter as "B.6, Formula (B.1)". (Metanorma in general is "more royalist than the king" in applying formatting rules and validation—which is what you would want of a computer-based tool.) 
-
-The label of the item cross-referenced, the use of brackets, and the containing reference are all taken care of by the gem; the document author needs only give the item identifier in the Asciidocto source (e.g. `<<``formulaB-1``>>` generates either "Formula (B.1)" or "B.6, Formula (B.1)", depending on where in the document it occurs.)
-
-List items can be cross-referenced by inserting a bookmark at the very start of the list item:
-
-[source,asciidoc]
---
-. Ordered list
-.. [[id]] This is the first list item
-... [[id]] This is a list sub-item
---
-
-== Asciidoctor Tips
-
-As noted, the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] should be your companion when authoring any Asciidoc documents, including Asciidoc documents under Metanorma. There are some more specialised aspects of Asciidoctor markup, which you might need to dig deeper to find in the manual; we list some of them here.
-
-* A note or admonition can be made to span multiple paragraphs (including lists and tables), by making it a https://asciidoctor.org/docs/user-manual/#delimited-blocks[delimited block]:
-
-[source,asciidoc]
---
-[NOTE]
-====
-This is a multi-paragraph note.
-
-It includes:
-
-* A list
-
-|===
-| And 
-
-| a table
-|===
-====
---
-
-* https://asciidoctor.org/docs/user-manual/#using-attributes-set-assign-and-reference[Attribute references] can be used as template variables in a document: if your document contains the text `{foo}`, you can assign the value to be populated in `{foo}` by setting it as a document attribute in the Asciidoctor header: `:foo: this is the text to replace "foo"`. In the Rice Model document example, document attributes are used to provide the Subcommittee and Technical Committee names, which are populated as template entries in the document foreword.
-
-* List items can contain other blocks in Asciidoctor, through concatenating blocks; e.g.
-+
-[source.asciidoc]
---
-* List
-+
-|===
-| Contains | A table
-
-|===
---
-+
-However, downstream renderers may not be able to cope with embedding blocks within list items. In particular, Word will force a carriage return between a list item, and a list or table contained in the item. So output like the following, with the list number flush with the embedded block, is not possible in Word (though it is in HTML):
-
-....
-a)  1. Text
-b)  |-------|------ |
-    | table | table |
-    |---------------|
-c)  Definition Term   Definition
-    Definition Term   Definition
-....

data/docs/navigation.adoc

@@ -1,23 +0,0 @@
----
-items:
-- title: Introduction
-  items:
-    - { title: Quickstart, path: quickstart/ }
-- title: Using Metanorma-ISO
-  items:
-    - { title: Authoring guidance, path: guidance/ }
-    - { title: Output formats, path: outputs/ }
-    - { title: HTML output, path: htmloutput/ }
-    - { title: Customisation, path: customisation/ }
-    - { title: AsciiISO syntax, path: asciiiso-syntax/ }
-- title: "Adopting Metanorma: FAQ"
-  items:
-    - { title: How to adopt StanDoc in your own specs, path: adopting-spec/ }
-    - { title: How to use StanDoc toolchain for your specs, path: adopting-toolchain/ }
-    - { title: How to style HTML output, path: styling-output-html/ }
-    - { title: How to style MS Word output, path: styling-output-msword/ }
-    - { title: How to localize the output, path: localizing-output/ }
-    - { title: How to bypass AsciiDoc, path: replacing-asciidoc/ }
----
-
-= Navigation