xml2rfc Frequently Asked Questions
Alice Russo
RFC Production Center
arusso@amsl.com
March 2019
This is a list of frequently asked questions regarding xml2rfc. Please send questions or corrections to the xml2rfc mailing list.
Note: 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.
The Basics
What is xml2rfc?
xml2rfc is a tool that lets you convert an XML source file into a text, HTML, nroff, or expanded XML file. It is available from xml2rfc.ietf.org as a web-based service or for download. Version 3 of the tool adds new See the How much XML do I need to know?. See Sections 1.3 and 4.4. features and will be used by the RFC Editor to create RFCs. The current version is here:
Why should I use xml2rfc?
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.)
How much XML do I need to know?
You need the essentials. XML uses start and end tags, which are nested and matching, and they are case-sensitive. See the section "XML basics" of [howto] for more details.
Where can I get more information?
- [RFC7991]
- xml2rfc mailing list: https://www.ietf.org/mailman/listinfo/xml2rfc
Creating a Draft
What's the recommended setup?
not yet updated
You have several choices when getting started with xml2rfc, such as:
- Use the tool on the web or install it locally.
- Use the citation libraries online or maintain a local copy.
- Edit in your favorite editor or use an XML editor.
Where can I get a template?
not yet updated
Several templates are available from http://tools.ietf.org/tools/templates. They include templates for a generic draft (e.g., draft-davies-template-bare.xml), as well as for a draft containing a MIB (e.g., mib-doc-template-xml.txt).
Can I do it without a template?
not yet updated
Sure. We recommend copying the front matter from a template or the XML source of an existing document, then going from there. Put <t> tags around paragraphs, and <figure><artwork> tags around figures. Use <![CDATA[ ... ]]> for blocks of code or figures that contain <. (See What is CDATA for? for more information.)
For references, replace [RFC2119] with <xref target="RFC2119"/>. For cross-references to sections, replace Section 9 with <xref target="sec_cons"/> (if Section 9 has anchor="sec_cons"). See Using References for more information.
How do I use the 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
   category="info"
   submissionType="IETF"
   ipr="trust200902"
   docName="draft-ietf-wgname-topic-00"
   updates="1234, 1235"
   obsoletes="1236"
   sortRefs="true">

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.
Why is xml2rfc giving me errors?
not yet updated
At the top, if there is the PI <?rfc strict="yes"?>, then xml2rfc is trying to enforce I-D nits and DTD validity.
If you are getting "This file does not begin with an XML declaration", have you entered the filename correctly? It can indicate a problem with the first line (<?xml version="1.0">) or it can mean "File not found". Also, check the permissions on the file.
One common error is caused by mismatched tags. For example, when there is a missing </t>, the error might appear as follows:

end tag "section" does not match open element "t" around line 65

Using Bill's xml2rfc validator can provide more precise error messages.
Using References
How do I put in a reference?
not yet updated
A set of online citation libraries are maintained on xml2rfc.ietf.org. They include citations for RFCs, Internet-Drafts, and documents produced by the W3C and 3GPP, among others.
To make use of the citation libraries, there are 2 methods:
1. define an ENTITY at the top:

<!ENTITY RFC2119 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml">

and use &RFC2119; in the references section
2. Note: As long as they match, the name you use in the ENTITY definition and the &name; in the references section are your choice, and may be uppercase or lowercase (i.e., rfc2119 or RFC2119 or keywords). We suggest choosing uppercase (i.e., to match the anchor of the reference) in order to make it easier to be consistent.
3. use an include in the references section

<?rfc include="reference.RFC.2119.xml"?>

For an Internet-Draft, the citation file uses the draft string. For example:

<?rfc include="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="" />
    </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-ietf-" or the version number>".
How do I insert the full reference?
There are several ways to insert the full reference element from the citation library:
1. Keep a local copy of the citation libraries. They are available from https://xml2rfc.ietf.org.
2. Use a browser to look it up online, e.g., https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml, and copy the page source.
3. Run xml2rfc with output mode set to XML. The output will include the complete reference elements for any entities and includes.
How do I make the reference tag [RFC2119] instead of [1]?
In the rfc element, set the attribute symRefs="yes" for symbolic references. This makes reference tags be the same as the anchor (e.g., [RFC2119]), instead of numerical (e.g., [1]).
symrefs="yes" is the default, starting with v1.33 of xml2rfc.
How do I make the reference tag [IKEv2] instead of [RFC4306]?
Use the displayreference element and set the to attribute to the nickname. Tip: place it before the 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:
[IKEv2]
Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T. Kivinen, "Internet Key Exchange Protocol Version 2 (IKEv2)", STD 79, RFC 7296, DOI 10.17487/RFC7296, October 2014, <https://www.rfc-editor.org/info/rfc7296>.
How do I get the references listed in alphabetical order?
In the rfc element, set the attribute sortRefs="yes". Note that sortRefs only has an effect if symRefs="yes".
How do I reference a URL?
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="http://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/>.

How do I get two sections of references: Normative and Informative References?
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>

How do I make a cross-reference to another section?
not yet updated
Make sure the section you want to reference has an anchor attribute. For example:

  <section title="Security Considerations" anchor="sec_cons">

Then, refer to it with an xref element:

  See <xref target="sec_cons" />.

which yields the text output:

See Section 9.

(where the number of that section is determined dynamically).
What about referring to a section in another document? or How do I link to a section in another RFC?
not fully updated
Use xref. Examples below are from draft-v3-features. Set sectionFormat to various options.
"of": See Section 1 of [RFC7991].
"comma": See [RFC7991], Section 2.2.
"parens": See [RFC7991] (Appendix A).
"bare": See B.
(default): See Section 1 of [RFC7991].
With text content: See the wonderful Section 2 of RFC 7991.
How do I get 'See Sections 9 and 10' instead of 'See Section 9 and Section 10'?
Use the format attribute. For example, assuming the anchor attributes for the relevant sections have the values "sec_cons" and "IANA_cons":

See Sections <xref target="sec_cons" format="counter" /> and
<xref target="IANA_cons" format="counter" />.

yields the text output:

See Sections 9 and 10.

Note: The format attribute can have the value "title", which displays the title of the section. For example,

See the <xref target="sec_cons" format="title" />.

yields the text output:

See the Security Considerations.

Using Lists
How do I get different kinds of lists?
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].
- type="1": 1, 2, 3, ...
- type="I": I, II, III, ...
- type="i": i, ii, iii, ...
- type="a": a, b, c, ...
- type="A": A, B, C, ...
- type="REQ%d": See Section 4.2.
How do I get a list like (1), (2), (3) or (a), (b), (c)?

(1)
(2)    is   <ol type="(%d)">
(3)

(a)
(b)    is   <ol type="(%c)">
(c)

REQ1:
REQ2:  is   <ol type="REQ%d:">
REQ3:

How do I get continuous numbering in a list that is split by text (or across sections)?
Set the group attribute of the <ol> element. For example:
1. apples
2. blueberries
3. cherries
Here is some text in between.
1. dragonfruit
2. elderberry
3. fig
How do I get indentation? or How do I use definition lists?
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:
Unassigned:
Unused and available for assignment via documented procedures.
Reserved:
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.
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:
Unassigned:
Unused and available for assignment via documented procedures.
Reserved:
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.
The Finer Points
What is CDATA for?
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 &lt;) So it is especially good for when there are XML examples in the document.
How do I get an unnumbered figure?
not yet updated
Remove the anchor attribute for that figure. Figure elements without anchor attributes will not be automatically numbered (i.e., "Figure 1").
What are the entities used for special characters?
To prevent these characters from being parsed as XML, use

&amp; for &
&lt; for <
&gt; for >

In addition, the following entities are defined:

&apos; for '
&quot; for "
&nbsp; for non-breaking space
&nbhy; for non-breaking hyphen

How do I put a line break into the title of the document?
Insert &nbsp; (non-breaking space) between words that you want to keep together on a line.
How do I indicate the editor of the document?
Use the role attribute of the author element. For example:

<author initials="J" surname="Doe" fullname="John Doe" role="editor">

How do I insert questions for my coauthors?
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]]

Miscellaneous
How do I know if my XML is valid?
xml2rfc validates it. Also, you can run rfclint: https://pypi.org/project/rfclint/.
Can I get a different kind of HTML output?
not yet updated
Yes, rfc2629.xslt by Julian Reschke provides a different kind of HTML output than the HTML output mode of xml2rfc. It is available for download from http://greenbytes.de/tech/webdav/rfc2629xslt.zip. See "Transforming RFC2629-formatted XML through XSLT" for more information.
Is there a tool that will turn my text file into an XML file (i.e., id2xml)?
Yes, id2xml is available here: https://pypi.org/project/id2xml/. It is available as a web service on https://xml2rfc.ietf.org/.
New with v3
How do I convert my XML file from v2 to v3 so I can make use of the new features?
On the command line: xml2rfc --v2v3 inputfile.xml
Using the web service (https://xml2rfc.tools.ietf.org/experimental.html), select "Output format: convert v2 to v3 XML".
What are the new features with v3?
Some highlights are including UTF-8 characters, text formatting, and SVG diagrams. For complete details, see Section 1.3 of [RFC7991].
How do I insert non-ASCII characters?
With encoding="utf-8" in your XML file, you can insert the characters directly into the file in the following locations:
- body of the document
- author name and organization (fullname, initials, and surname attributes; organization element)
- author's postal address (street, city, region, code, and country elements)
- author's email address
Each of these elements has an ascii attribute to hold the ASCII equivalent, which will also appear in the output format. For the author element, the attributes are named asciiFullname, asciiInitials, andasciiSurnames.
For background, see [RFC7997].
Example from RFC 7997 (which comes from RFC 7613):
A sample of legal passwords
# | Password | Notes
14 | < πß๗ > | Non-ASCII letters are OK (e.g., π; ß; ๗)
15 | < Jack of ♦s > | Symbols are OK (e.g., ♦)
16 | < foo bar > | is mapped to U+0020 and thus the full string is mapped to <foo bar>
How do I insert a table?
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 Meetings in 2005
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].
How do I generate SVG that will be accepted in an RFC?
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.
How do I include SVG in my document?
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">
Example:
TCP Header Format (from RFC 793)

         [figure: diagram of TCP header]

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Source Port          |       Destination Port        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        Sequence Number                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Acknowledgment Number                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Data |           |U|A|P|R|S|F|                               |
   | Offset| Reserved  |R|C|S|S|Y|I|            Window             |
   |       |           |G|K|H|T|N|N|                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           Checksum            |         Urgent Pointer        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Options                    |    Padding    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                             data                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Late 408s to Non-INVITEs (from RFC 4321)

  [figure: diagram of late 408s]
How do I get bold, italics, or a fixed-width font?
Use
- <em> for italics,
- <strong> for bold, and
- <tt> for fixed-width font.
Note: in the text output, <em> yields underscores, <strong> yields asterisks around the text, and <tt> yields quotation marks.
Example:
Names beginning with the string "xml", or with any string which would match (('X'|'x') ('M'|'m') ('L'|'l')), are reserved for standardization in this or future versions of this specification.
Note:
The Namespaces in XML Recommendation [XMLNames] assigns a meaning to names containing colon characters. Therefore, authors should not use the colon in XML names except for namespace purposes, but XML processors must accept the colon as a name character.
- Both em and strong: really important thing.
- Both tt and strong: really important string.
How do I get subscript and superscript?
Use <sub> for subscript, and <sup> for superscript.
Example (from RFC 7845):

xn =∑ak *  x(n - k)

xn =∑ak *  x(n - k)

Use case (from RFC 6386):
X_{ij} = L_i + A_j - P
Example (from RFC 6330):
- x_0 = (y + i) mod 2^8
- x_1 = (floor(y / 2^8) + i) mod 2^8
- x_2 = (floor(y / 2^{16}) + i) mod 2^8
- x_3 = (floor(y / 2^{24}) + i) mod 2^8
What are the possible values for the type of the sourcecode element?
abnf, asn.1, bash, c++, c, cbor, dtd, java, javascript, json, mib, perl, pseudocode, python, rnc, xml, and yang.
Ths list is subject to change; for details, see Section 2.48.4 of [RFC7991].
Do I have to use the bcp14 element each time a keyword (e.g., "MUST") appears in my document?
It is not a MUST, but it makes the usage more clear.
SHOULD without the <bcp14> element, SHOULD with it.
What is the best way to print a hardcopy?
Print the PDF.
How do I download the XML source files for all RFCs?
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. After RFC TBD, the XML files will be available for download https://www.rfc-editor.org/retrieve/bulk.
What has been deprecated from xml2rfc v2?
See Section 1.3.3 of [RFC7991]. Section 1.3.3 of RFC 7991.
Acknowledgments
This FAQ was made possible by the tools, documentation, and test files created by Henrik Levkowetz, Julian Reschke, Paul Hoffman, and Sandy Ginoza.
Informative References
[W3C]

World Wide Web Consortium (W3C)
[RFC7991]

The "xml2rfc" Version 3 Vocabulary
DOI 10.17487/RFC7991
RFC 7991
P. Hoffman
December 2016
[xml2rfc]

xml2rfc
[howto]

Writing I-Ds and RFCs using XML (revised)
Marshall Rose
22 July 2006
[readme]

xml2rfc v1.33
M Rose
B Fenner
C Levert
28 February 2008
[templates]

Templates directory
[RFC7997]
[RFC7996]