Citations and localities

General

Citations of references in Metanorma are formulated as cross-references.

The anchor cross-referenced is the internal identifier given for the bibliographic entry.

Example 1. Example of specifying a reference anchor (ref1 is the anchor)

<<ref1,part=IV,chapter=3,paragraph=12>>

Metanorma AsciiDoc works in a similar way to typical AsciiDoc: any text in a cross-reference that follows a comma constitutes custom text for the cross-reference.

A cross-reference <<ISO7301,the foregoing reference>> will be rendered as “the foregoing reference”, and hyperlinked to the ISO7301 reference.

Localities

General

Citations can include details of where in the document the citation is located.

These localities are entered by suffixing the lowercase type of locality, then an equals sign, then the locality value or range of values.

Multiple instances of locality and reference can be provided, delimited by comma or colon.

The references cannot contain spaces. Any text following the sequence of localities will be displayed instead of the localities.

Locality types

The following locality types are recognised in Metanorma:

section: a general section
clause: a clause
part: a document part
paragraph: a paragraph
chapter: a chapter
page: a page
line: a line identified by the line number
table: a table
annex: an annex
figure: a figure
example: an example
note: a note
formula: a mathematical formula
list: a list
time: a particular time
anchor: an anchor
whole: whole
title: the title

Except for the locality types of whole and title, all locality types require explicit specification of an identifier to make sense.

Example 2. Example locality types that are used on their own

whole
title

Example 3. Example locality types that need to be used with identifiers

note 1 (or note=1)
page 77-99 (or page="77-79")
annex A (or annex=A)
line 399 (or line=399)

Locality types not listed here shall be entered using the mechanism described at Custom locality.

Simple locality

A simple locality is specified with a unique location identifier or free text.

Example 4. Example of referencing locality in Metanorma citations

<<ISO7301,clause=3.1-3.4>>

NOTE: This table is based on <<ISO7301,table=1>>.

Sampling shall be carried out in accordance with <<xxx,section="5-3-1,bis">>

Example 5. Example that renders a reference as free text

// renders as: "the foregoing reference"
<<ISO712,the foregoing reference>>

To refer to the “whole” item, or the title within a block, the corresponding keyword is used (whole, title), without an argument.

Example 6. Example of referencing with a "whole" locality

// renders as: "ISO 712, Whole of text"
<<ISO712,whole>>

Hierarchical locality

A hierarchical location is specified through consecutive narrower localities.

Example 7. Example of referencing a hierarchical locality

// renders as "`Part IV, Chapter 3, paragraph 12`"
<<ref1,part=IV,chapter=3,paragraph=12>>

Example 8. Example that renders the reference with (multiple) hierarchical localities

// renders as: "ISO 712, Section 5, Page 8-10"
<<ISO712,section=5, page 8-10>>

Example 9. Example of referencing locality with additional text

// renders as "ISO 712, 5:8-10"
// ("5:8-10" treated as replacement text for all the foregoing)
<<ISO712,section=5, page=8-10: 5:8-10>>

Discontinuous locality

Discontinuous localities can be named by repeating the same locality type.

Example 10. Example of referencing a discontinuous locality

// renders as "`page 4, page 7`"
<<ref1,page=4,page=7>>

Discontinuous localities can also be specified by delimiting sequences of localities with semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.24]

Example 11. Example of referencing discontinuous hierarchical localities

// renders as "`Part IV, Chapter 3; Part VI, Chapter 9`"
<<ref1,part=IV,chapter=3;part=VI,chapter=9>>

Complex locality

Complex relations between discontinuous references can be specified by prefixing conjoining verbs to sequences of localities separated by semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4].

This will result in overt connectives between the references, which will be internationalised.

Conjoining verbs include:

and!
or!
from!
to!

Example 12. Example of referencing a complex locality

// renders as: "`Chapters 3 and 7`"
<<chapter=3;and!chapter=7>>

Example 13. Example of referencing a complex locality that contains a hierarchical locality

// renders as: "Part IV, Chapter 3 or Part VI, Chapter 9"
<<ref1,part=IV,chapter=3;or!part=VI,chapter=9>>

Note	This is similar to the behavior in Combination of cross-references.

As with cross-references, more than two references combined by “and” should be marked up with semicolons. internationalization during rendering will take care of separating the references by colon, and inserting any necessary conjunction wording (“and”).

Example 14. Example of referencing multiple references that are complex localities

<<ref1,clause=3.2;clause=4.7;clause=4.9;clause=9>>
// or
<<ref1,clause=3.2;and!clause=4.7;and!clause=4.9;and!clause=9>>

Note

If references are joined with semicolons and connectives, but the locality is not supplied for a cross-reference, it is filled in by referring to the preceding conjoined cross-reference [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.0]. For example, clause=3.2;and!4.7;to!4.9;and!9 is corrected internally to the more explicit clause=3.2;and!clause=4.7;to!clause=4.9;and!clause=9.

Trailing text after the sequence of locality=reference (or locality{space}reference) is treated as custom text for the cross-reference, as would occur normally in a typical cross-reference.

The locality can appear in quotations if it contains special characters (like dashes or commas).

Custom locality

Locality types not listed in Locality types are entered using the "custom locality" functionality.

Metanorma accepts a fixed list of locality types in cross-references (see Locality types), which is not meant to be exhaustive of all possible locality types.

annex is recognized as a generic reference to annexes in documents, but it does not recognize appendixes (instead of annexes), or as distinct from annexes (as is the case in ISO deliverables).

A custom locality is entered by prefixing the locality type with locality:.

A custom locality has the following properties:

The locality type will be rendered as text preceding the equal sign.
The locality type shall not contain commas, colons, or space.
The locality type is meant to be valid for all languages.

Note
The custom locality locality:appendix would be used for both English and French texts.
Localization of custom locality types is managed through inclusion in the internationalization YAML file for that language, which has to be customized as part of the Metanorma flavor implementation.

Note
The custom locality locality:appendix is realized as French Appendice through configuration in the Metanorma flavor implementation.

Example 15. Example of referencing a custom locality the locality: prefix

This encoding:

<<ISO-IEC_DIR_1_ISO_SUP,annex=SL,locality:appendix=2,clause=3.2>>

Renders as:

"ISO/IEC DIR 2, Annex SL, Appendix 2, Clause 3.2"

Locality plus custom text

Any text after the bibliographic localities is still treated as custom cross-reference text.

As with references without localities, the custom cross-reference text is the only text that is displayed in the document; but the cross-reference still captures the specific locality of the reference, e.g. for cross-reference generation.

Example 16. Example of referencing with bibliographic localities with additional custom text

<<ISO7301,clause=5,table=1,the foregoing reference>>

rendered as:

the foregoing reference

Anchor locality

Exceptionally, the anchor locality is only used in HTML, to generate anchor links to other HTML pages [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].

It is intended for use with bibliographic anchors linking to URLs (repo:(), path:()): see Referencing from a Metanorma collection and Referencing from Metanorma or Relaton files.

Example 17. Example of using the anchor locality for rendering in HTML output

The following input:

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

...

* [[[ISO7301,path:(./iso7301.html,ISO 7301)]]]

will render in HTML as:

<a href="./iso7301.html#xyz">ISO 7301, Clause 2, Table 1a, page 7-9</a>

Case and dropped locality labels

The capital%, lowercase% and droploc% options used for internal cross-references can also be used as prefixes to localities, modifying how those localities are rendered [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.9].

Example 18. Example of using droploc in a citation locality

// renders as "ISO 7301, 2"
<<ISO7301,droploc%clause=2>>

Example 19. Example of using lowercase in a citation locality

// renders as "ISO 7301, clause 2"
<<ISO7301,lowercase%clause=2>>

Styled cross-references

General

Cross-referenced citations can have a style attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4], as with internal cross-references.

There are two groups of style values allowed as citation styles:

Document identifier style types
General citation style types

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	This syntax is identical to that used for internal cross-references (Cross-reference styles).

Document identifier style types

The first are "docidentifier types" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4].

A "docidentifier" is a unique identifier assigned to a bibliographic resource that can substitute the primary identifier of the reference. These are commonly used for standards documents.

Those values are looked up in Relaton (and the Metanorma Semantic XML of the document).

Values available for the style attribute depend on the docidentifier types available for the specific bibliographic resource.

Common docidentifier types include:

for ISO standards: ISO, URN
for IEC standards: IEC, URN
for ITU standards: ITU

For example, given the citation:

<bibitem type="standard" id="bib1">
...
<docidentifier type="ISO" primary="true">ISO/FDIS 17664-1</docidentifier>
<docidentifier type="URN">urn:iso:std:iso-fdis:17664:-1:ed-1:fr</docidentifier>
...
</bibitem>

A crossreference [bib1] will be populated by default with the primary or else the first docidentifier value found, ISO/FDIS 17664-1. However, given style=URN%, the first docidentifier value of type URN will be sought instead, and the cross-reference will be populated by default as URN urn:iso:std:iso-fdis:17664:-1:ed-1:fr.

General citation style types

The second type are general citation types. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.3.5]

The following citation types can be used to override the default citation style for a given reference.

author_date: the author and date of a citation; a disambiguating letter is added to the date if there are multiple references with the same author and date

Jones 2001, Jones & Smith 2003b
author_date_br: same as author_date, but with parentheses around the date

Jones (2001), Jones & Smith (2003b)
author: the author alone

Jones, Jones & Smith
date: the date alone. (used when an author-date citation is typographically broken up)

2001, 2003b
reference_tag: the bibliographic tag of the citation, which appears as its identifier before the reference in the bibliography

ISO 634 [1], [NIST623]
title: the title of the reference alone

Chicago Manual of Style
title_reference_tag: the title of the reference, followed by the bibliographic tag

Chicago Manual of Style [22]
full: the full bibliographic citation as it appears in the bibliography, though without its final full stop.
short: a truncated version of the full bibliographic citation, used specifically for in-document references; typically this omits URLs and dates of access.

<<ISO7301,style=short%>> # renders as "ISO 7301"
<<ISO7301,style=full%>>  # renders as "ISO 7301:2020, ... (full citation)"
<<ISO7301,style=author_date%>> # renders as "ISO 2020"

The default citation format for a flavour, which this attribute overrides, varies.

Typically, it is:

In normative references, the document identifier (e.g. ISO 7301) is used.
In the bibliography (or informative references), either the document identifier or an ordinal number (e.g. [3]) is used.

Note	In JIS and IEEE, these defaults are overridden, using short citations and author-date citations in a subset of references. Specifying the citation style explicitly prevents such overriding.

Link-only references

A standards document can be cross-referenced in Metanorma without that document appearing in the document references.

Such cross-reference is treated as equivalent to a cross-reference to a hidden citation, as documented in hiding citations.

Link-only references can be added to Metanorma AsciiDoc using the following command:

++std-link:[...]++

Where the std-link command contains the same text as a normal cross-reference to a standard, including localities and other directives. There is no need for an explicit bibliographic entry. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4].

The following two examples are equivalent:

Example 20. Link-only reference of ISO 123 using std-link

std-link:[ISO 123,droploc%clause=3]

Example 21. Link-only reference of ISO 123 using a hidden citation

<<ref1,droploc%clause=3>>

[bibliography]
== Bibliography

* [[[ref1,hidden(ISO 123)]]]

Combination of citations

Simple citations can be combined with connectives, in a similar fashion to cross-references (Combination of cross-references), and which will be internationalised as appropriate [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7].

Example 22. Example of rendering a range of citations

The following citation range:

<<from!context;to!improvement>>

is rendered as:

From [3] to [7]