Document attributes (AsciiRFC v2)


Below are listed only document attributes that are unique to Metanorma’s processing of RFC XML v2 IETF documents. The document attributes particular to RFC XML v3, and used in the current version 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


Specifies document status. Choices:

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

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

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

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

      Defaults to internet-draft.

Global Options


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


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.


Optional. Default value false. Allowed values: true, false. Only applies to v2. By default, <vspace blankLines="1"> is inserted after the definition in a v2 definition list, to satisfy the requirement from idnits validation that definition terms be separated by a carriage return from the definition. That is, by default inline definition lists are rendered as paragraphing definition lists. If the option is on, the additional vspace element is not added, and inline definition lists are left as is.


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.


Optional. Name of directory. If present, gives the name of a directory from which RFC XML references are to be read into the document, rather than assuming the references are already present in the document.


Optional. Comma-delimited list of reference anchors. Used in conjunction with :biblio-dir:, which uses a single directory for all references: this attribute lists those references which are to be considered normative, and listed under the “Normative References” heading.

Basic 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 &nbsp;.

Shared RFC XML v3/v2 syntax:

= Document Title

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


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


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


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


Optional. A comma-separated list of RFC numbers or Internet-Draft names that this document obsoletes. Delimited by comma + space. RFC XML: rfc@obsoletes


Optional. A comma-separated list of RFC numbers or Internet-Draft names that this document updates. Delimited by comma + space. RFC XML: rfc@updates


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


Optional. Latest revision date of document. Default value is current time. 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


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 <>". See here. RFC XML: front/area


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


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


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


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

  • false (mapped in v2 to: no)

  • true (mapped in v2 to: yes)

    RFC XML: rfc@consensus

Different RFC XML v3/v2 syntax:


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. When doctype is set to:

  • internet-draft: the value should be in the form draft-ietf-somewg-someprotocol-07.

    • RFC XML: rfc@docName

  • rfc: the value should be a number like 7991 as described in here RFC XML: rfc@number


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

  • standard (mapped in v2 to: std)

  • informational (mapped in v2 to: info)

  • experimental (mapped in v2 to: exp)

  • bcp

  • historic

    RFC XML rfc@category


Mandatory. Set the intended series of this document. 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) (mapped in v2 to: std)

  • informational (mapped in v2 to: info)

  • experimental (mapped in v2 to: exp)

  • 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) (mapped in v2 to: std)

  • full-standard nnnn (RFC only, where nnnn is the document number) (mapped in v2 to: std)

  • historic

    RFC XML front/@category (exp and historic only supported for Internet Drafts; document number not used)


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

  • IETF (default)

  • independent

  • IAB

  • IRTF

    RFC XML: rfc@submissionType

RFC XML v2 only


Optional. The document series is defined by the category attribute; seriesNo is only applicable to the values info ("FYI" series), std ("STD" series), and bcp ("BCP" series). RFC XML v3 counterpart: rfc@seriesNo

Processing Instructions

The xml2rfc tool accepts processing instructions of the form <?rfc keyword='value'?>: see . (Of these, sort-refs, sym-refs and toc-include are also present in the RFC XML v3 specifcation, 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 options.


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


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


render author information


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


when producing a HTML file, use this image


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


render <cref> information


when producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the rfcedstyle PI)


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


insert editing marks for ease of discussing draft versions


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


override the center footer string


override the leftmost header string


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


include boilerplate from Section 10.4(d) of


generate mailto: URL, as appropriate


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)


generates "(work in progress)", as appropriate


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


title of the top-level section containing all references


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.


if there already is an automatically generated Acknowledg(e)ment section, pluralize its title and add a short sentence acknowledging that xml2rfc was used in the document’s production to process an input XML source file in RFC-2629 format


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


(sortrefs) sort references


try to enforce the ID-nits conventions and DTD validity


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)


(symrefs) use anchors rather than numbers for references


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) generate a table-of-contents


control whether the word "Appendix" appears in the table-of-content


if :toc-include: is "yes", then this determines the depth of the table-of-contents


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


affects horizontal spacing in the table-of-content


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


put the famous header block on the first page


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 an 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.

The additional document option rfc2629xslt (default value: true) injects into the document header the processing instruction <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>, which impacts on the output of xml2rfc.

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


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


Optional. Author’s initials excluding surname. Defaults to dynamically calculated initials. Distinct from the AsciiDoc :initials: attribute, which includes surname. RFC XML: front/author@initials


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


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


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


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

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



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


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


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


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 of author, non-city/region/code/country portion. Multiple lines concatenated with "\ " will be split into separate <street> elements. RFC XML: front/author/address/postal/street


City portion of author’s address RFC XML: front/author/address/postal/city


Region, state or province portion of author’s address. For US/CA the 2-letter state code. RFC XML: front/author/address/postal/region


Country of author’s address RFC XML: front/author/address/postal/country


Postal code of author’s address RFC XML: front/author/address/postal/code

This source:

:street: 57 Mt Pleasant St\ Technology Park
:city: Dullsville
:region: NSW
:country: Australia
:code: 3333

Produces this RFC XML output:

    <street>57 Mt Pleasant St</street>
    <street>Technology Park</street>

Metanorma processing instructions

These instructions have been introduced for metanorma-ietf, to make processing more consistent with other flavours of Metanorma, or to customise its generation of XML.