References (AsciiRFC v3)

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.

Note	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 differently.

Note	Metanorma will automatically convert references containing other references (with `relation[@type = 'includes']` into `referencegroup` elements [added in https://github.com/relaton/relaton-ietf/releases/tag/v3.3.1]. That includes references automatically fetched by Relaton.

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 reference elements 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 or bibliographic spans notation. 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!

[[ref2]] (1)
[%bibitem]
=== The New Shostakovich (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?
---

back/references/reference/@anchor
back/references/reference/front/title
back/references/reference/front/author/@initials
back/references/reference/front/author/@surname
back/references/reference/@target
back/references/reference/format/@type
back/references/reference/format/@target
back/references/reference/front/date
back/references/reference/front/keyword
back/references/reference/front/abstract

As of this writing, the following features of RFC XML v3 referencing are not supported:

displayreference
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>

Caches

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,

delete your ~/.metanorma-ietf-workgroup-cache.json file;
insert the document attribute :flush-caches: true into the header of the document being processed.