Metanorma
On this page

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 text-ref-allowed-anchors 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.

Example

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

Scope

Metanorma cross-references the following kinds of object with generated cross-reference text.

Other objects will generate a placeholder text, [[{ID}]], if no text has been supplied for the cross-reference.

Note

Paragraphs are automatically numbered for cross-referencing, although numbered paragraphs are not displayed in any current flavor. (They were numbered in the UNECE flavor, but that flavor has been archived.)

So a paragraph may be referenced as "Clause 3, Paragraph 5", but the number "5" will not appear before the paragraph in the currently supported flavors.

Note
The only cross-references possible at the inline-level are to bookmarks (e.g. [[anchor]]). The automatically generated text in that case is to the nearest parent with associated cross-reference text; typically, that will be a numbered paragraph.

Cross-reference styles

Metanorma supports multiple cross-reference styles [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.6].

Cross-reference styles can be specified at the individual cross-references using the following syntax:

<<LOCATOR,style={STYLE}%>>

Where,

LOCATOR
is the locator, which could be an anchor;
STYLE
is one of the cross-reference styles codes.
Note
The document attribute :xrefstyle: applies the same setting as a document default.

The following cross-reference styles are available:

short
(default) the clause type and number is used as the cross-reference.

"Clause 3.1.2"

basic
the title of the clause is used as the cross-reference.

"Other considerations"

full
combines the title with the clause type/number cross-reference.

"Clause 3.1.2, Other considerations"

id
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 of a cross-reference rendered in the "id" style

"/req/crs/crs-uri", where /req/crs/crs-uri is an identifier of the referenced object.

Example of a cross-reference rendered in the basic style
<<anchor,style=basic%>>
Example of a cross-reference rendered in the short style
<<anchor,style=short%>>
Example of a cross-reference rendered in the full style
<<anchor,style=full%>>
Example of a cross-reference rendered in the "id" style

The following cross-reference:

[[my-anchor]]
=== My title
...
=== Another place
<<my-anchor,style=id%>>

Renders the cross-reference as:

"my-anchor"

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)
  • from and to (clauses from A to B)

These conjunctives are prefixed to the cross-reference anchor, separated by !.

.Example of rendering a continuous locality range

Example
<<context;to!improvement>>

rendered as

Clauses 7 to 9

.Example of rendering a disjoint locality range

Example
<<context;and!improvement>>

rendered as

Clauses 7 and 9

Of the connectives, from and to are presumed to nest more closely than and or or, and there is no provision for complex nesting.

Custom words can be substituted for the predefined conjoining verbs by appending a colon, following by the desired verb, which remains mandatory to determine semantics [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.3.0].

The rendering of the to! conjunction of "to" can be replaced with "through" by specifying to:through!, which indicates that the intended semantics is still that of "to", but the word through should be used in rendering instead.

If a connective is left out before to, from is presupposed; otherwise, and is presupposed.

Sequences of more than two cross-references all logically joined by and should be separated with ; with no commas:

Commas in the encoding of references indicates separation of subreference:

  • table2 means "table 2 within clause 3"

Continuous and disjoint localities can be used together.

.Example of rendering continuous and discontinuous locality ranges in the same cross-reference

Example
<<clause3_2;clause4_6;clause4_7;clause9>>
// or
<<clause3_2;and!clause4_6;and!clause4_7;and!clause9>>

Renders as:

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.

Example of cross-reference without labels and prefixes
Clauses <<context,droploc%>> to <<improvement,droploc%>>

renders as:

Clauses 7 to 9

Custom cross-reference labels and prefixes

To insert a custom label for a cross-reference, as opposed to the label specific to the content and following the rules for that kind of content, use the syntax label=...% [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.6].

The label should appear as it will rendered, including with the right capitalisation.

Note
This is almost always a violation of SDO style, and is not recommended.
Example of rendering a subclause reference with custom prefix "Subclause"

You could change "Clause" to "Subclause" instead of what is expected for a subclause by Metanorma for ISO (whether Clause 7.9 or just 7.9).

<<context,label=Subclause%>>

to be rendered as

Subclause 7.9

Note
This approach changes only the label of the item being pointed to. If the Metanorma flavour qualifies the cross-reference with a reference to its container, e.g. Clause 5 Note 2, label will only alter the label of the item (Note), and not that of its container (Clause).

Anchor ID syntax

Anchor IDs of any type (cross-references, items, bibliographies, etc.) are ultimately converted into XML, and therefore should 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 Namespace Declaration.

If such an anchor ID is found in a Metanorma document, it will be left alone in Semantic XML [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.8], and errors will be reported against the anchor ID unaltered. However, the anchor will be sanitised in Presentation XML, so that it does not violate the NCName requirements.

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

Differences between anchors and content identifiers

In Metanorma Semantic XML, a distinction is made between user-supplied anchors for elements (@anchor), and content identifiers (@id) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.8].

Anchor attributes appear on elements only when supplied by the user, and are the targets of any cross-references. So long as the user does not edit them in the source, they will remain the same, and they are intended for use as element locators.

Note
Metanorma also automatically assigns anchors for all terms, to be used in cross-references from concept mentions. These are derived from the term designation.

There is also a requirement that all block- and clause-level elements have an identifier which can be referenced for document processing in Metanorma, whether the user has supplied a value or not. This is generated by Metanorma as an auto-generated content identifier. Auto-generated identifiers in Metanorma have the form of a GUID, prefixed with _; e.g. _01234567-89ab-cdef-0123-456789abcdef.

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, followed by 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 content identifier.

In Presentation XML, the content identifier is preserved as @semx-id. The attribute @id is used as the element anchor, and is the NCNname-normalised counterpart to @anchor, if supplied; if @anchor is not supplied, the value of @semx-id is used. That means that all elements with content identifiers can be cross-referenced in Presentation XML, not just those elements with user-supplied anchors.

Anchor aliasing

It is possible to use more than one string to be used as an anchor for the same element.

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: Metanorma AsciiDoc 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 with anchor misccontaineranchor_aliases under the (`metanorma-extension` 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.

[.preface]
== metanorma-extension
[[_misccontainer_anchor_aliases]]
|===
| id1 | http://www.example.com | second-alias-of-anchor
|===

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 of setting a series of localities

Example

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

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

See localities and locality values.

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

Inline elements

An anchor can be specified to refer to various locations:

[[block-anchor]]
|===
| [[bookmark]] This is a cell that is not pointed to by the bookmark anchor.
| anchor:ABC[*this is some text referenced by ABC*]
|===
<<block-anchor,This cross-reference points to the entire table>>
<<bookmark,This cross-reference points to the bookmark preceding the text "This is a cell...", but not to the text itself>>
<<ABC,This cross-reference points to the boldface text span "This is some text referenced by ABC">>

Source anchor tracers

Warning
This demonstrates advanced knowledge of Metanorma and its model rendering capabilities.

Metanorma XML preserves the links between different representations of the same source data wherever possible, to establish traceability.

This is particularly important when connecting a serialisation of external data, stored in metanorma-extension, to a Metanorma XML representation of that data.

Metanorma provides the command source-id:{anchor}[text] in order to establish such connections, particularly in the Lutaml processing of external data into Metanorma XML. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.9]

This command wraps text (as a serialisation of external data) in a span element with the @source attribute anchor, which corresponds to an @anchor identifier inserted in the serialisation of that source data.

Example

Suppose there is a LutaML serialisation of the widget model that is being rendered into a Metanorma document.

In order to trace the widget model attributes in an external model, with value ABC, the external model is serialized under metanorma-extension with a defined anchor, say as <widget anchor="11214">ABC</widget>.

Then the Metanorma representation of that attribute is mapped back to the serialisation with the expression source-id:11214[ABC], which is realised in Metanorma XML as <span source="11214">ABC</span>, where 11214 is used as the cross-reference binding the two together.

This allows the final serialized representation of the widget model back to its original external model source.

If source-id:{anchor}[] is used with empty text, the @source attribute is assigned instead to the XML element containing the command.

Example

The following assigns @source = "11214" to the note containing the command.

NOTE: This is a note source-id:11214[]

Hyperlinks

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:

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

Hyperlinks can also have a rendering style set with a flavour-specific value [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.1]; this option is currently only used in IETF.

This is specified by appending ,style=... after the text in the URL command:

Example
http://www.example.com[style=brackets]
http://www.example2.com[text to go into the hyperlink,style=brackets]

External references

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

.Example of referencing an anchor in a cross-referenced document

Example

The following code:

<<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 of referencing an anchor in an external document

Example

The following code:

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