Text formatting

Index terms

General

Metanorma supports index entries with primary, secondary and tertiary index terms. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].

Primary index terms are listed under the first-level index, the secondary index terms are listed under the primary index terms' sub-index, and the tertiary index terms are listed under the secondary index term’s sub-index.

Illustration of an index in Metanorma with primary and secondary indexes are shown
Figure 1. Illustration of an index in Metanorma with primary and secondary indexes are shown.

Index term behavior differs per rendered output format:

  • In PDF, indexes are rendered as references to page numbers.

  • In HTML and DOC, indexes are rendered as references to the nearest labelled block; a note, example, figure, formula etc., if the index term is contained within it, or a clause or subclause, otherwise.

Index term links are only rendered in certain flavours, and do not appear otherwise in DOC, PDF or HTML output.

Note
Currently, only the ISO, IETF and BIPM flavours render index terms.

Rendered index term syntax

Metanorma index entries are entered through two different syntaxes. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10].

Rendered index term: ((Term))

  • Produces the output “Term”; and

  • Links to the primary index term of the same name, “Term”.

Hidden index term: (((IndexTerm1))), (((IndexTerm1, IndexTerm2))) or (((IndexTerm1, IndexTerm2, IndexTerm3)))

  • Produces no output; and

  • Links to the primary index term IndexTerm1. And if provided, links to the secondary nesting, IndexTerm2 and the tertiary nesting IndexTerm3.

EXAMPLE:

The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)),
was to carry Excalibur (((Sword, Broadsword, Excalibur))).

Rich-text formatting

Rich-text formatting in index terms is supported [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0].

signifying by divine providence that I, ((*Arthur*)),
was to carry Excalibur (((Sword~E~, stem:[sqrt(E)], Excalibur))).
Note
Formatting of index terms is ignored in IETF rendering.

Entry ranges

Metanorma supports index entries that involve ranges [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0], using the command index-range:to[…​].

The command itself accepts an AsciiDoc index entry, such as ((...)) or (((...))).

The index entry range starts at the location of the index-range command, in the same way as the index command it contains; the end of the range is the element with the anchor to, and that is expected to be provided as a bookmark.

signifying by divine providence that I, index-range:end-range-1[((*Arthur*))],
was to carry Excalibur index-range:end-range-2[(((Sword~A~, stem:[sqrt(2)], Excalibur)))].

...

and so forth.[[end-range-1]]

...

_Sic explicit fabula._[[end-range-2]]

The preceding example has a visible index entry for Arthur, ranging from the location of *Arthur* up to end-range-1, and a hidden index entry for SwordA, ranging from the location of Sword~A~ up to end-range-2.

Cross-references

Metanorma also supports “see” and “see also” cross-references between index terms [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.5], using the index command.

The command takes at least two parameters:

  • the primary index term to be cross-referenced;

  • the target of the cross-reference;

  • optionally, the secondary and tertiary index term to be cross-referenced.

index:see[Satchmo,Louis Armstrong]
index:see[James Brown,influences,Hank Ballard and the Midnighters]
index:also[guitar,electric,technique,Jimi Hendrix]

Rendered as:

  • Satchmo, see Louis Armstrong

  • James Brown

    • influences, see Hank Ballard and the Midnighters

  • guitar

    • electric

      • technique, see also Jimi Hendrix

Cross-references

General

Cross-references are realized 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>>...
Warning
See Anchor ID syntax for allowed characters in anchor IDs.
Note
Cross-reference text in Metanorma adheres to guidance given in ISO/IEC DIR 2 for internal cross-references, in order to guarantee unambiguous referencing.

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 Metanorma ISO 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 (e.g. \<<formulaB-1>> generates either “Formula (B.1)” or “B.6, Formula (B.1)”, depending on where in the document it occurs.)

If the cross-reference is given with droploc% as its text, then the label and prefix are dropped: the cross-reference value is given in isolation [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.4].

This can be done for example for ranges:

Clauses <<context,droploc%>> to <<improvement,droploc%>>

to be rendered as e.g.

Clauses 7 to 9

Anchor ID syntax

Anchor IDs of any type (cross-references, items, bibliographies, etc.) are directly converted into XML, and therefore must not contain the following:

  • colons

  • whitespaces or;

  • words starting with numbers.

These cases are not supported in XML; permitted characters are specified by the NCName attribute for Namesapece Declaration.

Colons in cross-references are used for indirect cross-references between files in the same collection, to delimit namespaces and containers from anchor IDs [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4].

Localities

Normally in AsciiDoc, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference.

So a cross-reference <<ISO7301,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.

Note
This differs from the normal AsciiDoc treatment of custom text.

EXAMPLE: “ISO 7301, Clause 2, Table 1a, pp. 7-9” would be expressed as:

<<ISO7301,clause=2,table=1a,page=7-9>>

List items

List items can be cross-referenced by inserting a bookmark at the very start of the list item:

. Ordered list
.. [[id1]] This is the first list item
... [[id2]] This is a list sub-item

Definition List Terms

Definition list terms can be cross-referenced by inserting a bookmark at the very start of the term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.0]:

[[id1]]Term 1:: Definition
[[id2]]Term 2::: Another Definition

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 Metanorma 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

In localities and locality values, anchor can be integrated in citations of documents via references.

For example:

<<ISO7301,anchor=xyz>>

will generate a hyperlink to the element with ID xyz in document ISO7301. This convention is necessary for cross-references between documents in a Metanorma document collection.

Outside of that, Metanorma will process cross-references to anchors within external documents just like typical AsciiDoc.

EXAMPLE:

<<document1.adoc#b>>

will be processed as a link to anchor #b in document document1.adoc.

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 <xref target="document1#b">, in HTML as <a href="document1.html#b">, and in PDF as <a href="document1.pdf#b">.

Table of contents

General

A table of contents is provided at the start of a Metanorma document rendering, either as:

  • prefatory material in electronic document formats (PDF, Word); or

  • a sidebar in the HTML output.

This table is typically a listing of all clauses of the document, and runs two levels deep.

In some flavours, a separate table of contents is inserted for figures, tables, and recommendations.

Manual compilation

A manual table of contents command has been added to Metanorma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5].

This is intended for a local table of contents, e.g., at the start of an appendix.

The table of contents command is utilized as follows.

toc:["xpath1:depth1","xpath2:depth2","xpath3:depth3"...]

Where,

  • depth is a number indicating the depth of indentation of the ToC entry (default value 1)

  • xpath is the XPath of the title being indexed in the Metanorma XML.

For instance, in the following command:

toc:["//clause[@id = 'clause1'\]/clause/title","//clause[@id = 'clause1'\]/clause/clause/title:2"]
  • all titles of subclauses of the clause with ID clause1 are at the first depth level of the manual table of contents (defaults to depth 1)

  • all titles of sub-subclauses of the clause with ID clause1 are at the second depth level of the manual table of contents

This means that the table of contents will have of the first-level clause with ID clause1, running three levels deep.

Variant titles

Clauses in Metanorma normally have only one title, and that title is used to compile the table of contents.

However, the manual table of contents can make use of variant titles instead.

Variant titles [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5] are entered as paragraphs with a variant-title role attribute within a clause, as follows:

=== Proper title

[.variant-title,type=toc]
This is the variant title

Text of section.

Variant titles are not rendered in the body of the text. However, any variant titles of type toc are used instead of the title as the entry text for a manual table of contents.

As of this writing, variant titles are not used to generate the automated all-of-document table of contents, or tables of other entities.