greenbytes GmbH

Hafenweg 16 MuensterNW48155 Germany julian.reschke@greenbytes.de http://greenbytes.de/tech/webdav/

This document defines the 'XML2RFC' vocabulary; an XML-based (Extensible Markup Language) language used for writing Internet Drafts and RFCs. Discussion of this draft takes place on the XML2RFC mailing list (xml2rfc@ietf.org), which has its home page at .

This document describes version 2 ('v2') of the 'XML2RFC' vocabulary; an XML language () used for writing RFCs () and Internet Drafts (). It obsoletes the original version ("v1") , which contained the original language definition, and which was subsequently extended ("v2"). Furthermore, it discusses potential extensions in a future revision ("v3").

The vocabulary is defined in prose, based on the Relax NG schema () contained in . Note that the schema can be used for automated validity checks, but certain constraints are only described in prose.

Need to fill in element and attribute descriptions.

Contains the abstract of the document. The abstract ought to be self-contained and thus should not contain references or unexpanded abbreviations. See Section 4.3 of for more information. This element appears as child element of: <front> ().

one or more <t> elements ()

Provides address information for the author. This element appears as child element of: <author> ().

one optional <postal> element () one optional <phone> element () one optional <facsimile> element () one optional <email> element () one optional <uri> element ()

This element appears as child element of: <reference> ().

In any order: text <xref> elements () <eref> elements () <iref> elements () <cref> elements () <spanx> elements ()

This element appears as child element of: <front> ().

text

This element appears as child element of: <figure> ().

(optional) Allowed values: "left" (default) "center" "right"

(optional)

(optional)

(optional)

(optional)

(optional)

(optional)

(optional) Allowed values: "default" "preserve" (default)

text

This element appears as child element of: <front> ().

(optional)

(optional)

(optional) Allowed values: "editor"

(optional)

one optional <organization> element () one optional <address> element ()

This element appears as child element of: <rfc> ().

optional <references> elements () optional <section> elements ()

This element appears as child element of: <texttable> ().

In any order: text <xref> elements () <eref> elements () <iref> elements () <cref> elements () <spanx> elements ()

This element appears as child element of: <postal> ().

text

This element appears as child element of: <postal> ().

text

This element appears as child element of: <postal> ().

text

This element appears as child element of: <annotation> (), <c> (), <postamble> (), <preamble> (), and <t> ().

(optional)

(optional)

text

Provides information about the publication date. Note that this element is used both for the boilerplate of the document being produced, and also inside bibliographic references. In the first case, it defines the publication date, which, when producing internet drafts, will be used for computing the expiration date. When "year", "month" or "day" are left out, the processor will attempt to use the current system date if the attributes that are specified do match the system date. Note that month names need to match thee full (English) month name ("January", "February", "March", "April", "May, "June", "July", "August", "September", "October", "November", or "December") in order for expiration calculations to work. In the second case, the date information will be embedded as-is into the reference text. Therefore, also vague dates ("ca. 2000"), date ranges etc. are allowed. This element appears as child element of: <front> ().

(optional)

(optional)

(optional)

This element appears as child element of: <address> ().

text

This element appears as child element of: <annotation> (), <c> (), <postamble> (), <preamble> (), and <t> ().

(mandatory)

text

This element appears as child element of: <address> ().

text

This element appears as child element of: <section> (), and <t> ().

(optional) Allowed values: "left" (default) "center" "right"

(optional)

(optional)

(optional)

(optional)

(optional) Allowed values: "true" "false" (default)

(optional)

(optional)

optional <iref> elements () one optional <preamble> element () one <artwork> element () one optional <postamble> element ()

This element appears as child element of: <reference> ().

(optional)

(optional)

(mandatory)

This element appears as child element of: <reference> (), and <rfc> ().

one <title> element () one or more <author> elements () one <date> element () optional <area> elements () optional <workgroup> elements () optional <keyword> elements () one optional <abstract> element () optional <note> elements ()

This element appears as child element of: <annotation> (), <c> (), <figure> (), <postamble> (), <preamble> (), <section> (), and <t> ().

(mandatory)

(optional) Allowed values: "true" "false" (default)

(optional)

This element appears as child element of: <front> ().

text

This element appears as child element of: <t> ().

(optional)

(optional)

(optional)

one or more <t> elements ()

This element appears as child element of: <rfc> ().

one or more <section> elements ()

This element appears as child element of: <front> ().

(mandatory)

one or more <t> elements ()

This element appears as child element of: <author> ().

(optional)

text

This element appears as child element of: <address> ().

text

This element appears as child element of: <address> ().

one or more <street> elements () In any order: <city> elements () <region> elements () <code> elements () <country> elements ()

This element appears as child element of: <figure> (), and <texttable> ().

In any order: text <xref> elements () <eref> elements () <iref> elements () <cref> elements () <spanx> elements ()

This element appears as child element of: <figure> (), and <texttable> ().

In any order: text <xref> elements () <eref> elements () <iref> elements () <cref> elements () <spanx> elements ()

This element appears as child element of: <references> ().

(optional)

(optional)

one <front> element () optional <seriesInfo> elements () optional <format> elements () optional <annotation> elements ()

This element appears as child element of: <back> ().

(optional)

one or more <reference> elements ()

This element appears as child element of: <postal> ().

text

This is the root element of the xml2rfc vocabulary. Processors distinguish between RFC mode ("number" attribute being present) and Internet-Draft mode ("docname" attribute being present). It is invalid to specify both. Setting neither can be useful for producing other types of document (but is out-of-scope for this specification).

(optional) Document category (see ). Allowed values: "std" "bcp" "info" "exp" "historic"

(optional) Affects the generated boilerplate. See for more information. Allowed values: "no" "yes"

(optional) For Internet Drafts, this specifies the draft name (which appears below the title). Note that the file extension is not part of the draft, so in general it should end with the current draft number ("-", plus two digits). Furthermore, it is good practice to disambiguate current editor copies from submitted drafts (for instance, by replacing the draft number with the string "latest"). See Section 7 of for further information.

(optional) Represents the Intellectual Property status of the document. See for details. Allowed values: "full2026" "noDerivativeWorks2026" "none" "full3667" "noModification3667" "noDerivatives3667" "full3978" "noModification3978" "noDerivatives3978" "trust200811" "noModificationTrust200811" "noDerivativesTrust200811" "trust200902" "noModificationTrust200902" "noDerivativesTrust200902" "pre5378Trust200902"

(optional) Identifies a Section within the document for which extraction "as-is" is explicitly allowed (only relevant for historic values of the "ipr" attribute).

(optional) The number of the RFC to be produced.

(optional) A comma-separated list of RFC numbers or Internet-Draft names.

(optional) When producing a document within document series (such as "STD"): the number within that series.

(optional) The document stream. See Section 2 of for details. Allowed values: "IETF" (default) "IAB" "IRTF" "independent"

(optional) A comma-separated list of RFC numbers or Internet-Draft names.

(optional) The natural language used in the document (defaults to "en"). See Section 2.12 of for more information.

one <front> element () one <middle> element () one optional <back> element ()

This element appears as child element of: <back> (), <middle> (), and <section> ().

(optional)

(mandatory)

(optional) Allowed values: "include" "exclude" "default" (default)

In any order: <t> elements () <figure> elements () <texttable> elements () <iref> elements () optional <section> elements ()

Names the document series in which this document appears, and also specifies an identifier within that series. This element appears as child element of: <reference> ().

(mandatory) The name of the series. The following names trigger specific processing (such as for auto-generating links, and adding descriptions such as "work in progress"): "BCP", "FYI", "Internet-Draft", "RFC", and "STD".

(mandatory) The identifier within the series specified by the "name" attribute. For BCPs, FYIs, RFCs, and STDs this is the number within the series. For Internet Drafts, it is the full draft name (ending with the two-digit version number).

This element appears as child element of: <annotation> (), <c> (), <postamble> (), <preamble> (), and <t> ().

(optional)

(optional) Allowed values: "default" "preserve" (default)

text

This element appears as child element of: <postal> ().

text

This element appears as child element of: <abstract> (), <list> (), <note> (), and <section> ().

(optional)

(optional)

In any order: text <list> elements () <figure> elements () <xref> elements () <eref> elements () <iref> elements () <cref> elements () <spanx> elements () <vspace> elements ()

This element appears as child element of: <section> ().

(optional) Allowed values: "left" "center" (default) "right"

(optional)

(optional) Allowed values: "all" "none" "headers" "full" (default)

(optional) Allowed values: "true" "false" (default)

(optional)

one optional <preamble> element () one or more <ttcol> elements () optional <c> elements () one optional <postamble> element ()

This element appears as child element of: <front> ().

(optional)

text

This element appears as child element of: <texttable> ().

(optional) Allowed values: "left" (default) "center" "right"

(optional)

text

This element appears as child element of: <address> ().

text

This element appears as child element of: <t> ().

(optional)

This element appears as child element of: <front> ().

text

This element appears as child element of: <annotation> (), <c> (), <postamble> (), <preamble> (), and <t> ().

(optional) Allowed values: "counter" "title" "none" "default" (default)

(optional) Allowed values: "true" "false" (default)

(mandatory)

text

Register application/xml2rfc+xml.

We thank Marshall T. Rose for both the original design and the reference implementation of the "xml2rfc" formatter.

Latest version available at .

jjc@jclark.com

IETF Trust IETF Trust IETF Trust

For RFCs, the category determines the "maturity level" (see Section 4 of ). The allowed values are "std" for "Standards Track", "bcp" for "BCP", "info" for "Informational", "exp" for "Experimental", and "historic" for - surprise - "Historic". For Internet Drafts, the category attribute is not needed, but will appear on the front page ("Intended Status"). Supplying this information can be useful, because reviewers may want to know.

As of the time of this writing, this attribute value can take a long list of values. As frequently, this is not the result of a grand plan, but simply for historic reasons. Of these values, only a few are currently in use; all others are supported by the various tools for backwards compatibility with old source files. Note: some variations of the boilerplate are selected based on the document's date; therefore it is important to specify the "year", "month" and "day" attributes of the <date> element when archiving the XML source of an Internet Draft on the day of submission. Disclaimer: THIS ONLY PROVIDES IMPLEMENTATION INFORMATION. IF YOU NEED LEGAL ADVICE, PLEASE CONTACT A LAWYER. For further information, refer to . Finally, for the current "Status Of This Memo" text, the submissionType attribute determines whether a statement about "Code Components" is inserted (this is the case for the value "IETF", which also happens to be the default). Other values, such as "independent", suppress this part of the text.

The name for these values refers to the "TLP" ("IETF TRUST Legal Provisions Relating to IETF Documents"), on effect February 15, 2009 (). Updates to this document were published on September 12, 2009 () and on December 28, 2009 (), modifying the license for code components (see for further information). The actual text is located in Section 6 ("Text To Be Included in IETF Documents") of these documents. The tools will automatically produce the "right" text depending on the document's date information (see above): TLPstarting with publication date 2009-11-01 2010-04-01

This should be the default, unless one of the more specific '*trust200902' values is a better fit. It produces the text in Sections 6.a and 6.b of the TLP.

This produces the additional text from Section 6.c.i of the TLP: This document may not be modified, and derivative works of it may not be created, except to format it for publication as an RFC or to translate it into languages other than English. Note: this clause is incompatible with RFCs to be published on the Standards Track.

This produces the additional text from Section 6.c.ii of the TLP: This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft. Note: this clause is incompatible with RFCs to be published on the Standards Track.

This produces the additional text from Section 6.c.iii of the TLP, frequently called the "pre-5378 escape clause": This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. See Section 4 of for further information about when to use this value. Note: this text appears under "Copyright Notice", unless the document was published before November 2009, in which case it appears under "Status Of This Memo".

The attribute values "trust200811", "noModificationTrust200811" and "noDerivativesTrust200811" are similar to their "trust200902" counterparts, except that they use text specified in .

The attribute values "full3978", "noModification3978" and "noDerivatives3978" are similar to their counterparts above, except that they use text specified in RFC 3978 (March 2005).

The attribute values "full3667", "noModification3667" and "noDerivatives3667" are similar to their counterparts above, except that they use text specified in RFC 3667 (February 2004).

The attribute values "full2026" and "noDerivativeWorks2026" are similar to their counterparts above, except that they use text specified in RFC 2026 (October 1996). The special value "none" was also used back then, and denied the IETF any rights beyond publication as Internet Draft.

The <appendix> element has been removed; to generate an appendix, place a <section> inside <back>.

Many attributes have lost their "default" value; this is to avoid having document semantics differ based on whether a DTD was specified and evaluated. Processors will handle absent values the way the default value was specified before.

<artwork>: Has a set of new attributes: "name", "type", "src", "align", "alt", "width", and "height". () <author>: The <organization> element is now optional. The "role" attribute was added. () <date>: All attributes are now optional. () <figure>: Has a set of new attributes: "suppress-title", "src", "align", "alt", "width", and "height". () <iref>: Has a new "primary" attribute. () <list>: The "style" attribute isn't restricted to a set of enumerated values anymore. The "hangIndent" and "counter" attributes have been added. () <rfc>: The "ipr" attribute has gained additional values. The attributes "consensus", "iprExtract", "submissionType", and "xml:lang" have been added. () <reference>: <annotation> allows adding prose to a reference. () <references>: Can now appear multiple times, and carry a "title" attribute (so that normative and informative references can be split). () <section>: The new "toc" attribute controls whether it will appear in the Table Of Contents. <iref> can now appear as direct child element. () <t>: The "anchor" attribute can now be used as well, however there are restrictions on how they can be referred to. ()

The following elements have been added: <annotation> (), <c> (), <cref> (), <format> (), <spanx> (), <texttable> ().

The list below is just a starting point. Allow multiple paragraphs in list items; eliminating the need to use <vspace> (see ). Make the <date> element optional; all of its content is optional already. Deprecate or remove the <format> element; right now it's not used for the generation of the plain text document anyway. Allow <reference>s that identify a document set such as a BCP. Allow overriding the "anchor" attribute of an included <reference> element. Add a way to add prose to a reference that avoids abuse of <seriesInfo>. Extend <xref> so that subsection/anchors can be specified (see ). Remove the "pageno" attribute which seems to be both undocumented and non-functional. Extend <figure> to support different types of artwork (such as by specifying certain type attribute values, see ), and also avoid having to markup code (such as ABNF) as "artwork". Also, it would be good if "code components" could be marked as such. Finally, even in preformatted text use of markup could be useful to support (a) references, or (b) highlighting the important bits (). If contact information is changed to allow non-ASCII characters: add a place for a ASCII fallback (probably just for the author names). The content model for <postal> ought to be more strict to allow at most one of <city>, <region>, <code>, and <country>. Cleanup the set of overlapping attributes between <figure> and <artwork>. <spanx> has both a weird whitespace model ("preserve") and problematic styling. Consider to deprecate it in favor of elements such as <em> and <code>. Extend the concept of language tagging to at least examples and contact information to address potential japanese/chinese font confusion.

With comments being stripped; using "diff -C100" to add change marks.

(from Appendix B of , converted using "trang" into Relag NG Compact Notation )