Metanorma: Aequitate Verum

Metanorma for IETF

References (AsciiRFC v2)

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.

Note
 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 [bibliography], 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)
++++

  1. back/references/reference

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.

External Directory

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 :normative: 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.)

For example:

= 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)

  1. 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 RFC2119 is optional, and in fact will be ignored, since the anchor is recognized as an external reference. A file corresponding to I-D.abarth-cake will not be ignored, if that file contains a seriesInfo element nominating a specific draft version.

  2. The references in the ./refs directory are by default considered informative; this attribute indicates that RFC2119 and AsciiDoc are to be considered normative.

  3. Metanorma-IETF differentiates between bibliographic references and cross-references to other anchors within the document.

  4. 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 RFC2119 or 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 references@anchor 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 http://xml.resource.org/public/rfc/, 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 <reference anchor="RFC2119"/>, 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 seriesInfo element 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.)

Caches

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 xml2rfc. If you want to refresh the caches,

  • delete your ~/.metanorma-ietf-biblio-cache.json and ~/.metanorma-ietf-workgroup-cache.json files;

  • insert the document attribute :flush-caches: true into 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].