References and bibliography
General
In standard documents typically there are two types of references, namely the “Normative references” and the “Bibliography” (informative references).
The following fixed clause names identifies a bibliography:
Normative referencesBibliography
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 of creating the “Normative references” clause in an ISO deliverable
In ISO, the “Normative references” clause is stated in Clause 2 (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 2 of an ISO deliverable
[bibliography]
== Normative references
* [[[ISO8601-1,ISO 8601-1:2019]]] _First normative reference_
* [[[ISO8601-2,ISO 8601-2:2019]]] _Second normative reference_
...
// This is after the last clause of an ISO deliverable
[bibliography]
== Bibliography
* [[[ISO10241-1,ISO 10241-1]]] _First bibliographic reference_
...Normative and informative references are normally recognised by the distinct title given them, specific to the flavour; however, the normative status of the bibliographic section can be given explicitly with a normative boolean attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.7]:
[bibliography,normative=true]
== References normative
...
[bibliography,normative=false]
== References informativeBibliography 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 of having multiple bibliography sub-sections
== 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_== Bibliography in the above EXAMPLE was preceded by [bibliography].In Metanorma IETF, the bibliography sections “Normative references” and “Informative references” are separate, where the “Informative references” section is optional:
[bibliography]
== Normative references
* [[[id1,1]]], _First normative reference_
...
// Optional
[bibliography]
== Informative references
* [[[idn, n]]], _First informative reference_
...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
General
In the "Normative references" clause, any content before the list of references is ignored, and replaced by predefined text specific to the Metanorma flavour.
The predefined text may vary according to the contents of the bibliography:
- an empty bibliography will usually have different initial text from a bibliography with references;
- for some flavours, text will be different depending on whether the references are dated or not.
When located in a subclause
If the list of normative references are nested in a subclause, the predefined text is placed in the first clause that contains references, and no other clause types.
This is to allow the predefined text to be associated with nested bibliographies, but not clauses containing both references and other text [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12].
[bibliography]
== Normative references
// boilerplate goes here
[bibliography]
=== Simple references
[bibliography]
=== Complex references== General
=== Scope
[bibliography]
=== Normative references
// boilerplate goes hereOverriding predefined text
To override default predefined text, the user can provide their own initial text with an open block marked as boilerplate containing the text [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.0].
[bibliography]
== Normative references
[.boilerplate]
--
The following contract document is referred to in the text in such a
way that some or all of its content constitutes requirements of this
document.
--Moving predefined text
To move the default predefined text elsewhere in the bibliography structure, set the content of the boilerplate block as (default) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12].
The (default) text will be overwritten with the correct predefined text.
[bibliography]
== Normative references
[bibliography]
=== Normative references
[.boilerplate]
--
(default)
--Entering individual references
Bibliographic entries are entered as unordered lists in Metanorma AsciiDoc within a dedicated clause or section.
A single bibliographic entry must be preceded by a bibliographic anchor, in triple brackets, as shown in the following syntax:
* [[[{anchor},{document identifier or reference tag}]]], _{reference list text}_The following data elements are needed in a reference entry:
- anchor
- document identifier or reference tag
- reference list text
- anchor
- a user-defined string that is an internal identifier used for cross-referencing within the current document. This string is typically composed with ASCII characters and hyphens or underscores. Other characters are not recommended.WarningSee Anchor ID syntax for allowed characters in anchor IDs.
- document identifier
- the authoritative document identifier of the bibliographic item. Standardized deliverables such as International Standards from ISO and IEC are assigned authoritative identifiers, such as "ISO 8601-1" or "ISO 8601-1:2019". This is often used for auto-fetching of bibliographic details (see auto-fetch). When a document identifier is used, the reference tag is also set to be identical.
- reference tag
- a user-defined string used for rendering a mention of this bibliographic item in the resulting output. This is typically in a format defined by the user, or publication conventions adopted by the user. See reference-tags for more information.
- reference list text
- a user-defined, pre-formatted description about the bibliographic item. This text is either formatted according to ISO 690:2021, or publication conventions like MLA, APA or the Chicago Manual of Style. If encoded in the ISO 690:2021 format, the resulting citation will be a machine-readable one. If the bibliographic entry is auto-fetched, the reference list text can be left out, as it will instead be generated based on the fetched entry.
A bibliographic reference can optionally be followed by one or more notes. This allows an annotated bibliography to be generated. Notes are sorted together with their preceding bibliographic entry, and are rendered as part of that entry.
* [[[ref1,ISO 639:1988]]], _Code for individual languages and language groups_
NOTE: This standard was subsequently split up from 1998 into parts.
NOTE: This was the first edition to use two-letter codes.
* [[[ref2,ISO 639-2:1998]]], _Code for individual languages and language groups, Part 2: Alpha-3 code_
NOTE: This is the first instance of three-letter codes in ISO-639.Best practice
There are several ways of entering bibliographic references as shown in entering-refs.
As best practice, we recommend the following order of entering bibliographic references, only using a later method if the former method does not:
- autofetch
- Manual encoding
It is strongly recommended that the automatic fetching method be used for data consistency, correctness, and the ease of use whenever possible.
If automatic fetching is not available for a particular reference, and if machine-readability or accurate rendering is important, either use annotated citation spans or AsciiBib for entering structured and detailed bibliographic information within a document.
The basic form of a reference is a pre-formatted reference, which relies on the user to supply a properly formatted reference.
Reference tags
Named reference tags
Named reference tag with automatic reference fetching
Users can provide both their own alphanumeric label, and the well-defined publication identifier for a cited standards document.
If the publication identifier is recognized for auto-fetching, the bibliographic entry will be automatically retrieved. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.15]:
If the publication identifier is not recognized for auto-fetching, the bibliographic entry will display the user-supplied reference list text after the comma.
If a named reference is to be auto-fetched, it is entered by prefixing the named reference tag (in parentheses) to the publication identifier:
* [[[{anchor},({reference tag}){publication identifier}]]], _{reference list text}_.Example of named reference tag fetched automatically
* [[[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)_Rich-text formatting is supported within the named reference tag [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.3].
.Example of rich-text formatting in named reference tag
* [[[ISO9000,(ISO/IEC Guide **99**:2007)ISO/IEC Guide 99:2007]]]
* [[[ISO9000,(ISO 9000:2005 footnote:[Superseded by ISO 9000:2015.])ISO 9000:2005]]]The preferred way of modifying a fetched reference to add a footnote indicating its status (added to the reference tag in most flavours) is to give a footnote after the citation. This is useful for cases where a cited reference is out-of-date but unsuitable to be updated [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.1.6].
.Example of added footnote to a named reference tag (ISO/IEC 17025:2017)
* [[[ISO_IEC_Guide_99_2007,ISO/IEC Guide 99:2007]]] footnote:[Also known as JCGM 200]
* [[[ISO_IEC_17000_2004,ISO/IEC 17000:2004]]]
Entering bibliographic references
Automatic fetching via Relaton ("auto-fetch")
General
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 the appropriate Relaton extension.
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.
Standards identifier / Document identifier lookup
The format of the standard identifier required for automatic lookup is documented at Automatic reference lookup.
.Example of specifying an auto-fetched reference
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
DOI identifier lookup
DOI identifiers are supported as auto-fetch targets [added in https://github.com/relaton/relaton-cli/releases/tag/v1.14.0] through the Crossref bibliographic information service.
This means that any book, journal article, conference paper or dataset that has a DOI and bibliographic information at Crossref can be cited by providing its DOI identifier as its bibliographic tag. Metanorma will import the bibliographic details of the reference from Relaton and format them in the required format of the current Metanorma flavour.
This is triggered by an identifier string prefixed with doi: or DOI , followed by the full DOI identifier.
.Example of specifying an auto-fetched DOI reference
The following will trigger auto-fetching:
* [[[ref1,doi:10.1045/november2010-massart]]]and gets rendered as:
Massart D., Shulman E., Nicholas N., Ward N., & Bergeron F. Taming the Metadata Beast: ILOX. D-Lib Magazine Vol. 16 No. 11/12. November 2010. Available from: http://dx.doi.org/10.1045/november2010-massart"
ISBN identifier lookup
ISBN identifiers are supported as auto-fetch targets [added in https://github.com/relaton/relaton-cli/releases/tag/v1.14.0] through the OpenLibrary API service [added in https://github.com/relaton/relaton-cli/releases/tag/v1.17.2].
This is triggered by an identifier string prefixed with isbn: or ISBN , with the number following the ISBN-10 or ISBN-13 number, with or without dashes.
.Example of specifying an auto-fetched ISBN reference
The following will trigger auto-fetching:
* [[[ref1,ISBN 978-0-12-064481-0]]]and gets rendered as:
Arvo, J. Graphics gems II. 1991. Boston, London: AP Professional.
Automatic fetching of joint publications
Metanorma recognises two types of joint publication:
- Joint publications proper (or merged publications), in which the one document is considered to be published simultaneously by two different standards bodies.
- Dual publications, for which the publications are treated as separate bibliographic entries, listed together with phrasing like "also published as:".
[[[anchor,merge(CODE1, CODE2)]]]merges together the two bibliographic entries fetched underCODE1andCODE2: the bibliographic entry is that ofCODE1, but the publication information ofCODE2(the publishing organisation and the distinct document identifier) are added to the entry.[[[anchor,dual(CODE1, CODE2)]]]treats the two bibliographic entries separately.
Referencing from a Metanorma collection
Metanorma allows bibliographic entries to be specified for retrieval from a Metanorma collection [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1].
Details on Collections cross-referencing. 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.
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.
repo:(...) function is mutually exclusive to path:(...), they cannot be used together.Referencing an attachment
Metanorma allows entries to specify file attachments, as described in Attachments [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10].
This is achieved with the following syntax:
* [[[anchor,attachment:(file location of attachment relative to current file)]]]Referencing from Metanorma or Relaton files
Metanorma allows bibliographic entries to be specified by either relative or absolute paths [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], where a path leads to a Metanorma XML or a Relaton RXL reference file.
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.
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.
path:(...) function is mutually exclusive to repo:(...), they cannot be used together.Entering pre-formatted references
For generic references, by default, Metanorma only supports formatted references, which are given as such in the AsciiDoc source.
.Example of a pre-formatted reference
[bibliography]
== Normative references
* [[[edge_mesh,Edge Mesh]]], Y. SAHNI, J. CAO, S. ZHANG and L. YANG.
_Edge Mesh: A New Paradigm to Enable Distributed Intelligence in Internet of Things_.
In: IEEE Access, vol. 5, pp. 16441-16458, 2017, doi: 10.1109/ACCESS.2017.2739804.This is rendered as:
[1] Y. SAHNI, J. CAO, S. ZHANG and L. YANG. Edge Mesh: A New Paradigm to Enable Distributed Intelligence in Internet of Things. In: IEEE Access, vol. 5, pp. 16441-16458, 2017, doi: 10.1109/ACCESS.2017.2739804.
Encoding semantic bibliographic elements ("bibliographic spans")
General
Metanorma supports semantic markup of bibliographic entries, to allow generation of machine-readable references from pre-formatted reference entries.
Different from a pre-formatted reference, of which the entire content is treated as a single block of text to be rendered as-is, with no further processing, semantic markup allows authors to mark up segments of a reference semantically to generate a machine-readable reference that suits the flavor's citation style.
A pre-formatted reference like the following is human-readable, but does not indicate to Metanorma how to extract useful information from it -- what the document identifier is, who the authors are, who the editors are, etc.
.Example encoding of a pre-formatted bibliographic item
Wozniak, S., Jobs, Steve, & Hoover, J. Edgar. 1991 [1996]. _Work_ In Gates W. H. &
UNICEF (eds.), Collected Essays. _Bibiographers Anonymous_, 5: 2–21. ISO 1234.
Geneva: International Standardization Organization. http://www.example.comMetanorma provides the "bibliographic span" mechanism to allow authors to annotate critical bibliographic information as the content of the list item that declares the bibliographic entry. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6].
This method allows authors to provide bibliographic information at a level of detail supported by the Relaton citation model. The span categories supported are described below.
In the resulting reference text, any punctuation or formatting will be provided by Metanorma, following the flavor's reference style.
Syntax:
* [[[anchor,reference tag]]],
span:{span-type}[{span content}]
span:{span-type}[{span content}]
...
span:{span-type}[{span content}]Textual annotation
Metanorma supports annotations surrounding the bibliographic spans in the reference.
While Metanorma only processes the content within the spans, authors can choose to add punctuation, formatting and other text around the spans for readability.
.Example encoding of a bibliographic item inline with semantic markup
These two entries are equivalent.
With no punctuation or formatting:
* [[[A, B]]],
span:surname[Wozniak] span:initials[S.]
span:surname[Jobs] span:givenname[Steve]
span:surname[Hoover] span:initials[J.] span:givenname[Edgar]
span:date.issued[1991]
span:date[1996]
span:title[Work]
span:in_surname.editor[Gates] span:in_initials.editor[W. H]
span:in_organization[UNICEF]
span:in_title[Collected Essays]
span:series[Bibliographers Anonymous]
span:docid.ISO[ISO 1234]
span:pubplace[Geneva]
span:publisher[International Standardization Organization]
span:uri.citation[http://www.example.com]
span:volume[5]
span:pages[2-21]
span:type[inbook]With punctuation and formatting:
* [[[A, B]]],
span:surname[Wozniak], span:initials[S.], span:surname[Jobs], span:givenname[Steve],
& span:surname[Hoover], span:initials[J.] span:givenname[Edgar].
span:date.issued[1991].
span:date[1996].
span:title[_Work_].
In span:in_surname.editor[Gates], span:in_initials.editor[W. H] &
span:in_organization[UNICEF],
span:in_title[Collected Essays].
_span:series[Bibliographers Anonymous]._
span:docid.ISO[ISO 1234].
span:pubplace[Geneva]:
span:publisher[International Standardization Organization].
span:uri.citation[http://www.example.com].
vol. span:volume[5],
pp. span:pages[2-21]
span:type[inbook]Note the distinction made in the example between Wozniak and Jobs (authors of the paper), and Gates and UNICEF (editors of the book including the paper). Similarly, note the distinction between the title of the paper (Work), and the title of the book including the paper (Collected Essays).
Supported bibliographic span types
The span types supported are not an exhaustive list of bibliographic fields. If more detail is required (or a dynamically generated reference is to be generated), one of the following explicit bibliographic entry methods should be used instead.
The span categories supported are:
surname- Author surname. Must always precede the initials or the given name of an author.
initials- Author initials.
givenname- Author given name.
fullname- Combination of author surname and initials or given names, according to strict syntax (see below) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.0]
organization- Corporate author.
surname.XXX- Contributor surname, with role XXX (e.g. editor).
initials.XXX- Contributor initials, with role XXX (e.g. editor).
givenname.XXX- Contributor given name, with role XXX (e.g. editor).
fullname.XXX- Contributor full name, with role XXX (e.g. editor).
organization.XXX- Corporate contributor, with role XXX (e.g. editor).
title- Title.
in_title- Title of containing bibliographic item. For types
inbook,inproceedings,incollection, the title of the book, proceedings, collection containing the item. in_surname,in_initials,in_givenname,in_organization- Name of contributor for containing bibliographic item
For types
inbook,inproceedings,incollection, the author or more usually editor of the book, proceedings, collection containing the item.So
in_surname.editor,in_givenname.editorgive the name of the editor of the book or proceedings that a paper is included in. series- Series title. For articles, this is the journal title.
docid- Document identifier.
docid.XXX- Document identifier, of type
XXX. The identifiers follow Relaton XML practice, and the following types are in place for the major classes of bibliographic identifier:
metanorma-ordinal- ordinal number provided for reference, normally supplied automatically by Metanorma and used only for bibliography
title- identifier repeating the title of the reference, supplied automatically in normative reference contexts when no other identifier has been provided
metanorma- identifier not otherwise recognised as specific to an SDO
repository- link to other document in a Metanorma collection
ISBN- This identifier is an International Standard Book Number (ISBN-10 or ISBN-13)
ISSN- This identifier is an International Standard Serial Number (ISSN-8 or ISSN-13)
DOI- This identifier is a Digital Object Identifier (DOI)
URN- This identifier is a Uniform Resource Name (
urn:namespace) ISO- This identifier is an International Organization for Standardization publication identifier
IEC- This identifier is an International Electrotechnical Commission publication identifier
IETF- This identifier is an Internet Engineering Task Force publication identifier
IEEE- This identifier is an Institute of Electrical and Electronics Engineers publication identifier
BIPM- This identifier is a Bureau International des Poids et Mesures publication identifier
BSI- This identifier is a British Standards Institution publication identifier
NIST- This identifier is a National Institute of Standards and Technology publication identifier
JIS- This identifier is a Japanese Industrial Standards publication identifier
ITU- This identifier is an International Telecommunication Union publication identifier
IHO- This identifier is an International Hydrographic Organization publication identifier
CalConnect- This identifier is a CalConnect publication identifier
PLATEAU- This identifier is a PLATEAU publication identifier
Ribose- This identifier is a Ribose publication identifier
publisher- Publisher.
pubplace- Place of publication.
date- Date published. All dates in Metanorma are entered in ISO 8601-1:2019
YYYY-MM-DDformat. date.XXX- Date with type XXX (e.g. published, created, issued)
edition- Edition
version- Version
note- Note (can also be used for miscellaneous content)
note.XXX- Note, of a specialized type XXX. More than one type can be applied to a note; in that case, the different values are comma delimited.
More than one note can be present in a bibliographic entry. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.3.0]
For notes that are intended to be rendered with bibliographic entries, as part of an annotated bibliography, the note type
displayis required.Example* [[[A,1]]] span:note.display,editorial[This entry may be revised later.] * [[[B,1]]] span:note.display[This entry may be revised later.] uri- URI.
uri.XXX- URI, of type XXX.
classification- Classification of bibliographic resource [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
classification.XXX- Classification of bibliographic resource as being of type XXX [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
span:classification.color[red]can be interpreted as "the bibliographic resource is classified as having color: red". keyword- Keyword of bibliographic resource [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.1.9]
abstract- Abstract of bibliographic resource, can contain inline markup [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
pages- page or page range (e.g. 9, 9-11)
issue- issue or issue range (e.g. 9, 9-11)
volume- volume or volume range (e.g. 9, 9-11)
language- language of citation (ISO 639-2 encoding) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.2.0]. Used for localisation and internationalisaton of citation rendering.
script- script of citation (ISO 15924 encoding) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.2.0]. Used for localisation and internationalisaton of citation rendering.
locale- locale of citation (encoded per IETF RFC 5646, Clause 2.2.4) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.2.0]. Used for localisation and internationalisaton of citation rendering.
type- Document type. List of valid document types given in Relaton model -- Bibitem type. The type is suppressed from rendering. If not supplied, it is assumed to be
standard. It is vital to provide this field, if the reference is not a standard: most bibliographic fields are ignored when rendering standards.standard, book, inbook
If spans are used, an inline image included in the reference is interpreted as the depiction of the resource [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
span:title[Standard 123] image:thumbnail.jpg[]span:surname[Fields], span:initials:[W.C.], never span:initials:[W.C.] span:surname[Fields].surname and either initials or givenname, any subsequent instances of surname or either initials or givenname are interpreted as belonging to a new contributor of the same role.span:fullname[] is intended as a convenience method to substitute span:surname[], span:initials[], span:givenname[] in a single macro. It has a strict syntax, and any special cases need to be marked up with the separate, explicit name parts instead:- The surname is a single word (space-delimited), occurring at the end. See the examples below.
span:fullname[A. D. Navarro Cortez]- surname is Cortez.
span:initials[A. D.] span:surname[Navarro Cortez]- surname is Navarro Cortez.
span:fullname[A. D. Navarro-Cortez]- surname is Navarro-Cortez.
- Anything before the surname is a given name. So in
span:fullnamename[J. Edgar Hoover], both J. and Edgar are processed as given names. - If everything before the surname ends in a full stop, they are all deemed initials. So in
span:fullname[A. D. Navarro Cortez], A. D. are parsed as initials.
After the first instances of surname and either initials or givenname, any subsequent instance of surname is interpreted as belonging to a new contributor of the same role.
Any given names and surnames MUST follow the surname that they relate to. If the names are ordered differently between the first and subsequent name, e.g. Wozniak, S. & Steve Jobs, that will be taken care of in rendering: they cannot be annotated in that way.
For presentations,
titleis the title of the presentationseriesis the title of the conferenceorganization.distributoris the organizer of the conference
The rendering of different bibliographic types is quite different in the various stylesheets that SDOs follow, and strange things will happen if Metanorma gets the bibliographic type wrong.
Under Metanorma, the default bibliographic type is standard, and most SDOs render standards in bibliographies with very little data (no author, no publisher, no date outside of the document identifier, and so on).
If you use this notation to enter any document other than a standard, you must specify the type of document, using span:type[].
Last access date auto-retrieval and override
Metanorma supports auto-retrieval of URLs in order to set the "last accessed" date for a bibliographic item with URL.
This is performed through the relaton-render gem, where the URLs in the reference will be tried for access, and Metanorma styles the result to align to the flavour's bibliographical stylesheet.
Append span:date.accessed[2020-01-01] at the end of the reference.
If your flavour requires date last accessed to be supplied for references with URLs, you should use date.accessed[...] to do so.
If you do not do so, Metanorma will try to access the URLs in the reference automatically.
If the URI is not accessible, no date last accessed will be given.
Typically, SDO expectation is that authors should provide dates last accessed for references they have reviewed themselves.
Auto-fetch bibliographic date cut-off
When a document is published, it is published with a bibliography that reflects the state of the bibliography at the time of publication. This means that if a reference is cited with no publication date, in a document with a publication date of 2019, its bibliography should represent the status of references as of 2019, which is what the document would have been published with.
Metanorma supports this principle of bibliographic date cut-off, to prevent anachronism when compiling older documents.
This feature is achieved by configuring Relaton to fetch the version of the reference as of the document date of publication or last update, if the reference is cited with no publication date.
This means that if a reference was published before 2019, but entered into draft in 2022, the version of the reference fetched for the 2019 document should present the cited document as published as of 2019, not as draft as of 2022.
Overriding auto-fetched reference fields
Depending on the quality of the bibliographic record fetched, it may be necessary to amend or emend the auto-fetched information.
Auto-fetched references can be altered by specifying the amend(...) function on the document identifier of the reference, and then providing amended information fields using the bibliographic span notation (span:...[]) to override the auto-fetched information. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.1.3].
If the amend(...) function is not used, the bibliographic spans will be treated as a full override: the auto-fetched information will be ignored, and only the information in the bibliographic spans will be used for the reference.
The bibliographic span notation (span:...[]) is used to specify bibliographic fields to a bibliographic record in the bibliography [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.4].
- Data encoded in the title following the bibliographic anchor with
span:[]is used to supplement auto-fetched information. - If the
spaninformation presents information absent in the fetched record, it is added to the record. - If the
spaninformation presents information corresponding in the fetched record, it overwrites it. - Information is broken down by type:
- If an identifier, or URI, or date is of a given type, it overwrites only identifiers of the same type in the fetched record (e.g.
span:docid.BSI[BSI EN 8000],span:date.published[2010]).
- The same applies to contributors: contributors of a given type overwrite only contributors of the same type in the fetched record.
- For document identifiers, you will need the type of the SDO issuing the document, which is typically the standard organization abbreviation. Look at the Semantic XML of the document for the currently fetched document, to make sure.
- Information is replaced, not additive.
To illustrate, the following citation modifies the record fetched from Crossref.
* [[[ref1,amend(doi:10.1045/november2010-massart)]]],
span:surname.author[Johnson], span:givenname.author[Boris],
span:pages[8-10],
span:date.published[2021]The modifications are:
- The pages span are added to the source record, which contains volume and issue information, but no page information.
- The authors listed for the source record are overwritten by the single author "Boris Johnson".
- The date published is overwritten by the new date 2021. The date the article was issued, by contrast, is left alone.
Importing bibliographic records from other formats
Metanorma can import files containing bibliographic records in other formats [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.9]. To date, only Bibtex is supported.
In order to specify an external Bibtex file, use the relaton-data-source document attribute:
:relaton-data-source: path/to/bibtex-fileIn order to specify multiple external Bibtex files, use relaton-data-source-{id} document attributes, where the value of {id} is the source identifier used to differentiate each import file:
:relaton-data-source-bib1: path/to/first/bibtex-file
:relaton-data-source-bib2: path/to/second/bibtex-fileReferences to a bibliographic item imported this way are expressed in the bibliography with the bibliographic anchor local-file(SOURCE, KEY), where SOURCE is the name of the source identifier for the import file, and KEY is the identifier of the reference in the import file. So given the import statements above,
== Bibliography
* [[[ref1, local-file(bib1, tc211)]]]will import the reference inside the Bibtex file path/to/first/bibtex-file (the value of relaton-data-source-bib1) that starts as e.g.
@book{tc211
...
}If only one file was imported through relaton-data-source, the source identifier is omitted (or else "default" is used):
== Bibliography
* [[[ref1, local-file(tc211)]]]Entering with AsciiBib
Bibliographic entries can be entered in the AsciiBib format.
AsciiBib is a bibliography entry format that uses AsciiDoc definition lists to capture the structure of Relaton XML.
This approach is documented in relaton.org.
.Example of entering an entry using AsciiBib (ISO 123) with an AsciiBib ID
[bibliography]
== Normative references
[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid::
type::: ISO
id::: ISO 123
docid::
type::: ABC
id::: 32784
type:: standardThe id attribute of %bibitem clauses (the anchor of the clause) can be overridden by a Metanorma AsciiDoc anchor on the clause [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1].
This can be required for Metanorma AsciiDoc to process cross-references correctly.
_, as Metanorma AsciiDoc uses that to indicate anchors it inserts automatically, which are not supplied in the source..Example of entering an entry using AsciiBib (ISO 123) with an AsciiDoc anchor
[bibliography]
== Normative references
[[iso123]]
[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid::
type::: ISO
id::: ISO 123
docid::
type::: ABC
id::: 32784
type:: standardSuppressing display
It is expected that if a citation is made in the main body of the document, its corresponding reference will be included in the bibliography. It is however possible to suppress display of that reference in the bibliography, by wrapping it in hidden() [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.4].
[bibliography]
== Bibliography
* [[[ref1,hidden(ISO 639-1)]]], ISO 639-1.
* [[[ref2,ISO 639-2]]], ISO 639-2.Entering with Relaton XML (EXPERT only)
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.
.Example of entering an entry using Relaton XML (ISO 1)
[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>
++++Reference processing flags
General
Various processing flags can be entered at the document identifier element to specify different reference processing behaviour. All such flags are optional.
Reference processing flags need to be entered according to the following patterns:
[[[{anchor},nofetch(hidden(dropid({document identifier or reference tag})))]]]nofetch()- Disable automatic lookup of references. See disable-auto-fetch
hidden()- Do not show this item in the bibliography. See hidden-citations.
dropid()- Do not display the document identifier. See dropid.
repo:() and path:() functions are to be entered as document identifiers in this pattern.Disable auto-fetch with `nofetch()`
Ignoring document identifiers with `dropid()`
The document identifier is critical to formulating both citations and bibliographies. There are times, however, where the supplied document identifier is to be ignored in bibliographies.
When a manual bibliographic item is entered (not auto-fetched), with a user-defined anchor and the document identifier in triple brackets, followed by bibliographic details provided as text.
In this case, the bibliographic item is rendered with the document identifier placed in brackets after the provided bibliographic details, as it is shown in dropid-example-1.
.Example of a manually-entered bibliographic item with document identifier shown after bibliographic details
* [[[id1,ELOT 743]]], _Transliteration of Greek into Roman script._Notice that the document identifier is placed in brackets after the provided bibliographic details:
[1] Transliteration of Greek into Roman script. [ELOT 743]
There are situations where it is useful to suppress the document identifier in the bibliography, for example:
- the bibliographic item is not a standard, so the identifier should not be used;
- there is no authoritative form for the document identifier for this bibliographic item.
The dropid() [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.4] citation processing flag can be used to suppress the appearance of the document identifier in the bibliography.
.Example of using dropid(...) to drop rendering of a document identifier in the bibliography
* [[[id1,dropid(GIBBON)]]], Gibbon, Edward. 1776-1789. _Decline and fall of the Roman Empire._ London: Strahan & Cadell.The resulting rendering omits the document identifier:
[1] Gibbon, Edward. 1776-1789. Decline and fall of the Roman Empire. London: Strahan & Cadell.
As noted above, leaving the refeence tag as a space has the same effect: *[[[id, ]]], Gibbon....
CSV notation
The notation shown up to this point for reference processing flags has the potential of being too complicated to parse, if deeply nested or if the parentheses of flags are combined with the parentheses of user-supplied labels or of "all parts".
For that reason, an alternative notation is supported, involving key/value pairs delimited by comma and equals signs in the anchor label [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4].
For example, the following two references are equivalent:
[bibliography]
== Normative references
* [[[iso8601_1,nofetch((Date-Time)ISO 8601-1:2019)]]], _Date and time — Representations for information interchange — Part 1: Basic rules_
* [[[iso8601_1a,nofetch=true,usrlabel=Date-Time,code=ISO 8601-1:2019]]], _Date and time — Representations for information interchange — Part 1: Basic rules_The CSV-based notation has the following keys:
nofetchtrue|falsehiddentrue|falsedropidtrue|falselocal-file- (filename of local Relaton cache)
repo- (repository name)/(document entry)
path- (file path)
number- (number, for a numeric ID of a citation)
usrlabel- (user-supplied label of reference)
code- (authoritative identifier of reference)
If no key is supplied in the CSV entry, it is assumed to be a code; e.g. nofetch=true,usrlabel=Date-Time,ISO 8601-1:2019 is interpreted as nofetch=true,usrlabel=Date-Time,code=ISO 8601-1:2019.