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

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  .

Shared RFC XML v3/v2 syntax:

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

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

:equivalent:

(Any status) URL for any alternate representation of this document. RFC XML: front/link[@rel = 'alternate']/@href

: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

  • true

    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: front/seriesInfo@value,: `rfc@docName

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

: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

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

:submission-type

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

  • IETF (default)

  • independent

  • IAB

  • IRTF

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

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. 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]”). RFC XML: rfc@symRefs

:toc-include:

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

: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

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

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

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

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

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 concatenated with "\ ". 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

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.