xml2rfc FAQ | January 2022 | |
Russo | Informational | [Page] |
This is a list of frequently asked questions regarding xml2rfc, a tool that can be used to create Internet-Drafts or RFCs.¶
This FAQ is for version 3 of xml2rfc; the vocabulary has been changed significantly from version 2. For guidance on version 2, please see the FAQ for xml2rfc v2.¶
This document has been replaced by https://authors.ietf.org.¶
xml2rfc is a tool that lets you convert an XML source file into a text, HTML, PDF, expanded XML file, or various other options. It is available as a web-based service (https://author-tools.ietf.org/) or for download (https://pypi.org/project/xml2rfc/. Version 3 of the tool adds new features and is used by the RFC Editor to create RFCs.¶
It's an easy way to create an Internet-Draft in the proper format. It handles boilerplate text and reference text. The HTML and PDF output formats have new features (such as including SVG figures and non-ASCII characters), and the source file can be used for metadata extraction. Also, the RFC Editor will make use of your source file. (For background, see the RFC Format FAQ.)¶
You need the essentials. XML uses start and end tags, which are nested and matching, and they are case-sensitive. See "XML basics" in Writing I-Ds and RFCs using XML (revised) for more details.¶
You have several choices when getting started with xml2rfc, such as:¶
There are also tools available to let you edit non-XML source and then compile it to xml2rfc XML:¶
If you intend to host your draft in git
or on Github, see
https://ietf-gitwg.github.io/ for advice.¶
There is a v3 template available here: https://tools.ietf.org/tools/templates/draft-davies-template-bare-07.xml. In addition, several templates for xml2rfc v2 are available from https://tools.ietf.org/tools/templates [templates]. They include templates for a generic draft (e.g., draft-davies-template-bare.xml), as well as for a draft containing a MIB module (e.g., mib-doc-template-xml.txt).¶
You can convert an existing XML file from the v2 vocabulary to the v3 vocabulary using xml2rfc --v2v3 (see Section 7.1), and go from there. Use <t> elements for paragraphs, and <figure><artwork> elements for figures. Use <![CDATA[ ... ]]> within <sourcecode> or <artwork> elements that contain the less than character (<). (See What is CDATA for? for more information.)¶
To get a citation like "[RFC2119]", use <xref
target="RFC2119"/>
. See Using References for more information.¶
rfc
element to create an Internet-Draft?
Use the category
attribute to indicate the intended category of your
draft, where std
is Standards Track, info
is
Informational, exp
is Experimental, bcp
is Best Current
Practice, and historic
is Historic.¶
Use the submissionType
attribute to indicate the intended
document stream, where the value can be IETF
, IAB
,
IRTF
, or independent
.¶
See Appendix A.1 of [RFC7991] for information about the ipr attribute.¶
Use the docName attribute to indicate the filename.¶
If the document potentially updates or obsoletes any RFCs, use the updates and obsoletes attributes to indicate the relevant RFC numbers. For Internet-Drafts, this information will be displayed in the header, followed by "(if approved)".¶
For example, putting it together:¶
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info" submissionType="IETF" ipr="trust200902" docName="draft-ietf-wgname-topic-00" updates="1234, 1235" obsoletes="1236" sortRefs="true" version="3">¶
Note: The attributes number and seriesNo will be added by the RFC Editor if your draft is approved for publication as an RFC.¶
Note: Some features that used to be processing instructions (in v2)
are now attributes of the rfc element (in v3) -- for
example, sortRefs
and symRefs
.¶
A set of online citation libraries are maintained on xml2rfc.tools.ietf.org [xml2rfc]. They include citations for RFCs, Internet-Drafts, and documents produced by the W3C and 3GPP, among others.¶
To make use of the citation libraries, use an xi:include in the references section as follows.¶
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>¶
For an Internet-Draft, the citation filename uses the draft string. For example:¶
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-wgname-topic.xml"/>¶
Preferably, use the citation libraries when possible. However, another option is to include the complete reference element (see Section 3.2). Here's a template of a reference element:¶
<reference anchor="" target=""> <front> <title></title> <author initials="" surname="" fullname=""> <organization /> </author> <date month="" year="" /> </front> <seriesInfo name="" value="" /> <refcontent></refcontent> </reference>¶
All are cited textually in the same manner -- by using xref elements where the target corresponds to the anchor of the reference element, e.g., <xref target="RFC2119" />. The anchors for RFCs are "RFCNNNN" (4 digits, using leading zeros) and the anchors for Internet-Drafts are "I-D.<name without "draft-" or the version number>".¶
There are several ways to insert the full reference element from the citation library:¶
In the rfc
element, set the attribute symRefs="no"
for
symbolic references. This makes reference tags be numeric, e.g., [1], instead
of symbolic, e.g., [RFC2119].¶
Use the displayreference
element and set the to
attribute to
the nickname. Tip: place it before the first references
element. For example:¶
<displayreference target="RFC7296" to="IKEv2"/> <references> [...] <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7296.xml"/>¶
yields:¶
In the rfc element, set the attribute sortRefs="yes"
. Note that sortRefs only has an effect if symRefs="yes"
.¶
The eref element for an external reference creates a link in the HTML output. For example:¶
<eref target="https://www.w3.org">¶
yields https://www.w3.org.¶
<eref target="https://www.w3.org">W3C Home Page</eref>¶
yields W3C Home Page.¶
Another option is using xref and creating a reference that uses the target attribute for the URL. For example:¶
<reference anchor="W3C" target="https://www.w3.org/"> <front> <title>World Wide Web Consortium (W3C)</title> <author/> </front> </reference>¶
yields¶
[W3C] "World Wide Web Consortium (W3C)", <https://www.w3.org/>.¶
Use the name element (child of the references element) as follows:¶
<back> <references> <name>Normative References</name> ... </references> <references> <name>Informative References</name> ... </references> </back>¶
Use <referencegroup> with an xi:include for each RFC inside of it:¶
<referencegroup anchor="STD78" target="https://www.rfc-editor.org/info/std78"> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5343.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5590.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5591.xml"/> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6353.xml"/> </referencegroup>¶
which yields¶
[STD78] Schoenwaelder, J., "Simple Network Management Protocol (SNMP) Context EngineID Discovery", STD 78, RFC 5343, September 2008. Harrington, D. and J. Schoenwaelder, "Transport Subsystem for the Simple Network Management Protocol (SNMP)", STD 78, RFC 5590, June 2009. Harrington, D. and W. Hardaker, "Transport Security Model for the Simple Network Management Protocol (SNMP)", STD 78, RFC 5591, June 2009. Hardaker, W., "Transport Layer Security (TLS) Transport Model for the Simple Network Management Protocol (SNMP)", STD 78, RFC 6353, July 2011. <https://www.rfc-editor.org/info/std78>¶
Make sure the section you want to reference has an anchor attribute. For example:¶
<section anchor="s_using_lists">¶
Then, refer to it with an <xref> element:¶
See <xref target="s_using_lists" />.¶
which yields¶
See Section 4.¶
(where the number of that section is determined dynamically).¶
Use <xref> and set the sectionFormat attribute to various options.¶
Use <xref> with the format attribute. For example, assuming the anchors for the relevant sections match the targets:¶
See Sections <xref target="s_using_refs" format="counter" /> and <xref target="s_using_lists" format="counter" />.¶
yields the output:¶
See Sections 3 and 4.¶
Note: The format attribute can have the value "title", which displays the title of the section. For example,¶
See Sections <xref target="s_using_refs" format="title" /> and <xref target="s_using_lists" format="title" />.¶
yields the output:¶
See Using References and Using Lists.¶
Use <xref> with sectionFormat="bare". For example:¶
See Sections <xref target="RFC3550" section="5" sectionFormat="bare" /> and <xref target="RFC3550" section="6" sectionFormat="bare" /> in <xref target="RFC3550"/>.¶
yields the output:¶
For bulleted lists, use the <ul> element.¶
For an empty list (indentation only), use the <ul> element with
empty="true"
.¶
For definition lists (a.k.a. hanging lists in xml2rfc v2), use the <dl> element. See Section 4.4.¶
For numbers or letters, use the type attribute of the <ol> element; examples below.¶
For full details, see Section 2.34.5 of [RFC7991] and the schema documentation.¶
(1) (2) is <ol type="(%d)"> (3) (a) (b) is <ol type="(%c)"> (c) REQ1: REQ2: is <ol type="REQ%d:"> REQ3:¶
Set the group attribute to the same value for each <ol> element. For example:¶
<ol type="REQ%d:" group="reqs"> <li>do a</li> <li>do b</li> </ol> <t>Here is text in between.</t> <ol type="REQ%d:" group="reqs"> <li>do c</li> <li>do d</li> </ol> <t>Here is more text in between.</t> <ol type="REQ%d:" group="reqs"> <li>do e</li> <li>do f</li> </ol>¶
yields:¶
Here is text in between.¶
Here is more text in between.¶
Use a <dl> element (definition list), where each <dt> (term) in has a corresponding <dd> (description).¶
For example:¶
<dl> <dt>Unassigned:</dt> <dd>Unused and available for assignment via documented procedures.</dd> <dt>Reserved:</dt> <dd>Not to be assigned. Reserved values are held for special uses, such as to extend the namespace when it become exhausted. Reserved values are not available for general assignment.</dd> </dl>¶
yields:¶
Note: The appearance is slightly different in the text output.¶
Use newline="true"
to get a line
break after the term. For example:¶
<dl newline="true"> <dt>Unassigned:</dt> <dd>Unused and available for assignment via documented procedures.</dd> <dt>Reserved:</dt> <dd>Not to be assigned. Reserved values are held for special uses, such as to extend the namespace when it become exhausted. Reserved values are not available for general assignment.</dd> </dl>¶
yields:¶
The key is that any text before or after the inner list must be in a <t> element.¶
Example: <ol> nested within <dl>¶
<dl> [...] <dt>Foo validator:</dt> <dd> <t>It performs the following actions:</t> <ol type="1" spacing="compact"> <li>runs</li> <li>jumps</li> <li>walks</li> </ol> </dd> [...] </dl>¶
yields:¶
Example: <ul> nested within <ol>¶
<ol type="Step %d:"> [...] <li><t>Send it to</t> <ul spacing="compact"> <li>Alice</li> <li>Bob</li> <li>Carol</li> </ul> </li> [...] </ol>¶
yields:¶
A CDATA block is left alone by xml2rfc. It does not try to parse XML inside of a CDATA block. (For example, if a figure contains "<", you don't have to use <) So it is especially good for when there are XML examples in the document.¶
To prevent these characters from being parsed as XML, use¶
& for & < for < > for >¶
In addition, the following entities are defined:¶
for non-breaking space &nbhy; for non-breaking hyphen &wj; for word joiner¶
Use the role attribute of the author element. For example:¶
<author initials="J" surname="Doe" fullname="John Doe" role="editor">¶
In a "Contributors" section, you can use the <contact> element, which has the same structure as the <author> element. Including address information is optional.¶
In an "Acknowledgments" section, you can use the <contact> element within <t> to list inviduals' names (typically without address information).¶
You can use comments <!-- --> or <cref> elements. Comments are only visible in the XML source file.¶
Example of using comments:¶
<!-- [JD] This point needs revision.-->¶
<cref> will show up in the output when the attribute display="true" (which is the default).¶
Example of using <cref>:¶
<cref anchor="Q1" source="JD">This point needs revision.</cref>¶
yields¶
This point needs revision.JD¶
xml2rfc validates it. Also, you can run rfclint: https://pypi.org/project/rfclint/.¶
Yes, rfc2629.xslt by Julian Reschke provides a different kind of HTML output than the HTML output mode of xml2rfc. See "Transforming RFC7749-formatted XML through XSLT" for more information.¶
Yes, id2xml is available here: https://pypi.org/project/id2xml/. It is available as a web service on https://xml2rfc.tools.ietf.org/.¶
On the command line: xml2rfc --v2v3 inputfile.xml
. You can
use the --add-xinclude
option to replace RFC and I-D reference elements
with the appropriate xi:include element.¶
Or, using the web service (https://xml2rfc.tools.ietf.org/experimental.html), select "Output format: convert v2 to v3 XML".¶
After converting it to v3, please see Section 7.2.¶
You may want to do the following (for the sake of generating good output and having a semantically accurate XML file):¶
Review each list.¶
Review each <artwork>.¶
xml2rfc
warns "Setting consensus="true" for IETF STD document".
xml2rfc
fails with "Reserved anchor name: section-.... Don't
use anchor names beginning with one of u-, section-, iref-, figure-,
table-".
Other errors can appear if you're using a helper tool to write your XML:¶
If you're using kramdown-rfc2629:¶
date
for a reference, xml2rfc
fails with "Expected <date> attribute "year" to be an integer, but
found "n.d.""
date: false
to your reference to avoid the error.¶
If you're using i-d-template:¶
xml2rfc
warns that "The 'docName' attribute of the <rfc/>
element should have a revision number as the last component:
docName="draft-foo-bar-02"."
Some highlights are including Unicode characters, text formatting, and SVG diagrams. For complete details, see Section 1.3 of [RFC7991].¶
With encoding="utf-8"
in your XML file, you can use non-ASCII
characters in the following locations:¶
fullname
,
initials
, and surname
attributes, while the
asciiFullname
, asciiInitials
, and
asciiSurname
attributes hold the ASCII equivalents)¶
ascii
attribute to hold the ASCII equivalent, which will also appear in
the output format.¶
body of the document¶
The <u> element goes around a Unicode character;
set the format
attribute (using the keywords num, name, lit, char, and ascii)
to indicate what is rendered in the output. See the schema documentation.¶
Below are examples of using¶
<u format="num-lit">水</u>¶
and various other options for the format attribute.¶
For example:¶
<table anchor="table_ex"> <name>IETF Meetings in 2005</name> <thead> <tr> <th align='center'>IETF #</th> <th align='center'>City</th> <th align='center'># of Attendees</th> </tr> </thead> <tbody> <tr> <td align="center">62</td> <td align="center">Minneapolis</td> <td align="center">1133</td> </tr> <tr> <td align="center">63</td> <td align="center">Paris</td> <td align="center">1450</td> </tr> <tr> <td align="center">64</td> <td align="center">Vancouver</td> <td align="center">1240</td> </tr> </tbody> </table>¶
yields:¶
IETF # | City | # of Attendees |
---|---|---|
62 | Minneapolis | 1133 |
63 | Paris | 1450 |
64 | Vancouver | 1240 |
Data from https://www.ietf.org/how/meetings/past/.¶
For full details, see Section 2.54 of [RFC7991].¶
You can check your SVG file against the SVG Tiny 1.2
spec on the experimental page
(https://xml2rfc.tools.ietf.org/experimental.html),
and a script called svgcheck
is available here: https://pypi.org/project/svgcheck/.¶
For more information, see [RFC7996] and Tips on creating SVG files.¶
From RFC 7991:¶
There are at least five ways to include SVG in artwork in Internet-Drafts:¶
- Inline, by including all of the SVG in the content of the element, such as: <artwork type="svg"><svg xmlns="http://www.w3.org/2000/ svg...">¶
- Inline, but using XInclude (see Appendix B.1), such as: <artwork type="svg"><xi:include href=...>¶
- As a data: URI, such as: <artwork type="svg" src="data:image/ svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3...">¶
- As a URI to an external entity, such as: <artwork type="svg" src="http://www.example.com/...">¶
- As a local file, such as: <artwork type="svg" src="diagram12.svg">¶
For any given SVG artwork, you can provide an ASCII art equivalent (for use in the text output) by using the <artset> element. For example:¶
<figure> <name>TCP Header Format</name> <artset> <artwork alt="TCP Header" type="svg" src="https://www.rfc-editor.org/materials/format/svg/tcp-header.svg"/> <artwork alt="TCP Header from RFC 793" type="ascii-art"> [... ASCII ART ...] </artwork> </artset> </figure>¶
which yields:¶
Use <sub> for subscript and <sup> for superscript.¶
Example (using text from RFC 6330):¶
Please see the list on https://www.rfc-editor.org/materials/sourcecode-types.txt.¶
For more information, see Section 2.48.4 of [RFC7991].¶
For a YANG module, please use <sourcecode> with type="yang" and markers="true". The latter creates the <CODE BEGINS> and <CODE ENDS> tags in the output. If you set the name attribute, the filename will appear in the output. For example:¶
<sourcecode type="yang" markers="true" name="foo.yang">¶
yields¶
<CODE BEGINS> file "foo.yang" [...] <CODE ENDS>¶
It is not a MUST, but it makes the usage more clear.¶
Print the PDF.¶
The source files of RFCs have changed over time. Most RFCs have NROFF source files; sometimes an XML file has been archived. You can request an XML source file directly from rfc-editor@rfc-editor.org. For RFCs created after the transition to xml2rfc v3, the XML files will be available for bulk download from https://www.rfc-editor.org/retrieve/bulk.¶
Please see "Deprecated Elements and Attributes" in the schema documentation.¶
This FAQ was made possible by the tools, documentation, and test files created by Henrik Levkowetz, Julian Reschke, Paul Hoffman, and Sandy Ginoza. Also, thanks to Jeffrey Yaskin for contributing.¶