metanorma-standoc 1.1.9 → 1.2.0

data/docs/guidance.adoc

@@ -1,436 +0,0 @@
-= 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/metanorma/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/metanorma/metanorma-iso/blob/master/spec/examples/rice.adoc[AsciiDoc version] of the ISO Standard exemplar, the https://www.iso.org/publication/PUB100407.html["Rice document"]. If you use this document as a template for your own ISO standard document, you will find most of the formatting you need illustrated there.
-
-== Usage
-
-See the README on https://github.com/metanorma/metanorma-iso#usage[how to deploy and use the gem].
-
-== 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).
-
-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/metanorma/isodoc/blob/master/lib/isodoc/i18n-en.yaml, substituting translations for each of the fields given.
-
-The Chinese (Simplified) template also localises punctuation and spacing, mapping them away from the default Latin punctuation used elsewhere in the gem.
-
-== Validation
-
-All 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. 
-
-The content warnings come first, and are prefixed with `ISO Style`. They try to impose rules on content taken from http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf[ISO/IEC DIR 2], including restrictions on where requirements may be stated, usage of decimal points, hanging clauses, and subclauses that are the only child of their parent clause. While the error detection is not infallible, they should be reviewed at least once. Where possible, the gem will give the ID or section heading associated with the error. For example:
-
-[source,console]
---
-ISO style: WARNING (Section: ): Footnote may contain requirement: The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.
-ISO style: WARNING (Section: Wire sieve,): possible decimal point: 0.02
-ISO style: invalid technical committee type XYZ
-ISO style: AnnexA-4-1:Preparation of test sample: subsection is only child
---
-
-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.
-
-For example:
-
-[source,console]
---
-value of attribute "date" is invalid; must be an ISO date @ 454:183
-element "review" missing required attribute "from" @ 454:183
-element "subsection" not allowed here; expected the element end-tag or element "admonition", "dl", "example", "figure", "formula", "note", "ol", "p", "quote", "review", "sourcecode", "table" or "ul" @ 467:52
-value of attribute "date" is invalid; must be an ISO date @ 476:233
-IDREF "Annex-A-2" without matching ID @ 315:50
-IDREF "last_conformance_class" without matching ID @ 649:236
-IDREF "Annex-A" without matching ID @ 308:141
---
-
-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.
-
-== 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/metanorma/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 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.
-
-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`.
-
-== 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.
-
-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.
-
-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.
-
-
-=== Bibliographies
-
-The Normative References and the Bibliography must be preceded by the style attribute `[bibliography]`, so that the references they contain may be recognised as such. 
-
-All bibliographic entries must be given as unordered lists. 
-
-Currently the gem only supports formatted citations, which are given as such in the Asciidoc source. In the future, we expect to integrate the documents with http://www.bibtex.org[BibTex] databases, through the https://github.com/riboseinc/asciidoctor-bibliography[asciidoctor-bibliography] gem.
-
-==== ISO References
-
-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:
-
-[source,asciidoc]
---
-* [[[ricepotentialmilling,ISO 6646]]], _Rice -- Determination of the potential milling yield from paddy and from husked rice_
-* [[[ISOGuide73, ISO Guide 73:2009]]], _Risk management -- Vocabulary_
---
-
-[subs="quotes"]
-ISO 6646 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`.)
-
-If an ISO reference is in preparation, ISO/IEC DIR 2 dictates that details of the reference status be given as a footnote. In Asciidoc, this is done by giving the date as a double dash, and following the bibliographic anchor with a footnote macro:
-
-[source,asciidoc]
---
-* [[[ISO16634,ISO 16634:--]]] footnote:[Under preparation. (Stage at the time of publication ISO/DIS 16634)], _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_
---
-
-If an ISO reference includes all parts of the standard, that is indicated by appending `(all parts)` after the reference anchor:
-
-[source,asciidoc]
---
-* [[[ISO16634,ISO 16634 (all parts)]]] _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_
---
-
-
-In informative references, 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
-
-[source,asciidoc]
---
-[bibliography]
-== Bibliography 
-
-* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
---
-
-is displayed as:
-
-[quote]
-____
-*Bibliography*
-
-[1] ISO 3696, _Water for analytical laboratory use -- Specification and test methods_
-____
-
-==== 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.
-
-==== Non-ISO References
-
-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)
---
-
-==== 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).
-
-[source,asciidoctor]
---
-<<ISO7301,clause=3.1-3.4>>
-
-NOTE: This table is based on <<ISO7301,table=1>>.
-
-Sampling shall be carried out in accordance with <<xxx,section="5-3-1,bis">>
---
-
-Any text after the bibliographic localities is still treated as custom cross-reference text; e.g. `<<ISO7301,clause=5,table=1,the foregoing reference>>`. 
-
-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_.
-
-
-=== Terms and Definitions
-
-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.
-
-Terms and Definitions sections follow a strict grammar, which is reflected in their Asciidoc markup:
-
-* The term is given as a subheading at the appropriate level (three equal signs, unless there are subsections in the Terms and Definition section). The term may be crossreferenced from other terms, in which case it should have an anchor.
-* The term is optionally followed by alternative/admitted terms, which must be marked up in an `+alt:[...]+` macro; deprecated terms, which must be marked up in a `+deprecated:[...]+` macro; and a term domain, which must be marked up in a `+domain:[...]+` macro.
-* The definition of the term is given in a separate paragraph.
-* The definition is optionally followed by examples (paragraphs with an `[example]` style attribute).
-* The definition is then optionally followed by notes (denoted with a `NOTE:` prefix).
-* The definition is then followed by a citation for the term, marked with a `[.source]` role attribute). 
-* The citation is a cross-reference to a normative reference, optionally followed by a comma and a modification if applicable.
-
-For example,
-
-[source,asciidoc]
---
-[[paddy]]
-=== paddy 
-alt:[paddy rice]
-alt:[rough rice]
-deprecated:[cargo rice]
-domain:[rice]
-
-rice retaining its husk after threshing
-
-[example]
-Foreign seeds, husks, bran, sand, dust.
-
-NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking. 
-
-[.source]
-<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated,
-and Note 1 to entry is not included here
---
-
-The requirement that the source of a term be given in a citation also applies when the source is a term bank, such as http://www.electropedia.org[IEV]. By ISO convention, IEV references are not included in the bibliography, but for consistency and validation purposes, the IEV should be cited as a normal reference, with the term given as a clause, and the source should be named as IEV in the bibliography. The XML encoding of the document will include the IEV reference, substituting a canonical form of the reference in the bibliography; the output rendering of the document will drop the reference from the bibliography. For example:
-
-[source,asciidoc]
---
-[.source]
-<<ievtermbank,clause="103-01-02">>
-....
-
-[bibliography]
-* [[[ievtermbank,IEV]]], _IEV: Electropedia_
-// will be excluded from HTML and Word output. Will be replaced by a canonical reference in XML output.
---
-
-Note that, for IEV entries to be validated, the IEV reference must be given as a Clause, and in quotes (otherwise the locality syntax would be interpreted as a range); so `<<ievtermbank,clause="103-01-02">>` for IEV 103-01-02.
-
-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.)
-
-[source,asciidoc]
---
-=== stem:[t_90] 
-alt:[stem:[t_A]]
-
-Time to launch.
---
-
-However, the gem will treat any standalone paragraph in a term section, consisting of just a stem macro, as an admitted term:
-
-[source,asciidoc]
---
-=== stem:[t_90] 
-
-stem:[t_A]
-
-Time to launch.
---
-
-
-=== 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.
-
-=== Clauses
-
-Blank subclause headings can be given as `=== {blank}`. These are used when you want to give a subclause number for a new subclause, but without an associated header text. So e.g. in the Rice Model document,
-
-[source,asciidoc]
---
-=== Physical and chemical characteristics 
-
-==== {blank}
-
-The mass fraction of moisture, determined in accordance with...
---
-
-renders as 
-
-____
-*4.2. Physical and chemical characteristics*
-
-*4.2.1.*  The mass fraction of moisture, determined in accordance with...
-____
-
-
-Inline subclause headings (e.g. for test methods) are indicated by preceding the heading with the `[%inline-header]` option attribute. So in the Rice Model document,
-
-[source,asciidoc]
---
-[%inline-header]
-==== Sieve, 
-
-with round perforations of diameter 1,4 mm.
---
-
-renders as 
-
-____
-*A.2.1.1. Sieve,* with round perforations of diameter 1,4 mm.
-____
-
-
-Normative clauses are indicated with the attribute `[obligation=informative]`; they 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]`).
-
-Appendixes to annexes can occur, although they are not mentioned in ISO/IEC DIR 2; ISO/IEC DIR 1 features them. They are marked up as immediate subsections of annexes, and must be tagged with an option attribute of "appendix":
-
-[source,asciidoc]
---
-[appendix]
-== Annex A
-Text
-
-[%appendix]
-=== Appendix 1
-Text
---
-
-The numbering of annexes and appendices is automatic: do not insert "Annex A" or "Appendix 1" as part of the title. Annex and Appendix titles can be left blank, as with Clauses.
-
-== Text markup
-
-=== Mathematical formatting
-
-Mathematical formatting is done using the `[stem]` macro. 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.)
-
-=== Formulae
-
-Formulae are marked up as `[stem]` blocks. Any explanation of symbols in the formula is given as a "where" paragraph, followed by a definition list. For example:
-
-[source,asciidoc]
---
-[[formulaA-1]]
-[stem]
-++++
-w = (m_D) / (m_s)
-++++
-
-where
-
-stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
-stem:[m_D]:: is the mass, in grams, of grains with that defect; 
-stem:[m_S]:: is the mass, in grams, of the test sample. 
---
-
-=== Figures
-
-Like formulae, figures can be followed by a definition list for the variables used in the figure; the definition list is preceded by `+*Key*+`. For example:
-
-[source,asciidoc]
---
-[[figureC-1]]
-.Typical gelatinization curve
-image::rice_images/rice_image2.png[]
-footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]
-
-*Key*
-
-stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent
-stem:[t]:: cooking time, expressed in minutes
-stem:[t_90]:: time required to gelatinize 90 % of the kernels
-P:: point of the curve corresponding to a cooking time of stem:[t_90]
-
-NOTE: These results are based on a study carried out on three different types of kernel.
---
-
-Subfigures are entered by including images in an Asciidoc example:
-
-[source,asciidoc]
---
-[[figureC-2]]
-.Stages of gelatinization
-====
-.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels)
-image::rice_images/rice_image3_1.png[]
-
-.Intermediate stages: Some fully gelatinized kernels are visible
-image::rice_images/rice_image3_2.png[]
-
-.Final stages: All kernels are fully gelatinized
-image::rice_images/rice_image3_3.png[]
-
-====
---
-
-=== Tables
-
-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.
-
-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.
-
-=== 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).
-
-=== Notes
-
-Notes that are not at the end of a clause are folded into the preceding block, if that block is not delimited (so that the user could not choose to include or exclude a note): that is, notes are folded into a preceding paragraph, list, formula, or figure.
-
-=== Reviewer Notes
-
-We have introduced a mechanism in the gem to annotate arbitrary blocks of text, using Asciidoc sidebars and anchors for the beginning and end of the annotation; see https://github.com/metanorma/metanorma-standoc#reviewer-notes[discussion in the 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.
-
-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)".
-
-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.)
-
-List items can be cross-referenced by inserting a bookmark at the very start of the list item:
-
-[source,asciidoc]
---
-. Ordered list
-.. [[id]] This is the first list item
-... [[id]] This is a list sub-item
---
-
-== Asciidoctor Tips
-
-As 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.
-
-* A note or admonition can be made to span multiple paragraphs (including lists and tables), by making it a https://asciidoctor.org/docs/user-manual/#delimited-blocks[delimited block]:
-
-[source,asciidoc]
---
-[NOTE]
-====
-This is a multi-paragraph note.
-
-It includes:
-
-* A list
-
-|===
-| And 
-
-| a table
-|===
-====
---
-
-* https://asciidoctor.org/docs/user-manual/#using-attributes-set-assign-and-reference[Attribute references] can be used as template variables in a document: if your document contains the text `{foo}`, you can assign the value to be populated in `{foo}` by setting it as a document attribute in the Asciidoctor header: `:foo: this is the text to replace "foo"`. In the Rice Model document example, document attributes are used to provide the Subcommittee and Technical Committee names, which are populated as template entries in the document foreword.

data/docs/htmloutput.adoc

@@ -1,115 +0,0 @@
-= HTML and Word HTML Output
-
-In order to create CSS stylesheets for the HTML and Word HTML output of the Metanorma tool, it is necessary to understand the structure of the HTML it generates.
-
-== HTML
-
-=== Top-Level Structure
-
-The `head` of the HTML document contains a single stylesheet (the `:htmlstylesheet` parameter of `HtmlConvert.new()`), and some brief script calls that are embedded in the Ruby code (initialising jQuery, including webfonts).
-
-The `body` of the HTML document is divided into the following parts:
-
-* A title section (`<div class="title-section">`), comprising identifying information about the document, such as appears in a title page in print. 
-** The section is populated with an HTML template (the `:htmlcoverpage` parameter of `HtmlConvert.new()`). The information in this section is sourced from document metadata, rather than document content proper; the gem uses http://liquidmarkup.org[Liquid Template] to populate the HTML template. Different fields usually have distinct class names for CSS styling; these can vary by gem. 
-** For example, ISO documents have `coverpage_docnumber` (for the document ID), `coverpage_techcommittee` (for the technical committee responsible for the document), `doctitle-en` (for the English-language title of the document), `doctitle-fr` (for the French title), `title, subtitle, part` (for the three components of the document title), and `coverpage_docstage` (for the stage of publication of the document).
-* A prefatory section (`<div class="prefatory-section">`), comprising boilerplate information which also does not come from document content proper. This is typically restricted to a copyright statement (`<div class="copyright">`), contact details, and a table of contents `<div id="toc">`. 
-** The section is also populated with a Liquid HTML template (the `:htmlintropage` parameter of `HtmlConvert.new()`). 
-** The table of contents in the HTML template is a placeholder; it is populated by a table of contents script included among the scripts loaded into the HTML body.
-* The main section of the document (`<main class="main-section">`), which is populated with the document content.
-* Optionally, a colophon (`<div class="colophon">`), which is populated with boilerplate information and/or document metadata. (Currently colophons in Metanorma gems appear only in Word output.)
-* Scripts. These are populated from a static file (the `:scripts` parameter of `HtmlConvert.new()`). These are expected to include https://www.mathjax.org[MathJax], a Table of Contents generator, and a script for handling footnotes.
-
-=== Body markup
-
-Within the body of the document, different blocks and inline spans of the Metanorma document model (https://github.com/metanorma/metanorma-model-standoc[Standoc XML], https://github.com/metanorma/basicdoc-models[BasicDoc XML]) are represented by different CSS classes, as follows:
-
-==== Sections
-
-Symbols and abbreviated terms:: `<div class="Symbols">` (contents are a definition list)
-Appendix title:: `<h1 class="Annex">`
-Appendix, Bibliography, Introduction:: `<div class="Section3">`
-Introduction title:: `<h1 class="IntroTitle">`
-Foreword title:: `<h1 class="ForewordTitle">`
-Deprecated term:: `<p class="DeprecatedTerms">`
-Alternative term:: `<p class="AltTerms">`
-Primary term:: `<p class="Terms">`
-Term header:: `<p class="TermNum">`
-Document title (in body):: `<p class="zzSTDTitle1">`
-
-==== Blocks
-
-Note:: `<div class="Note">`
-Note label:: `<span class="note_label">`
-Figure:: `<div class="figure">`
-Figure title:: `<span class="FigureTitle">`
-Example:: `<table class="example">` or `<div class="example">`
-Example label:: `<span class="example_label">`
-Sourcecode:: `<p class="Sourcecode">`
-Admonition:: `<div class="Admonition">`
-Formula:: `<div class="formula">`
-Blockquote:: `<div class="Quote">`
-Blockquote attribution:: `<p class="QuoteAttribution">`
-Footnote:: `<aside class="footnote">`
-Ordered list:: `<ol>`
-Unordered list:: `<ul>`
-Definition list:: `<dl>`
-Normative reference:: `<p class="NormRef">`
-Informative reference:: `<p class="Biblio">`
-Table:: `<table>`
-Table title:: `<p class="TableTitle">`
-Table head:: `<thead>`
-Table body:: `<tbody>`
-Table foot:: `<tfoot>`
-
-==== Inline
-
-Hyperlink:: `<a>`
-Cross-Reference:: `<a>`
-Stem expression:: `<span class="stem">`
-Small caps:: `<span style="font-variant:small-caps;">`
-Emphasis:: `<i>`
-Strong:: `<b>`
-Superscript:: `<sup>`
-Subscript:: `<sub>`
-Monospace:: `<tt>`
-Strikethrough:: `<s>`
-Line Break:: `<br>`
-Horizontal Rule:: `<hr>`
-Page Break:: `<br>` (realised as page break in Word HTML)
-
-
-== Word HTML
-
-=== Word HTML and Word HTML CSS
-
-The Word HTML documented here is what is used by the gems to generate DOC output. For more on why Word HTML is used, instead of OOXML or HTML 5 embedded into DOCX, see https://github.com/metanorma/html2doc/wiki/Why-not-docx%3F
-
-Word HTML, and the Word HTML version of CSS, are restricted compared to the HTML and CSS you are likely familiar with. Word HTML is a subset of HTML 4; Word HTML CSS has a weakened set of selectors, and a range of Microsoft-specific extensions (prefixed with `@` or `mso-`). The weakened set of selectors means you cannot assume that classes are inherited by their children; normal CSS would apply formatting on a `div` class to its child paragraphs, but Word HTML would expect you to repeat that class definition for `p`.
-
-Some of the necessary caveats are listed in https://github.com/metanorma/html2doc/blob/master/README.adoc. The styling of lists in particular is quite different to normal CSS, and requires a Word-specific selector to define list styles (the `:ulstyle ` and `:olstyle ` parameter of `WordConvert.new()`).
-
-Word HTML and CSS is not well-documented (even though there is a 1500 page manual from Microsoft); fortunately saving Word documents to HTML will reveal the Word HTML and Word HTML CSS that can be used to generate the same formatting. The stylesheets need to follow the conventions of Word HTML, and should be formulated by saving Word documents as HTML, and extracting their CSS stylesheets. Note that the CSS is prefixed with a set of font definitions; these too should be obtained by saving Word documents as HTML.
-
-=== Top-Level Structure
-
-The headers and footers of a Word document are defined in Word HTML in a separate file, `header.html` (the `:header` parameter of `WordConvert.new()`), which is included in the file manifest for the document. The header.html file is cross-referenced to the Word HTML CSS file, and contains a separate `div` for each header and footer type; refer to the instances in the gems for illustration.
-
-The `head` of the Word HTML document contains two stylesheets (the `:wordstylesheet` and `:standardsheet` parameter of `WordConvert.new()`). The `:wordstylesheet` is intended as generic Word markup, while `:standardsheet` is intended to contain styling specific to the standard. No scripts are supported in Word HTML. 
-
-The other elements of the Word HTML head are populated by the https://github.com/metanorma/html2doc[html2doc gem]: a reference to a manifest of included files (specifically images and the header file), and settings to open the document in Print View at 100% magnification.
-
-The `body` of the Word HTML document is divided into the following parts:
-
-* A title section (`<div class="WordSection1">`), comprising identifying information about the document, such as appears in a title page in print. 
-** The section is populated with an HTML template (the `:wordcoverpage` parameter of `WordConvert.new()`). As with HTML, the information in this section is sourced from document metadata, rather than document content proper; and the gem uses http://liquidmarkup.org[Liquid Template] to populate the HTML template. 
-* A prefatory section (`<div class="WordSection2">`), comprising boilerplate information which does not come from document content proper (such as a Table of Contents shell), as well as prefatory material from the document content. The prefatory section is set in the CSS stylesheet to have Roman numerals for its pagination.
-** Because of the requirement for Roman numerals, prefatory material from the document is sent to this section, whereas all document content in the HTML document is sent to the main section.
-* The main section of the document (`<div class="WordSection3">`), which is populated with the remaining document content. The main section is set in the CSS stylesheet to have Arabic numerals for its pagination.
-* Optionally, a colophon (`<div class="colophon">`), which is populated with boilerplate information and/or document metadata. 
-
-=== Body markup
-
-With the exception of the top-level document sections, discussed above, the Word HTML generated by the gem use the same CSS classes as the HTML proper. As already noted, the quirks of Word HTML CSS mean that classes need to be repeated on descendant elements that are not required in normal CSS.
-
-The handling of footnotes and comments in Word HTML uses idiosyncratic Word HTML markup, including custom CSS, and is generated separately their the HTML counterparts in the gems.