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>>...
|See Anchor ID syntax for allowed characters in anchor IDs.|
|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
\<< generates either “Formula (B.1)” or “B.6, Formula (B.1)”,
depending on where in the document it occurs.)
Metanorma supports multiple cross-reference styles [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.6].
The document attribute
The following cross-reference styles are available:
(default) the clause type and number is used as the cross-reference.Example 1. Example of a cross-reference rendered in the "short" style"Clause 3.1.2"
the title of the clause is used as the cross-reference.Example 2. Example of a cross-reference rendered in the "basic" style"Other considerations"
combines the title with the clause type/number cross-reference.Example 3. Example of a cross-reference rendered in the "full" style"Clause 3.1.2, Other considerations"
the cross-reference is to be rendered as the target anchor identifier (or any identifier aliasing the anchor) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7].Example 4. Example of a cross-reference rendered in the "id" style
/req/crs/crs-uriis an identifier of the referenced object.
These cross-reference styles can be specified at the individual cross-references by using the following syntax:
LOCATORis the locator, which could be an anchor;
STYLEis one of the cross-reference styles codes.
The following cross-reference:
[[my-anchor]] === My title ... === Another place <<my-anchor,style=id%>>
Renders the cross-reference as:
Combination of cross-references
It is possible to combine multiple cross-references into a single expression, which will be internationalised as appropriate [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4].
Multiple cross-references are separated by
Conjunctives recognised between cross-references are:
and(clauses A and B)
or(clauses A or B)
to(clauses from A to B)
These conjunctives are prefixed to the cross-reference anchor, separated by
Clauses 7 to 9
Clauses 7 and 9
Of the connectives,
to are presumed to nest more closely than
or, and there is no provision for complex nesting.
If a connective is left out before
from is presupposed; otherwise,
Sequences of more than two cross-references all logically joined by
be separated with
; with no commas:
[clause3;table2]means "clause 3, and table 2"
Commas in the encoding of references indicates separation of subreference:
table2means "table 2 within clause 3"
Continuous and disjoint localities can be used together.
<<clause3_2;clause4_6;clause4_7;clause9>> // or <<clause3_2;and!clause4_6;and!clause4_7;and!clause9>>
clause 3.2, 4.6, 4.7 and 9
Cross-references without labels and prefixes
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, as follows.
Clauses <<context,droploc%>> to <<improvement,droploc%>>
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:
words starting with numbers.
These cases are not supported in XML; permitted characters are specified by the NCName attribute for Namespace 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].
If an anchor is not assigned to an entity, Metanorma by default assigns a GUID
to be its identifier. Auto-generated identifiers are prefixed with
In order to keep anchors stable within a single version of the document, Metanorma calculates those GUIDs as an MD5 Hash of the XPath of the element, and its text content [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.8].
So long as neither the text content nor the position in the document of the entity changes, an entity will retain the same GUID anchor.
It is possible to use more than one identifier to refer to the same anchor. This is useful particularly for Linked Data documents, where a URI is treated as the identifier of a document block or term, and the URI is used to reference that document element: Asciidoctor and XML syntax both prevent URIs from being used themselves as document anchors.
In order to specify the aliases of anchors manually, you will need to specify a table
_misccontainer_anchor_aliases under the
Misc-Container clause) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7].
Each row of that table will have the anchor as its first cell, and aliases of the anchor as the other
cells; there can be more than one alias of an anchor.
== Misc-Container [[_misccontainer_anchor_aliases]] |=== | id1 | http://www.example.com | second-alias-of-anchor |===
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
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 differs from the normal AsciiDoc treatment of custom text.|
“ISO 7301, Clause 2, Table 1a, pp. 7-9” would be expressed as:
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
This is specified by appending
,title=… after the text in the URL macro in
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]
In localities and locality values, anchor can be integrated in citations of documents via references.
The following code:
will generate a hyperlink to the element with ID
xyz in document
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.
The following code:
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