This documents the handling of references in the previous version of Metanorma AsciiDoc aligned with RFC XML v2 [deprecated in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.0]. The current version of Metanorma AsciiDoc for IETF (aka AsciiRFC v3), which is aligned with RFC XML v3, is much closer aligned to the rest of Metanorma than this version. In particular, the current version uses native Metanorma representation of references, as auto-fetched via Relaton identifier, or notated as Relaton definition lists.
|This section supplements References & Bibliography in general Metanorma documentation.|
Embedded in Document
References are expected to be provided in raw RFC XML v2 format.
RFC requires two separate bibliographies, one for normative and one for informative references;
either can be omitted. All bibliography sections in the must be styled with the prefix
and must appear in sequence, before any appendices.
By default, the references cited must be included as raw RFC XML, and separated into the normative and informative sections.
[bibliography] == Normative References ++++ (raw XML) (1) ++++ [bibliography] == Informative References ++++ (raw XML) (1) ++++
In postprocessing, bibliographic entries available from http://xml.resource.org/public/rfc are replaced with external references to that entry, using XML entities. Do not insert your own entities or XML includes into the references; Metanorma-IETF will have difficulty processing them.
As an alternative, the document attribute
:biblio-dir: can nominate a directory
in which separate XML files can be placed, one for each reference to be included.
Metanorma-IETF will read in from that directory only the files that have actually been cited,
and insert them into the appropriate bibliography,
without the references needing to be given under the bibliographies as above.
(In fact, any XML already provided will be deleted.)
By default, references will be considered informative; the document attribute
can be used to specify a comma-delimited list of normative references.
Metanorma will issue a warning if any cited reference is not included in the directory. External references do not have to be included in the directory: they will be recognized by comparing their anchors against the external bibliography cache, and referenced as entities or includes. Particular drafts of Internet-Draft documents do still need to be included as separate documents (see Lookup of external references.)
= The Holy Hand Grenade of Antioch Arthur Pendragon :doctype: internet-draft :workgroup: silly :biblio-dir: refs (1) :normative: RFC2119, AsciiDoc (2) [[xyz]] == Hello Hello * a <<RFC2119,See internet draft subsection 2.3>> * b <<I-D.abarth-cake>> * b2 <<I-D.abarth-cake,what>> * b1 <<I-D.abarth-cake,See internet draft subsection 2.3>> * c <<xyz,format=counter: xyzzy>> (3) * d <<biblio>> (4) * e <<AsciiDoc,AsciiDoctor>> * f <<mathrefs>> [[biblio]] === Biblio See biblio [bibliography] == Normative References (4) [bibliography] == Informative References (4)
The RFC XML references are included in the directory
./refs, with one file per reference. For example, we would expect it to contain a file corresponding to the reference
mathrefs. A file corresponding to
RFC2119is optional, and in fact will be ignored, since the anchor is recognized as an external reference. A file corresponding to
I-D.abarth-cakewill not be ignored, if that file contains a
seriesInfoelement nominating a specific draft version.
The references in the
./refsdirectory are by default considered informative; this attribute indicates that
AsciiDocare to be considered normative.
Metanorma-IETF differentiates between bibliographic references and cross-references to other anchors within the document.
The bibliographic headers need to be provided as above, and its titles are expected to be "Normative References" and "Informative References"; Metanorma will look for those titles specifically in order to insert the references it identifies from the file. However, no XML content is expected to be provided under each heading, and any XML content that is provided will be ignored.
Lookup of external references
In order to speed the lookup of references on the http://xml.resource.org/public/rfc website for external
references, a cache of references is built the first time the gem is run, in the user’s home directory:
~/.metanorma-ietf-biblio-cache.json. This maps all the canonical anchors for external references as defined
by the IETF, such as
CCITT.E163.1988, to the URLs that their RFC reference is stored on.
References are detected for replacement in the AsciiDoc document by matching the
attribute to one of those canonical anchors; the content of the local RFC XML reference is not checked.
(For rebuilding the cache, see Caches.)
Rather than hand crafting RFC XML references for RFC documents, or other references hosted at
you need only create a dummy
<reference> element containing the IETF-defined anchor for that citation. In postprocessing, any
references that are hosted at xml.resource.org will be identified by their anchor, and replaced by entities.
(The complete list of authoritative
RFC XML bibliographies is available from https://xml2rfc.tools.ietf.org , online and in zipped form.)
Because the content of any externally defined
<reference> element is overwritten with an entity or include,
you do not need to provide a full reference. You can supply a minimal reference like
but note that such a reference is invalid in the RFC XML schema, and the gem will report a missing element during processing.
(The document will still be processed successfully.) To prevent any validation error reports, the minimal syntactically valid reference is:
<reference anchor="RFC2119"> <front> <title/> <author/> <date/> </front> </reference>
If you wish to cite a specific version of an Internet-Draft, you will need to include the
in the reference that identifies the specific version; the anchor is the same for all internet drafts. For example:
<reference anchor="I-D.abarth-cake"> <front> <title/> <author/> <date/> </front> <seriesInfo name="Internet-Draft" value="draft-abarth-cake-00"/> </reference>
As discussed under External Directory, any citations of specific versions of an Internet-Draft need to be included as explicit files in an external directory of RFC XML references, since the seriesInfo draft information cannot be recovered by the anchor. However, any other external references do not require a corresponding directory file (although normative references do still need to be named in the
:normative: document attribute.)
The cache of externally addressable bibliographic information is built from screenscraping the contents of:
The caches are not rebuilt daily, as the bibliographic cache is with
If you want to refresh the caches,
insert the document attribute
:flush-caches: trueinto the header of the document being processed; or
run the asciidoctor executable with option
-a flush-caches=true(which has the same effect).
Formerly a cache of current IETF and IRTF workgroups was also built from screenscraping the contents of:
This functionality has moved to being bundled with new gem releases, instead of being cached dynamically [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.4.0].