Transforming RFC2629-formatted XML through XSLT

Table of Contents

1  Introduction
2  Supported RFC2629 elements
 2.1  Extension elements
3  Processing Instructions
 3.1  Supported xml2rfc-compatible PIs
 3.2  Unsupported xml2rfc-compatible PIs
 3.3  Extension PIs
4  Anchors
5  Supported XSLT engines
 5.1  Standalone Engines
 5.2  In-Browser Engines
6  Transforming to HTML
 6.1  HTML compliance
 6.2  Standard HTML LINK elements
 6.3  Standard HTML metadata
 6.4  Dublin Core (RFC2731) metadata
7  Transforming to XHTML
8  Transforming to CHM (Microsoft Compiled Help)
9  Transforming to PDF via XSL-FO
 9.1  Extension feature matrix
 9.2  Example: producing output for Apache FOP
10  Utilities
 10.1  Checking References
 10.2  Producing reference entries for books
11  Informative References
§  Author's Address
§  Index

1 Introduction

This document describes a set of XSLT transformations that can be used to transform RFC2629-compliant XML (see [RFC2629]) to various output formats, such as HTML and PDF. The main topics are

• compliance to the xml2rfc XML element set (Section 2),
• support for xml2rfc processing instructions (Section 3),
• the names of anchor elements generated in HTML and PDF output (Section 4),
• various XSLT engines that can be used (Section 5),
• outputting HTML (Section 6) and XHTML (Section 7),
• outputting CHM (Compiled Microsoft Help, Section 8),
• outputting PDF through XSL-FO (Section 9) and
• various utilities (Section 10).

2 Supported RFC2629 elements

rfc2629.xslt supports both all RFC2629 grammar elements and the extensions implemented in xml2rfc 1.21.

2.1 Extension elements

In addition, rfc2629.xslt supports a set of extension elements, using elements and attributes in the namespace "http://greenbytes.de/2002/rfcedit". They are used for

• simple issue tracking and change tracking and
• adding additional metadata to the generated documents (such as HTML LINK elements to related documents, see Section 6.2).

Note that these extensions are experimental. Please email the author in case you're interested in using these extensions.

3 Processing Instructions

All PIs can be set as XSLT parameter as well, overriding any value that is found in the source file to be transformed.

Using processing instructions:

<?rfc toc="yes"?>
<?rfc-ext support-rfc2731="no"?>

Using XSLT parameters:

saxon foo.xml rfc2629.xslt xml2rfc-toc=yes \
  xml2rfc-ext-support-rfc2731=no > result.hzml 

3.1 Supported xml2rfc-compatible PIs

3.2 Unsupported xml2rfc-compatible PIs

3.3 Extension PIs

4 Anchors

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 following anchors get auto-generated:

5 Supported XSLT engines

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) currently are not supported.

5.1 Standalone Engines

The following XSLT engines are believed to work well:

• MSXML3 and MSXML4 (<http://msdn.microsoft.com/xml>; these processors do not support exsl:node-set(), but have a similar proprietary extension)
• Saxon (<http://saxon.sourceforge.net/>)
• Xalan (<http://xml.apache.org/xalan-j/>)
• xsltproc (libxslt) (<http://xmlsoft.org/XSLT/>, make sure that you have a current version)

5.2 In-Browser Engines

The following browsers seem to work fine:

• Internet Explorer 5.5 (Windows version, if MSXML3 is installed)
• Internet Explorer 6 (Windows version)

The following browsers are known not to work properly:

• Mozilla (missing extension function - see change request at Mozilla Bug 215242)

6 Transforming to HTML

Transformation to HTML can be done inside the browser if it supports XSLT. To enable this, add the following processing instruction to the start of the source file:

  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

(and ensure that rfc2629.xslt is present).

6.1 HTML compliance

The transformation result is supposed to conform to the HTML 4.01 strict DTD [HTML]. This can be checked using the W3C's online validator at <http://validator.w3.org>.

6.2 Standard HTML LINK elements

LINK elements exist since HTML 2.0. They can be used to embed content-independant links inside the document. Unfortunately, only few user agents fully support this element, namely Mozilla where it's called "Site Navigation Bar" (by default disabled!).

The following LINK elements are produced:

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

6.3 Standard HTML metadata

The following standard HTML META elements are produced:

6.4 Dublin Core (RFC2731) metadata

Unless turned off using the "rfc-ext support-rfc2731" processing instruction, the transformation will generate metadata according to [RFC2731].

The following DCMI properties are produced:

7 Transforming to XHTML

Transforming to XHTML requires slightly different XSLT output options and is implemented by the derived transformation script rfc2629toXHTML.xslt.

Note: Microsoft Internet Explorer does not support XHTML. Therefore it usually makes more sense to generate plain old HTML.

8 Transforming to CHM (Microsoft Compiled Help)

To generate a CHM file using Microsoft's HTML Help Compiler (hhc), three files are required in addition to the HTML file.

1. hhc - table of contents file (HTML)
2. hhk - index file (HTML)
3. hhp - project file (plain text)

The three files are generated with three specific transformations, each requiring the additional XSLT parameter "basename" to specify the filename prefix.

Example:

saxon rfc2616.xml rfc2629toHhp.xslt basename=rfc2616  > rfc2616.hhp
saxon rfc2616.xml rfc2629toHhc.xslt basename=rfc2616  > rfc2616.hhc
saxon rfc2616.xml rfc2629toHhk.xslt basename=rfc2616  > rfc2616.hhk
hhc rfc2616.hhp

9 Transforming to PDF via XSL-FO

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.

As Apache FOP needs special workarounds (page breaking, table layout), and some popular extensions aren't standardized yet, the translation produces a generic output (hopefully) conforming to [XSL-FO-11-WD]. Specific backends (xsl11toFop.xslt, xsl11toXep.xslt, xsl11toAn.xslt) the provide post-processing for the individual processors.

9.1 Extension feature matrix

9.2 Example: producing output for Apache FOP

Example:

saxon rfc2616.xml rfc2629toFo.xslt > tmp.fo
saxon tmp.fo xsl11toFop > rfc2629.fo

10 Utilities

10.1 Checking References

check-ietf-references.xslt can be used to check all references to RFC-series IETF publications (note this script requires a local copy of <ftp://ftp.isi.edu/in-notes/rfc-index.xml>). For instance:

> saxon rfc2518.xml check-ietf-references.xslt
Normative References:
RFC1766: [PROPOSED STANDARD] obsoleted by RFC3066 RFC3282
RFC2277: [BEST CURRENT PRACTICE] (-> BCP0018) ok
RFC2119: [BEST CURRENT PRACTICE] (-> BCP0014) ok
RFC2396: [DRAFT STANDARD] ok
RFC2069: [PROPOSED STANDARD] obsoleted by RFC2617
RFC2068: [PROPOSED STANDARD] obsoleted by RFC2616
RFC2141: [PROPOSED STANDARD] ok
RFC2279: [PROPOSED STANDARD] obsoleted by RFC3629
Informational References:
RFC2026: [BEST CURRENT PRACTICE] (-> BCP0009) ok
RFC1807: [INFORMATIONAL] ok
RFC2291: [INFORMATIONAL] ok
RFC2413: [INFORMATIONAL] ok
RFC2376: [INFORMATIONAL] obsoleted by RFC3023

10.2 Producing reference entries for books

amazon-asin.xslt uses the Amazon web services to generate a <reference> element for a given ASIN (ISBN). For instance:

<?xml version="1.0" encoding="utf-8"?>
<references>
 <reference target="urn:isbn:0134516591">
   <front>
     <title>Simple Book, The: An Introduction to Internet Management,
               Revised Second Edition</title>
     <author surname="Rose"
                fullname="Marshall T. Rose" initials="M. T. "/>
     <author surname="Marshall"
                fullname="Rose T. Marshall" initials="R. T."/>
     <seriesInfo name="Prentice Hall" value=""/>
     <date year="1996" month="March"/>
   </front>
 </reference>
</references>

Note that the resulting XML usually requires checking, in this case Amazon's database is playing tricks with Marshall's name...

11  Informative References

Author's Address

Index

A B C D E F G H I K L M N P R S T X