= 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. == Usage See the README on https://github.com/riboseinc/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/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. 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/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 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 `<>` 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] -- <> NOTE: This table is based on <>. Sampling shall be carried out in accordance with <> -- Any text after the bibliographic localities is still treated as custom cross-reference text; e.g. `<>`. 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 `<>`, 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: `<````>` will be rendered as _ISO 24333, Clause 5_, but `<````>` 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] <>, 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]. Formally, IEV references should be cited as `IEC 60050-nnn:2011`, where `n` is the top-level clause; 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:2001 references. [source,asciidoc] -- [.source] <> ... [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 `<>` 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. -- As defined above, all terminal subclauses of a term section are treated as term definitions. Exceptionally, an introductory section can be treated as a subclause instead of a term, by prefixing it with the style attribute `[.nonterm]`: [source,asciidoctor] -- == Terms and definitions [.nonterm] === Introduction The following terms have non-normative effect, and should be ignored by the ametrical. === Anapaest metrical foot consisting of a short, a long, and a short -- === Symbols and Abbreviations Symbols and Abbreviations sections are expected to be simple definition lists (http://asciidoctor.org/docs/user-manual/#labeled-list["labelled lists"] in 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/riboseinc/metanorma-iso#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. * List items can contain other blocks in Asciidoctor, through concatenating blocks; e.g. + [source.asciidoc] -- * List + |=== | Contains | A table |=== -- + However, downstream renderers may not be able to cope with embedding blocks within list items. In particular, Word will force a carriage return between a list item, and a list or table contained in the item. So output like the following, with the list number flush with the embedded block, is not possible in Word (though it is in HTML): .... a) 1. Text b) |-------|------ | | table | table | |---------------| c) Definition Term Definition Definition Term Definition ....