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.
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.
|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:
Produces the output “Term”; and
Links to the primary index term of the same name, “Term”.
Hidden index term:
(((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,
IndexTerm2and the tertiary nesting
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))).
|Formatting of index terms is ignored in IETF rendering.|
Metanorma supports index entries that involve
ranges [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0],
using the command
The command itself accepts an AsciiDoc index entry, such as
The index entry range starts at the location of the
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
a hidden index entry for SwordA, ranging from the location of
Sword~A~ up to
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],
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]
Satchmo, see Louis Armstrong
influences, see Hank Ballard and the Midnighters
technique, see also Jimi Hendrix
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
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.
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.
depthis a number indicating the depth of indentation of the ToC entry (default value
xpathis 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
clause1are at the first depth level of the manual table of contents (defaults to depth
all titles of sub-subclauses of the clause with ID
clause1are 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
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
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.
[type=toc] === Table of contents This is a table of contents. ==== First subsection * <<xref1>> * <<xref2,This is a modified title>> ==== Second subsection * <<xref3>> * <<xref4>>
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.
Of course, if an explicit cross-reference text is given in a
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.