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 of specifying a reference anchor (ref1 is the anchor)

Example

<<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 locality types that are used on their own

whole
title

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 of referencing locality in Metanorma citations

Example

<<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 that renders a reference as free text

Example

// 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 of referencing with a "whole" locality

Example

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

Hierarchical locality

A hierarchical location is specified through consecutive narrower localities.

.Example of referencing a hierarchical locality

Example

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

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

Example

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

.Example of referencing locality with additional text

Example

// 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 of referencing a discontinuous locality

Example

// 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 of referencing discontinuous hierarchical localities

Example

// 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 of referencing a complex locality

Example

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

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

Example

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

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.

Note

All 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 of referencing multiple references that are complex localities

Example

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

.Example of referencing a custom locality the locality: prefix

Example

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 of referencing with bibliographic localities with additional custom text

Example

<<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 of using the anchor locality for rendering in HTML output

Example

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 of using droploc in a citation locality

Example

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

.Example of using lowercase in a citation locality

Example

// 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

Example

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 cross-reference 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
authordatebr: 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
titlereferencetag: 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.

Example

<<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:

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

Example

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

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

Example

<<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 of rendering a range of citations

Example

The following citation range:

<<from!context;to!improvement>>

is rendered as:

From [3] to [7]