Document attributes

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 (in v3)

    • 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 (in v3)

    • rfc@docName will be set to the :name: attribute (in v2)

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

    • rfc/front/seriesInfo@name attribute will be set to RFC (in v3)

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

    • rfc@number will be set to the :name: attribute (in v2)

      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.

:inline-definition-lists:

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.

: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 ~/.asciidoc-rfc-biblio-cache.json and ~/.asciidoc-rfc-workgroup-cache.json.

:biblio-dir:

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.

:normative:

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

:abbrev:

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

:ipr:

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

:ipr-extract:

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

:obsoletes:

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

:updates:

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

:submission-type:

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

:revdate:

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

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

  • true (mapped in v2 to: yes)

    RFC XML: rfc@consensus

Different RFC XML v3/v2 syntax:

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

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

    • RFC XML v3: front/seriesInfo@value

    • RFC XML v2: rfc@docName

  • rfc: the value should be a number like 7991 as described here

    • RFC XML v3: front/seriesInfo@value

    • RFC XML v2: rfc@number

:status

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

  • fyi (v3 only)

  • full-standard (v3 only)

  • historic (v2 only).

  • RFC XML v3: front/seriesInfo[1]/@status

  • RFC XML v2: rfc@category

:intended-series

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 v3: front/seriesInfo[2]/@status; front/seriesInfo[2]/@name = ""

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

:submission-type

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

  • IETF (default)

  • independent

  • IAB

  • IRTF

  • RFC XML v3: rfc@submissionType and rfc/front/seriesInfo@stream

  • RFC XML v2: rfc@submissionType

RFC XML v2 only

:series-no:

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

RFC XML v3 only

: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

:sort-refs:

Optional. Defaults to false. Values: true or false. Specifies whether the prep tool should sort references. Supported in v2 as a processing instruction. RFC XML: rfc@sortRefs

: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]”). Supported in v2 as a processing instruction. RFC XML: rfc@symRefs

:toc-include:

Optional. Defaults to true. Values: true or false. Specifies whether formatter should contain a table of contents. Supported in v2 as a processing instruction. RFC XML: rfc@tocInclude

:link: URL, URL REL

Optional. Comma-delimited links to an external document related to this document. RFC XML: front/link@href = URL, front/link@rel = REL (if supplied)

There are 4 types of values:

  1. (RFC only) ISSN for this RFC document (rel set to item, link value in form of urn:issn:);

  2. (RFC only) DOI for this RFC document (rel set to describedBy, link value in form specified by RFC7669);

  3. (Final Draft) Internet-Draft submitted to become published RFC (rel set to convertedFrom, link value set to "IETF-controlled web site that retains copies of Internet-Drafts");

  4. (Any status) ISSN (rel set to alternate, link value as any author run web site).

Processing Instructions

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 v3 RFC XML 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.

: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

:compact:

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

: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 boilerplate 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.

:rfcprocack:

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

:slides:

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

:sort-refs:

(sortrefs) sort references

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

:sym-refs:

(symrefs) use anchors rather than numbers for references

: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-content

:toc-depth:

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

:tocindent:

if toc 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 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 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

:fullname{_i}:

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

:forename_initials{_i}:

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

:lastname{_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

:organization{_i}:

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

:organization_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

: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

:street{_i}:

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{_i}:

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

:region{_i}:

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{_i}:

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

:code{_i}:

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

:postal-line{_i}:

Used to directly format postal addresses without regard to the prior types. Ignored in RFC XML v2. Multiple lines are concatenated with "\ ". The postal-line attribute is mutually exclusive with the presence of street, city, region, country and code attributes. RFC XML: front/author/address/postal/postalLine

This source:

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

Produces this RFC XML output:

<address>
  <postal>
    <street>57 Mt Pleasant St</street>
    <street>Technology Park</street>
    <city>Dullsville</city>
    <region>NSW</region>
    <code>3333</code>
    <country>Australia</country>
  </postal>
</address>

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.