metanorma-iso 1.0.8 → 1.0.9

data/docs/guidance.adoc

@@ -1,23 +1,29 @@
 = Guidance for Authoring
-The Asciidoc 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 Asciidoc 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: the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] will be your companion (supplemented by the https://github.com/riboseinc/metanorma-iso#asciidoctor-model-additions[additions to markup made for ISO standards]. However we have tried to make things easier for you by preparing an https://github.com/riboseinc/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.
+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.
 
-== Usage
+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.
 
-See the README on https://github.com/riboseinc/metanorma-iso#usage[how to deploy and use the gem].
+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/riboseinc/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/riboseinc/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
 
-The gem 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).
+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. The gem 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/riboseinc/isodoc/blob/master/lib/isodoc/i18n-en.yaml, substituting translations for each of the fields given.
+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/riboseinc/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 AsciiISO documents that are processed by the Asciidoctor-ISO gem 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. 
+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:
 
@@ -29,7 +35,9 @@ ISO style: invalid technical committee type XYZ
 ISO style: AnnexA-4-1:Preparation of test sample: subsection is only child
 --
 
-The syntax errors come afterwards, and they report the line number and line position of the syntax error in the intermediate XML format generated by the gem. (For example, the AsciiDoc document `rice.adoc` generates the intermediate 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.
+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:
 
@@ -44,25 +52,29 @@ IDREF "last_conformance_class" without matching ID @ 649:236
 IDREF "Annex-A" without matching ID @ 308:141
 --
 
-Currently validation only processes English-language text for language-specific rules (e.g. requirements); French validation is planned.
-
-The gem also validates terms cited from the IEV against the online IEV Electropedia entries: if the preferred term does not match the form given in the IEV for that entry, it will issue a warning.
+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 Asciidoc document header (the list of colon-delimited attributes at the start of the document), and the https://github.com/riboseinc/metanorma-iso#document-attributes[README documents what those fields should be]. Use the Rice document as a template, and be careful about sticking to the guidelines on populating them.
+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/riboseinc/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.
 
-The Rice document contains some additional fields that are not essential to ISO rendering, and help Asciidoctor preview the document with its native renderer, should you so choose. (For example, `:appendix-caption: Annex` ensures that the native Asciidoctor renderer calls appendices Annexes; but the Word and HTML output of the gem will do so regardless of how this value is populated.) You will need to leave the `:stem:` field in if you have any AsciiMath or MathML to include in the document; otherwise they will not be detected.
+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 accented characters for the French 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): `: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`.
+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 `Introduction`, `Scope`, `Normative References`, `Terms and Definitions`, `Symbols and Abbreviations`, and `Bibliography` need to be titled as such.
+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
 
-The Foreword of an ISO standard is detected as any text between the document header and the first section header (the document preamble). The Rice document gives the `.Foreword` title to the preamble, but the gem will supply the "Foreword" title regardless of what title is present.
+[heading=terms and definitions]
+== Terms, definitions and abbreviations
+--
 
-In the Rice document, Asciidoctor section numbering is disabled for the Foreword and Introduction, and reenabled for the Scope. Again, the gem will number those sections correctly whatever the markup.
+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
@@ -71,11 +83,11 @@ The Normative References and the Bibliography must be preceded by the style attr
 
 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 http://www.bibtex.org[BibTex] databases, through the https://github.com/riboseinc/asciidoctor-bibliography[asciidoctor-bibliography] gem.
+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.
 
-==== ISO References
+==== References to standards
 
-For ISO and related standards, the entry must be preceded by a bibliographic anchor, in triple brackets: this consists of an internal identifier (used in citations), followed by the ISO identifier for the reference as its label. For example:
+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]
 --
@@ -84,8 +96,10 @@ For ISO and related standards, the entry must be preceded by a bibliographic anc
 --
 
 [subs="quotes"]
-ISO 6646 is 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`.)
+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]
@@ -99,9 +113,9 @@ If an ISO reference includes all parts of the standard, that is indicated by app
 --
 * [[[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, ISO references are still given with the same format of bibliographic anchor, and they are cited by ISO document code -- although they are displayed with an incrementing reference number in brackets instead. So
+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]
 --
@@ -109,6 +123,8 @@ In informative references, ISO references are still given with the same format o
 == 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:
@@ -118,36 +134,21 @@ ____
 *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
 ____
 
-==== ISO Reference Fetching
-
-If any bibliographic entry has a label prefixed with `ISO`, e.g. `[[` `[ricepotentialmilling,ISO 6646]` `]]`, the gem accesses the ISO website (via the `isobib` stem), and screenscrapes the details of that item. The screenscraped data overrides any content about the item provided in the document, since the ISO website is treated as the bibliographic source of truth on ISO documents.
+The bracketed reference numbers are expected to be correct and in order: they are not overriden in rendering.
 
-==== Non-ISO References
+==== Relaton Reference Fetching
 
-In normative references, non-ISO documents must still be given a document code (or title) in their bibliographic anchor:
-
-[source,asciidoc]
---
-* [[[RFC4291,IETC RFC 4193]]] _Unique Local IPc6 Unicast Addresses_, October 2005. http://www.ietf.org/rfc/rfc4291.txt
-* [[IANAMediaTypes,IANA Media Types Assignment]]], March 2017. http://www.iana.org/assignments/media-types/media-types.xthml
---
-
-In informative references, non-ISO documents are both displayed and cited with reference numbers in brackets. Those numbers are given in the reference anchor instead of the ISO document code. ISO references appear before non-ISO references; the reference number is expected to be correct in context:
-
-[source,asciidoc]
---
-* [[[IEC61010-2,IEC 61010-2:1998]]], _Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material_
-
-* [[[ref10,10]]] [smallcap]#Standard No I.C.C 167#. _Determination of the protein content in cereal and cereal products for food and animal feeding stuffs according to the Dumas combustion method_ (see http://www.icc.or.at)
---
+The https://github.com/riboseinc/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 AsciiISO 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).
+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,asciidoctor]
 --
@@ -160,18 +161,20 @@ 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>>`. 
 
-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: 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.
 
-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_.
+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/riboseinc/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 standard, 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.
+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 Asciidoc markup:
+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.
@@ -204,7 +207,7 @@ NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kerne
 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 http://www.electropedia.org[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 Electropedia references to be to a single reference, named `IEV` in the normative references. In rendering the Asciidoctor into ISO 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 Electropedia references with id `IEC 60050-nnn`: they will be duplicated by the automatically generated references.)
+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]
 --
@@ -220,7 +223,7 @@ The requirement that the source of a term be given in a citation also applies wh
 
 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.
 
-Asciidoc 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.)
+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]
 --
@@ -258,7 +261,7 @@ 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 Asciidoc nomenclature). The gem takes care of sorting the symbols in the order prescribed by ISO/IEC DIR 2, provided the symbols are in AsciiMath; sorting MathML entries is not currently supported.
+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
 
@@ -281,6 +284,7 @@ ____
 *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,
 
@@ -299,13 +303,15 @@ ____
 ____
 
 
-Normative clauses are indicated with the attribute `[obligation=informative]`; they are normative by default.
+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. For ISO standards, annexes are treated as normative by default; if they are informative, they must additionally be tagged with an obligation of "informative" (so `[appendix, obligation= informative]`).
+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]`.
 
-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":
+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]
 --
@@ -317,6 +323,7 @@ Text
 === 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.
 
@@ -324,7 +331,7 @@ The numbering of annexes and appendices is automatic: do not insert "Annex A" or
 
 === Mathematical formatting
 
-Mathematical formatting is done using the `[stem]` macro. Asciidoc supports http://asciimath.org[AsciiMath] and LaTeX natively (AsciiMath by default); as of this writing the gem only supports AsciiMath. AsciiMath is converted to Microsoft Word's OOML 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.)
+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
 
@@ -366,7 +373,7 @@ 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 are entered by including images in an Asciidoc example:
+Subfigures (which appear in ISO) are entered by including images in an Asciidoc example:
 
 [source,asciidoc]
 --
@@ -387,17 +394,19 @@ image::rice_images/rice_image3_3.png[]
 
 === Tables
 
-Asciidoc tables are quite powerful for a non-XML markup language, but we have had to add the option of multiple header rows (attribute `headerrows=n`), to deal with the complexity of ISO tables with labels, variables, and units lining up in the header.
+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
 
-Unordered lists in Word are rendered with em-dashes instead of bullets, as preferred by ISO. Ordered lists in Word are rendered with their labels bracketed. (_a)_, _1)_, etc.) 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 Asciidoc, which allows the user to specify the label of an ordered list, is ignored.
+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.) 
 
 === Footnotes
 
-Asciidoc 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. At best, 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).
+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
 
@@ -405,15 +414,15 @@ Notes that are not at the end of a clause are folded into the preceding block, i
 
 === Reviewer Notes
 
-We have introduced a mechanism in the gem to annotate arbitrary blocks of text, using Asciidoc sidebars and anchors for the beginning and end of the annotation; see https://github.com/riboseinc/metanorma-iso#reviewer-notes[discussion in the README].
+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/riboseinc/metanorma-standoc#reviewer-notes[discussion in the metanorma-standoc README].
 
 == Cross-references
 
-The gem follows the guidance given in ISO/IEC DIR 2 rigorously. 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.
+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 PDF Rice model document, 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)".
+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 Asciidoc (e.g. `<<``formulaB-1``>>` generates either "Formula (B.1)" or "B.6, Formula (B.1)", depending on where in the document it occurs.)
+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:
 
@@ -426,7 +435,7 @@ List items can be cross-referenced by inserting a bookmark at the very start of
 
 == Asciidoctor Tips
 
-As we have 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.
+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]:
 

data/docs/localizing-output.adoc

@@ -0,0 +1,57 @@
+= How can I localize the resulting output?
+
+[TIP]
+====
+* Copy the `lib/isodoc/i18n-en.yaml` file from the isodoc gem to your gem.
+* Edit the right-hand text in the file.
+* Give the file location as the `i18nyaml` document attribute in any files you wish to use your localisation.
+====
+
+Every piece of text generated by the toolset instead of the author is looked up in an internationalisation file; that means that if the language setting for the document changes, and there is an internationalisation file for that language, all output is localised to that language. Of the existing gems, metanorma-gb is localised in this way for English and Chinese, and metanorma-iso is localised for English, French and Chinese. 
+
+The localisation files are http://yaml.org[YAML] files stores in `lib/isodoc/`, named `i18n-{languagecode}.yaml`. (In the case of Chinese, the script code is added to the filename: `i18n-zh-Hans.yaml`.) Most localised text are direct mappings from English metalanguage to the target language (including English itself); there are also instances of hashes in the YAML files. Most localisation text consists of one- or two-word labels, such as "Figure" or "Annex"; some boilerplate text is also included in the localisation text, such as the ISO text describing the use of external sources in Terms and Definitions.
+
+Localisation is mostly used for translation purposes, but they can also be used to customise the rendering of particular labels in English. For example, the default English label for a first-level supplementary section is "Annex", reflecting ISO practice; but in the metanorma-sample gem, as seen above, this label is overruled in code to be "Appendix" instead.
+
+The YAML files are read into the `IsoDoc` classes through the `i18n_init()` method of `IsoDoc::...::HtmlConvert` and `Isodoc::...::WordConvert`. The localisation equivalents for the nominated language are read from the corresponding YAML file into the `@labels` hash. The base Isodoc instance of `i18n_init()` also assigns an instance variable for each label (e.g. `@annex_lbl` for English "Annex"). These instance variables are used to generate all automated text in the Isodoc classes.
+
+All current gems inherit their localisation files from the base isodoc gem. The local `i18n_init()` instance can overwrite individual labels in code (metanorma-csd), or they can read in a local additional YAML file for the same language (metanorma-gb). If you are implementing a completely new language, you will need to replace the base `i18n_init()` method rather than inheriting from it, to ensure that the local YAML files are read in.
+
+The foregoing describes how to incorporate localisation into your gem on a permanent basis; but the toolset also allows you to nominate a YAML localisation file just for the current document. In Asciidoc, the YAML file is nominated as the i18nyaml document attribute; for IsoDoc, it is passed in as the `i18nyaml` hash attribute to the initialisation method. You will still need to access the base IsoDoc YAML instances, to make sure that all necessary labels are given in your YAML document.
+
+=== Example internationalisation code
+
+* metanorma-mpfd/lib/isodoc/mpfd/i18n-en.yaml: customisation of clause label in YAML
+
+[source]
+--
+clause: Paragraph
+--
+
+* metanorma-m3d/lib/isodoc/m3d/m3dhtmlconvert.rb: customisation of annex label as class variable
+
+[source,ruby]
+--
+      def i18n_init(lang, script)
+        super
+        @annex_lbl = "Appendix"
+      end
+--
+
+* metanorma-gb/lib/isodoc/gb/gbhtmlconvert.rb: code to read in internationalisation YAML templates (merges superclass `@labels` map, derived from the parent Isodoc::HtmlConvert class, with the labels read in from the GB-specific YAML templates.)
+
+[source,ruby]
+--
+      def i18n_init(lang, script)
+        super
+        y = if lang == "en"
+              YAML.load_file(File.join(File.dirname(__FILE__), "i18n-en.yaml"))
+            elsif lang == "zh" && script == "Hans"
+              YAML.load_file(File.join(File.dirname(__FILE__),
+                                       "i18n-zh-Hans.yaml"))
+            else
+              YAML.load_file(File.join(File.dirname(__FILE__), "i18n-zh-Hans.yaml"))
+            end
+        @labels = @labels.merge(y)
+      end
+--

data/docs/navigation.adoc

@@ -0,0 +1,23 @@
+---
+sections:
+- name: Introduction
+  items:
+    - quickstart
+- name: Using Metanorma-ISO
+  items:
+    - guidance
+    - outputs
+    - htmloutput
+    - customisation
+    - asciiiso-syntax
+- name: "Adopting Metanorma: FAQ"
+  items:
+    - adopting-spec
+    - adopting-toolchain
+    - styling-output-html
+    - styling-output-msword
+    - localizing-output
+    - replacing-asciidoc
+---
+
+= Navigation

data/docs/quickstart.adoc

@@ -1,377 +1,179 @@
-= Quickstart Guide for AsciiISO
+= Quickstart Guide
 
-This is a guide on how to get started using AsciiISO to create ISO standards documents compliant with http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf[ISO/IEC DIR 2 "Principles and rules for the structure and drafting of ISO and IEC documents"], in Microsoft Word and HTML formats.
+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. See link:https://www.metanorma.com/software/Metanorma_processor/[List of Metanorma processors].
 
-AsciiISO is the purposed-design syntax for creating ISO documents based on the AsciiDoc syntax.
-
-AsciiISO is currently used as input to the Asciidoctor-ISO renderer, which produces the corresponding https://github.com/riboseinc/isodoc-models[ISOXML schema] (in `.xml`), which in turn uses the https://github.com/riboseinc/isodoc[isodoc] gem to convert ISOXML into the final output formats, HTML (`.html`) and Word Document (`.doc`).
+This is a guide on how to get started using Metanorma to create documents aligned with different standards classes (such as ISO, GB, CSD, etc), in Microsoft Word and HTML formats. This guide is written to apply generically across the standards classes that can be expressed in Metanorma; guidance specific to a particular standards class is given as TIPs.
 
+Metanorma takes text in the _Asciidoctor markup language_ as input (consult the https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] on the basics of this markup language).
+Metanorma makes some adjustments to the text format for its requirements;
+these adjustments (which we refer to as _Metanorma Asciidoctor_, or AsciiISO) are documented in relevant sections of this documentation.
+Metanorma uses Asciidoctor to generate _Metanorma XML_, as an intermediate, semantic representation of standards content.
+Metanorma XML in turn is processed by the https://github.com/riboseinc/isodoc[isodoc] gem to generate output in Microsoft Word (`.doc`) and HTML (`.html`).
 
 == Even quicker summary
 
-In order to start a new ISO document, or migrate your document from Word:
+In order to start a new Metanorma document, or migrate your document from Word:
 
-. Install <<installation>>
+. Install <<installation>> (for your specific Metanorma standards class)
 . Clone the https://github.com/riboseinc/isodoc-rice/[AsciiISO Rice]
 
 To migrate:
 
-. Use our https://github.com/riboseinc/reverse_asciidoctor[reverse_asciidoctor] gem to help you convert a Word document into AsciiISO. That said, the conversion will not be 100% clean and you will have to manually fix some syntax (especially if your Word document contains an index, stray anchors, and equations).
+. Use our https://github.com/riboseinc/reverse_asciidoctor[reverse_asciidoctor] gem to help you convert a Word document into Asciidoctor. Be warned that the conversion will not be 100% clean, and you will have to manually fix some syntax (especially if your Word document contains an index, stray anchors, and equations).
 . Move the content back to the cloned isodoc-rice.
+. The isodoc-rice repository is set up for the ISO standards class; if you are not working with ISO, change its makefile to refer to the correct standards class (e.g. from `bundle exec metanorma -t iso -x doc,xml,html $^` to `bundle exec metanorma -t rsd -x doc,xml,html $^`
 
+[[supported-standards]]
+== Supported standards 
 
-[[installation]]
-== Installation instructions
-
-The Asciidoctor-ISO tool is a https://en.wikipedia.org/wiki/RubyGems[Ruby gem], and works on the command line. The https://en.wikipedia.org/wiki/Ruby_programming_language[Ruby programming language] can be installed on Windows (e.g. https://rubyinstaller.org), but is typically run on a Unix command line—including Linux and MacOS. The following instructions are for the Unix console.
-
-Asciidoctor-ISO in turn builds on the https://asciidoctor.org[Asciidoctor gem], which interprets the Asciidoctor markup language in Ruby. Installing the Asciidoctor-ISO gem will install the Asciidoctor gem, if it is not already installed.
-
-Ruby comes with Linux and MacOS. Asciidoctor-ISO uses Ruby 2.4.0, and you may need to update your Ruby instance to use that version. Refer to https://www.ruby-lang.org/en/documentation/installation/
 
-You can install the Asciidoctor-ISO gem, and all its dependencies, through the Ruby gem installer:
+As of this writing, Metanorma supports the following standards classes:
 
-[source,console]
---
-gem install metanorma-iso
---
+* https://github.com/riboseinc/metanorma-iso[ISO and IEC] (`iso`)
+* https://github.com/riboseinc/metanorma-gb[Chinese National standards] (`gb`)
+* https://github.com/riboseinc/metanorma-csd[Calconnect] (`csd`)
+* https://github.com/riboseinc/metanorma-csand[Cloud Security Alliance] (`csand`)
+* https://github.com/riboseinc/metanorma-m3d[Messaging, Malware and Mobile Anti-Abuse Working Group (M^3^AAWG)] (`m3d`)
+* https://github.com/riboseinc/metanorma-rsd[Ribose] (`rsd`)
+* https://github.com/riboseinc/metanorma-acme[Acme (shell for user-customised standards)] (`acme`)
+* https://github.com/riboseinc/metanorma-mpfd[Mandatory Provident Fund Schemes Authority, Hong Kong (MPFA)] (`mpfd`)
+* https://github.com/riboseinc/metanorma-unece[United Nations Economic Commission for Europe] (`unece`)
 
-If you want the latest version of the gem (which is still heavily under development), you can install it from Github:
+== Installing on Linux and macOS
 
-[source,console]
---
-git clone https://github.com/riboseinc/metanorma-iso.git
-cd metanorma-iso
-gem build *.gemspec
-gem install *.gem
---
+Install Metanorma-ISO gem and its dependencies:
 
-== How to set up a new project
+You can install the metanorma-cli gem, and all its dependencies, through the Ruby gem installer:
 
-At its simplest, all you need is a text document in Asciidoctor format, which you compile using the Asciidoctor-ISO gem. To keep document dependencies in order, you should keep your document in a distinct folder:
 
 [source,console]
 --
-mkdir new_standard
-cd new_standard
-vi new_standard.adoc
+gem install metanorma-cli
 --
 
-To compile the document, execute the `asciidoctor` script, flagging it to use the ISO variant:
+If you want the latest version (note: may not be stable due to active development),
+you can install it from Github:
 
 [source,console]
 --
-asciidoctor --trace -b iso -r 'metanorma-iso' new_standard.adoc
---
-
-NOTE: This command syntax will be changed soon.
-
-This will generate two files from the `new_standard.adoc` document (provided it is well-formed!): `new_standard.html` is a standalone HTML document, and `new_standard.doc` is a Word document (currently in the pre-2007 `.doc` format, but Microsoft Word will open it fine). Both these files are generated via an intermediate XML file, `new_standard.xml`, which represents the structure of the document following the rules of ISO/IEC DIR 2, as captured in the https://github.com/riboseinc/isodoc-models[ISOXML schema].
-
-Even if there are no errors in the Asciidoctor syntax, the document may still raise warnings to the console as it is being validated. The validation comes from ISO/IEC DIR 2, and consists of two parts: warnings about document content (e.g. requiring space before a percentage sign; requiring that the scope not contain text that looks like a recommendation); and warnings about document structure. The latter are generated by running the generated XML against the ISOXML schema, and report the line numbers of the XML document where issues are observed.
-
-=== Template
-
-To author Asciidoctor documents, you need to be familiar with the Asciidoctor syntax, as well as the Asciidoctor-ISO extensions to the syntax and conventions. The https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] documents Asciidoctor itself; the https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[Guidance for Authoring in Asciidoctor-ISO] and the https://github.com/riboseinc/metanorma-iso/blob/master/README.adoc[Asciidoctor-ISO Readme] are the complete documentation for the ISO-specific extensions. But the simplest way to get started is to take a ready-made Asciidoctor-ISO document, and edit it, observing how it approaches various formatting tasks.
-
-The https://www.iso.org/publication/PUB100407.html["Rice document"] is the ISO's model document of an international standard. An Asciidoctor-ISO version of the document is available at https://github.com/riboseinc/isodoc-rice/ . We suggest downloading the site, and editing it.
-
-The `iso-rice-en.adoc` document consists of a document header, and it references the separate `body/body-en.adoc` document for the document proper (`include::body/body-en.adoc[]`). You can just continue on with the document text after the document header—so long as you remember to leave a blank line between the two.
-
-== AsciiDoc syntax supported
-
-The Rice document illustrates almost the full range of formatting available via Asciidoctor; Annex E (which is not in the original) illustrates features not demonstrated in the original document.
-
-Syntax includes the following; the links are to the Asciidoctor User Manual. All examples are taken from the Asciidoctor-ISO Rice document.
-
-=== https://asciidoctor.org/docs/user-manual/#doc-header[Document header]
-
-Attributes of the document, which typically appear in the coverpage (if at all), rather than in the document proper. The permitted attributes for Asciidoctor-ISO, and their expected values, are documented in the https://github.com/riboseinc/metanorma-iso#document-attributes[Asciidoctor-ISO Readme]. Note that the author line expected in Asciidoctor is not used; the title line is likewise ignored, in favour of attributes describing the three-part bilingual title.
-
-[source,asciidoctor]
---
-= Rice model
-:docnumber: 17301
-:tc-docnumber: 17301
-:ref-docnumber: ISO 17301-1:2016(E)
-...
---
-
-=== Inline formatting
-
-* https://asciidoctor.org/docs/user-manual/#text-formatting[Formatting marks]: bold, italic, monospace, subscript, superscript
-
-[source,asciidoctor]
---
-This document specifies minimum requirements and test methods for rice (_Oryza sativa L._).
---
-
-* https://asciidoctor.org/docs/user-manual/#anchordef[Anchors] (for internal cross-references): these can be defined for any section or subsection, and any block (e.g. images, lists, examples, formulas, and so forth). The numbering of all blocks and clauses is automated, and does not need to be provided in the text.
-* https://asciidoctor.org/docs/user-manual/#internal-cross-references[Internal Cross-references] reference anchors within the document. By default, the text for these is also automated, to follow ISO/IEC DIR 2, including naming the container of a block where required (e.g. `B.6, Formula (B.1)` for a formula in an annex). However, cross-references can supply their own text as an override, following a comma (e.g. `<``<AnnexB,the following annex>``>`).
-
-[source,asciidoctor]
---
-The International Organization for Standardization (ISO) draws attention to the fact that it is claimed that compliance with this document may involve the use of a patent concerning sample dividers given in <<AnnexA>> and shown in <<figureA-1>>.
-
-...
-[[figureA-1]]
-.Split-it-right sample divider
-image::images/rice_image1.png[]
---
-
-* https://asciidoctor.org/docs/user-manual/#url[URLs]
-
-[source,asciidoctor]
---
-http://www.iso.org/obp[OBP]
---
-
-* https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM support] (mathematical expressions), as both inline and block formatting. (ISO Formulae are expressed as stem blocks.) Asciidoctor natively uses http://asciimath.org[AsciiMath] for its mathematical expressions; the `:stem:` document attribute must be present for AsciiMath to be recognised. The gem will ensure that any AsciiMath is rendered in the HTML output, and converted to Microsoft Office's OOXML (via MathML) in the Word output. Asciidoctor also supports LaTeX, but the gem does not cater for converting LaTeX to a Word-compatible output.
-
-[source,asciidoctor]
---
-[[formulaA-1,A.1]]
-[stem]
-++++
-w = (m_D) / (m_s)
-++++
-
-where
-
-stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
---
-
-* https://asciidoctor.org/docs/user-manual/#user-footnotes[Footnotes]. Note that footnotes are treated as inline formatting, so they cannot straightforwardly span more than a single paragraph in Asciidoctor. Footnotes within figures and tables are rendered within their blocks, as required by ISO/IEC DIR 2.
-
-[source,asciidoctor]
---
-containing a mass fraction of 4,1 % iodine and 6,3 % potassium iodide in deionized water such as Lugols.footnote:[Lugols is an example of a suitable product available commercially. This information is given for the convenience of users of this document and does not constitute an endorsement by ISO of this product.]
---
-
-=== Blocks
-
-Blocks are groupings of paragraphs and text into larger units, commonly https://asciidoctor.org/docs/user-manual/#delimited-blocks[delimited], and optionally including a https://asciidoctor.org/docs/user-manual/#title[title] and https://asciidoctor.org/docs/user-manual/#metadata-2[metadata].
-
-* https://asciidoctor.org/docs/user-manual/#unordered-lists[Unordered lists]
-
-[source,asciidoctor]
---
-The main changes compared to the previous edition are:
-
-* updated normative references;
-* deletion of 4.3.
---
-
-* https://asciidoctor.org/docs/user-manual/#ordered-lists[Ordered lists]. Note that ISO/IEC presupposes that the first level of an ordered list is indexed with a lowercase letter. The gem automatically creates labels for the nested levels of ordered lists, and ignores any https://asciidoctor.org/docs/user-manual/#numbering-styles[numbering styles] indicated by the user.
-
-[source,asciidoctor]
---
-. the sampling method used;
-. the test method used;
-. the test result(s) obtained or, if the repeatability has been checked, the final quoted result obtained;
---
-
-* https://asciidoctor.org/docs/user-manual/#labeled-list[Definition lists]. These are used for all keys of figures and formulae, and as the content of Symbols and Abbreviations clauses and subclauses:
-
-[source,asciidoctor]
---
-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.
---
-
-Note that the key to a figure must be preceded by the paragraph `*Key*`, and the key to a formula must be preceded by the paragraph `where`.
-
-* https://asciidoctor.org/docs/user-manual/#tables[Tables]. Asciidoctor supports a rich range of table formatting (which the Asciidoctor-ISO gem extends further).
-
-[source,asciidoctor]
---
-[[tableD-1]]
-[cols="<,^,^,^,^",headerrows=2]
-.Repeatability and reproducibility of husked rice yield
-|===
-.2+| Description 4+| Rice sample
-| Arborio | Drago footnote:[Parboiled rice.] | Balilla | Thaibonnet
-
-| Number of laboratories retained after eliminating outliers | 13 | 11 | 13 | 13
-| Mean value, g/100 g | 81,2 | 82,0 | 81,8 | 77,7
-|===
---
-
-* https://asciidoctor.org/docs/user-manual/#images[Images], which are mapped to ISO figures, with accompanying titles:
-
-[source,asciidoctor]
---
-[[figureC-1]]
-.Typical gelatinization curve
-image::images/rice_image2.png[]
-footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]
---
-
-* https://asciidoctor.org/docs/user-manual/#admonition[Admonitions], which express Notes, Warnings, Cautions, etc.
-
-[source,asciidoctor]
---
-CAUTION: Only use paddy or parboiled rice for the determination of husked rice yield.
+git clone https://github.com/riboseinc/metanorma-cli.git
+cd metanorma-cli
+gem build *.gemspec
+gem install *.gem
+bundle update
 --
 
-* https://asciidoctor.org/docs/user-manual/#prose-excerpts-quotes-and-verses[Block quotes]
+The final `bundle update` step updates the dependent gems, and is necessary because those gems are even more heavily under development.
 
-[source,asciidoctor]
---
-[quote, ISO, "ISO7301,clause 1"]
-_____
-This International Standard gives the minimum specifications for rice (_Oryza sativa_ L.) which is subject to international trade. It is applicable to the following types: husked rice and milled rice, parboiled or not, intended for direct human consumption. It is neither applicable to other products derived from rice, nor to waxy rice (glutinous rice).
-_____
---
+[TIP]
+====
+The Metanorma tool is a suite of https://en.wikipedia.org/wiki/RubyGems[Ruby gems], and works on the command line. The https://en.wikipedia.org/wiki/Ruby_programming_language[Ruby programming language] can be installed on Windows (e.g. https://rubyinstaller.org), but is typically run on a Unix command line—including Linux and MacOS. The following instructions are for the Unix console.
 
+The starting poing of the Metanorma tool is the `metanorma-cli` gem (command line interface); it references various other gems that the tool is based on, including the converter from Asciidoctor to Metanorma XML (`metanorma-standoc`), the converters from Metanorma XML to HTML and Word (`isodoc`, `html2doc`), the variants of Metanorma for different standards classes (`metanorma-iso`, `metanorma-csd`, etc.), and tools for processing bibliographies (`relaton`, `isobib` etc.)
 
-* https://asciidoctor.org/docs/user-manual/#example[Examples]
-* https://asciidoctor.org/docs/user-manual/#listing-blocks[Listing blocks] (source code), including https://asciidoctor.org/docs/user-manual/#callouts[source code callouts]
+The Metanorma tools processing Asciidoctor, in turn, build on the https://asciidoctor.org[Asciidoctor gem], which interprets the Asciidoctor markup language in Ruby. Installing the Metanorma gem will install the Asciidoctor gem, if it is not already installed.
 
-[source,asciidoctor]
-----
-.Sample Code
+Ruby comes with Linux and MacOS. Asciidoctor-ISO uses at minimum Ruby 2.3.0, and you may need to update your Ruby instance to use that version. Refer to https://www.ruby-lang.org/en/documentation/installation/
 ====
 
-[source,ruby]
---
-puts "Hello, world."
-%w{a b c}.each do |x| <1>
-  puts x
-end
---
-<1> This is an annotation
-====
-----
 
-* https://asciidoctor.org/docs/user-manual/#comments[Comments] (which are *not* rendered in the output)
 
-[source,ruby]
---
-// all terms and defs references are dated
---
 
-=== Sections
+== Setting up a new project
 
-* The Asciidoctor https://asciidoctor.org/docs/user-manual/#doc-preamble[Document preamble] is treated as the document Foreword: it is the text appearing between the document header and the first section header. (Note that the foreword is here given a https://asciidoctor.org/docs/user-manual/#title[block title], but that will be provided automatically anyway.)
+At its simplest, all you need is a text document in Asciidoctor-like AsciiISO format,
+which you compile using the Metanorma-ISO gem.
 
-[source,asciidoctor]
---
-[[foreword]]
-.Foreword
-ISO (the International Organization for Standardization)
---
+To keep document dependencies in order, place your document in a distinct folder:
 
-* The Asciidoctor https://asciidoctor.org/docs/user-manual/#sections[Sections] correspond to ISO clauses, starting with the Introduction (if present). Each section and subsection is delimited with a header; the number of equal signs before the header indicate the level of nesting of the section, starting with two equal signs. No numbering should be given for any header: numbering is done automatically by the gem.
 
-[source,asciidoctor]
+[source,console]
 --
-== Sampling
-Sampling shall be carried out in accordance with <<ISO24333,clause 5>>
-
-== Test methods
-
-=== Moisture content
-
-Determine the mass fraction of moisture in accordance with the method specified in <<ISO712>>.
-...
-
+mkdir new_standard
+cd new_standard
+vi new_standard.adoc
 --
 
+To compile the document, execute the `asciidoctor` script, flagging it to use a specific standards class with the `-t` flag (refer to <<stupported-standards>> for the abbreviations used); e.g.
 
-== Asciidoctor-ISO specific syntax
-
-Full details of Asciidoctor-ISO–specific markup and conventions is given in the https://github.com/riboseinc/metanorma-iso/blob/master/README.adoc[Asciidoctor-ISO Readme] and the https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[Guidance for authoring].
-
-https://asciidoctor.org/docs/user-manual/#section-styles[Section styles] are used to indicate specific types of section: `[bibliography]` for Normative References and Bibliography, `[appendix]` for Annexes, and `[%appendix]` for Appendixes (annexes of annexes). These styles must be provided for the sections to be processed correctly: bibliographic references will not be recognised as such, for example, without the `[bibliography]` style applied:
-
-[source,asciidoctor]
---
-[bibliography]
-== Bibliography
-
-* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
+[source,console]
 --
-
-The sections that have a fixed position according to ISO/IEC DIR 2 (Introduction, Scope, Normative References, Terms and Definitions, Symbols and Abbreviations, Bibliography) need to be titled as such, as first-level headings.
-
-=== Terms and Definitions
-
-Terms and Definitions sections follow a strict grammar in their Asciidoctor-ISO markup, as ISO/IEC DIR 2 prescribes their structure so strictly. The following illustrates the complete structure of a term entry; the Rice document splits up these features among several terms.
-
-[source,asciidoctor]
+metanorma -t iso new_standard.adoc
 --
-[[paddy]]
-=== paddy
-alt:[paddy rice]
-alt:[rough rice]
-deprecated:[cargo rice]
-domain:[rice]
 
-rice retaining its husk after threshing
+This will generate two files from the `new_standard.adoc` document (provided it is well-formed):
 
-[example]
-Foreign seeds, husks, bran, sand, dust.
+* `new_standard.html`, a standalone HTML document,
+* `new_standard.doc`, a Word document
+  (currently in the pre-2007 `.doc` format, but Microsoft Word will open it fine).
 
-NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking.
+Both these files are generated via an intermediate XML file, `new_standard.xml`, which represents the structure of the document as it is formally defined by the standards body, and captured in the https://github.com/riboseinc/metanorma-model-iso[Metanorma XML schema].
 
-[.source]
-<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated,
-and Note 1 to entry is not included here
---
+Even if there are no errors in the Asciidoctor syntax, the document may still raise warnings to the console as it is being validated. The validation comes from the formal definition of the standard class (e.g. ISO/IEC DIR 2 in the case of ISO and IEC), and consists of two parts: warnings about document content (e.g., for ISO, requiring space before a percentage sign; requiring that the scope not contain text that looks like a recommendation); and warnings about document structure. The latter are generated by running the generated XML against the ISOXML schema, and report the line numbers of the XML document where issues are observed.
 
-Term banks such as the http://www.electropedia.org[IEV] must be treated like any other document, with terms treated as clauses; e.g. `<<IEV,clause "103-01-01">>`. The IEV must be explictly referenced with that label; when the XML is generated, it will be replaced by the official references to `IEC 60050-nnn:2001` standards documents.
 
-Exceptionally, an introductory section can be treated as a subclause instead of a term, by prefixing it with the style attribute `[.nonterm]`.
 
-=== References (Normative, Informative)
+Even if there are no errors in the syntax, the document may still raise warnings
+to the console as it is being validated.
+The validation comes from ISO/IEC DIR 2, and consists of two parts:
 
-All bibliographic entries must be given as unordered lists. Normative references are expected to include only ISO and related standards; informative references may include any source.
+* Warnings about document content
+  (e.g., requiring space before a percentage sign,
+  or requiring that the scope not contain text that looks like a recommendation).
+* Warnings about document structure
+  (found from running the generated XML against the ISOXML schema,
+  they report the line numbers of the XML document where issues are observed).
 
-For ISO and related standards, the reference is given as a bibliographic anchor (in triple brackets), consisting of an internal identifier followed by the ISO identifier. The internal identifier can be used in cross-references (citations). The date may be added to the ISO identifier, as required by ISO/IEC DIR 2; standards under preparation have their date given as `--`, and should be accompanied by a footnote detailing the status of the standard.
+== Starting with an example project
 
-[source,asciidoctor]
---
-Grade 3 quality as specified in <<ISO3696>>.
+Perhaps the simplest way to get started is to take an existing Metanorma-ISO document
+and edit it, observing how it approaches various formatting tasks.
 
-...
+The https://www.iso.org/publication/PUB100407.html["Rice document"]
+is the ISO's model document of an international standard.
+An Metanorma-ISO version of the document is available
+at https://github.com/riboseinc/isodoc-rice/.
+We suggest downloading the site, and editing it.
 
-* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
-* [[[ISO7301,ISO 7301:2011]]], _Rice -- Specification_
-* [[[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_
---
+The `iso-rice-en.adoc` document consists of a document header,
+and it references the separate `body/body-en.adoc` document for the document proper (`include::body/body-en.adoc[]`).
+You can just continue on with the document text after the document header—so long as you remember to leave a blank line between the two.
 
-Non-ISO references under normative references are still cited by document identifier. Under informative references, non-ISO documents are both displayed and cited with reference numbers in brackets. In Asciidoctor-ISO, the cross-reference is a normal anchor identifier; the bracket numbering for informative references is automatic.
+== Learning the AsciiDoc-based syntax
 
-[source,asciidoctor]
---
-For details concerning the use of the Dumas method, see References <<ref10>> and <<ref16>>.
+To author AsciiDoc documents, you need to be familiar with the _core AsciiDoc syntax_,
+as well as _the syntax extensions and conventions_ that are specific to Metanorma-ISO.
 
-...
+- Check out link:asciiiso-syntax[our AsciiISO syntax reference],
+  and link:guidance.adoc[Guidance for Authoring in Metanorma-ISO].
 
-* [[[ref10,10]]] [smallcap]#Standard No I.C.C 167#. _Determination of the protein content in cereal and cereal products for food and animal feeding stuffs according to the Dumas combustion method_ (see http://www.icc.or.at)
+- See also https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]
+  documenting Asciidoctor itself
+  and https://github.com/riboseinc/metanorma-iso/blob/master/README.adoc[Metanorma-ISO README].
 
-* [[[ref16,16]]] [smallcap]#Tkachuk R.# Nitrogen-to-protein conversion factors for cereals and oilseed meals. _Cereal Chem._ 1969, *46* (4) pp 419-423
---
-
-In cross-references, bibliographic localities (e.g. page numbers, clause numbers) can be added directly after the comma, as part of the cross-reference text. Bibliographic localities are expressed as a sequence of lowercase locality type, then an equal sign, then by the locality number or range:
+== Migrating existing documents from Microsoft Word
 
-[source,asciidoctor]
---
-<<ISO7301,clause=3.1>>
+. Use our https://github.com/riboseinc/reverse_asciidoctor[reverse_asciidoctor]
+gem to help you convert a Word document into AsciiISO.
++
+You will likely have to manually clean up some syntax
+(especially if your Word document contains an index, stray anchors, and equations):
+don’t rely on the automatic conversion to be 100% correct.
 
-NOTE: This table is based on <<ISO7301,table=1>>.
+- Check out link:asciiiso-syntax[our AsciiISO syntax reference],
+  and link:guidance.adoc[Guidance for Authoring in Asciidoctor-ISO].
 
-Sampling shall be carried out in accordance with <<ISO24333,clause=5>>
---
+- See also https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]
+  documenting Asciidoctor itself
+  and https://github.com/riboseinc/metanorma-iso/blob/master/README.adoc[Metanorma-ISO README].
 
-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_.
+== Migrating existing documents from Microsoft Word:
 
+. Use our https://github.com/riboseinc/reverse_asciidoctor[reverse_asciidoctor]
+  gem to help you convert a Word document into AsciiISO.
 
-=== Annexes
-
-For ISO standards, annexes are treated as normative by default; if they are informative, they must additionally be tagged with an obligation of "informative" (so `[appendix, obligation=informative]`).
-
-The numbering of annexes and appendices is automatic: do not insert "Annex A" or "Appendix 1" as part of the title.
+  You will likely have to manually clean up some syntax
+  (especially if your Word document contains an index, stray anchors, and equations):
+  don’t rely on the automatic conversion to be 100% correct.
+. Move the content back to the cloned isodoc-rice.