Collections cross-referencing

Cross-references

Direct cross-references

A source document can link to a target document in the same collection, or a specific location within the target document.

Documents are processed one document at a time; so such a link is encoded as a bibliographical reference, to an external document, as described in Bibliography.

This means that an author needs to define a bibliographic entry for each hyperlinked document in the same collection; those bibliographic entries will be suppressed from display in the collection.

Note	If the documents are to be used in isolation, those bibliographic entries still need to be displayed: otherwise, the reference cannot be made sense of.

The bibliographic reference for another document in the same collection is specified using the following syntax.

* [[[myanchor,repo:(current-metanorma-collection/docid)]]]

where docid is the document identifier as it appears in the collection manifest.

If no such anchor is given in the document, but the document identifier in the collection manifest matches a document identifier in the bibliography, then collection processing will still recognise that the document is referencing that other document [added in https://github.com/metanorma/metanorma/releases/tag/v1.3.12].

For instance, if the manifest includes an instance of identifier: ISO 44001, and the bibliographic reference of another document includes * [], then collection processing will automatically link all references to ISO 44001 to the collection instance of the document.

This allows documents to be included in a collection, without requiring their references to be edited.

The location to link to in the target document can be specified as a clause number, as in a typical citation:

Example 1. Example of specifying a cross-reference to a clause in the target document

<<myanchor,clause=3.1>>

The processor will then navigate the target document, to try to resolve the reference.

Note	Currently only one level of nesting of locations is implemented: the processor will not resolve references like `clause=3.1,note-3`.

Alternatively, the location can be specified as an anchor, e.g. <<myanchor,anchor=ident>>. The hyperlink will then be made directly to the element with anchor ident in the the target document. That approach is to be preferred as simpler.

For instance, we wish to link from the French BIPM Brochure to the English BIPM Brochure, and specifically to an example in the English document. We start by assigning the target document example an anchor identifier:

[[english_example]]
[NOTE]
====
For example: The maximum electric potential difference is
stem:[ii(U)_("max") = 1000 " "rm(V)] but not
stem:[ii(U) = 1000 " "rm(ii(V)_(max))].
The mass fraction of copper in the sample of silicon is
stem:[w("Cu") = 1.3 xx 10^(-6)] but not
stem:[1.3 xx 10^(-6) " "rm(w)//rm(w)].
====

We then define a citation in the source document, using that anchor:

Ce n'est que lorsque l'on écrit le nom de l'unité en toutes lettres que l'on
applique les règles grammaticales ordinaires (voir un exemple en anglais page
<<english-doc,anchor=english_example>>).

Finally, we define a bibliographic entry in the source document for the English-language target document:

[bibliography]
== Bibliography

* [[[english-doc,repo:(current-metanorma-collection/si-brochure-en)]]] (Version anglaise de la brochure BIPM).

The identifier given to the target document needs to match that given in the collection manifest:

manifest:
  level: brochure
  title: Brochure/Brochure
  docref:
    - fileref: si-brochure-fr.xml
      identifier: si-brochure-fr
    - fileref: si-brochure-en.xml
      identifier: si-brochure-en

This form of direct cross-reference is also used to reference attachments [added in https://github.com/metanorma/metanorma/releases/tag/v1.3.2]. For example, if you wanted to link to a text file from a collection document, the manifest would look as follows:

manifest:
  level: brochure
  title: Brochure/Brochure
  docref:
    - fileref: si-brochure-fr.xml
      identifier: si-brochure-fr
    - fileref: attachment.txt
      identifier: ABC
      attachment: true

And the hyperlink to the attachment, and the bibliographic entry for it, would be as follows:

Download the attachment from: <<theattachement>>.

....

[bibliography]
== Bibliography

* [[[theattachment,repo:(current-metanorma-collection/ABC)]]]

Indirect cross-references

In some documents, anchors (targets for cross-references) are inserted in various files in the collection, and we do not necessarily know at the time of authoring which files those anchors will end up in. A good example of that is computer-generated documentation of schemas: schema documentation is organised by entity, and the documentation of one entity can cross-reference attributes in a different entity. But at the time of authoring, we may not know which document the target entity will appear in, so we cannot supply a bibliographic entity naming that document.

To deal with that circumstance, Metanorma implements a special class of cross-references, which are namespaced and which use containers:

<<namespace:container>>
<<namespace:container,text>>
<<namespace:container:locality>>
<<namespace:container:locality,text>>

The namespace is provided to deal with the fact that such anchors can have different provenance, and they may have particular rendering requirements. (So if we are documenting two different schemas, we may want to differentiate their references, and render them differently.)
The container relies on the fact that such anchors can be grouped together in a target document, under a clause. (For example, a schema instance.) For efficient processing, we treat each of those container clauses as a single bibliographic reference, and use the identifier of that clause as the bibliographic anchor. We also assign the container clause the namespace as a type, again for efficiency and to enforce consistent rendering. This is mandatory.
The locality is the identifier of the particular component addressed within the container. It is an identifier in the target document, and will typically point to a subclause of the container clause.
The text is the text to be rendered for the cross-reference. If not provided, Metanorma will provide a clause reference for the target.

To give a worked example:

We are generating documentation for a set of schemas in the EXPRESS language as a Metanorma collection. We wish to point to the identifier basic_attribute_schema.id_attribute.identified_item from our source document. We do not know (or care) what document that identifier will turn up in: we will have collection processing deal with that.

basic_attribute_schema.id_attribute.identified_item is an identifier within the basic schema, and we are grouping the definitions of the basic schema together, under a single clause in the target document.

The target document will thus contain a container clause with identifier basic, containing all those definitions, including basic_attribute_schema.id_attribute.identified_item. The container clause is made to be of type express (because its content comes from that language, and we want to follow the conventions of that language in any processing).

[[basic]]
[type=express]]
=== Basic Schema

....

[[basic_attribute_schema.id_attribute.identified_item]]
===== Identified Item

The cross-reference to that identifier, from either the same document or a different document in the same collection, is:

<<express:basic:basic_attribute_schema.id_attribute.identified_item,Identified Item>>

We do not need to indicate which document basic_attribute_schema.id_attribute.identified_item is in, unlike for direct cross-references. Because of the namespacing, we know that we are looking for the identifier basic_attribute_schema.id_attribute.identified_item inside a clause with id basic and type express: that narrows down our search while generating the collection. The basic collection identifier is actually optional; but if you don’t provide it, you will need to put [type=express] on any cross-reference target, and collection processing will be more expensive.