Enables support for specific elements inside abstract elements (using this extension makes the document incompatible to the RFC7749 grammar; see description of conversion XSLT in Section 13.4).

rfc-ext

authors-section

xml2rfc-ext-authors-section

"end"

When "before-appendices", place the authors section between references and appendices (this ordering was used a long time ago).

rfc-ext

doi-uri

xml2rfc-ext-doi-uri

"http://dx.doi.org/{doi}"

URI template for DOIs.

rfc-ext

duplex

xml2rfc-ext-duplex

"no"

When set to "yes", format the PDF output for doublesided printing.

rfc-ext

errata

xml2rfc-ext-errata

Can be used to specify an errata file; output will link to individual errata when possible. See Section 6.6

rfc-ext

html-pretty-print

xml2rfc-ext-html-pretty-print

Used to specify a JS-based code pretty-printer; the value is the CSS class name to insert, followed by a blank space, followed by the URI of the JS library. For instance: "prettyprint https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"

rfc-ext

include-index

xml2rfc-ext-include-index

"yes"

When set to "no", no index will be generated.

rfc-ext

include-references-in-index

xml2rfc-ext-include-references-in-index

"no"

When set to "yes", index entries are generated for all references.

rfc-ext

insert-metadata

xml2rfc-ext-insert-metadata

"yes"

When set to "yes", include JS code that fetches current RFC metadata and inserts it into the front page (standards track, obsoletion, updates, errata).

Determines whether <xref> with text content generates additional text as in traditional text output ("text"), or just generates a link around the text ("nothing"). Note that the default might change in the future in order to achieve compatibility with other formatters.

The transformation automatically generates anchors that are supposed to be stable and predictable and that can be used to identify specific parts of the document. Anchors are generated both in HTML and XSL-FO content (but the latter will only be used for PDF output when the XSL-FO engine supports producing PDF anchors).¶

The transformation requires a non-standard extension function (see exsl:node-set) which is however widely available. XSLT processors that do not support this extension (or a functional equivalent, such as msxsl:node-set) currently are not supported.¶

Input documents do not always specify the date completely. In this case, the transformation attempts to let the XSLT engine to compute the system date, using either scripting in Microsoft's XSLT engine, or the exsl:date-time extension function.¶

Note that browsers in general do not load external DTDs nor external entities (see, for instance, Mozilla Bug 22942) thus entities like &nbsp; need to be declared in the internal subset (Appendix C.1).¶

LINK elements exist since HTML 2.0. They can be used to embed content-independant links inside the document. Unfortunately, only few user agents support this element. Firefox users may want to check the Link Widgets extension.¶

The following LINK elements are produced:

LINK type

description

alternate

for RFCs, a link to the authorative ASCII version on the IETF web site

appendic

pointer to all top-level appendics

author

pointer to "authors" section

chapter

pointer to all top-level sections

contents

pointer to table of contents

copyright

pointer to copyright statement

index

pointer to index

The figure below shows how Mozilla Firefox 1.0 displays the Site Navigation Bar for rfc2396.xml.

RFCs are immutable; once published, they do not change anymore. What does change though is their status, their relation to subsequent RFCs (such as when they are updated), and errata.¶

rfc2629toXHTML.xslt by default inserts code that will pull the relevant information from <https://tools.ietf.org>. This can be disabled by specifying the parameter "xml2rfc-ext-insert-metadata=no" (or by inserting the equivalent processing instruction into the source code).¶

Note: the status information really should be available from the RFC Editor, right now it only exists only in HTML form (such as in <https://www.rfc-editor.org/info/rfc2616>. Furthermore, the service provided by <https://tools.ietf.org> is considered experimental, so this feature might be changed or removed without prior notice.¶

...and no, we currently can't obtain the exact list of errata, just a flag indicating whether errata exist.¶

Unfortunately, the RFC Editor does not provide errata information in a well-defined machine readable format. What's available is "regular" HTML (and that could be the worst currently in use in standards bodies...).¶

parse-errata.xslt attempts to parse useful information out of these pages.¶

The code tries to make sense of the HTML, in particular it tries to detect what RFC sections each erratum applies to. The resulting XML format is work-in-progress and just contains the information that will be useful in subsequent formatting of the RFC.¶

When formatting the RFC for HTML output, the errata file can be passed as stylesheet parameter ("xml2rfc-ext-errata"). The output will include errata links at the beginnings of the section they apply to, or at the beginning of Section 1 when the location is unknown.¶

For the sake of embedding, three types of errata are relevant; their type is indicated with a symbol:¶

"held for update": reviewed and decided to be "held for document update" (these are mostly editorial); "scissors" symbol.

"submitted": submitted, but not reviewed; "letter" symbol.

"verified": reviewed and found to be correct; "checkmark" symbol.

To recap: the errata information is passed into the transformation as additional parameter. The errata information will not be automatically retrieved from the RFC Editor web site.¶

Transformation to XSL-FO [XSL-FO] format is available through rfc2629toFO.xslt (which includes rfc2629.xslt, so keep both in the same folder).¶

Compared to HTML user agents, XSL-FO engines unfortunately either come as open source (for instance, Apache FOP) or feature-complete (for instance, AntennaHouse XSL Formatter), but not both at the same time.¶

PDF output can also be produced directly from (X)HTML. One simple approach is to rely on the browser's printing function, and to use a printer driver that produces PDF. Depending on the brower's CSS capabilities, the output will behave properly with respect to table breaks etc.¶

An alternative is PrinceXML (see <http://www.princexml.com/>), which can produce PDF directly from (X)HTML input, based on the CSS printing information.¶

For instance, PDF output with text justification turned on can be produced with:

Using its "value" attribute, this element allows the definition of an internal link target alias for the enclosing element. This alias can then be used with the <ref> element for intra-document references.¶

Note that the anchor alias is not subject to the naming constraints that apply to anchor elements (which are XML names).¶

This element can be added as a top-level child element below <rfc> to indicate additional link information. It's currently used only when generating HTML output, in which case an HTML <link> element with identical attributes gets generated.¶

If the attribute "basename" is present, it is used to compute the target href based on the output format being generated (this is handy for "next"/"prev" links in a series of documents. In this case, the href attribute is not required.¶

This element is a simplified variant of the <xref> element, in that no "target" attribute needs to be specified, instead the text contents acts as identifier. That in itself wouldn't be terribly useful, but together with the <anchor-alias>, it allows referring to other parts of the document with minimal additional markup.¶

Sometimes, artwork occurs inside lists. To get it indent properly in xml2rfc's text output, it needs to be indented in the source. This is sub-optimal, as this whitespace will also appear in the HTML output, where it's already indented due to HTML's semantics. As a workaround, a "x:indent-with" attribute can be specified, containing a string that will be prepended to each line when clean-for-DTD.xslt is run (see Section 13.4).¶

Finally, when allowing pretty-printing of code (see "html-pretty-print" in Section 3.3, the "x:lang" attribute can used to explicitly opt into pretty-printing. If the pretty printer can figure out the code type without assistance, an empty value will be sufficient. Otherwise, the language can be specified in the attribute (such as "html"), which will in turn be coded into the CSS class as "lang-" concatenated with the language name.¶

The extension attribute below is allowed on the standard <iref> element: ¶

x:for-anchor specifies that the <iref> will also be automatically inserted whenever the specified anchor is cross-referenced -- this may save entering lots of <iref> instances. As a special case, a value of "" (empty string) refers to the anchor attribute of the closest ancestor.

The extension attribute below is allowed on the standard <list> element: ¶

x:indent specifies the amount of indentation for list items in hanging lists. This can be useful when the output format, such as XSL-FO, does not support automatical formatting. The value takes an XSL-FO width, such as "5em". The default is length of longest label in characters times 0.8em.

Also, the <list> element can take <x:lt> child elements instead of <t>, allowing to insert multiple paragraphs into a single list item.¶

If the document is supposed to be published on the IETF standards track, the desired level can be specified using the parameter intended-level as 'proposed', 'draft' or 'internet'. Alternatively, it can be specified inside the document using the attribute x:maturity-level on the <rfc> element (see Section 11.26).¶

Note: Downward references should be annotated using the <annotate> element, containing an <xref> to [BCP97].¶

When an XSLT 2.0 processor is used, links in the document can be checked as well using the link-check parameter ('yes' or 'no'). Note that this only works for http links to documents of type text/*.¶

for RFCs, the name attribute must be "RFC", and the value attribute must be the number of the RFC,

for Internet Drafs, the name attribute must be "ID" or "Internet-Draft", and the value attribute must be the file name of the draft (including the two-digit running number, but excluding a file extension),

for W3C documents, the name attribute must be "W3C", must start with "W3C ", or must start with "World Wide Web Consortium ", and the value attribute must be the "shorthand" name of the specification, such as "REC-xml-19980210".

Note: this stylesheet will need network access to check links and status of Internet Drafts. When running a Java-based XSLT engine, you may have to supply Java system properties specifying the HTTP proxy to be used, such as "-Dhttp.proxyHost=hostname -Dhttp.proxyPort=80".¶

gen-reference-graph.xslt generates a graph of RFC dependencies, using the same base data as in check-references.xslt (see Section 13.1). Its output is a "dot" file, to be processed by GraphViz (see <http://www.graphviz.org/>).¶

clean-for-DTD.xslt can be used to down-convert some extensions to a format that is supported by the existing xml2rfc formatters, mainly for the purpose of generating plain-text output. Note that these extensions are experimental (feedback appreciated).¶

<x:prose> elements are transformed into <seriesInfo> elements (which is an abuse of the element and only a workaround until xml2rfc gets a matching extension).

<x:ref> elements get replaced by <xref> elements, targetting either the anchor or another anchor with matching <x:anchor-alias> child element.

Note: the above list is known to be incomplete and needs work. For instance, most of the extensions described in Section 12 get some mapping as well.¶

As the output formatters evolve to support the V3 format (proposed in [RFC7991]), clean-for-DTD.xslt will start taking advantage of these changes. Right now, it supports three modes, one of which being used for the historic TCL processor, and the other ones being used with xml2rfc 2.5.2 and xml2rfc 2.6.0 (see https://pypi.python.org/pypi/xml2rfc/).¶

The modes can be selected using the xml2rfc-ext-xml2rfc-backend parameter or the rfc-ext/xml2rfc-backend processing instruction. The default mode is "201610" for documents with a publication date between January and May 2017, "201706" for documents newer than May 2017, and "201510" otherwise:¶

201510

For xml2rfc.tcl and versions of the Python formatter before version 2.5.2.

With extract-artwork.xslt, artwork elements named through the "name" attribute can be extracted. This can be used to automatically check their syntax (for instance, when ABNFs appear within a figure element).¶

For instance:

saxon rfc3986.xml extract-artwork.xslt name=uri.abnf

In addition, artwork of a specific type can be extracted, such as with:¶

saxon rfc3986.xml extract-artwork.xslt type=abnf

When extracting by type, artwork elements with a specified name can be excluded; this can be handy when the document uses some kind of schema language, and an appendix contains the collected schema, repeating definitions from earlier on. Example:¶

The "HTML Live Refresh" mode allows to run a text editor and a browser side-by-side, with the browser auto-updating every few seconds, displaying the updated HTML, and automatically navigating to the part of the page that changed last.¶

There are many methods for automatic inclusion of material in the XML source, such as the "include" processing instruction (see Section 3.1), external entities (Appendix C.1), or XInclude. In general, those share a common problem: the XML source file isn't self-contained, which makes it harder to submit it as Internet Draft.¶

The tool refresh-inclusions.sh does in-place replacement: it scans the source file for inclusion directives (expressed as XML processing instructions), and refreshes the included text with data from an external file. It will not modify the source file unless included material did actually change. When it does modify the source file, it will copy the original source to a backup file.¶

refresh-inclusions.sh can include both plain text (BEGINESCAPEDINC/ENDESCAPEDINC) and XML (BEGININC/ENDINC). The figure below was inserted using:¶

The prolog of the XML document can both be used to refer to an external DTD, and also to define internal entities (Section 2.8 of [XML]):¶

<?xml version="1.0"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- use "&MAY;" for a BCP 14 "MAY", see Section 11.4 -->
<!ENTITY MAY
"<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MAY</bcp14>">
<!-- re-declare "&nbsp;" as code point 160 (non-breaking space) -->
<!-- you may need this for UAs that do not read external DTDs -->
<!ENTITY nbsp
"&#160;">
<!-- allow later RFC2616 reference using "&rfc2616;" -->
<!-- the data will be fetched from xml.resource.org -->
<!ENTITY rfc2616 SYSTEM
"http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!-- allow a custom reference using "&mydraft;" -->
<!-- the data will be fetched from the same location as the
source file -->
<!ENTITY mydraft SYSTEM "reference.mydraft.xml">
]>

Note: including entities from a remote site will not work in browsers due to the Same-Origin policy.

Note: the name for the attribute sets may change in the future as more working is done with respect to customizability. In any case, overriding the settings in a separate file will be easier to maintain. Please contact the author if you find yourself trying to override style definitions that currently do not use attribute sets.¶

Note: the CSS style information used in rfc2629.xslt can be overriden in a similar (but less granular) way: just overwrite the template called "insertCss". As for XSL-FO, the class names may change in future.¶

Various attributes of the <rfc> element plus some child elements of <front> affect the automatically generated parts of the front page, such as the tabular information at the beginning, the "Status Of This Memo", and the "Copyright Notice".¶

When submitting an Internet Draft, this "boilerplate" is checked by "Idnits" (<http://tools.ietf.org/tools/idnits/>) for compliance with the current Intellectual Property rules, and thus it is important to set the correct values.¶

Furthermore, the RFC Production Center uses RFC7749-based tools to generate the final RFC text, so the more accurate the supplied information is, the less additional work is left, and the risk for errors in producing the final (and immutable!) document is reduced.¶

Note: this only applies to the case when IETF documents are produced. The "private" processing instruction allows to switch off most of the autogeneration logic.¶

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: ¶

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of Julian Reschke nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.¶