metanorma-iso 1.0.8 → 1.0.9

data/docs/asciiiso-syntax.adoc

@@ -0,0 +1,305 @@
+= AsciiISO syntax reference
+
+AsciiISO is syntax based on AsciiDoc, with some extensions specific to authoring ISO documents.
+
+== ISO specific syntax
+
+TIP: 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].
+
+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.
+
+== 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 Metanorma Asciidoctor 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 all Metanorma documents, and their expected values, are documented in the https://github.com/riboseinc/metanorma-standoc#document-attributes[metanorma-standoc Readme]; each standards-specific gem adds documentation of its own specific attributes (e.g. https://github.com/riboseinc/metanorma-iso#document-attributes). 
+
+Note that the initial title line and author line expected in Asciidoctor are ignored in favour of specific document attributes, although they still need to be supplied for the document to be valid.
+
+[source,asciidoctor]
+--
+= Rice model
+Author
+:docnumber: 17301
+:revdate: 2010-01-02
+:title:  Cereals and pulses -- Specifications and test methods -- Rice
+:language: en
+:status: published
+
+...
+--
+
+=== 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 automatically generated, 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. (Numbered 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.
+
+[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].
+
+TIP: For UNECE, paragraph numbering is generated automatically by the gem, which treats each paragraph as a leaf-node section. Paragraph numbers must not be entered in the Asciidoctor source.
+
+* 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]. The gem automatically creates labels for the nested levels of ordered lists (in the sequence lowercase letter–Arabic numeral–lowercase Roman numeral–upppercase letter–uppercase Roman numeral), 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:
+
+[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 Metanorma 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.
+--
+
+TIP: For UNECE, admonitions are used to render boxes. Admonitions can have titles.
+
+* https://asciidoctor.org/docs/user-manual/#prose-excerpts-quotes-and-verses[Block quotes]
+
+[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).
+_____
+--
+
+* 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]
+
+[source,asciidoctor]
+----
+.Sample Code
+====
+
+[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
+
+* 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.)
+
+[source,asciidoctor]
+--
+[[foreword]]
+.Foreword
+ISO (the International Organization for Standardization)
+--
+
+* The Asciidoctor https://asciidoctor.org/docs/user-manual/#sections[Sections] correspond to Metanorma 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]
+--
+== Sampling
+Sampling shall be carried out in accordance with <<ISO24333,clause 5>>
+
+== Test methods
+--
+
+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_
+--
+
+Sections whose position is set by the standard (e.g., for ISO, 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 Metanorma-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]
+--
+[[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
+--
+
+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)
+
+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.
+
+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.
+
+[source,asciidoctor]
+--
+Grade 3 quality as specified in <<ISO3696>>.
+
+...
+
+* [[[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_
+--
+
+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 Metanorma-ISO, the cross-reference is a normal anchor identifier; the bracket numbering for informative references is automatic.
+
+[source,asciidoctor]
+--
+For details concerning the use of the Dumas method, see References <<ref10>> and <<ref16>>.
+
+...
+
+* [[[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)
+
+* [[[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:
+
+[source,asciidoctor]
+--
+<<ISO7301,clause=3.1>>
+
+NOTE: This table is based on <<ISO7301,table=1>>.
+
+Sampling shall be carried out in accordance with <<ISO24333,clause=5>>
+--
+
+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_.
+
+
+=== 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.

data/docs/customisation.adoc

@@ -1,645 +1,7 @@
-= Gem Customisation Guide
+= Customising Metanorma
 
-In this guide, we give advice on how to adopt the Metanorma approach to document generation for your documents. We provide enough guidance for you to do full customisation, but we prefix each section with a Tip for quick-and-dirty implementation.
+Refer to Metanorma adoption FAQ for advice on how to adopt the Metanorma approach
+to document generation for your documents.
 
-== How can I adopt the StanDoc specification for my own publications?
-
-TIP: Copy the RSD schema from https://github.com/riboseinc/metanorma-iso/blob/master/grammars/rsd.rng. You may need to adapt some of the enums in the model, or in the ISO Standards model that it inherits; but in the first instance, you can just ignore the differences—and ignore the validation feedback that the toolset gives.
-
-The Standoc specification is expressed in http://www.relaxng.org[RelaxNG schema for XML], and is intended to be customisable for different types of publication. The customisation of Standoc relies on inheritance, with the following schemas embedded hierarchically:
-
-* https://github.com/riboseinc/bib-models[Relaton]: bibliography
-* https://github.com/riboseinc/basicdoc-models[BasicDoc]: block-level and inline formatting
-* https://github.com/riboseinc/metanorma-standoc[StanDoc]: organisation of sections for a generic standards document
-* Models specific to standards
-
-Because of the richness of the ISO standards model, most Standoc standards to date (including the sample gem https://github.com/riboseinc/metanorma-sample) inherit from the ISO Standards model, which itself inherits from Standoc.
-
-Specialisation of a model consists of:
-
-* Adding classes to a base model.
-* Changing attributes of a base model class. This is not restricted to adding attributes, as is the case in typical entity subclassing; it can also include removing attributes from a class, changing their obligation and cardinality, and changing their type, including changing enumerations. Attributes can be overruled at any level; for example, standards-specific models routinely enhance the bibliographic model at the base of the hierarchy.
-* For reasons of clarity, renaming classes and attributes is avoided in specialisation.
-
-To adapt the schema for your publication set,
-
-* Get familiar with the Standoc set of models, and identify any elements that you would want to represent differently for your documents (different types, different enums), or enhance for your documents (additional element attributes, additional elements)
-* Create a grammar inheriting from StanDoc or from a specific standard, which expresses what is distinctive about your grammar.
-** We recommend starting your modelling in UML, as an effective communication tool; compare the UML models for Standoc standards at https://github.com/riboseinc/metanorma-iso
-** The tool suite expects to validate against a set of schemas expressed in RelaxNG. We have been authoring grammars in RelaxNG Compact, as a more human-readable format, then compiling those grammars to RelaxNG using https://github.com/relaxng/jing-trang[jing-trang]. You can choose to use a different schema language, but you will need to customise the tool chain to validate against that form of schema instead.
-** In order to make schema inheritance easier, we have avoided using namespaces for the individual schemas; a namespace is added to the standards-specific schema at the very end of the inheritance chain.
-
-=== Schema customisation
-
-For example, the `rsd.rnc` schema, expressed in RelaxNG Compact, is specific to Ribose Standard documents: it inherits from the ISO Standards model, modifying 10 elements, and adding five. As an example of modifying elements, RSD permits preformatted text (Ascii art) in figures, which ISO does not:
-
-.ISO
-[source,asciidoctor]
-----
-figure =
-  element figure { 
-    attribute id { xsd:ID },
-    tname?, 
-    ( image | subfigure+ ),
-    fn*, dl?, note*
-  }
-----
-
-.RSD
-[source,asciidoctor]
-----
-figure =
-  element figure { 
-    attribute id { xsd:ID },
-    tname?, 
-    ( image | pre | subfigure+ ),
-    fn*, dl?, note*
-  }
-----
-
-The preformatted text tag `pre` is an addition to the RSD specification, which is why it lies outside the `include "isostandard.rnc {}"` container:
-
-.RSD
-[source,asciidoctor]
-----
-pre = element pre { text }
-----
-
-As another instance of customisation, the `BibItemType` enumeration of permissible bibliographical item types is extended in RSD to include the document types specific to RSD:
-
-.RSD
-[source,asciidoctor]
-----
-BibItemType |=
-"policy-and-procedures" | "best-practices" | "supporting-document" | "report" | "legal" | "directives" | "proposal" |
-        "standard"
-----
-
-
-== How can I adapt the StanDoc toolchain for my own publications?
-
-[TIP]
-====
-The easiest way to adopt StanDoc is to use the metanorma-acme gem: https://github.com/riboseinc/metanorma-acme, supplying your own stylesheets and HTML files for styling.
-
-If you wish to create a custom gem, in order to customise behaviour further:
-
-* Clone the metanorma-sample gem: https://github.com/riboseinc/metanorma-sample.
-* Change the namespace for RSD documents (`RSD_NAMESPACE = "https://open.ribose.com/standards/rsd"`) to a namespace specific to your organisation's document standard.
-* Change any references to `sample` or `Sample` in the gem to your organisation's document standard.
-* Change the styling of the document outputs (`.../lib/isodoc/XXX/html`).
-====
-
-The tool chains currently available proceed in two steps: map an input markup language (currently Asciidoctor only) into Standoc XML, and map Standoc XML into various output formats (currently Word doc, HTML, PDF via HTML). Running the metanorma tool involves a third step, of exposing the capabilities available in the first two in a consistent format. These two steps are represented as three separate modules, which are included in the same gem; for the Sample gem, they are `Asciidoctor::Sample`, `Isodoc::Sample`, and `Metanorma::Sample`. (In the case of Asciidoctor-ISO, almost all the content of `Isodoc::ISO` is in the isodoc gem, so the base classes of the two steps are in separate gems.) 
-
-Your adaptation of the toolchain will need to instantiate these three modules. The connection between the two first steps is taken care of in the toolchain, and metanorma explicitly invokes the two steps, feeding the XML output of the first step as input into the second. The metanorma-sample gem outputs both Word and HTML; you can choose to output only Word (as is done in metanorma-m3d), or only HTML (as is done in metanorma-csand), and you can choose to generate PDF from HTML as well (as is done in metanorma-csd).
-
-The modules involve classes which rely on inheritance from other classes; the current gems use `Asciidoctor::{Standoc, ISO}::Converter`, `Isodoc::{Metadata, HtmlConvert, WordConvert}`, and `Metanorma::Processor` as their base classes. This allows the standards-specific classes to be quite succinct, as most of their behaviour is inherited from other classes; but it also means that you need to be familiar with the underlying gems, in order to do most customisation.
-
-In the case of `Asciidoctor::X` classes, the changes you will need to make involve the intermediate XML representation of your document, which is built up through Nokogiri Builder; e.g. adding different enums, or adding new elements. The adaptations in `Asciidoctor::Sample::Converter` are limited, and most projects can take them across as is. 
-
-The customisations needed for Metanorma::Sample::Processor are minor, and involve invoking methods specific to the gem for document generation.
-
-The customisations needed for Isodoc::Sample are more extensive. Three base classes are involved: 
-
-* `Isodoc::Metadata` processes the metadata about the document stored in `//bibdata`. This information typically ends up in the document title page, as opposed to the document body. For that reason, metadata is extracted into a hash, which is passed to document output (title page, Word header) via the https://shopify.github.io/liquid/[Liquid template language].
-* `Isodoc::HtmlConvert` converts Standoc XML to HTML.
-* `Isodoc::WordConvert` converts Standoc XML to Word HTML; the https://github.com/riboseinc/html2doc[html2doc] gem then converts this to a .doc document.
-
-The `Isodoc::HtmlConvert` and `Isodoc::WordConvert` overlap substantially, as both use variants of HTML. However there is no reason not to make substantially different rendering choices in the HTML and Word branches of the code.
-
-=== Asciidoctor::Standoc customisation in metanorma-sample
-
-Examples from Asciidoctor::Sample in metanorma-sample. In the following snippets, the parameter `node` represents the current node of the Asciidoctor document, and `xml` represents the Nokogiri Builder node of the XML output.
-
-* The boilerplate representation of the document's author, publisher and copyright holder names Acme instead of ISO as the responsible organisation.
-
-[source,ruby]
---
-      def metadata_author(node, xml)
-        xml.contributor do |c|
-          c.role **{ type: "author" }
-          c.organization do |a|
-            a.name "Acme"
-          end
-        end
-      end
---
-
-* The editorial committees are represented as a single element, as opposed to ISO's name plus number. (`node.attr()` recovers Asciidoctor document attribute values.)
-
-[source,ruby]
---
-      def metadata_committee(node, xml)
-        xml.editorialgroup do |a|
-          a.committee node.attr("committee"),
-            **attr_code(type: node.attr("committee-type"))
-        end
-      end
---
-
-* The document title is monolingual, not bilingual. (`asciidoc_sub()` is already defined to apply Asciidoctor text substitutions to its contents, such as smart quotes and em-dashes.)
-
-[source,ruby]
---
-      def title(node, xml)
-        ["en"].each do |lang|
-          xml.title **{ language: lang, format: "plain" } do |t|
-            t << asciidoc_sub(node.attr("title"))
-          end
-        end
-      end
---
-
-* The document status is a single element, as opposed to ISO's two-part code.
-
-[source,ruby]
---
-      def metadata_status(node, xml)
-        xml.status(**{ format: "plain" }) { |s| s << node.attr("status") }
-      end
---
-
-* The document identifier is a single element.
-
-[source,ruby]
---
-      def metadata_id(node, xml)
-        xml.docidentifier { |i| i << node.attr("docnumber") }
-      end
---
-
-* A security element is added to the document metadata.
-
-[source,ruby]
---
-      def metadata_security(node, xml)
-        security = node.attr("security") || return
-        xml.security security
-      end
-
-      def metadata(node, xml)
-        super
-        metadata_security(node, xml)
-      end
---
-
-* Title validation and style validation is disabled.
-
-[source,ruby]
---
-      def title_validate(root)
-        nil
-      end
---
-
-* The root element of the document is changed from `iso-standard` to `sample-standard`.
-
-[source,ruby]
---
-      def makexml(node)
-        result = ["<?xml version='1.0' encoding='UTF-8'?>\n<sample-standard>"]
-        @draft = node.attributes.has_key?("draft")
-        result << noko { |ixml| front node, ixml }
-        result << noko { |ixml| middle node, ixml }
-        result << "</sample-standard>"
-        ....
-      end
---
-
-* The document type attribute is restricted to a prescribed set of options.
-
-[source,ruby]
---
-      def doctype(node)
-        d = node.attr("doctype")
-        unless %w{policy-and-procedures best-practices 
-          supporting-document report legal directives proposal 
-          standard}.include? d
-          warn "#{d} is not a legal document type: reverting to 'standard'"
-          d = "standard"
-        end
-        d
-      end
---
-
-* The `literal` asciidoctor block is processed as a preformatted tag (`pre`).
-(The code uses the built-in Asciidoctor `literal()` method, and embeds `pre` within a `figure` tag.)
-
-[source,ruby]
---
-      def literal(node)
-        noko do |xml|
-          xml.figure **id_attr(node) do |f|
-            figure_title(node, f)
-            f.pre node.lines.join("\n")
-          end
-        end
-      end
---
-
-* A `keyword` element is added. (The keyword is encoded through the role attribute of Asciidoc: `[.keyword]#text#`)
-
-[source,ruby]
---
-      def inline_quoted(node)
-        noko do |xml|
-          case node.type
-          ...
-          else
-            case node.role
-            ...
-            when "keyword" then xml.keyword node.text
-            else
-              xml << node.text
-            end
-          end
-        end.join
-      end
---
-
-* The inline headers of ISO are ignored.
-
-[source,ruby]
---
-      def sections_cleanup(x)
-        super
-        x.xpath("//*[@inline-header]").each do |h|
-          h.delete("inline-header")
-        end
-      end
---
-
-=== Metanorma::Processor customisation in metanorma-sample
-
-* `initialize` names the token by which Asciidoctor registers the standard
-
-[source,ruby]
---
-      def initialize
-        @short = :sample
-        @input_format = :asciidoc
-        @asciidoctor_backend = :sample
-      end
---
-
-* `output_formats` names the available output formats (including XML, which is inherited from the parent class)
-
-[source,ruby]
---
-      def output_formats
-        super.merge(
-          html: "html",
-          doc: "doc",
-          pdf: "pdf"
-        )
-      end
---
-
-* `version` gives the current version string for the gem
-
-[source,ruby]
---
-     def version
-        "Asciidoctor::Sample #{Asciidoctor::Sample::VERSION}"
-      end
---
-
-* `input_to_isodoc` is the call which converts Asciidoctor input into IsoDoc XML
-
-[source,ruby]
---
-      def input_to_isodoc(file)
-        Metanorma::Input::Asciidoc.new.process(file, @asciidoctor_backend)
-      end
---
-
-* `output` is the call which converts IsoDoc XML into various nominated output formats
-
-[source,ruby]
---
-      def output(isodoc_node, outname, format, options={})
-        case format
-        when :html
-          IsoDoc::Sample::HtmlConvert.new(options).convert(outname, isodoc_node)
-        when :doc
-          IsoDoc::Sample::WordConvert.new(options).convert(outname, isodoc_node)
-        when :pdf
-          IsoDoc::Sample::PdfConvert.new(options).convert(outname, isodoc_node)
-        else
-          super
-        end
-      end
---
-
-=== Isodoc::Standoc customisation in metanorma-sample
-
-* Setting the document title (`:doctitle`) in metadata, as a single element in ISO XML; ignore any document subtitle. 
-
-[source,ruby]
---
-      def title(isoxml, _out)
-        main = isoxml&.at(ns("//title[@language='en']"))&.text
-        set(:doctitle, main)
-      end
-
-      def subtitle(_isoxml, _out)
-        nil
-      end
---
-
-* Add to version metadata a metadata element for the revision date (already stored as `:revdate`), expressed as month+year (`:revdate_monthyear`)/
-
-[source,ruby]
---
-      def version(isoxml, _out)
-        super
-        revdate = get[:revdate]
-        set(:revdate_monthyear, monthyr(revdate))
-      end
-
-      def monthyr(isodate)
-        m = /(?<yr>\d\d\d\d)-(?<mo>\d\d)/.match isodate
-        return isodate unless m && m[:yr] && m[:mo]
-        return "#{MONTHS[m[:mo].to_sym]} #{m[:yr]}"
-      end
---
-
-* Initialise the HTML Converter: 
-** Set `@libdir`, the current directory of the HTML converter, and the basis of the `html_doc_path()` method for accessing HTML assets (the `html` subdirectory of the current directory).
-** Copy the logo JPG from the HTML asset directory to the working directory, so that it can be access by the HTML template; flag the copy for deletion at the end of processing.
-
-[source,ruby]
---
-      def initialize(options)
-        @libdir = File.dirname(__FILE__)
-        super
-        FileUtils.cp html_doc_path('logo.jpg'), "logo.jpg"
-        @files_to_delete << "logo.jpg"
-      end
---
-
-* Set the default fonts for the HTML rendering, which will be used to populate the HTML CSS stylesheet.
-
-[source,ruby]
---
-    class HtmlConvert < IsoDoc::HtmlConvert
-      def default_fonts(options)
-        {
-          bodyfont: (options[:script] == "Hans" ? '"SimSun",serif' : '"Overpass",sans-serif'),
-          headerfont: (options[:script] == "Hans" ? '"SimHei",sans-serif' : '"Overpass",sans-serif'),
-          monospacefont: '"Space Mono",monospace'
-        }
-      end
---
-
-* Set the default HTML assets for the HTML rendering.
-
-[source,ruby]
---
-    class HtmlConvert < IsoDoc::HtmlConvert
-      def default_file_locations(_options)
-        {
-          htmlstylesheet: html_doc_path("htmlstyle.scss"),
-          htmlcoverpage: html_doc_path("html_sample_titlepage.html"),
-          htmlintropage: html_doc_path("html_sample_intro.html"),
-          scripts: html_doc_path("scripts.html"),
-        }
-      end
---
-
-* Set distinct default fonts and HTML assets for the Word rendering.
-
-[source,ruby]
---
-    class WordConvert < IsoDoc::WordConvert
-      def default_fonts(options)
-        {
-          bodyfont: (options[:script] == "Hans" ? '"SimSun",serif' : '"Arial",sans-serif'),
-          headerfont: (options[:script] == "Hans" ? '"SimHei",sans-serif' : '"Arial",sans-serif'),
-          monospacefont: '"Courier New",monospace'
-        }
-      end
-
-      def default_file_locations(_options)
-        {
-          wordstylesheet: html_doc_path("wordstyle.scss"),
-          standardstylesheet: html_doc_path("sample.scss"),
-          header: html_doc_path("header.html"),
-          wordcoverpage: html_doc_path("word_sample_titlepage.html"),
-          wordintropage: html_doc_path("word_sample_intro.html"),
-          ulstyle: "l3",
-          olstyle: "l2",
-        }
-      end
---
-
-
-* Set the content of the HTML head, other than the CSS stylesheets. Note that the head title is given as a Liquid Template reference to metadata ()`{{ doctitle }}`, which we have seen populated above.)
-
-[source,ruby]
---
-     def html_head
-        <<~HEAD.freeze
-        <title>{{ doctitle }}</title>
-    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
-    <!--TOC script import-->
-    <script type="text/javascript" src="https://cdn.rawgit.com/jgallen23/toc/0.3.2/dist/toc.min.js"></script>
-    <!--Google fonts-->
-    ....
-    <style class="anchorjs"></style>
-        HEAD
-      end
---
-
-* Change the default label for annexes from "Annex" to "Appendix".
-
-[source,ruby]
---
-      def i18n_init(lang, script)
-        super
-        @annex_lbl = "Appendix"
-      end
---
-
-* Define rendering for the `pre` and `keyword` preformatted text tags.
-
-[source,ruby]
---
-      def pre_parse(node, out)
-        out.pre node.text # content.gsub(/</, "&lt;").gsub(/>/, "&gt;")
-      end
-      
-      def error_parse(node, out)
-        # catch elements not defined in ISO
-        case node.name
-        when "pre"
-          pre_parse(node, out)
-        when "keyword"
-          out.span node.text, **{ class: "keyword" }
-        else
-          super
-        end
-      end      
---
-
-* Render term headings in the same paragraph as the term heading number
-
-[source,ruby]
---
-      def term_cleanup(docxml)
-        docxml.xpath("//p[@class = 'Terms']").each do |d|
-          h2 = d.at("./preceding-sibling::*[@class = 'TermNum'][1]")
-          h2.add_child("&nbsp;")
-          h2.add_child(d.remove)
-        end
-        docxml
-      end
---
-
-
-== How can I style the resulting HTML output?
-
-[TIP]
-====
-* Clone the metanorma-sample gem: https://github.com/riboseinc/metanorma-sample.
-* Edit the `html_sample_titlepage.html` and `html_sample_intro.html` pages to match your organisation's branding.
-** Leave the Liquid Template instructions alone (`{{`, `{%`) unless you know what you're doing with them: they are how the pages are populated with metadata.
-* Edit the `default_fonts()` method in your `IsoDoc::...::HtmlConvert` class, to match your desired fonts.
-* Edit the `default_file_locations()` method in your `IsoDoc::...::HtmlConvert` class, to match your desired stylesheets and HTML templates.
-* Edit the `htmlstyle.scss` stylesheet to match your organisation's branding. The classes already in place there are used to style existing blocks of text; refer to the sample documents included in the gem (`spec/examples`) for their use.
-====
-
-Styling of output is intended to be configurable. HTML stylesheets are expressed in https://sass-lang.com/guide[SCSS], with their fonts populated through the `default_fonts()` method in the `IsoDoc::...::HtmlConvert` class. Frontispiece content is templated, populated from metadata parsed in the `IsoDoc::...::Metadata` class, via https://shopify.github.io/liquid/[Liquid templates]. The default stylesheets and HTML templates themselves are nominated in the `default_file_locations()` method in the `IsoDoc::...::HtmlConvert` class. That means you can change the styling of output documents readily, so long as you are aware of the functionality of the stylesheet.
-
-* Styling information is stored in the `.../lib/isodoc/html` folder of the gem, and applies to both Word and HTML content. For HTML content, the relevant files are `html_..._titlepage.html` (title page HTML template), `html_..._intro.html` (introductory HTML template, typically restricted to Table of Contents), `scripts.html` (Javascript scripts), and `htmlstyle.scss` (the HTML stylesheet).
-* The styling files to be loaded in are set in the `default_file_locations()` method of `IsoDoc::...::HtmlConvert`. The files can be overridden through document variables in the Asciidoc document.
-* Additional files (e.g. logos) can be loaded in the `initialize()` method of `IsoDoc::...::HtmlConvert`; for them to be access during document generation, they need to be copied to the working directory. (They can be removed subsequently by adding them to the `@files_to_delete` array. All image files are copied into an `_html` subdirectory.)
-* The HTML templates are populated through Liquid Templates: variables in `{{` correspond to the hash keys for metadata extracted in `IsoDoc::...::Metadata`, and its superclass `IsoDoc::Metadata` in the isodoc gem.
-* The SCSS stylesheets treat fonts as variables. Those variables are set in `default_fonts()`, which generates variable assignments for SCSS. Stylesheets normally recognise three fonts: `$bodyfont` for body text, `$headerfont` for headers and captions (which may be the same font as `$bodyfont`), and `$monospacefont` for monospace text. Note that `default_fonts()` takes the options passed to initialise `HtmlConvert` as a paremeter; the document language and script can be used to make different font choices for different document scripts. (The existing gems refer to `Latn`, Latin script, and `Hans`, Simplified Chinese script.)
-* Javascript scripts are populated in `scripts.html`; the scripts already in place in any gem you modify are in live use, and you should work out what they do before removing them. The AnchorJS script, for example, is used to generate navigable anchors in the document.
-* Additional scripts and fonts may be loaded in the document head through the `html_head()` method of  `IsoDoc::...::HtmlConvert`. The existing gems use the document head to load Jquery, the Table of Contents generation script, Google Fonts, and Font Awesome.
-* The classes in the SCSS stylesheet correspond to static HTML content in the HTML templates, and dynamic HTML content in the `IsoDoc::...::HtmlConvert` class, and its superclasses `IsoDoc::HtmlConvert` and `IsoDoc::Common` in the isodoc gem.
-
-An HTML document is populated as follows:
-* HTML Head wrapper (in `IsoDoc::HtmlConvert`)
-** `html_head()` content
-** `@htmlstylesheet` CSS stylesheet (expected to be in SCSS, generated from SCSS in the `generate_css()` method of `Isodoc::HtmlConvert`).
-* HTML Body
-** `@htmlcoverpage` HTML template (optional, corresponds to `html_..._titlepage.html`)
-** `@htmlintropage` HTML template (optional, corresponds to `html_..._intro.html`)
-** Document proper (converted from Standoc XML)
-** `@scripts` Javascript Scripts (optional, corresponds to `scripts.html`)
-
-== How can I style the resulting Word output?
-
-[TIP]
-====
-* There is no quick way of doing this.
-* Everything you can do in Word, you can do in Word HTML. Save Word documents as Word HTML to see how.
-* Clone the metanorma-sample gem: https://github.com/riboseinc/metanorma-sample.
-* Edit the `word_sample_titlepage.html` and `word_sample_intro.html` pages to match your organisation's branding. With lots of iterations of saving Word documents as HTML, for trial and error.
-** Leave the Liquid Template instructions alone (`{{`, `{%`) unless you know what you're doing with them: they are how the pages are populated with metadata.
-* Edit the `default_fonts()` method in your `IsoDoc::...::WordConvert` class, to match your desired fonts.
-* Edit the `default_file_locations()` method in your `IsoDoc::...::WordConvert` class, to match your desired stylesheets and file templates.
-* Edit the `wordstyle.scss` and `sample.scss` stylesheets to match your organisation's branding. With lots of iterations of saving Word documents as HTML, for trial and error.
-====
-
-Word output in the document toolset is generated through Word HTML, the variant of HTML that you get when you save a Word document as HTML. (That is why documents are saved in `.doc`, not `.docx`.) This has the advantage over https://en.wikipedia.org/wiki/Office_Open_XML[OOXML], the native markup of DOCX, of using a well-known markup language, with a low barrier to entry: if you want to work out how to do something in Word HTML, do it in Word, save the document as HTML, and open up the HTML in a text editor. (For more on the choice of using Word HTML, see https://github.com/riboseinc/html2doc/wiki/Why-not-docx%3F.)
-
-However Word HTML is not quite the HTML you are used to: it is a restricted, syntactically idiosyncratic variant of HTML 4, with a non-standard and weakened form of CSS. Doing any styling in Word HTML involves lots of trial and error, and paying close attention to how Word HTML does things in its CSS. We have documented a few of the clearer gotchas in https://github.com/riboseinc/html2doc/blob/master/README.adoc.
-
-It's still better than learning OOXML.
-
-The process for generating Word output is fairly similar to that for generating HTML, since both processes are generating a form of HTML; as we already noted, the two processes share a substantial amount of code. The main differences are in the handling of page-media features that CSS has lagged in (footnotes, pagination, headers and footers), and in the styling of lists, for which Word HTML uses custom (and undocumented) CSS classes prefixed with `@`, specifying inter alia the numbering for nine levels of nesting of the same list.
-
-* Styling information is stored in the `.../lib/isodoc/html` folder of the gem, and applies to both Word and HTML content. For Word content, the relevant files are `word_..._titlepage.html` (title page HTML template), `word_..._intro.html` (introductory HTML template, typically restricted to Table of Contents),  `wordstyle.scss` and `{name_of_standard}.scss` (the Word stylesheets), and `header.html` (document headers, footers, and endnote/footnote separators, referenced from the stylesheets).
-* The styling files to be loaded in are set in the `default_file_locations()` method of `IsoDoc::...::WordConvert`. 
-* As with HTML generation, additional files (e.g. logos) can be loaded in the `initialize()` method of `IsoDoc::...::WordConvert`. The `initialize()` method also sets the `@` styles in the stylesheet to be used for unordered and ordered lists; a single such style is intended to capture the behaviour of all levels of indentation. 
-* As with HTML output, the HTML templates are populated through Liquid Templates: variables in `{{` correspond to the hash keys for metadata extracted in `IsoDoc::...::Metadata`, and its superclass `IsoDoc::Metadata` in the isodoc gem.
-* As with HTML, the SCSS stylesheets treat fonts as variables, and are set in the `default_fonts()` method of `IsoDoc::...::WordConvert`.
-* Document headers and footers are set in the `header.html` file. This is also an HTML template, which is populated with metadata attributes through Liquid Template. The structure of `header.html` is determined by Word, and elements of `header.html` need to be crossreferenced from the Word stylesheet. To inspect Word `header.html` files, save a Word document as HTML, and look inside the `{document_name}.fld` folder generated alongside the HTML output.
-* The classes in the SCSS stylesheet correspond to static HTML content in the HTML templates, and dynamic HTML content in the `IsoDoc::...::WordConvert` class, and its superclasses `IsoDoc::WordConvert` and `IsoDoc::Common` in the isodoc gem.
-
-A Word HTML document is populated as follows:
-* HTML Head wrapper (in `IsoDoc::WordConvert`)
-** `@wordstylesheet` CSS stylesheet (generated from SCSS through the `generate_css()` method of `Isodoc::WordConvert`); corresponds to `wordstyle.scss`.
-** `@standstylesheet` CSS stylesheet (generated from SCSS through the `generate_css()` method of `Isodoc::WordConvert`); intended to override any generic CSS in `@wordstylesheet`. Optional, corresponds to `{name_of_standard}.scss`.
-* HTML Body
-** `@wordcoverpage` HTML template (optional, corresponds to `word_..._titlepage.html`). Included in `<div class=WordSection1>`.
-** `@htmlintropage` HTML template (optional, corresponds to `word_..._intro.html`). Included in `<div class=WordSection2>`. In the existing gems, WordSection2 is paginated with roman numerals. 
-** Document proper (converted from Standoc XML). Included in `<div class=WordSection2>` (prefatory material) and `<div class=WordSection3>` (main document). In the existing gems, WordSection3 is paginated with roman numerals.
-
-== 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
---
-
-== I can translate my specifications into IsoDoc XML myself (i.e. I don't like AsciiDoc, or I already have my own toolchain). Can I only use IsoDoc XML to produce pretty output?
-
-[TIP]
-====
-* Generate correct IsoDoc XML (make sure it validates!)
-* Create just the `IsoDoc::...::HtmlConvert` and/or `IsoDoc::...::WordConvert` classes to convert the IsoDoc XML into target formats.
-* Initialise the IsoDoc class passing the necessary information about fonts and scripts; the existing gems all illustrate this kind of initialisation.
-* Create the target format using the method `.convert(filename, xml)`.
-====
-
-The Asciidoctor-to-XML and XML-to-Output classes are separate, so you can invoke just the latter without the former. Of course, you will need to make sure that the IsoDoc XML you are passing to the generators is valid.
-
-The `IsoDoc::...::HtmlConvert` and/or `IsoDoc::...::WordConvert` are initialised in the existing gems with a hash giving the fonts to be used in the document (to be injected in the document SCSS stylesheets), the script of the document (to be used to pick the right font, in case of default font settings), and the `i18nyaml` YAML file for localisation. All existing gems have defaults set for these values on the Asciidoctor side invoking the class, so all parameters are optional.
-
-Once you have the classes set up, all you need to do is invoke the conversion of XML to the target format, with the method `.convert(filename, xml)`, where XML is the IsoDoc XML.
+You will usually find there a detailed customisation guidance prefixed with a short summary
+for a quick-and-dirty implementation.