Author’s documentation

References & Bibliography

General

The Normative References and the Bibliography must be preceded by the style attribute [bibliography], so that the references they contain may be recognized as such.

All entries in a Bibliography, whether standards or generic, are renumbered incrementally in the XML; if the number for generic references is updated, all citations of that reference will be updated as well.

By default, Metanorma does not change the ordering of references in the Bibliography from what has been entered by the authors. Metanorma flavours may reorder references.

Entering typical references

General

Typical bibliographic entries are given as unordered lists.

A single bibliographic entry must be preceded by a bibliographic anchor, in triple brackets: this consists of an internal identifier (used within Metanorma AsciiDoc for crossreferences), followed by a document identifier.

This is illustrated as:

* [[[{anchor},{document identifier or reference tag}]]], _{reference list text}_

Implied reference tags

Bibliographic entries for standards are expected to have the standard document identifier as the item label. References to well-defined standards codes use the document identifiers for citations (e.g. ISO 20483:2013).

* [[[ISO20483,ISO 20483:2013]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_
* [[[ISO6540,ISO 6540:1980]]]. _Maize -- Determination of moisture content (on milled grains and on whole grains)_

gets rendered as:

  • ISO 20483:2013. Cereals and cereal products — Determination of moisture content — Reference method

  • ISO 6540:1980. Maize — Determination of moisture content (on milled grains and on whole grains)

Numeric reference tags

Generic references in bibliographies, as opposed to standards references, use numbers, which are rendered bracketed, like [1].

* [[[ISO20483,1]]], _ISO 20483:2013 Cereals and cereal products -- Determination of moisture content -- Reference method_
* [[[ISO6540,1]]]. _ISO 6540:1980 Maize -- Determination of moisture content (on milled grains and on whole grains)_

gets rendered as:

  • [1] ISO 20483:2013 Cereals and cereal products — Determination of moisture content — Reference method

  • [2] ISO 6540:1980 Maize — Determination of moisture content (on milled grains and on whole grains)

Note
 To indicate usage of the numeric reference system, any number can be entered into the reference tag field. All references are automatically re-sorted and auto-incremented during compilation.

Named reference tags

Instead of numbers or standard document identifiers, user can supply their own alphanumeric labels for references. These are indicated by wrapping the label within the bibliographic anchor in brackets.

* [[[ISO20483,(CerMoist)]]], _ISO 20483:2013 Cereals and cereal products -- Determination of moisture content -- Reference method_
* [[[ISO6540,(MaiMoist)]]]. _ISO 6540:1980 Maize -- Determination of moisture content (on milled grains and on whole grains)_

gets rendered as:

  • [CerMoist] ISO 20483:2013 Cereals and cereal products — Determination of moisture content — Reference method

  • [MaiMoist] ISO 6540:1980 Maize — Determination of moisture content (on milled grains and on whole grains)

Entering formatted citations

For generic references by default, Metanorma only supports formatted citations, which are given as such in the AsciiDoc source.

The NIST flavour of Metanorma currently supports rendering of generic references, on an experimental basis.

See Automatic reference lookup topic.

Entering Relaton XML

Bibliographic entries can also be given as raw Relaton XML, in an AsciiDoc passthrough block. Of course, any Relaton XML bibitem entries need to be valid, and using correct id attributes:

[bibliography]
== Normative References

++++
<bibitem id="doc1">
<docidentifier>ISO 1</docidentifier>
<title>Geometrical product specifications (GPS) -- Standard reference temperature for the specification of geometrical and dimensional properties</title>
</bibitem>
++++

Citations

Citations of references in Metanora are formulated as cross-references; the id cross-referenced is the internal identifier given for the bibliographic entry (ref1 in the examples above).

In typical AsciiDoc, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference. So a cross-reference the foregoing reference will be rendered as “the foregoing reference”, and hyperlinked to the ISO7301 reference.

Localities

Citations can include details of where in the document the citation is located (or the word “whole”); these 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. Any 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 AsciiDoc cross-reference.

The locality can appear in quotations if it contains special characters (like dashes or commas). For 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">>

More examples:

<<ISO712,the foregoing reference>>     # renders as: the foregoing reference
<<ISO712,section=5, page 8-10>>         # renders as: ISO 712, Section 5, Page 8-10
<<ISO712,section=5, page=8-10: 5:8-10>> # renders as ISO 712, 5:8-10 ("5:8-10" treated as replacement text for all the foregoing)
<<ISO712,whole>>                        # renders as: ISO 712, Whole of text

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

A custom locality can be entered by prefixing it with locality::

<<ISO712,locality:frontispiece=5, page=8-10>>         # renders as: ISO 712, Frontispiece 5, Page 8-10

Custom localities may not contain commas, colons, or space. Localities with the locality: prefix are recognized in internationalization configuration files.

Any text after the bibliographic localities is still treated as custom cross-reference text; for example:

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

Automatic reference fetching

Relaton can fetch bibliographic entries for any standards known to have online bibliographic databases (ISO, IEC, IETF, GB, NIST, OGC, CalConnect).

Any bibliographic entry recognized through its document identifier prefix will by default have its bibliographic entry fetched by that gem. The fetched data overrides any content about the item provided in the document, since the online bibliography is treated as the source of truth for that standards document.

The format of the standard identifier required for automatic lookup is documeted at Automatic reference lookup.

For example, the following will trigger auto-fetching:

* [[[ref1,ISO 20483]]]

and gets rendered as:

  • ISO 20483:2013. Cereals and cereal products — Determination of moisture content — Reference method