This document documents the handling of references in the version of Metanorma AsciiDoc aligned with RFC XML v3 [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.0]. This version of AsciiDoc is much closer aligned to the rest of Metanorma than the version used in previous versions; in particular, the processing of references is consistent with that in the rest of Metanorma.
|This section supplements References & Bibliography in general Metanorma documentation.|
Embedded in Document
References in IETF AsciiDoc are processed as they are in the rest of Metanorma. References are defined with anchors and identifiers in a bibliographic entry list. If the identifier is recognised as a standard with online data (including IETF standards), the bibliographic data for that identifier is fetched, cached locally, and inserted into the Metanorma XML.
So for example
* [[[RFC7152,RFC 7152]]] will be
recognised as a citation of RFC 7152, and the corresponding bibliographic data will be fetched from the
corresponding online source. However, that data will be fetched not in its native RFC XML, but in Relaton
XML, as with the rest of Metanorma; a reference to
* [[[ISO639-2,ISO 639-2]]] would not be treated any
That said, any references recognised as being to IETF standards will include the URI for their RFC XML source,
and they will be replaced with an
xi:include link to that URI as an external reference, as is recommended
by default for IETF references. That means that the generated RFC XML v3 will still end up referencing
native RFC XML references.
Other Relaton XML references are converted to RFC XML
reference elements: in practice, such
are limited to containing author names, title, URI, document identifier, keywords, abstract, and publication date.
If no personal authors or editors are supplied, organisations are named again; if no authors or editors are
named at all (as is usual for standards), the publishing standards organisation is named as the author instead.
The document identifier is prefixed to the document title, as there is no separate provision for an identifier
in RFC XML.
A reference not auto-fetched from online sources is either a preformatted citation treated as a block,
or else a full citation, entered through AsciiBib. If the citation is preformatted, it is converted
to a standalone
reference/title, with no authors or dates. If the citation is broken down into elements,
it is processed as with auto-fetched references:
[bibliography] == Normative References // dispreferred encoding! * [[[ref1,1]]] MacDonald, Ian. 1991. _The New Shostakovich._ Boston: Northeastern University Press. // preferred encoding! [%bibitem] === The New Shostakovich (1) id:: ref1 (2) contributor.role:: author contributor.person.name.initial:: I. (3) contributor.person.name.surname:: MacDonald (4) link:: https://www.amazon.co.uk/New-Shostakovich-Ian-MacDonald/dp/184595064X (5) link:: type::: googlebooks (6) content::: https://books.google.com.au/books/about/The_new_Shostakovich.html?id=Arm7AAAAIAAJ (7) date:: (8) type::: published value::: 1991 keyword:: music (9) keyword:: Soviet Union (9) abstract:: (10) + --- Who was Dmitri Shostakovich? The USSR's official figurehead composer and son of the revolution that brought the Soviet state into being, or a secret dissident whose contempt for the totalitarian regime was scathing? Perhaps both? ---
As of this writing, the following features of RFC XML v3 referencing are not supported:
Raw RFC XML included in document source, or referenced directly from document source.
Internet draft versions
An IETF Internet Draft version by default is cited exactly as it is given in the online repository of Internet Drafts hosted by the IETF in https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/, including the version given there:
[bibliography] == References * [[[abarth,IETF(I-D.abarth-cake)]]], _Title_
<bibliography> <references id="_references" obligation="informative"> <title>Bibliography</title> <bibitem id="I-D.abarth-cake" type="standard"> ... <uri type="TXT">http://www.ietf.org/internet-drafts/draft-abarth-cake-01.txt</uri> <docidentifier type='IETF'>I-D.abarth-cake</docidentifier> <docidentifier type="Internet-Draft">draft-abarth-cake-01</docidentifier>
If the Internet Draft is given with a version number
-nn, the URI in the reference
and the document identifier is updated to cite that version [added in https://github.com/relaton/relaton-ietf/releases/tag/v0.9.0]:
[bibliography] == References * [[[abarth,IETF(I-D.abarth-cake-02)]]], _Title_
<bibliography> <references id="_references" obligation="informative"> <title>Bibliography</title> <bibitem id="I-D.abarth-cake" type="standard"> ... <uri type="TXT">http://www.ietf.org/internet-drafts/draft-abarth-cake-02.txt</uri> <docidentifier type='IETF'>I-D.abarth-cake</docidentifier> <docidentifier type="Internet-Draft">draft-abarth-cake-02</docidentifier>
The cache of current IETF and IRTF workgroups is built from screen-scraping the contents of:
The caches are fetched on launch. If you want to refresh the caches,
insert the document attribute
:flush-caches: trueinto the header of the document being processed.