Metanorma: Aequitate Verum

Writing in AsciiDoc, Part 3

Author’s picture Nick Nicholas on 16 Dec 2018

Marking up sections

We have already seen headings used inside a document to mark up sections. Standards documents have an expected structure of sections, and these need to be marked up rigorously in order for a document to comply. This means that you will need to go back over the headings you have marked up, and add further information to make them the right kind of section; either by adding style attributes, or by ensuring the heading wording complies with what is expected.

  • The Foreword of a document is taken to be all text between the document header and the first heading of the document. You can optionally use a caption like .Foreword instead of a heading, but the title to the foreword will be given automatically anyway.

[[foreword]]
.Foreword
ISO (the International Organization for Standardization)...

  • The Abstract of a document is any section with the style attribute of [abstract], regardless of what its actual title is. The abstract may not be rendered in some flavors of Metanorma (like ISO), although it will still be added to document metadata in the XML file (the bibdata element). In flavors where it is rendered, it may appear on the title page (e.g. UN documents), or before the Foreword.

[abstract]
== Summary

ISO (the International Organization for Standardization)...

  • The Introduction of a document is any section with the heading Introduction, or (as more advanced markup) with an attribute heading=introduction. (The heading= attribute can be used for all sections whose headings are meant to give their particular type.)

[heading=introduction]
== Enkonduko

ISO (la Internacia Organizafo por Normigo)...

  • The abstract, foreword and introduction together count as the preliminary material in a Metanorma document: they appear before the main text of the document, and in Word they are paginated with Roman rather than Arabic numerals.

  • Bibliographies, as we have seen, must have the [bibliography] style attribute. A document may have more than one bibliography, with different titles; ISO for example expects to see Normative References as the second clause of the document body, and Bibliography as the final clause.

  • Terms and Definitions and Symbols and Abbreviations are indicated by using that text in the heading, or in the heading= attribute. (The two sections can be merged together, as Terms, Definitions, Symbols and Abbreviations; in that case Symbols and Abbreviations is expected to be a distinct sub-clause.) Both these section types have particular markup requirements: the contents of Symbols and Abbreviations are one long definition list (which we’ll come to), while Terms and Definitions treats each term as a separate sub-clause, with its internal structure rigorously formatted.

Marking uo blocks

You have gone over all the sections in the document, refined their markup, and tested with Metanorma rendering to make sure that the sections, at least, make sense. The next step is to go back over and mark up all blocks.

The following are the types of block supported in Metanorma:

  • Unordered lists, which are bulleted, and can be nested. (The style of bullet varies by flavor.)

The main changes compared to the previous edition are:

* updated normative references;
* deletions:
** deletion of 4.3. [nested list item]
** deletion of 4.4. [nested list item]

  • Ordered lists, which can be nested. The label of each list item is normally set by the Metanorma flavor; this is so that ordered list items can be referenced consistently.

. 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; [nested list item]

  • Definition lists.

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.

  • Tables.

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

  • Images.

[[figureC-1]]
.Typical gelatinization curve
image::images/rice_image2.png[]

  • Admonitions (including Notes, and Warnings/Cautions).

CAUTION: Only use paddy or parboiled rice for the determination of husked rice yield.

  • Block quotes.

[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).
_____

  • Examples.

[example]
Foreign seeds, husks, bran, sand, dust.

  • Source code.

.Sample Code
====

[source,ruby]
--
puts "Hello, world."
%w{a b c}.each do |x| (1)
  puts x
end
--
<1> This is an annotation
====

  • Formulae (discussed below)

  • Comments (which are not rendered in output).

// all terms and defs references are dated

Go back over the document and insert markup for each block that isn’t a simple paragraph. The details of how each different block type works in Metanorma AsciiDoc are given in the Asciidoctor user manual (as we do not tire from telling), and any Metanorma extensions and adjustments are documented in the Metanorma documentation:

Marking up inline

The final stage of refining AsciiDoc markup is to focus on inline markup, within the bounds of the block. We have already seen formatting marks such as bold, italics, and monospace.

We have also seen the use of anchors, as an entity to be cross-referenced ([[anchor]], on its own line), and of internal cross-references, which reference an anchor (<<anchor>>); the text of both is generated automatically, and is auto-numbered. Anything that can be considered a cross-reference should be, so that the numbering of those references can be handled automatically; you will need to sweep through the document, to identify all such instances.

URLs are handled by a macro, consisting of a recognizable URL, followed optionally (without space) by square brackets containing the text to be hyperlinked; e.g.:

http://www.iso.org/[International Organization for Standardization].

Footnotes are also a macro, consisting of the text footnote:[], with the text of the footnote contained within the brackets. Metanorma AsciiDoc does not permit footnotes spanning more than one paragraph, so the contents of the footnote are expected to be a single line contained within the brackets. The footnote macro is also expected to be preceded by punctuation, although it is recognized as is, and can also be delimited by a preceding {blank} (which in Asciidoctor AsciiDoc is simply empty text; blank headers are also indicated by equals signs followed by {blank}).

Mathematical formatting, finally, is called STEM formatting in Metanorma AsciiDoc, and are entered using AsciiMath. Mathematical formatting can be either a block (which constitutes a formula for standards documents), or inline:

[[formulaA-1,A.1]]
[stem]
++++
w = (m_D) / (m_s)  (block)
++++

stem:[w = (m_D) / (m_s)] (inline)

In either case, the document attribute :stem: must be present in the document header, for such AsciiMath expressions to be recognized at all. The input AsciiMath will be converted to MathML and Open Office XML (for Word) downstream.

That is enough to get you started with marking up Metanorma AsciiDoc. You’re best placed to build up from simple structures to more complex, reading the available documentation, and looking at other existing samples of Metanorma; all Metanorma gems include sample documents, as well as snippets of Metanorma AsciiDoc used in internal tests (under the spec/asciidoctor directory of each gem.)

And if you get stuck, you can also ask your friendly neighborhood wizard, care of info@ribose.com, or by raising an issue on GitHub on the repository of your Metanorma flavor’s gem.

The author
Figure 1. The author, trying to pass as a friendly neighborhood wizard