Text formatting
Inline formatting
The following formatting macros are available in Metanorma.
Strikethrough
[strike]#strike through text#
which renders:

Small caps
[smallcap]#small caps text#
which renders:

Underline
The underline macro: [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.2]:
[underline]#underline text#
which renders:

Identifier
The identifier`
command, used to indicate that its contents are an identifier as
semantic markup (and not to be processed as a
hyperlink) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].
This functionality is very useful for encoding URIs, which can be virtually indistinguishable from URLs that can be resolved. URIs very often cannot be resolved since they are simply namespaced identifiers.
identifier:[http://www.example.com]
renders:
http://www.example.com
identifier
commandidentifier:[https://schemas.isotc211.org/19115/-1/mdb/1.3]
renders:
`https://schemas.isotc211.org/19115/-1/mdb/1.3
Nesting of styles
Character styles can be nested within each other, with both constrained and unconstrained formatting marks.
`*Boldmono__space__*`
Note
|
See Asciidoctor Text. |
Character substitutions
Metanorma AsciiDoc supports Asciidoctor-style character substitutions:
Source | Rendered as | Note |
---|---|---|
(C) |
© (Unicode 'Copyright Sign' |
|
(R) |
® (Unicode 'Registered Sign' |
|
(TM) |
™ (Unicode 'Trade Mark Sign' |
|
|
— (Unicode 'Em Dash' |
See NOTE below. |
... |
|
|
-> |
→ (Unicode 'Rightwards Arrow' |
|
=> |
⇒ (Unicode 'Rightwards Double Arrow' |
|
<- |
← (Unicode 'Leftwards Arrow' |
|
<= |
⇐ (Unicode 'Leftwards Double Arrow' |
|
|
Smart single quote, smart apostrophe |
|
|
Smart double quote |
Note
|
Replacement of - only occurs when placed between two word
characters, between a word character and a line boundary, or flanked
by spaces. Flanking spaces (as in x — y ) are rendered as thin
spaces (Unicode 'Thin Space' U+2009 ).
|
Metanorma AsciiDoc also recognises HTML and XML character references, and decimal and hexadecimal Unicode code points.
Links
Links to other Metanorma documents are expected to change their suffix depending on their target output format, (such as HTML, PDF, or DOC).
To make this happen, you can add the option update-type=true
to any links you
create to Metanorma
documents [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4],
so long as the link is relative and not absolute, and it does not have a file
suffix.
EXAMPLE:
link:../parent[update-type=true]
link:../child[This Is The Child Document,update-type=true]
This will link to ../parent.html
and ../child.html
in HTML, and to
../parent.pdf
and ../child.pdf
in PDF.
Corrigenda
Text to be marked as added or deleted in corrigenda is indicated through the
commands add:[…]
and del:[…]
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.0]:
del:[The use of echo cancellers on the VBD channel, as per Rec. ITU-T G.168.]
... or other forms of redundancy add:[(e.g. per <<rfc2198>>)]
Paragraph alignment
Paragraph alignment is defined as an attribute for paragraphs:
[align=left]
This paragraph is aligned left
[align=center]
This paragraph is aligned center
[align=right]
This paragraph is aligned right
[align=justified]
This paragraph is justified, which is the default
which renders

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 [align=left]
to make the paragraph look as normally expected:
[align=left]
Vache Equipment +
Fictitious +
World +
mailto:gehf@vacheequipment.fic[]
which renders

Page breaks
Page breaks can be given a page orientation, which applies from that point forward until the next page break with a page orientation [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.17].
Page orientation only appears in paged output, such as in Word.
To set content to landscape mode, the syntax is:
[%landscape]
<<<
To set content to portrait mode, the syntax is:
[%portrait]
<<<
If no orientation option is given, the text after the page break remains in the same orientation as that before. In Word, page breaks changing orientation are realised as distinct sections.
In Metanorma, documents are split into three sections by default:
-
a cover page,
-
a preface, and
-
the main document body (including annexes and bibliography)
-
(some documents also have a colophon)
The page orientation is reset at the start of the main document body to portrait
.
EXAMPLE:
// Content following this directive will be shown in landscape mode
[%landscape]
<<<
...
// Content following this directive will return to portrait mode
[%portrait]
<<<
...
Avoiding page breaks
The “keep with next” feature is useful if you want to indicate that a document element must belong on the same page with another element. Kind of like the opposite of a “page break”.
Most blocks support the boolean attributes keep-with-next
and
keep-lines-together
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].
The following syntax indicates that these two paragraphs will always be presented on the same page, even if the textual layout allows them to be split into two pages.
[keep-with-next=true]
This is a paragraph.
This is a paragraph that will be on the same page as the
immediately previous one.
Block quotes
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).
_____
renders as

Notes
Folding 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 list, formula, figure, or table.
Prevent notes from folding
To prevent a note from folding into the preceding block, add the attribute
keep-separate
to the
note [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.29].
Note
|
Extended to apply to tables [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]. |
* A
* B
* C
[NOTE,keep-separate=true]
====
Note not folded into its preceding block
====
Without the keep-separate=true
markup, the note would be attached to the list,
and numbered accordingly.
[NOTE]
This note will be folded in the preceding block.
NOTE: This one too.
Notes may be given a type through the attribute
type
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].
[NOTE,type=bibliographic]
====
Bibliographic note
====
Explicitly-defined terminology entry notes
Normally, notes are only tagged as term notes when they appear in the context of a terms section.
Rarely, term notes need to be presented in isolation, including in ISO Amendments or Technical Corrigenda.
To achieve that, mark the note up with
%termnote
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].
[NOTE%termnote]
====
Bibliographic note
====
Examples
Explicitly-defined terminology examples
Normally, examples are only tagged as term examples when they appear in the context of a terms section.
Rarely, term notes need to be presented in isolation, including in ISO Amendments or Technical Corrigenda.
To achieve that, mark the example up with %termexample
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2].
[%termexample]
====
Bibliographic note
====
Admonitions
General
Admonitions (“NOTE”, “IMPORTANT”, “WARNING”, “CAUTION” etc.) are typically inserted into the main content of a document providing guidance or request readers to exercise caution.
== General requirements
[NOTE]
====
This is just a note providing guidance.
====
[IMPORTANT]
====
This is an important message.
====
== Safety requirements
[WARNING]
====
This important notice applies to safety concerns.
====
[CAUTION]
====
This notice must not be ignored.
====
Whole document admonitions
Admonitions (“NOTE”, “IMPORTANT”, “WARNING”, “CAUTION” etc.) in the document body (i.e. within a main body clause) can be stated to apply to the entire document by moving them to the start of the document body, before the main sequence of clauses.
This can be done by giving them the attribute
beforeclauses=true
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.30].
== Scope
[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====
My scope text...
Preface admonitions
Admonitions in the document prefaces (including in the Foreword) can be stated
to apply to the entire preface by moving them to the start of the preface,
before the Foreword. This can be done by giving them the same attribute
beforeclauses=true
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.2].
= Document title
:document-attribute: XXXX
[IMPORTANT,beforeclauses=true]
====
This important notice applies to the entire document.
====
== Foreword
My foreword text...
Cover page admonitions
An admonition in the document prefaces can instead be flagged to be rendered on
the cover page of the document, through
coverpage=true
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.8].
= Document title
:document-attribute: XXXX
[IMPORTANT,coverpage=true]
====
This important notice appears on the cover page.
====
== Foreword
My foreword text...
Normally, the label of the type of admonition (NOTE, IMPORTANT, etc) is inserted at the start of the admonition in rendering. This may not be desirable, especially for coverpage admonitions.
Inserting the admonition type is suppressed through
notag=true
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.8].
= Document title
:document-attribute: XXXX
[IMPORTANT,coverpage=true,notag=true]
====
This important notice appears on the cover page.
====
== Foreword
My foreword text...
Footnotes
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.
When the text of a footnote is repeated in two different places, default behaviour in Metanorma, both for HTML and for DOC, is to use the same footnote number in both places, rather than treat the repetition as a new footnote.
Footnotes on document titles are
recognised [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1],
but by default they are not rendered, because of how document title pages are processed separately
in Metanorma via Liquid templates. Document title footnotes are moved into
/bibdata/note[@type = "title-footnote"]
, and are treated as document metadata, as are document
titles themselves. The location of the footnote within the title is not preserved.
Multi-paragraph footnotes can be entered using the macro footnoteblock:[id]
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.4],
where id
is the identifier of a note containing the contents of the footnote:
This is a paragraph.footnoteblock:[id] This continues the paragraph.
[[id]]
[NOTE]
--
This is
a multi-paragraph
footnote
--
Note
|
Multi-paragraph footnotes are a Metanorma AsciiDoc feature and not supported in typical AsciiDoc. |
Lists
Ordered lists
Ordered list labels conform to rules specified in ISO/IEC DIR 2 throughout Metanorma:
-
level 1: a), b), c) (called
alphabetic
), -
level 2: 1), 2), 3) (called
arabic
), -
level 3: i), ii), iii) (called
roman
), -
level 4: A), B), C) (called
alphabetic_upper
), -
level 5: I), II), III) (called
roman_upper
).
Note
|
This labeling applies to all output formats, including PDF, HTML and Word. |
In certain flavours (NIST, ITU, OGC), class=steps
is used to override this
numbering, and use Arabic numbering as the base instead:
-
level 1: 1), 2), 3)
-
level 2: a), b), c)
-
level 3: i), ii), iii)
-
level 4: A), B), C)
-
level 5: I), II), III)
The start
attribute for ordered lists is only allowed by certain Metanorma
flavors, such as BIPM and ISO. This is because of the difficulty of realising
the list numbering starting other than at 1 in autonumbered lists in Word HTML.
Note
|
This note applies to The In Word rendering the As of v2.0.3, the ability to specify the |
List items with more than one paragraph
Metanorma XML and HTML support multiple paragraphs within a single list item (see list continuation).
Note
|
In HTML output, all the paragraphs within a list item will be aligned. |
Note
|
Microsoft Word caveats
|
Definition lists
Definition lists are rendered by default horizontally, with the definition
in the same line as the term. In Word, definition lists are rendered as true
tables, and the width of the term column is determined by the Word auto-width
algorithm; if you need to ensure that terms are rendered in a single line in Word,
you may need to use non-breaking spaces and non-breaking hyphens
(which can be entered in AsciiDoc as HTML escapes:
or  
, and ‑
,
respectively; e.g. This is a non‑breaking term
instead of This is a non-breaking term
.)
Tables
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 already supports cells spanning multiple rows and columns, horizontal alignment, and [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3] vertical alignment.
Metanorma AsciiDoc adds the option of multiple header rows
via attribute 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
for accessibility.
Tables can be set with a width
attribute, which could be either a
percentage (e.g. 70%
) or a pixel count (e.g. 500px
). [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.21].
Note
|
The width attribute value aligns with HTML CSS and HTML 4 behavior.
|
[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,width=70%]
|===
.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
|===
which renders:

In Metanorma AsciiDoc:
-
table cell footnotes are rendered inside the table;
-
notes following the table are rendered inside the table footer.
Note
|
Typical AsciiDoc renders table cell footnotes inside the cell, and notes trailing the table outside the table. |
Tip
|
Table 1 in the Metanorma ISO Rice example document illustrates a large range of table formatting options. |
Table columns can also have their widths set [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3]. Table column widths must be enumerated explicitly per column to generate column widths.
EXAMPLE:
The following syntax will be processed as generating equal width columns.
[cols="1,1,1"]
Note
|
In typical AsciiDoc, [cols="3"] is considered a shorthand to
[cols="1,1,1"] , but this is not supported in Metanorma AsciiDoc.
|
Mathematical expressions
General
Metanorma AsciiDoc accepts mathematical input in these formats:
-
AsciiMath
-
LaTeX math
-
MathML
Math can be entered using one of the following mechanisms:
-
the
stem:[…]
,asciimath:[…]
and thelatexmath:[…]
commands; and -
the
[stem]
,[asciimath]
,[latexmath]
blocks delimited with++++
The math syntax used by stem:[…]
and [stem]
blocks depends on
the value of the document attribute :stem:
. It can be set to:
:stem: latexmath
-
any markup within
stem
is interpreted as LaTeX math :stem: asciimath
-
any markup within
stem
is interpreted as AsciiMath :stem:
-
(default) when left empty, AsciiMath is selected
stem:[…]
and [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.
Using AsciiMath
AsciiMath can be entered using the asciimath:[…]
command and the
[asciimath]
block delimited with ++++
.
The stem:[]
and [stem]
blocks can also be used if the document attribute
:stem: asciimath
has been specified in the document.
AsciiMath is converted into MathML using the asciimath gem.
The syntax of AsciiMath recognised by the asciimath
gem is more strict
than the common MathJax processor of AsciiMath.
For example, asciimath
insists on numerators being bracketed.
EXAMPLE:
(IEV 103-01-03)
The derivative of a distribution stem:[D] is another distribution
stem:[D'] defined for any function stem:[f](stem:[x]) by
stem:[D^( ' ) ( f ) = - D ( d f // d x )].
(ISO 10303-55, Clause 2)
[stem]
++++
f -= lambda x (a * x + b)
++++
Note
|
Some math expressions are NOT supported by AsciiMath — in that case it is necessary to use LaTeX math or MathML input. |
Using LaTeX math
LaTeX math can be entered using the latexmath:[…]
command and the
[latexmath]
block delimited with ++++
.
The stem:[]
and [stem]
blocks can also be used if the document attribute
:stem: latexmath
has been specified in the document.
LaTeX math is converted into MathML using the latexmath gem, which generates output compliant with the deterministic output of the NIST LaTeXML suite.
Note
|
LaTeX math parsing of the
LaTeXML’s latexmlmath command
is deterministically accurate.
The latexmath gem was created
to generate identical output to the latexmlmath command.
|
Unicode characters in the LaTeX source are translated into LaTeX escapes through the unicode2latex gem.
EXAMPLE:
(ISO 10303-110, Clause 4)
The only change from the above example would be the
nondimensionalization of viscosity, which would become,
latexmath:[\tilde{\tilde{\mu}} = mu / (rho_infty c_infty L)].
(ISO 10303-110, Clause 4)
[latexmath]
++++
\begin{array}{c@{\qquad}c@{\qquad}c}
\tilde{x} = x/L, \tilde{u} = u/c_\infty, \tilde{\rho} = \rho/\rho_\infty,
\tilde{y} = y/L, \tilde{v} = v/c_\infty, \tilde{p} = p/(\rho_\infty c_\infty^2),
\tilde{z} = z/L, \tilde{w} = w/c_\infty, \tilde{\mu} = \mu/\mu_\infty,
\end{array}
++++
The LaTeX math eqnarray
environment is not supported in Metanorma as
it is not supported by LaTeXML and the latexmath gem.
It is also not recommended by the general
LaTeX community due to inconsistencies in vertical alignment and other aspects
(see Madsen).
The proper LaTeX math syntax used to replace existing eqnarray
equations is to place the equations in separate blocks concatenated
with +
.
EXAMPLE:
These equations using the eqnarray
environment:
[latexmath]
++++
\begin{eqnarray*}
\bf{z^\prime} & = & \bf{\zeta} \\
\bf{x^\prime} & = & \langle \bf{\eta} \times \bf{\zeta} \rangle
\end{eqnarray*}
++++
should be re-arranged as:
[latexmath]
++++
\bf{z^\prime} = \bf{\zeta}
++++
+
[latexmath]
++++
\bf{x^\prime} = \langle \bf{\eta} \times \bf{\zeta} \rangle
++++
Formulae
Formulae are marked up as [stem]
blocks.
Any explanation of symbols in the formula is given in a definition list,
either preceded by a “where” paragraph (in English),
or [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3] marked up with [%key]
.
For example:
[[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.
[[formulaA-1]]
[stem]
++++
w = (m_D) / (m_s)
++++
[%key]
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.
which renders

Inequalities are indicated through the option attribute %inequality
:
[stem%inequality]
++++
A < B
++++
which renders

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”.
Figures
Like formulae, figures can be followed by a definition list for the variables used in the figure;
the definition list is either preceded by the paragraph *Key*
(in English),
or [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3] is marked up with [%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.
[[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:
image::data:image/png;base64,ivBO[alt text]
A discursive figure, containing text as well as images, can be marked up as an
example, with a [.figure]
role [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7]:
[[figureC-1]]
[.figure]
.Typical gelatinization curve
====
image::rice_images/rice_image2.png[alt text]
This is lots of discursive text
====
Subfigures
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[]
====
Image size
The size of an image can be modified via the height
and width
attributes.
By default, both height
and width
are set to the value auto
, which means
that the image will be shown according to the best visual settings determined
by Metanorma.
Image dimensions can also be fixed with pixel values with px
.
Note
|
The pixel is the only supported unit in image sizing right now. |
height
and width
attributes in pixels[height=150px,width=100px]
image::logo.jpg[]
In the height
and width
attributes, the px
suffix may be omitted.
px
unit[height=150,width=100]
image::logo.jpg[]
The auto
value indicates that the dimension does not have a fixed size but
retain the aspect ratio of the original image.
width
set to auto
based on the value of height
[height=150,width=auto]
image::logo.jpg[]
An unspecified dimension is considered auto
.
height
but not width
[height=150]
image::logo.jpg[]
Note
|
Treatment of image resizing may slightly differ across output formats. |
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.
.Caption
image::logo.jpg[]
image::logo.jpg[title=Caption]
Note
|
Similar to Asciidoctor AsciiDoc, the title attribute is treated as
identical to the dot-prefixed caption.
|
Metanorma supports a title
attribute on images for accessibility, which is
distinct from the figure caption.
This is entered in Metanorma as the titleattr
attribute:
[titleattr=Title Attribute]
image::logo.jpg
Or
image::logo.jpg[titleattr=Title Attribute]
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]
Note
|
The titleattr attribute does not get rendered in Word output due to Word
limitations. Word only supports a single image “Alt Text”, which would be set
by the caption.
Word’s description of “Alt Text” is:
“How would you describe this object and its context to someone who is blind?”.
|
Preformatted blocks
Figures can include preformatted blocks, as well as images.
For accessibility, preformatted blocks can be provided with an alt text attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].
___^_ / | \__/\ \ / ^ ^| / \_/ 0 0_ / \ / ___ 0 | / / \___ _/
Passthrough to Metanorma XML and target formats
Passthrough blocks
Passthrough text, such as XML tags, intended to be rendered in a target format unaltered, can be entered as a passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27].
This functionality enables automated processing, custom tagging, hacking into intermediary formats and experimental development of Metanorma output.
Warning
|
A broken Metanorma XML file will cause rendering of target formats to also break. Use with caution. |
Passthrough intended to be rendered in Metanorma XML (such as Metanorma XML tags), generated from Metanorma AsciiDoc input, can be entered as a passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], with no format indication.
EXAMPLE:
++++
<bibitem>
++++
Warning
|
Passthrough text may break the structure of the output format — it is the user’s responsibility to ensure the integrity of the resulting structure (e.g. XML) is retained. |
Passthrough intended to be rendered in a target format must be specified with
a format indication corresponding to one or more of the existing output formats
of Metanorma in a comma-delimited manner
(not limited to: html
, doc
, pdf
, rfc
, sts
).
EXAMPLE:
[format=rfc]
++++
<artset>
<artwork>
++++
Passthrough inline text
Metanorma AsciiDoc supports the following syntaxes for inline passthrough.
For passthrough of text that does not involve XML structural syntax:
-
...
-
...
-
...
EXAMPLE:
This is a special pass:[𝒞𝓪𝓼𝓮].
For passthrough of XML syntax or tags to Metanorma XML, which will require special character processing, use the following command:
-
...
EXAMPLE:
pass:c[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]
If the passthrough text is intended for one or more target formats, the formats needs to be specified with the following command:
-
pass-format:FORMAT[…]
, whereFORMAT
is a comma-delimited list of target formats [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7]
EXAMPLE:
pass-format:rfc[<u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>]
Source code
General
Source code is marked up as elsewhere in AsciiDoc, as a pre-formatted 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.
Markup in source code blocks
In a few cases, it is desirable to introduce markup into source code; for example, hyperlinking words in source code to external definitions, or else introducing formatting in lieu of automated highlighting.
In order to achieve this, Metanorma allows inline AsciiDoc markup to be introduced into source code, isolating it from the rest of the source code through delimiters. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4]
By default, the delimiters are {{{
and }}}
; these can be overridden (in case
{{{
and }}}
are already used in the document) through the document attributes
:sourcecode-markup-start:
and sourcecode-markup-end:
.
[source,ruby]
--
{{{*def*}}} method1(x)
{{{<<method2-definition,method2>>}}}(x) + 3
end
--
Pseudocode
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 do not need to be separated by line breaks, although two carriage returns in a row are still interpreted as a new paragraph. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10]
-
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.)
The attribute 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.
[filename="image1.gif"]
image::logo.gif
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.
Auto-numbering
General
The following document elements (“elements”) are auto-numbered by Metanorma, so users do not need to specify any numbering in their source documents:
-
figures
-
tables
-
examples
-
notes
-
formulas
-
sourcecode, pseudocode
-
permissions, recommendations and requirements.
The conventions for numbering vary by Metanorma flavour, but the default is to number all elements consecutively in the main body of a document, and separately in each Annex/Appendix, prefixed bt the Annex/Appendix number.
Multi-level numbering
Metanorma’s auto-numbering functionality assigns numbers to elements consecutively. Sometimes, more than one level of numbering is required for a sequence of elements; for instance, 17a, 17b.
To indicate that, all elements in the subsequence are assigned the same
subsequence
attribute:
[stem,subsequence=A]
++++
A
++++
[stem,subsequence=A]
++++
B
++++
[stem,subsequence=B]
++++
C
++++
[stem,subsequence=B]
++++
D
++++
[stem]
++++
E
++++
Gets rendered as:
A (1a)
B (1b)
C (2a)
D (2b)
E (3)
Unnumbered elements
Sometimes a document element needs to be excluded from auto-numbering.
This is achieved by giving it the option attribute %unnumbered
:
[[figureC-1]]
[%unnumbered]
.Typical gelatinization curve
image::rice_images/rice_image2.png[]
Sourcecode and pseudocode snippets are by default numbered as figures
[added in https://github.com/metanorma/isodoc/releases/tag/v1.0.10]. If they
are not to be numbered, they need to be given the %unnumbered
option attribute.
[sourcecode%unnumbered]
----
for (i = 0; i < n; i++) { bounce(v[i], wall) }
----
// This is also unnumbered
[%unnumbered]
[pseudocode]
----
stem:[forall v_{i}] *bounce* stem:[v_{i}] off the wall
----
Prevention of double-numbering
If a document element is included in a block type that is already subject to numbering, it will be excluded from auto-numbering.
This means that tables, sourcecode and pseudocode, and figures are excluded from auto-numbering within examples, requirements, recommendations, permissions, tables, figures, sourcecode and pseudocode. [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.11]
Override numbering
There are circumstances when auto-numbering of elements needs to be overriden; for instance, numbering out of sequence in updated documents.
In these cases, elements can be given an optional number
attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1],
assigning a required document element number to override auto-numbering.
Elements subsequent to that element will be auto-numbered so as to follow the previous element, so long as the supplied number belongs to the same sequence.
For subsequences, number shall have only subsequence scope.
[sourcecode,number=7]
----
for (i = 0; i < n; i++) { bounce(v[i], wall) }
----