Metanorma: Aequitate Verum

Metanorma for IETF

Document attributes (AsciiRFC v3)

Note

The document attributes listed below are unique to Metanorma’s processing of RFC XML v3 IETF documents, [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.0]. The document attributes particular to RFC XML v2, and used in previous versions of this gem, are given separately.

For common document attributes, see Document attributes reference in general Metanorma author’s documentation. That page describes attributes that apply to all Metanorma flavors, not just IETF.

For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

Document type

:doctype:

Specifies document status. Choices:

  • :doctype: internet-draft sets the document as an Internet-Draft (default value):

    • rfc/front/seriesInfo@name attribute will be set to Internet-Draft

    • rfc/front/seriesInfo@value will be set to the value of :name: attribute, stripping any file suffixes, but including any draft number; e.g. draft-ietf-somewg-someprotocol-07

    • rfc@docName will be set to the :docnumber: attribute

  • :doctype: rfc sets the document as an RFC:

    • rfc/front/seriesInfo@name attribute will be set to RFC

    • rfc/front/seriesInfo@value will be set to the value of :name: attribute, stripping the initial rfc- prefix and any file suffixes

    • rfc@number will be set to the :name: attribute

      Defaults to internet-draft.

Global options

:no-rfc-bold-bcp14:

Optional. Default value true. Allowed values: true, false. Override default assumption that boldface uppercase BCP14 word is to be rendered with bcp14 tag.

:smart-quotes:

Optional. Default value true. Allowed values: true, false. Permit smart quotes, when they are specified explicitly in AsciiDoc (as "`...`", '`...`'). When disabled, smart quotes are rendered as straight quotes, and Asciidoc’s default conversion of straight apostrophes to smart is undone.

:flush-caches:

Optional. Default value false. Allowed values: true, false. Delete and reload the caches of references to be included externally, and of workgroups, during processing of this document. The caches are stored in ~/.metanorma-ietf-biblio-cache.json and ~/.metanorma-ietf-workgroup-cache.json.

Note
 Workgroups are no longer fetched externally; they are bundled with gem releases [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.4.0]. ~/.metanorma-ietf-workgroup-cache.json is therefore no longer used.
:use-xinclude:

Optional. Default value true. Allowed values: true, false. If present, references to IETF documents are handled as XIncludes as recommended by IETF’s "xml2rfc Frequently Asked Questions, 3.1". Otherwise, they are left as embedded XML.

Setting this to false allows you to compile final output using xmlrfc with cached reference content without triggering its Internet-fetching functionality ("xml2rfc Frequently Asked Questions, 3.2") [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.8]

Document attributes

Metanorma-IETF allows setting the RFC XML document header using the following document attributes. Complying with AsciiDoc syntax, no blank lines are permitted between the title, listing of authors, and the document attributes.

Also following AsciiDoc syntax, character entities will be ignored in the document header:   in the header for example will be rendered as  .

Note
 Most attributes listed here, unless specifically stated, are common between AsciiRFC v3 (RFC XML v3) and AsciiRFC v2 (RFC XML v2).
:title:

Mandatory. Title of document. RFC XML: rfc/front/title

:abbrev:

Mandatory. Abbreviation of document title. Usually the document name without the keyword draft-. RFC XML: rfc/front/title@abbrev

:asciititle:

ASCII version of the title, in case author wants to override the default ASCII equivalent generated by Ruby (through the sterile gem).

:name

Mandatory. Sets the document’s name. This should be a number if the document is an RFC, and a name (in the form of draft-ietf-somewg-someprotocol-07) if it is an Internet-Draft (in which case it should be expressed under the :docnumber: attribute).

When doctype is set to:

  • internet-draft: the value should be in the form draft-ietf-somewg-someprotocol-07. RFC XML: front/seriesInfo@value,: `rfc@docName

  • rfc: the value should be a number like 7991 as described here RFC XML: front/seriesInfo@value, rfc@number

    Note
    		 Usage here differs from usage in AsciiRFC v2.
:status

Set the current status of this document. Synonym: :docstage:. The following values are allowed:

  • standard

  • informational

  • experimental

  • bcp

  • fyi

  • full-standard

    RFC XML: front/seriesInfo[1]/@status, rfc@category.

    Note
    		 Usage here differs from usage in AsciiRFC v2.
:intended-series

Mandatory. Set the intended series of this document. Space delimited. For Internet Drafts, this indicates the intended series once the document is published as an RFC. For RFCs, this indicates the current status of the document. The following values are allowed:

  • standard (I.-D. only)

  • informational

  • experimental

  • bcp (I.-D. only)

  • bcp nnnn (RFC only, where nnnn is the document number)

  • fyi (I.-D. only)

  • fyi nnnn (RFC only, where nnnn is the document number)

  • full-standard (I.-D. only)

  • full-standard nnnn (RFC only, where nnnn is the document number)

  • historic

    RFC XML: front/seriesInfo[2]/@status; front/seriesInfo[2]/@name = ""; front/@category (exp and historic only supported for Internet Drafts; document number not used).

    Note
    		 This differs from usage in AsciiRFC v2. Metanorma-IETF takes care of any needed translation between the v2 vocabulary (e.g. info) and the v3 vocabulary (e.g. informational).
:submission-type

Set document submission type for this document. The following values are allowed:

  • IETF (default)

  • independent

  • IAB

  • IRTF

  • editorial

    RFC XML: rfc@submissionType and rfc/front/seriesInfo@stream.

    Note
    		 Usage here differs from usage in AsciiRFC v2.
:ipr:

Mandatory. IP status of document. See here. Defaults to trust200902. RFC XML: rfc@ipr.

Note
 Usage here differs from usage in AsciiRFC v2.
:ipr-extract:

Optional. Identifies a section that can be extracted from text. See here. RFC XML: rfc@iprExtract.

Note
 Usage here differs from usage in AsciiRFC v2.
:obsoletes:

Optional. A comma-separated list of identifiers of standards that this document obsoletes. If these are IETF documents, they must be identified using Relaton conventions: RFC 7991, IETF(draft-ietf-acvp-subsha). Delimited by comma + space. RFC XML: rfc@obsoletes

:updates:

Optional. A comma-separated list of identifiers of standards that this document updates. If these are IETF documents, they must be identified using Relaton conventions: RFC 7991, IETF(draft-ietf-acvp-subsha). Delimited by comma + space. RFC XML: rfc@updates

:included-in:

(RFC only) ISSN for this RFC document. Identifiers expected to be in form of urn:issn:. RFC XML: front/link[@rel = 'item']/@href.

Note
 The odd selection of :included-in: is in fact the closest match to the link type "item" used in RFC 7991.
:described-by:

DOI for this RFC document. Identifiers expected to be in form specified by RFC7669. RFC XML: front/link[@rel = 'describedby']/@href

:derived-from:

(Final Draft) Internet-Draft submitted to become published RFC. If these are IETF documents, they must be identified with the URL of the Internet Draft on the IETF-controlled web site that retains copies of Internet-Drafts. RFC XML: front/link[@rel = 'convertedFrom']/@href

:instance-of:

(Any status) URL for any alternate representation of this document. RFC XML: front/link[@rel = 'alternate']/@href [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.8]

Note
 Formerly this was called :equivalent: and :instance:.
:submission-type:

Optional. Document stream of document described in RFC7841. Allowed values: IETF (default), independent, IAB, and IRTF. RFC XML: rfc@submissionType

:published-date:

Optional. Latest revision date of published document. Default value is current date. Accepts ISO 8601 date. Also accepts YYYY year, and YYYY[-]MM year/month. For consistency with AsciiDoc, :revdate: is given as an ISO 8601 date; the converter breaks it down into day, month name and year. RFC XML: front/date@day, front/date@month, front/date@year

:circulated-date:

Optional. Latest revision date of draft document. (The two are not differentiated in RFC XML; :circulated-date: is used if :published-date: is not available.) Default value is current date. Accepts ISO 8601 date. Also accepts YYYY year, and YYYY[-]MM year/month. For consistency with AsciiDoc, :revdate: is given as an ISO 8601 date; the converter breaks it down into day, month name and year. RFC XML: front/date@day, front/date@month, front/date@year

:area:

Optional. Comma delimited text on which IETF area this document relates to. Value should “be either the full name or the abbreviation of one of the IETF areas as listed on http://www.ietf.org/iesg/area.html”. See here. RFC XML: front/area

:workgroup:

Optional. Comma delimited text on which IETF or IRTF workgroup or research group this document originates from. See here. RFC XML: front/workgroup

:keyword:

Optional. Comma delimited text for singular keywords used for RFC index and metadata. RFC XML: front/keyword

:xml-lang:

Optional. Set the document language. By default this is en. RFC XML: rfc@xml:lang

:consensus:

Set document consensus for this document. The following values are allowed:

  • false

  • true

    RFC XML: rfc@consensus

:index-include:

Optional. Defaults to true. Values: true or false. Specifies whether formatter should include an index in generated files. If the source file has no <iref> elements, an index is never generated. RFC XML: rfc@indexInclude

Note
 This attribute is new in AsciiRFC v3 (RFC XML v3).
:sort-refs:

Optional. Defaults to false. Values: true or false. Specifies whether the prep tool should sort references. RFC XML: rfc@sortRefs

Note
 This attribute is new in AsciiRFC v3 (RFC XML v3).
:sym-refs:

Optional. Defaults to true. Values: true or false. Specifies whether formatter should use symbolic references (such as “[RFC2119]”) or not (such as “[3]”). RFC XML: rfc@symRefs

Note
 This attribute is new in AsciiRFC v3 (RFC XML v3).
:toc-include:

Optional. Defaults to true. Values: true or false. Specifies whether formatter should contain a table of contents. RFC XML: rfc@tocInclude

Note
 This attribute is new in AsciiRFC v3 (RFC XML v3).
:toc-depth:

Determines the depth of the table-of-contents; e.g. a value of 3 means three levels of heading are included. RFC XML: rfc@tocDepth

Note
 This attribute is new in AsciiRFC v3 (RFC XML v3).
:show-on-front-page:

Display organization of author on front page of IAB documents (default: true). Introduced in Levkowetz' implementation notes. RFC XML: organization/@showOnFrontPage, applied to all organizations named in the document front matter.

Note
 This attribute is new in AsciiRFC v3 (RFC XML v3).
Example 1. Example of document metadata for an IETF document
= The Holy Hand Grenade of Antioch
Arthur son of Uther Pendragon
:doctype: internet-draft
:submission-type: independent
:intended-series: informational
:docnumber: draft-camelot-holy-grenade-01
:status: informational

Author attributes

As multiple authors can be specified, the document attribute to specify the first author uses a unsuffixed attribute name :role, and the second author’s attributes onwards use a numeric suffix to identify the author: :role_2, :role_3, etc.

Name and affiliation

:fullname{_i}:

Optional. Author’s full name. Can set here instead of document header’s “Author” line. RFC XML: front/author@fullname

:initials{_i}:

Optional. Author’s initials excluding surname. RFC XML: front/author@initials

:givenname{_i}:

Given names of Author. Not used directly in RFC XML, but initials can be derived from them if not explicitly included. RFC XML: front/author@initials

:surname{_i}:

Optional. Author’s last name. Can set here instead of document header’s “Author” line. RFC XML: front/author@surname

:role{_i}:

Optional. Defaults to author. Possible values: author, editor. If author is supplied, the attribute is not populated. RFC XML: front/author@role

:affiliation{_i}:

Optional. Defaults to "". Author’s organization affiliation. RFC XML: front/author/organization

:affiliation_abbrev{_i}:

Optional. Defaults to "". Author’s organization’s abbreviation shown. RFC XML: front/author/organization@abbrev

Note
 You can provide organization information without providing name information for an author.

Address

:email{_i}:

Email of author. RFC XML: front/author/address/email

:fax{_i}:

Fax number of author. Deprecated in v3. RFC XML: front/author/address/facsimile

:contributor-uri{_i}:

URI of author. RFC XML: front/author/address/uri

:phone{_i}:

Author’s phone number. Scheme-specific part of a tel URI (does not include the prefix tel:). See RFC3966 global-number-digits. RFC XML: front/author/address/phone

:address{_i}:

Used to directly format postal addresses without regard to the prior types. Multiple lines are given as separate lines, each ending with a space, then a plus symbol, then a backslash symbol (" + \").

The postal-line attribute is mutually exclusive with the presence of street, city, region, country and code attributes (which are not currently supported).

RFC XML: front/author/address/postal/postalLine

:address: Palace + \
Camel Lot 1 + \
UK

Processing instructions for xml2rfc

The xml2rfc tool accepts processing instructions of the form <?rfc keyword='value'?>: see https://xml2rfc.tools.ietf.org/authoring/README.html#processing.instructions . (Of these, sort-refs, sym-refs and toc-include are also present in the RFC XML v3 specification, as attributes of the root rfc element: v3-specific document attributes.)

Those processing instructions which apply to the entire document can also be specified in Metanorma-IETF as document attributes.

:artworkdelimiter:

when producing txt or nroff files, use this string to delimit artwork

:artworklines:

when producing txt or nroff files, add this many blank lines around artwork

:authorship:

render author information

:autobreaks:

automatically force page breaks to avoid widows and orphans (not perfect)

:background:

when producing a HTML file, use this image

:colonspace:

put two spaces instead of one after each colon (“:”) in txt or nroff files

:comments:

render <cref> information

:docmapping:

use hierarchical tags (e.g., <h1>, <h2>, etc.) for (sub)section titles

:editing:

insert editing marks for ease of discussing draft versions

:emoticonic:

automatically replaces input sequences such as \|*text\| by, e.g., <strong>text</strong> in html output

:footer:

override the center footer string

:header:

override the leftmost header string

:inline:

if comments is "yes", then render comments inline; otherwise render them in an "Editorial Comments" section

:iprnotified:

include predefined text from Section 10.4(d) of http://tools.ietf.org/html/rfc2026

:linkmailto:

generate mailto: URL, as appropriate

:linefile:

a string like 35:file.xml or just 35 (file name then defaults to the containing file’s real name or to the latest linefile specification that changed it) that will be used to override xml2rfc's reckoning of the current input position (right after this PI) for warning and error reporting purposes (line numbers are 1-based)

:notedraftinprogress:

generates “(work in progress)”, as appropriate

:private:

produce a private memo rather than an RFC or Internet-Draft

:refparent:

title of the top-level section containing all references

:rfcedstyle:

attempt to closely follow finer details from the latest observable RFC-Editor style so as to minimize the probability of being sent back corrections after submission.

This directive is a kludge whose exact behavior is likely to change on a regular basis to match the current flavor of the month; presently, it will:

  • capitalize the adjective “This” in automatically generated headings,

  • use the variant “acknowledgement” spelling instead of Merriam Webster’s main “acknowledgment” dictionary entry,

  • use the “eMail” spelling instead of Knuth’s more modern “email” spelling,

  • only put one blank line instead of two before top sections,

  • omit “Intellectual Property and Copyright Statements” and “Author’s Address” from the table of content, and

  • not limit the indentation to a maximum tag length in <references> sections.

:slides:

when producing a HTML file, produce multiple files for a slide show

:strict:

try to enforce the ID-nits conventions and DTD validity

:subcompact:

if compact is yes, then you can make things a little less compact by setting this to no (the default value is the current value of the compact PI)

:text-list-symbols:

modify the list of symbols used (when generated text) for list type="symbols". For example, specifying abcde will cause “a” to be used for 1st level, “b” for the 2nd level, etc, cycling back to the first character “a” at the 6th level. Specifying o* will cause the characters “o” and "*" to be alternated for each successive level.

:toc-include:

(toc) generate a table-of-contents

:tocappendix:

control whether the word “Appendix” appears in the table-of-contents

:toc-depth:

if :toc-include: is yes, then this determines the depth of the table-of-contents; e.g. a value of 3 means three levels of heading are included

:tocindent:

if :toc-include: is yes, then setting this to yes will indent subsections in the table-of-contents

:tocnarrow:

affects horizontal spacing in the table-of-content

:tocompact:

if :toc-include: is yes, then setting this to no will make it a little less compact

:topblock:

put the famous header block on the first page

:useobject:

when producing a HTML file, use the <object> html element with inner replacement content instead of the <img> HTML element, when a source XML element includes a src attribute

Exceptionally, compact, toc-include, sym-refs, sort-refs and strict are is set by default to yes, subcompact to no, and toc-depth to 4.