Network Working Group A. Russo
Internet-Draft RFC Production Center
Intended status: Informational February 2019
Expires: 17 August 2019
xml2rfc Frequently Asked Questions
Abstract
This is a list of frequently asked questions regarding xml2rfc.
Please send questions or corrections to the xml2rfc mailing list
(https://www.ietf.org/mailman/listinfo/xml2rfc).
*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 (https://xml2rfc.tools.ietf.org/
xml2rfcFAQ.html).
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 5 August 2019.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License.
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?
3. Using References
3.1. How do I put in a reference?
3.2. How do I insert the full reference?
3.3. How do I make the reference tag [RFC2119] instead of
[1]?
3.4. How do I make the reference tag [IKEv2] instead of
[RFC4306]?
3.5. How do I get the references listed in alphabetical
order?
3.6. How do I reference a URL?
3.7. How do I get two sections of references: Normative
and Informative References?
3.8. How do I make a cross-reference to another section?
3.9. What about referring to a section in another
document? or How do I link to a section in another RFC?
3.10. 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 a list like (1), (2), (3) or (a), (b),
(c)?
4.3. How do I get continuous numbering in a list that is
split by text (or across sections)?
4.4. How do I get indentation? or How do I use definition
lists?
5. The Finer Points
5.1. What is CDATA for?
5.2. How do I get an unnumbered figure?
5.3. What are the entities used for special characters?
5.4. How do I put a line break into the title of the
document?
5.5. How do I indicate the editor of the document?
5.6. How do I insert questions for my coauthors?
6. Miscellaneous
6.1. How do I know if my XML is valid?
6.2. Can I get a different kind of HTML output?
6.3. Is there a tool that will turn my text file into an
XML file (i.e., id2xml)?
7. New with v3
7.1. How do I convert my XML file from v2 to v3 so I can
make use of the new features?
7.2. What are the new features with v3?
7.3. How do I insert non-ASCII characters?
7.4. How do I insert a table?
7.5. How do I generate SVG that will be accepted in an
RFC?
7.6. How do I include SVG in my document?
7.7. How do I get bold, italics, or a fixed-width font?
7.8. How do I get subscript and superscript?
7.9. What are the possible values for the type of the
sourcecode element?
7.10. Do I have to use the bcp14 element each time a
keyword (e.g., "MUST") appears in my document?
7.11. What is the best way to print a hardcopy?
7.12. How do I download the XML source files for all RFCs?
7.13. What has been deprecated from xml2rfc v2?
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
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. Creating a Draft
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.2. Where can I get a template?
// not yet updated // // -- --AR
Several templates are available from http://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 (e.g., mib-doc-template-xml.txt).
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
tags around paragraphs, and tags around figures.
Use for blocks of code or figures that contain <.
(See What is CDATA for? for more information.)
For references, replace [RFC2119] with . For
cross-references to sections, replace Section 9 with (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 [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:
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 , 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 () 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 , 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.
3. Using References
3.1. How do I put in a reference?
// not yet updated // // -- --AR
A set of online citation libraries are maintained on xml2rfc.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, there are 2 methods:
1. define an ENTITY at the top:
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
For an Internet-Draft, the citation file uses the draft string.
For example:
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:
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., . The anchors for RFCs are "RFCNNNN"
(4 digits, using leading zeros) and the anchors for Internet-Drafts
are "I-D.".
3.2. 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 [xml2rfc].
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.
3.3. 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.
3.4. 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:
[...]
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, .
3.5. 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"".
3.6. How do I reference a URL?
The eref element for an external reference creates a link in the HTML
output. For example:
yields https://www.w3.org.
W3C Home Page
yields W3C Home Page (http://www.w3.org).
Another option is using xref and creating a reference that uses the
target attribute for the URL. For example:
World Wide Web Consortium (W3C)
yields
[W3C] "World Wide Web Consortium (W3C)", .
3.7. How do I get two sections of references: Normative and Informative
References?
Use the name element (child of the references element) as follows:
Normative References
...
Informative References
...
3.8. How do I make a cross-reference to another section?
// not yet updated // // -- --AR
Make sure the section you want to reference has an anchor attribute.
For example:
Then, refer to it with an xref element:
See .
which yields the text output:
See Section 9.
(where the number of that section is determined dynamically).
3.9. What about referring to a section in another document? or How do I link
to a section in another RFC?
// not fully updated // // -- --AR
Use xref. Examples below are from draft-v3-features. Set
sectionFormat to various options.
"of": See [RFC7991].
"comma": See [RFC7991].
"parens": See [RFC7991].
"bare": See [RFC7991].
(default): See [RFC7991].
With text content: See [the wonderful Section 2 of RFC 7991].
3.10. 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 and
.
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 .
yields the text output:
See the Security Considerations.
4. Using Lists
4.1. How do I get different kinds of lists?
For bulleted lists, use the
element.
For an empty list (indentation only), use the
element with
"empty="true"".
For definition lists (a.k.a. hanging lists in xml2rfc v2), use the
element. See Section 4.4.
For numbers or letters, use the type attribute of the element;
examples below.
For full details, see [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.
4.2. How do I get a list like (1), (2), (3) or (a), (b), (c)?
(1)
(2) is
(3)
(a)
(b) is
(c)
REQ1:
REQ2: is
REQ3:
4.3. How do I get continuous numbering in a list that is split by text (or
across sections)?
Set the group attribute of the element. For example:
1. apples
2. blueberries
3. cherries
Here is some text in between.
4. dragonfruit
5. elderberry
6. fig
4.4. How do I get indentation? or How do I use definition lists?
Use a
element (definition list), where each
(term) in has a
corresponding
(description).
For example:
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.
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:
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.
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.
5. The Finer Points
5.1. 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 <) So it is especially good for when there are
XML examples in the document.
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 &
< for <
> 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 (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:
5.6. How do I insert questions for my coauthors?
You can use comments or elements. Comments are only
visible in the XML source file.
Example of using comments:
will show up in the output when the attribute display="true"
(which is the default).
Example of using :
This point needs revision.
yields
[[This point needs revision.--JD]]
6. Miscellaneous
6.1. How do I know if my XML is valid?
xml2rfc validates it. Also, you can run rfclint:
https://pypi.org/project/rfclint/.
6.2. Can I get a different kind of HTML output?
// not yet updated // // -- --AR
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"
(http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html) for
more information.
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/.
7. New with v3
7.1. 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".
7.2. What are the new features with v3?
Some highlights are including UTF-8 characters, text formatting, and
SVG diagrams. For complete details, see [RFC7991].
7.3. 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].
7.4. How do I insert a table?
For example:
IETF Meetings in 2005
IETF #
City
# of Attendees
62
Minneapolis
1133
63
Paris
1450
64
Vancouver
1240
yields:
+--------+-------------+----------------+
| IETF # | City | # of Attendees |
+========+=============+================+
| 62 | Minneapolis | 1133 |
+--------+-------------+----------------+
| 63 | Paris | 1450 |
+--------+-------------+----------------+
| 64 | Vancouver | 1240 |
+--------+-------------+----------------+
Table 1: IETF Meetings in 2005
Data from https://www.ietf.org/how/meetings/past/.
For full details, see [RFC7991].
7.5. 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
(https://www.rfc-editor.org/rse/wiki/doku.php?id=svg_files).
7.6. 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: