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

1.2. Why should I use xml2rfc?

It's an easy way to create an Internet-Draft in the properformat. It handles boilerplate text and reference text. The HTMLand PDF output formats have new features (such as including SVG figures and non-ASCIIcharacters), and the source file can be used for metadataextraction. Also, the RFC Editor will make use of your source file.(For background, see theRFC 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. Seethe section "XML basics" of[Writing I-Ds and RFCs using XML (revised)] formore 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, thengoing from there. Put <t> tags around paragraphs, and<figure><artwork> tags around figures. Use <![CDATA[ ... ]]> for blocks ofcode or figures that contain <. (SeeWhat is CDATA for? for more information.)¶

For references, replace [RFC2119] with <xref/>.For cross-references to sections, replace Section 9 with<xref/> (if Section 9 has anchor="sec_cons"). SeeUsing References for more information.¶

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

Use thecategory attribute to indicate the intended category of your draft, wherestd is Standards Track,info is Informational,exp is Experimental,bcp is Best Current Practice, andhistoric is Historic.¶

Use thesubmissionType attribute to indicate the intendeddocument stream, where the value can beIETF,IAB,IRTF, orindependent.¶

SeeSection A.1 of [RFC7991]¶

Use the docName attribute to indicate the filename.¶

If the document potentially updates or obsoletes any RFCs, use theupdates and obsoletes attributes to indicate the relevant RFCnumbers. For Internet-Drafts, this information will be displayed inthe 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 andsymRefs.¶

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 istrying 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 withthe first line (<?xml version="1.0">) or it can mean "File notfound". Also, check the permissions on the file.¶

One common error is caused by mismatched tags. For example, whenthere 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 withempty="true".¶

For definition lists (a.k.a. hanging lists in xml2rfc v2), use the <dl> element. SeeSection 4.4.¶

For numbers or letters, use the type attribute of the <ol> element; examples below.¶

For full details, seeSection 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": SeeSection 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 attributeswill 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¶

&amp; 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 keeptogether 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 webservice onhttps://xml2rfc.ietf.org/.¶