Metanorma: Aequitate Verum

Upgrading Metanorma IETF documents from metanorma-ietf v1 to v2

Author’s picture Ronald Tse on 10 Jun 2020


Since metanorma-ietf v2 was released in January, we have been migrating a number of documents to the newer version.

In order to migrate Metanorma IETF documents to v2 you need to know what exactly has changed for the author:

  1. Metanorma-IETF now only supports RFC XML v3 output — IETF (and therefore xml2rfc) has already switched to RFC XML v3.

  2. Metanorma-IETF now generates a Metanorma XML file, and then converts it into a RFC XML file. xml2rfc is them used to convert the RFC XML file to TXT, HTML, etc.

  3. The bibliographic mechanism has entirely changed.

Changes needed

  1. In :mn-output-extensions:, the output format is now rfc not xmlrfc2 or xmlrfc3. (because we only support xmlrfc3 now)

  2. :submissionType: is now :submission-type:

  3. The :status:, :intended-series values are very picky in xml2rfc (xml2rfc will balk at the values full-standard and standard, info works)

  4. The references sections have changed — the mechanism to do RFC references is via auto-fetch and manual entry.

Migrating the bibliography

Automated reference fetching

Metanorma now supports the automatic fetching of many standard documents as citations.

This includes IETF RFCs/Internet-Drafts, ISO, IEC, ITU, W3C, NIST, CalConnect, OGC, etc.

EXAMPLE: Instead of doing this previously:

== Normative References

<reference anchor="RFC2119"
    <title>Key words for use in RFCs to Indicate
      Requirement Levels</title>
    <author initials="S." surname="Bradner" fullname="S. Bradner">
    <date year="1997" month="March"/>
  <seriesInfo name="BCP" value="14"/>
  <seriesInfo name="RFC" value="2119"/>
  <seriesInfo name="DOI" value="10.17487/RFC2119"/>

In IETF RFCs and I-Ds, you just need this:

== Normative References

* [[[RFC2119,RFC 2119]]]

Custom reference notation

For custom bibliographic items, Metanorma now supports AsciiBib, which is a way of specifying bibliographic data in an AsciiDoc-like syntax (with ASCII, of course).

EXAMPLE: Instead of doing this:

== Informative References

<reference anchor="grail_film">
    <title>Monty Python and the Holy Grail</title>
    <author initials="G." surname="Chapman"/>
    <author initials="J." surname="Cleese"/>
    <author initials="E." surname="Idle"/>
    <author initials="T." surname="Gilliam"/>
    <author initials="T." surname="Jones"/>
    <author initials="M." surname="Palin"/>
    <date year="1975"/>

Do this:

== Informative References

== Monty Python and the Holy Grail
contributor:: G. Chapman
contributor:: J. Cleese
contributor:: E. Idle
contributor:: T. Gilliam
contributor:: T. Jones
contributor:: M. Palin
date.type:: published
date.value:: 1975


Metanorma-IETF v2 heavily simplifies bibliographic handling and realizes a consistent syntax across all Metanorma flavors.

This is a blessing especially for those that work with multiple standardization bodies, where cross-publication is common.

Hope you enjoy the upgraded, declarative, authoring experience!