xml2rfc Frequently Asked Questions

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 xml2rfc.ietf.org [xml2rfc] as a web-based service or for download. Version 3 of the tool adds new features and will be used by the RFC Editor to create RFCs. The current version is here: ¶

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

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 [Writing I-Ds and RFCs using XML (revised)] for more details. ¶

1.4. Where can I get more information?

• [RFC7991]¶
• xml2rfc mailing list: https://www.ietf.org/mailman/listinfo/xml2rfc ¶

2.1. What's the recommended setup?

not yet updated--AR¶

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

2.3. Can I do it without a template?

not yet updated--AR¶

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

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, 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 Section A.1 of [RFC7991]¶

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

2.5. Why is xml2rfc giving me errors?

not yet updated--AR¶

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

4.1. 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. ¶

5.2. How do I get an unnumbered figure?

not yet updated--AR¶

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

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

5.4. 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. ¶

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

5.6. 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]]
            

6.3. 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/. ¶