Metanorma: Aequitate Verum

Author's documentation

Indexes and table of contents

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 1. Example of specifying rendered index term and hidden index terms
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 in index terms

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

Only one target is to be given per macro; if there are multiple targets, they need to be specified in separate macros. Metanorma will concatenate them correctly.

index:also[guitar,electric,technique,Jimi Hendrix]
index:also[guitar,electric,technique,Eric Clapton]

Rendered as:

  • guitar

    • electric

      • technique, see also Jimi Hendrix, Eric Clapton

Index placement

If any index terms are present in a document, and the current flavour supports indexes, then an index section will be automatically generated and appended to the end of the document.

To override the title of the index section, or indicate where it should be placed, use the index section markup shown below.

[index]
== Index

Any index will be appended after any content you may choose to place in the index section, but indexes typically appear with no preface.

Automated index terms

If the document attribute :index-terms: is used, all terms (and symbols) are indexed automatically in postprocessing.

The document does not need to include explicit index terms for them [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.3].

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.

Automated table of contents generation

The table of contents is generated automatically for Word, HTML, and PDF output.

  • In Word, it takes the form of a normal Word Table of Contents; the page numbers are not populated when the document is generated, and the table of contents needs to be refreshed (Right Click: Update Field).

  • In HTML, it takes the form of a side panel. In PDF, it takes the form of an introductory table of contents; because the PDF is generated from HTML in Metanorma, there are no page numbers in the table of contents.

By default, the table of contents includes two levels of heading. More levels of heading can be set by using the document attribute :toclevels:; e.g. :toclevels: 3 for three levels of heading included. The number of levels of heading to include can be set separately for HTML and for DOC/PDF, by using the document attributes :htmltoclevels:, :pdftoclevels: and :doctoclevels:.

The location of the table of contents is set by default for each flavour, and is normally at the start of the document preface. If the user wishes to insert a signpost for tables of content, the clause type toc is reserved to indicate where the table of contents will go. But Metanorma by default will not allow any flexibility in where the table of contents will be rendered --- and will move it to the start of the preface.

[.preface,type=toc]
== Table of contents

Using the toc command to generate a ToC

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 toc 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.

Manually specifying a ToC

A manual table of contents can also be provided as a clause of type toc [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7] without using the toc command.

Any table of contents entries within that manual table of contents are expected to be provided as cross-references within unordered lists.

The table of contents can contain subclauses, each with its own list of cross-references, and other text.

Example 2. Example of manually specifying a ToC
[type=toc]
=== Table of contents

This is a table of contents.

==== First subsection

* <<xref1>>
* <<xref2,This is a modified title>>

==== Second subsection

* <<xref3>>
* <<xref4>>

Variant titles

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

However, a manually created 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.

Note
 Of course, if an explicit cross-reference text is given in a toc clause, that takes priority.

Variant titles are also used to generate the automated all-of-document table of contents for HTML and PDF documents [added in https://github.com/metanorma/isodoc/releases/tag/v1.8.5]. They are not used in Word DOC output, because tables of contents for Word documents are generated dynamically from the current heading.

Variant titles are not currently used to generate the tables of other entities.