= 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/metanorma/metanorma-iso/blob/master/README.adoc[Asciidoctor-ISO Readme] and the https://github.com/metanorma/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/metanorma/metanorma-standoc#document-attributes[metanorma-standoc Readme]; each standards-specific gem adds documentation of its own specific attributes (e.g. https://github.com/metanorma/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,asciidoc]
--
= 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,asciidoc]
--
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,asciidoc]
--
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,asciidoc]
--
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,asciidoc]
--
[[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,asciidoc]
--
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,asciidoc]
--
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,asciidoc]
--
. 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,asciidoc]
--
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,asciidoc]
--
[[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,asciidoc]
--
[[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,asciidoc]
--
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,asciidoc]
--
[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,asciidoc]
----
.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,asciidoc]
--
[[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,asciidoc]
--
== 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: `[abstract]` for Abstracts, `[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,asciidoc]
--
[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; this also applies to Abstracts) need to be titled as such, as first-level headings.

TIP: Abstracts are not rendered in ISO and GB standards, but they are still incorporated into the document metadata (`bibdata`) at the start of the Metanorma XML generated.

=== 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,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
--

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,asciidoc]
--
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,asciidoc]
--
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,asciidoc]
--
<<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.