xml2rfc Frequently Asked Questions

Abstract

This is a list of frequently asked questions regarding xml2rfc. Please send corrections or additions to hagens@isi.edu.

Table of Contents

1.  The Basics
    1.1.  What is xml2rfc?
    1.2.  Why should I use xml2rfc?
    1.3.  How much XML do I need to know?
    1.4.  Where can I get more information?
2.  Creating a Draft
    2.1.  What's the recommended setup?
    2.2.  Where can I get a template?
    2.3.  Can I do it without a template?
    2.4.  How do I use the rfc element to create an Internet-Draft?
    2.5.  Why is xml2rfc giving me errors?
    2.6.  What are PIs? What PIs are available?
3.  Using References
    3.1.  How do I put in a reference?
    3.2.  How do I cite a reference?
    3.3.  How do I insert the full reference?
    3.4.  How do I make the reference tag [RFC2119] instead of [1]?
    3.5.  How do I make the reference tag [IKEv2] instead of [RFC4306]?
    3.6.  How do I get the references listed in alphabetical order?
    3.7.  How do I reference a URL?
    3.8.  How do I get two sections of references: Normative and Informative References?
    3.9.  How do I make a cross-reference to another section?
    3.10.  What about referring to a section in another document?
    3.11.  How do I get 'See Sections 9 and 10' instead of 'See Section 9 and Section 10'?
4.  Using Lists
    4.1.  How do I get different kinds of lists?
    4.2.  How do I get blank lines between list items?
    4.3.  How do I get a list like (1), (2), (3) or (a), (b), (c)?
    4.4.  How do I get continuous numbering across separate lists?
    4.5.  How do I get indentation?
    4.6.  How do I use hanging lists?
5.  Using Figures and Tables
    5.1.  Is artwork the right way to include preformatted text, like an SDP message?
    5.2.  What is CDATA for?
    5.3.  How do I get an unnumbered figure?
    5.4.  How do I insert a table?
6.  The Finer Points
    6.1.  What are the entities used for special characters?
    6.2.  How do I put a line break into the title of the document?
    6.3.  How do I control vertical whitespace?
    6.4.  How do I indicate the editor of the document?
    6.5.  How do I insert questions for my coauthors?
7.  Miscellaneous
    7.1.  How do I know if my XML is valid?
    7.2.  Can I get a different kind of HTML output?
    7.3.  Is there a tool that will turn my text file into an XML file (i.e., rfc2xml)?
    7.4.  I like nroff. How do nroff commands relate to xml2rfc?
8.  Acknowledgments
9.  Informative References
§  Author's Address

1.  The Basics

1.1.  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 xml.resource.org (, “xml2rfc,” .) [1] as a web-based service or for download.

1.2.  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 output is handy for posting, and the source file can be used for metadata extraction. Also, the RFC Editor will make use of your source file if your document is approved for publication as an RFC.

1.3.  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 [2] (Rose, M., “Writing I-Ds and RFCs using XML (revised),” July 2006.) for more details.

1.4.  Where can I get more information?

• HOWTO: http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html (Rose, M., “Writing I-Ds and RFCs using XML (revised),” July 2006.) [2]
  contains descriptions of elements and attributes, and the DTD
• README: http://xml.resource.org/authoring/README.html (Rose, M., Fenner, B., and C. Levert, “xml2rfc v1.33,” February 2008.) [3]
  contains instructions for installing xml2rfc locally
  contains the list of processing instructions (PIs) & their descriptions
• xml2rfc mailing list: http://lists.xml.resource.org/mailman/listinfo/xml2rfc
• "Introduction to xml2rfc" tutorial slides from July 2008
• xml2rfc tutorial slides by Elwyn Davies from March 2006
• the XML templates discussed in Section 2.2 (Where can I get a template?)

2.  Creating a Draft

2.1.  What's the recommended setup?

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 such as XMLmind.
• Note: With XMLmind, you can use Bill's configuration that provides a WYSIKN (What You See Is Kinda Neat) interface available from http://code.google.com/p/xml2rfc-xxe/.

The quick-start setup is:

• Use the tool on the web.
• Use the citation libraries online (see Section 3.1 (How do I put in a reference?)).
• Edit in your favorite editor.
• Start with a template (see Section 2.2 (Where can I get a template?)).

2.2.  Where can I get a template?

Several templates are available from http://tools.ietf.org/tools/templates (IETF Tools, “Templates directory,” .) [4]. 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).

2.3.  Can I do it without a template?

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? (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 (Using References) for more information.

2.4.  How do I use the rfc element to create an Internet-Draft?

Use the category attribute to indicate the intended category of your draft. Standards Track, Informational, Experimental, Best Current Practices, and Historic correspond to the values std, info, exp, bcp, and historic, respectively.

Use the ipr attribute to indicate the relevant IPR. The values are full3978, noModification3978, and noDerivatives3978. (When the value is not full3978, the attribute iprExtract is used to indicate a section of the document that may be extracted for separate publication. Its value is equal to the anchor of the relevant section.) See "Conformance with RFC 3978" in [2] (Rose, M., “Writing I-Ds and RFCs using XML (revised),” July 2006.) for more information.

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"
   ipr="full3978"
   docName="draft-ietf-wgname-topic-00"
   updates="1234, 1235"
   obsoletes="1236">

Note: the attributes number and seriesNo will be added by the RFC Editor if your draft is approved for publication as an RFC.

2.5.  Why is xml2rfc giving me errors?

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 Fenner's xml2rfc validator (http://www.fenron.com/~fenner/ietf/xml2rfc-valid/) can provide more precise error messages. See also Section 7.1 (How do I know if my XML is valid?).

2.6.  What are PIs? What PIs are available?

Processing instructions (PIs) contain directives to xml2rfc. See the full list of PIs here: http://xml.resource.org/authoring/README.html#anchor6.

A common block of PIs at the top of an Internet-Draft is:

<?rfc toc="yes"?>         <!-- generate a table of contents -->
<?rfc symrefs="yes"?>     <!-- use anchors instead of numbers for references -->
<?rfc sortrefs="yes" ?>   <!-- alphabetize the references -->
<?rfc compact="yes" ?>    <!-- conserve vertical whitespace -->
<?rfc subcompact="no" ?>  <!-- but keep a blank line between list items -->

3.  Using References

3.1.  How do I put in a reference?

A set of online citation libraries are maintained on xml.resource.org (, “xml2rfc,” .) [1]. 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 "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
   

   and use &RFC2119; in the references section.
   
   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 (e.g., rfc2119, RFC2119, or keywords). We suggest choosing uppercase (which would match the anchor of the reference) in order to make it easier to remember.



2. use an include PI 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"?>
   

Another option is to include the complete reference element (see Section 3.3 (How do I insert the full reference?)).

3.2.  How do I cite a reference?

All references are cited textually in the same manner -- by using xref elements where the target corresponds to the anchor of the reference element:

<xref target="RFC2119" />

yields

[RFC2119]

assuming the PI symrefs="yes" (which is the default).

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

3.3.  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 http://xml.resource.org (, “xml2rfc,” .) [1].
2. Use a browser to look it up online, e.g., http://xml.resource.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 include PIs.

Preferably, use the citation libraries when possible. However, you can create your own reference element. Here is an empty 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>

3.4.  How do I make the reference tag [RFC2119] instead of [1]?

Use the PI for symbolic references. <?rfc symrefs="yes" ?> 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.

3.5.  How do I make the reference tag [IKEv2] instead of [RFC4306]?

Insert the full reference (see Section 3.3 (How do I insert the full reference?)) and change the anchor tag.

For example, change

<reference anchor='RFC4306'>

to

<reference anchor='IKEv2'>

3.6.  How do I get the references listed in alphabetical order?

Insert the PI <?rfc sortrefs="yes"?>. Note that sortrefs only has an effect if symrefs="yes".

3.7.  How do I reference a URL?

The eref element for external references creates a link in the HTML output. For example:

<eref target="http://www.3gpp.org">3GPP Home Page</eref>

yields the following HTML output: 3GPP Home Page Note: for text output for Internet-Drafts, we recommend using xref and creating a reference that uses the target attribute for the URL. For example:

    <reference anchor="3GPP" target="http://www.3gpp.org">
        <front>
            <title>3GPP Home Page</title>
            <author initials="" surname="" fullname="">
                <organization />
            </author>
        </front>
    </reference>

yields

   [3GPP]     "3GPP Home Page", <http://www.3gpp.org>.

3.8.  How do I get two sections of references: Normative and Informative References?

Use the title attribute of the references element as follows:

    <back>
      <references title="Normative References">
	...
      </references>
      <references title="Informative References">
	...
      </references>
    </back>

3.9.  How do I make a cross-reference to another section?

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

3.10.  What about referring to a section in another document?

You can hard-code the section number when referring to a specific section in a separate document. For example:

 Section 4.1 of  <xref target="RFC5226" />

which yields the text output:

Section 4.1 of [RFC5226]

Note: If using rfc2629.xslt (Can I get a different kind of HTML output?), the HTML output can include a link to the specific section in the HTML version of the RFC. For example, if you use xref as follows:

<xref target="RFC5226" x:fmt="of" x:sec="4.1"/>

it yields the following link:

http://tools.ietf.org/html/rfc5226#sec-4.1

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

4.  Using Lists

4.1.  How do I get different kinds of lists?

Use the style attribute of the list element:

style="empty": simply indents list items. (default)

style="numbers": 1., 2., 3.

style="letters": a., b., c.

style="symbols": bulleted with o, o, o
nested lists are bulleted with *, then +

style="format %d": See Section 4.3 (How do I get a list like (1), (2), (3) or (a), (b), (c)?).

style="hanging": See Section 4.6 (How do I use hanging lists?).

4.2.  How do I get blank lines between list items?

Use the PIs compact="yes" and subcompact="no" at the top. This will put one blank line between list items. (If you want to remove blank lines between items in a specific list, then turn subcompact on and off around that list.)

Note: the fine-tuning of whitespace has more relevance to the text output than the HTML output.

4.3.  How do I get a list like (1), (2), (3) or (a), (b), (c)?

(1)
(2)    is   <list style="format (%d)">
(3)

(a)
(b)    is   <list style="format (%c)">
(c)

REQ1:
REQ2:  is   <list style="format REQ%d:">
REQ3:

4.4.  How do I get continuous numbering across separate lists?

Use the counter attribute of the list element. Choose a name for the counter, then for each list that you want to be numbered (or lettered) continuously, set the counter attribute to that same name. Note that this works only if the style attribute is set to format to create customized format lists (How do I get a list like (1), (2), (3) or (a), (b), (c)?), as described above.

For example,

<t>Here is text introducing the first pair.
  <list style="format REQ%d:" counter="my_count">
    <t>First req.</t>
    <t>Second req.</t>
  </list>
</t>

<t>Here is text introducing the next pair.
  <list style="format REQ%d:" counter="my_count">
    <t>Third req.</t>
    <t>Fourth req.</t>
  </list>
</t>

<t>Here is text introducing the last pair.
  <list style="format REQ%d:" counter="my_count">
    <t>Fifth req.</t>
    <t>Sixth req.</t>
  </list>
</t>

yields the text output:

   Here is text introducing the first pair.

   REQ1:  First req.

   REQ2:  Second req.

   Here is text introducing the next pair.

   REQ3:  Third req.

   REQ4:  Fourth req.

   Here is text introducing the last pair.

   REQ5:  Fifth req.

   REQ6:  Sixth req.

4.5.  How do I get indentation?

Lists without the style attribute (i.e., the default style="empty") will yield indented text. For example,

<t>The locations of IETF meetings in 2007 were:
  <list>
    <t>Prague</t>
    <t>Chicago</t>
    <t>Vancouver</t>
  </list>
</t>

yields the following text output:

   The locations of IETF meetings in 2007 were:

      Prague

      Chicago

      Vancouver

4.6.  How do I use hanging lists?

When the list style="hanging", each <t> item in the list has the hangText attribute. Also, the list attribute hangIndent takes the number of spaces to indent. For example,

<list style="hanging" hangIndent="6">
     <t hangText="Unassigned:">Unused and available for assignment via
            documented procedures.</t>

     <t hangText="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.</t>
</list>

yields the following text output:

   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 output is slightly different in the HTML output:

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.

You can use <vspace /> to get the text output to have a line break similar to the HTML output. For example:

<list style="hanging" hangIndent="6">
     <t hangText="Unassigned:">
       <vspace />
       Unused and available for assignment via
       documented procedures.</t>

     <t hangText="Reserved:">
       <vspace />
       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.</t>
</list>

yields the following text output:

   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

5.  Using Figures and Tables

5.1.  Is artwork the right way to include preformatted text, like an SDP message?

Yes. You can simply use <artwork> (without <figure>) when you don't need to title the artwork.

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

For example:

<figure><artwork><![CDATA[
      Here is a figure that mentions XML elements such as <xref>.
]]></artwork></figure>

5.3.  How do I get an unnumbered figure?

Remove the anchor attribute for that figure. Figure elements without anchor attributes will not be automatically numbered (i.e., "Figure 1").

5.4.  How do I insert a table?

The texttable element is used for creating tables; it contains ttcol elements to define the columns and c elements to hold the contents of each cell. For example,

<texttable anchor="table_ex" title="IETF Meetings in 2005">
    <ttcol align='center'>IETF #</ttcol>
    <ttcol align='center'>City</ttcol>
    <ttcol align='center'># of Attendees</ttcol>
    <c>62</c>
    <c>Minneapolis</c>
    <c>1133</c>
    <c>63</c>
    <c>Paris</c>
    <c>1450</c>
    <c>64</c>
    <c>Vancouver</c>
    <c>1240</c>
    <postamble>Data from http://www.ietf.org/meetings/past.meetings.html</postamble>
</texttable>

yields this text output

                 +--------+-------------+----------------+
                 | IETF # |     City    | # of Attendees |
                 +--------+-------------+----------------+
                 |   62   | Minneapolis |      1133      |
                 |        |             |                |
                 |   63   |    Paris    |      1450      |
                 |        |             |                |
                 |   64   |  Vancouver  |      1240      |
                 +--------+-------------+----------------+

         Data from http://www.ietf.org/meetings/past.meetings.html

                      Table 1: IETF Meetings in 2005

Note: for tables that are more complex, inserting the table as a figure (i.e., inside of <figure> <artwork> tags) might be the best option.

6.  The Finer Points

6.1.  What are the entities used for special characters?

To prevent these characters from being parsed as XML, use

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

In addition, the following entities are defined:

' for '
" for "
  for non-breaking space
&nbhy; for non-breaking hyphen
&rfc.number; uses the number attribute of the rfc element to
             display the RFC number.

6.2.  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. For example, if you have the text output

      Very Very Very Very Important Protocol (4VIP) Cryptographic
                             Authentication

In the XML, you can insert one &nbsp; as follows:

    <title abbrev="4VIP Cryptographic Authentication">
       Very Very Very Very Important Protocol (4VIP) Cryptographic&nbsp;Authentication
    </title>

to get this text output:

             Very Very Very Very Important Protocol (4VIP)
                      Cryptographic Authentication

6.3.  How do I control vertical whitespace?

Use the PIs compact and subcompact.

We recommend compact="yes" and subcompact="no".

• compact="yes" will not start each main section on a new page.
• subcompact="no" will put one blank line between list items.

6.4.  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">

6.5.  How do I insert questions for my coauthors?

You can use comments <!-- --> or <cref> elements:

1. Comments are only visible in the XML source file. Example of using comments:

   <!-- [JD] This point needs revision.-->
   

2. <cref> will show up in the text output if you have the PI <?rfc comments="yes"?>.
   
   Example of using <cref>:

   <cref anchor="Q1" source="JD">This point needs revision.</cref>
   

   Further, the PI <?rfc inline="yes" ?> controls whether the comments are displayed inline or at the end of the document.
   
   Output when <?rfc inline="yes" ?>:

   [[Q1: This point needs revision. --JD]]
   

   Output when <?rfc inline="no" ?> in text:

   [Q1]
   

   and at the end of the document:

   Editorial Comments
   
      [Q1]  JD: This point needs revision.
   

7.  Miscellaneous

7.1.  How do I know if my XML is valid?

You can use an XML editor that validates. Also, an xml2rfc validator by Bill Fenner is available here:
http://www.fenron.com/~fenner/ietf/xml2rfc-valid/

Note: xml2rfc is designed to be as forgiving as possible, so perhaps it will successfully convert an XML file that is not valid.

7.2.  Can I get a different kind of HTML output?

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.

7.3.  Is there a tool that will turn my text file into an XML file (i.e., rfc2xml)?

An alpha version of rfc2xml by Brian Adamson and Ian Chakeres is available here: http://sourceforge.net/projects/rfc2xml/

7.4.  I like nroff. How do nroff commands relate to xml2rfc?

A rough translation

NROFF    XML2RFC

.ti #    to change indentation, use list elements.

.in #    all text will be at .in 3
         unless using lists or artwork

.nf      <artwork> </artwork>

.fi      all text in <t> tags will be wrapped

.ne #    <?rfc needLines="#" ?>

.bp      <?rfc needLines="100" ?>

.br      <vspace blankLines="0" /> or <vspace />

.sp #    <vspace blankLines="#" />

\-       &nbhy;  (non-breaking hyphen. will not be broken across a line)

\0       &nbsp;  (non-breaking space.)

[N/A]    &wj; (prevents a line from breaking where it is placed)
              for example: MPLS/&wj;BGP prevents the line from being
              broken after the "/" in MPLS/BGP

8.  Acknowledgments

This FAQ was made possible by the tools, documentation, and templates created by Marshall Rose, Bill Fenner, Charles Levert, Julian Reschke, Elwyn Davies, David Harrington, Pekka Savola, and Henrik Levkowetz.

9. Informative References

Author's Address