Metanorma: Aequitate Verum

Author's documentation

Cross-reference basics

Basic anchor syntax

Note
 This article looks at the technical details of cross-references in Metanorma AsciiDoc. If you want to learn how to insert cross-references, read Adding links and cross-references

The basic mechanism for cross-references is setting anchors to place that should be referenced.

Example of an anchor and a reference
[[anchor-id]]
== Target clause

The requirements are...

== Reference clause

As seen in <<anchor-id>>...

Valid anchor IDs

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

Unambiguous referencing

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.

Example 1. Example of differently rendered reference depending on locality

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

Bibliographic localities in Metanorma AsciiDoc

In vanilla 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.

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

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

Read more about localities and locality values in the Bibliography documentation.