Strikethrough and small caps
The following formatting macros are used for strikethrough and small caps text:
[strike]#strike through text# [smallcap]#small caps text#
Paragraph alignment is defined as an attribute for paragraphs:
[align=left] This paragraph is aligned left [align=right] This paragraph is aligned right [align=center] This paragraph is aligned center [align=justified] This paragraph is justified, which is the default
If you have line-breaks in a paragraph, and the default alignment in the stylesheet
is justified (as is often the case in Word output), you will need to set
to make the paragraph look as normally expected:
[align=left] Vache Equipment + Fictitious + World + firstname.lastname@example.org
As in normal AsciiDoc, block quotes are preceded with an author and a citation; but the citation is expected to be in the same format as all other citations, a cross-reference optionally followed by text, which may include the bibliographic sections referenced:
[quote, ISO, "ISO7301,section 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). _____
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.
Table and figure footnotes are treated differently from all other footnotes: they are rendered at the bottom of the table or figure, and they are numbered separately.
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).
Metanorma AsciiDoc ignores the
List items with more than one paragraph
Metanorma XML and HTML support multiple paragraphs within a single list item (see list continuation).
|In HTML output, all the paragraphs within a list item will be aligned.|
MS Word caveats
Metanorma AsciiDoc tables are required to handle the full range of complexity of standardization documents, and is therefore significantly more powerful than typical AsciiDoc tables, even when typical AsciiDoc already handles tables very well for a non-XML markup language.
Metanorma AsciiDoc adds the option of multiple header rows
headerrows to deal with the complexity
of standardization documents' tables
requiring labels, variables, and units to lining up in the header.
Tables can also have alternate text as a title,
alt, and summary text,
summary, both of which are to be rendered as a summary of the table
[headerrows=2,alt=Table of maximum mass fraction of defects in husked rice,summary=Table enumerating the permissible mass fraction of defects in husked and various classes of milled rice] |=== .2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice + stem:[w_max] | in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice | Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5 |===
Typical AsciiDoc allows table cells to have footnotes (which Metanorma renders inside the table) and notes following the table (which Metanorma moves inside the table footer).
Table 1 in the AsciiISO Rice example document illustrates a large range of table formatting options.
Metanorma AsciiDoc accepts mathematical input in either LaTeX math or AsciiMath, with the following conventions:
The document attribute
:stem:means any markup tagged as
[stem]before a block delimited with
) is interpreted as AsciiMath.
The document attribute
:stem: latexmathmeans any markup tagged as
[stem]before a block delimited with
) is interpreted as LaTeX.
Any markup tagged as
[asciimath]before a block delimited with
) is interpreted as AsciiMath.
Any markup tagged as
[latexmath]before a block delimited with
) is interpreted as LaTeX.
Any Unicode characters in the LaTeX source are translated into LaTeX escapes, through the unicode2latex gem.
In addition, stem markup that contains MathML markup (as detected by an initial
<math … >) is interpreted as MathML.
MathML is used as the internal representation of STEM expressions in Metanorma: AsciiMath and LaTeX math in Metanorma AsciiDoc are converted into MathML, using the asciimath gem and the LaTeXML processor of LaTeXML, respectively.
The syntax of AsciiMath recognised by the
Formulae are marked up as
Any explanation of symbols in the formula is given as a “where” paragraph,
followed by a definition list.
[[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.
Inequalities are indicated through the option attribute
[stem%inequality] ++++ A < B ++++
In most flavours, equations and inequalities are both referenced in the same way, as “Formula”.
In some flavours (e.g. ITU), they are referenced differently as “Equations” and “Inequalities”.
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:
[[figureC-1]] .Typical gelatinization curve image::rice_images/rice_image2.png[alt text] 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.
As an extension to AsciiDoc syntax, Metanorma allows Data URLs as the URL for an image:
Subfigures (which appear in ISO formats, for example) are entered by including images in AsciiDoc examples.
[[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 ====
auto is accepted for image width and height attributes. It is only passed on
to HTML output; if the output is to Word, both the width and height attributes are stripped
from the image.
Captions and titles
As elsewhere in Metanorma, the caption of an image (of the figure containing the image) is set with a line prefixed with dot above the image.
Similar to Asciidoctor AsciiDoc, the
Metanorma supports a
title attribute on images for accessibility, which is
distinct from the figure caption.
This is entered in Metanorma as the
[titleattr=Title Attribute] image::logo.jpg
Both captions and titles could be used together.
.Rice husk separation in rice farm at Breton near Dinan image::logo.jpg[titleattr=Photo of rice husks being separated]
Source code is marked up as elsewhere in AsciiDoc, as a preformatted source snippet to be rendered in monospace font, and with spaces preserved:
[source,ruby] ---- def increment(x) x + 1 end ----
Source code highlighting can be used automatically to highlight keywords specific to the nominated computer language.
Pseudocode is a mix between formal math with code like properties commonly used in computer science and related fields.
Unlike source code, pseudocode is typically in a proportional font, but it still needs to be indented to reflect code structure. Moreover, pseudocode typically requires source code highlighting such as boldface; but unlike well-defined computer languages, there is no guaranteed way of automating such highlighting.
Pseudocode is supported in Metanorma as a special class of example, marked up with a pseudocode block macro with these differences:
text within a pseudocode block is treated as normal text, including respect for inline formatting;
lines need to separated by line breaks (
indentation spaces at the start of each line are preserved, by converting them into non-breaking spaces; initial tabs are converted into four non-breaking spaces.
[pseudocode] ==== *do in-parallel* + [smallcap]#SharedAccess# + *enddo* [smallcap]#ExclusiveAccess# stem:[-=] + *if* _ag.mode_ = _exclusive_ stem:[^^ AA t in] [smallcap]#Token# : _t.available_ *then* + *do forall* _t_ : stem:[in] [smallcap]#_Token_# + _t.owner_ := _ag_ + *enddo* + *endif* ====
Filenames for extraction
Images, source code, and requirements can all be extracted out of the
generated Metanorma XML downstream, by the
metanorma -e command.
By default, the filename for each extracted snippet is automatically generated. (Extraction only applies to data-uri encoded images, which no longer preserve their filename.)
filename on images, source code, and requirements
gives the filename that any inline-encoded
images, source code, and requirements should be
exported to, if that is requested by downstream tools.
In this instance, the image is read in from logo.gif, but is converted in the
XML output to a data-uri encoding. The encoding will have the filename attribute
of "image1.gif"; that instructs any downstream processing that extracts images
out of the file (such as
metanorma -e) to extract this image to the file image1.gif,
instead of using an automatically generated filename.
All figures, tables, examples, formulas, permissions, recommendations and requirements ("assets") are autonumbered by Metanorma, so users do not need to specify any numbering in their source documents. The conventions for numbering vary by Metanorma flavour, but the default is to number all assets consecutively in the main body of a document, and separately in each Annex/Appendix, prefixed bt the Annex/Appendix number.
Autonumbering numbers assets consecutively. Some times, more than one level of numbering
is required for a sequence of assets; e.g. 17a, 17b. To indicate that, all assets
in the subsequence are assigned the same
[stem,subsequence=A] ++++ A ++++ [stem,subsequence=A] ++++ B ++++ [stem,subsequence=A] ++++ C ++++ [stem,subsequence=A] ++++ D ++++ [stem] ++++ E ++++
Rarely, an asset needs to be excluded from autonumbering. This is indicated by giving
it the option attribute
[[figureC-1]] [%unnumbered] .Typical gelatinization curve image::rice_images/rice_image2.png
Cross-references are realised in Metanorma AsciiDoc by assigning an anchor to the block to be referenced, and writing a cross-reference containing that anchor ID:
[[anchor-id]] == Target clause The requirements are... == Reference clause As seen in <<anchor-id>>...
The anchor ID must follow the NCName constraints of xml:id:
it must start with with a letter, an underscore, or a colon.
The guidance given in ISO/IEC DIR 2 for internal cross-references guarantees unambiguous referencing and is followed rigorously by Metanorma.
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.
For example, in the AsciiISO Rice model sample document formula B.1 is defined in Annex B.6, and is referenced in B.6 and B.7.
In the Rice model document published by ISO, both instances are cited as "Formula (B.1)". However, Metanorma follows ISO/IEC DIR 2 in citing the former as "Formula (B.1)", but the latter as "B.6, Formula (B.1)".
In this sense, Metanorma is "more royalist than the king" in applying formatting rules and validation—which is what you would want of a computer-based tool.
The label of the item cross-referenced, the use of brackets, and the containing reference
are all taken care of by Metanorma; the document author needs only give the item identifier
in the AsciiDoc source
<< generates either “Formula (B.1)” or “B.6, Formula (B.1)”,
depending on where in the document it occurs.)
Normally in AsciiDoc, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference.
So a cross-reference
the foregoing reference
would be rendered as "the foregoing reference", and hyperlinked to the ISO7301 reference.
In Metanorma AsciiDoc 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 AsciiDoc treatment of custom text.
List items can be cross-referenced by inserting a bookmark at the very start of the list item:
. Ordered list .. [[id]] This is the first list item ... [[id]] This is a list sub-item
Hyperlinks to URIs can have alt text, which is used in accessibility (corresponding to the HTML
a@title attribute). This is specified by appending ",title=…" after the text in the
URL macro in AsciiDoc:
http://www.example.com[text to go into the hyperlink] http://www.example2.com[text to go into the second hyperlink,title=This is a tooltip for the link]
Cross-references to external documents
Metanorma will process cross-references to anchors within external documents just like AsciiDoc would normally. For example,
will be processed as a link to anchor
#b in document
If the reference uses the
.adoc suffix, as in the example above, it is stripped in Metanorma XML
and substituted with the extension of the current document type during document generation.
The above example is rendered in Metanorma XML as
in HTML as
<a href="document1.html#b">, and in PDF as