References & Bibliography
General
In standard documents typically there are two types of references, namely the “normative references” and the “bibliography” (informative references).
Every bibliographic section must be preceded by the style attribute
[bibliography]
so that references they contain may be recognized as such:
[bibliography]
== Bibliography
* [[[id1,1]]] _First reference_
* [[[id2,2]]] _Second reference_
* [[[id3,3]]] _Third reference_
EXAMPLE: In ISO, the “Normative references” clause is stated in Clause 3 (ISO Directives Part 2, Clause 15), while the “Bibliography” section is set as the last unnumbered section at the end of document (ISO Directives Part 2, Clause 21). It should be typeset as the following:
...
// This is clause 3
[bibliography]
== Normative references
* [[[ISO8601-1,ISO 8601-1:2019]]] _First normative reference_
* [[[ISO8601-2,ISO 8601-2:2019]]] _Second normative reference_
...
// This is the last section
[bibliography]
== Bibliography
* [[[ISO10241-1,ISO 10241-1]]] _First bibliographic reference_
...
Bibliography sections can be split into subsections.
Metanorma AsciiDoc requires each subsection containing references
to be styled with [bibliography]
, and raises an (ignorable)
warning if the subsections are contained in a section itself
styled with [bibliography]
.
EXAMPLE:
== Bibliography
[bibliography]
=== Part 1
* [[[id1,1]]] _First reference_
* [[[id2,2]]] _Second reference_
* [[[id3,3]]] _Third reference_
[bibliography]
=== Part 2
* [[[id4,4]]] _Fourth reference_
* [[[id5,5]]] _Fifth reference_
* [[[id6,6]]] _Sixth reference_
Note
|
A warning will be raised if == Bibliography in the above EXAMPLE was
preceded by [bibliography] .
|
Note
|
In Metanorma IETF, the bibliography sections “Normative references” and “Informative references” are separate, where the “Informative references” section is optional:
See References (AsciiRFC v3) for further details. |
Numbering and ordering
All entries in a bibliography section, whether standards or generic, are renumbered incrementally in the Metanorma 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 sections from what has been entered by the authors. Some Metanorma flavours will reorder references to suit document requirements.
That said, all references in a references section are grouped together, even if there is intervening text in the source document. Only notes are left attached to their reference, in order to enable annotated bibliographies.
Predefined text
Any initial text in a Normative Reference section (before the first reference) is replaced by predefined text specific to the Metanorma flavour.
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, consisting of:
-
an internal identifier (used within Metanorma AsciiDoc for cross-references); and
-
a document identifier.
This is illustrated as:
* [[[{anchor},{document identifier or reference tag}]]], _{reference list text}_
Warning
|
See Anchor ID syntax for allowed characters in anchor IDs. |
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
).
This is entered as:
* [[[{anchor},{document identifier as reference tag}]]], _{reference list text}_
EXAMPLE:
* [[[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)
A well-defined standards code as the item label will by default result in the reference details for the bibliographic entry being auto-fetched, provided that auto-fetching has been defined for that class of standard (Automatic reference fetching ("auto-fetch")).
Numeric reference tags
Generic references in bibliographies, as opposed to standards
references, use numbers, which are rendered bracketed, like [1]
.
This is entered as:
* [[[{anchor},{number}]]], _{reference list text}_
EXAMPLE:
* [[[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. |
Normative references must use either standard document identifiers, or named reference tags.
Note
|
Numeric references cannot be used for entries in normative references, as bibliography numbering starts at 1. Execution will abort if a numeric reference tag is found in normative references, in order to prevent numbering confusion [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.4]. |
Named reference tags
General
References can be tagged with user-supplied alphanumeric labels, in addition to numbers or standard document identifiers.
These are indicated by wrapping the label within the bibliographic anchor in brackets.
Named reference tag with fully specified bibliographic entry
If the reference text is fully specified, and where no auto-fetching of the bibliographic entry is necessary, a user-supplied label is entered using the following syntax:
* [[[{anchor},({reference tag})]]], _{reference list text}_
Note
|
These alphanumeric labels will not result in the bibliographic entry being auto-fetched. |
EXAMPLE:
* [[[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)
Named reference tag with automatic reference fetching
Users can provide both their own alphanumeric label, and the well-defined reference identification code for the standards document.
This will result in the bibliographic entry being auto-fetched, so long as that auto-fetch is supported for that class of references [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.15]:
If a named reference is to be auto-fetched, it is entered by prefixing the named reference tag (in parentheses) to the document identifier:
* [[[{anchor},({reference tag}){reference identification code}]]], _{reference list text}_
EXAMPLE:
* [[[ISO20483,(CerMoist)ISO 20483]]], _ISO 20483:2013 Cereals and cereal products -- Determination of moisture content -- Reference method_
* [[[ISO6540,(MaiMoist)ISO 6540]]]. _ISO 6540:1980 Maize -- Determination of moisture content (on milled grains and on whole grains)_
Alternate bibliography formats
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>
++++
AsciiBib
Finally, bibliographic entries can be entered as AsciiDoc definition lists, capturing the structure of Relaton XML. This approach is documented in relaton.com.
[bibliography]
== Normative References
[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid::
type::: ISO
id::: ISO 123
docid::
type::: ABC
id::: 32784
type:: standard
The id
attribute of bibitem clauses (the anchor of the clause) can be overridden by an AsciiDoc
anchor on the clause [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].
This can be required for AsciiDoc to process crossreferences correctly. Any such anchors must not be
preceded by _
, as AsciiDoc uses that to indicate anchors it inserts automatically, which are not
supplied in the source.
[bibliography]
== Normative References
[[iso123]]
[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid::
type::: ISO
id::: ISO 123
docid::
type::: ABC
id::: 32784
type:: standard
Citations
Citations of references in Metanorma 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 <<ISO7301,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.
-
By default, these are interpreted as hierarchically refining a single location in a text, through consecutive narrower localities
EXAMPLE: “Part IV, Chapter 3, paragraph 12”:
<<ref1,part=IV,chapter=3,paragraph=12>>
-
Discontinuous localities can be named by repeating the same locality type
EXAMPLE: “page 4, page 7”:
<<ref1,page=4,page=7>>
-
Discontinuous references can also be be specified by delimiting sequences of localities with semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.24]
EXAMPLE: “Part IV, Chapter 3; Part VI, Chapter 9”:
<<ref1,part=IV,chapter=3;part=VI,chapter=9>>
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:
// renders as: "the foregoing reference"
<<ISO712,the foregoing reference>>
// renders as: "ISO 712, Section 5, Page 8-10"
<<ISO712,section=5, page 8-10>>
// 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>>
// renders as: "ISO 712, Whole of text"
<<ISO712,whole>>
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:
:
// renders as: "ISO 712, Frontispiece 5, Page 8-10"
<<ISO712,locality: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>>
Anchors
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()
):
see HTML links.
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>
Automatic reference fetching ("auto-fetch")
Relaton databases
Relaton can fetch bibliographic entries for any standards known to have online bibliographic databases.
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 documented at Automatic reference lookup.
Note
|
Currently Metanorma supports auto-fetching document identifiers from: ISO, IEC, IETF, GB, NIST, OGC, CalConnect. |
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
Other databases
Metanorma allows bibliographic entries to be specified for retrieval from arbitrary databases [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].
This is achieved with the following syntax:
* [[[anchor,repo:(repository-name/document-entry,document-identifier)]]]
This retrieves item document-entry
from repository repository-name
; the document
identifier "document-identifier" is retained in order for citations to remain well-formed.
Bibliographical information about the entry is not auto-fetched via Relaton.
By default, repo:(repository-name/document-entry)
is left in the Metanorma XML as
a document identifier, of type "repo"; it will typically be resolved in post-processing.
HTML links
Metanorma allows bibliographic entries to be specified by either relative or absolute hyperlink [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].
This is achieved with the following syntax:
* [[[anchor,path:(hyperlink,document-identifier)]]]
As with repo:()
bibliographic entries, the document
identifier document-identifier
is retained in order for citations to remain well-formed.
Bibliographical information about the entry is not auto-fetched via Relaton. Instead, if the hyperlink is local, Metanorma will look for an XML (Metanorma XML) or RXL (Relaton XML) file at the nominated location with the same filename, and read in the bibliographic metadata from there.
All citations of this entry in the document (referencing anchor
) will be rendered with
the hyperlink in HTML.