Metanorma: Aequitate Verum

Metanorma for IETF

Document attributes (AsciiRFC v2)

Note

The document attributes listed below 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

:doctype:

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

: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 ~/.metanorma-ietf-biblio-cache.json and ~/.metanorma-ietf-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.

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: &nbsp; in the header for example will be rendered as &nbsp;.

Note
 Most attributes listed here, unless specifically stated, are common between AsciiRFC v3 (RFC XML v3) and AsciiRFC v2 (RFC XML v2).
= 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

: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: rfc@docName

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

    Note
    		 Usage here differs from usage in AsciiRFC v3.
: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

  • historic

    RFC XML rfc@category

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

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)

    Note
    		 Usage here differs from usage in AsciiRFC v3.
: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

Note
 This attribute is only available in AsciiRFC v3.
:submission-type

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

  • IETF (default)

  • independent

  • IAB

  • IRTF

    RFC XML: rfc@submissionType

    Note
    		 Usage here differs from usage in AsciiRFC v3.
: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

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

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>

Attributes for xml2rfc 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 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.

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 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:
: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-include: is "yes", then this determines the depth of the table-of-contents

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