Preface

Let's start at the beginning:

  <?xml version=''1.0"?>   <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"   xmlns:saxon="http://icl.com/saxon"   exclude-result-prefixes="saxon"   version="1.0">   <!-- ====================================================================== -->   <!-- xmlspec.xsl: An HTML XSL[1] Stylesheet for XML Spec V2.1[2] markup   Version: $Id: xmlspec.xsl,v 1.42 2003/07/11 17:12:45 NormanWalsh Exp $   URI: http://dev.w3.org/cvsweb/spec-prod/html/xmlspec.xsl   Authors: Norman Walsh ([e-mail])   Chris Maden ([e-mail])   Ben Trafford ([e-mail])   Eve Maler ([e-mail])   Henry S. Thompson ([e-mail])   Date:     Created 07 September 1999   Last updated $Date: 2003/07/11 17:12:45 $ by $Author:   NormanWalsh$   -->  

A fairly standard control header. There's a lot of change history as well, which I'll leave out. The stylesheet is an XML document, so it starts with an XML declaration. There's no encoding declaration; actually, all the characters are ASCII, which means that almost any XML parser should be able to load this document without difficulty.

Note that the <xsl:stylesheet> element specifies «version="1.0" » . This doesn't guarantee that the stylesheet makes no use of XSLT 2.0 features, but it's a good clue: it means that when the stylesheet is run on an XSLT 2.0 processor, it will run in backwards -compatibility mode, and when run on an XSLT 1.0 processor, errors will be reported at compile time if any XSLT 2.0 constructs are found. This stylesheet is widely used to produce a whole range of documents, and like most other organizations, W3C wouldn't want its business-critical publishing operation to rely on beta release software. So the main stylesheet does indeed stick to XSLT 1.0. As we'll see later, some of the "overlays" to the stylesheet do take advantage of 2.0.

The reference to the Saxon namespace (in fact the old Saxon 6.5 namespace) in the header turns out to be a red herring. There is no use of this namespace within the body of the document, and the stylesheet has no dependencies on features specific to Saxon or any other XSLT processor. Someone put this in to do some experiments, and forgot to take it out. It does no harm, apart from raising a false alarm about the portability of the stylesheet.

The <xsl:output> element defines the output method as html , and indicates the public identifier of the version of HTML that is being generated, which will be copied into the generated output file. This is good practice. It isn't essential, but of course the W3C wants to produce HTML that conforms to its own recommended practice.

  <xsl:preserve-space elements="*"/>   <xsl:strip-space elements="   abstract arg attribute authlist author back bibref blist body case col   colgroup component constant constraint constraintnote copyright def   definitions descr div div1 div2 div3 div4 div5 ednote enum enumerator   example exception footnote front gitem glist graphic group header   htable htbody inform-div1 interface issue item itemizedlist langusage   listitem member method module note notice ol olist orderedlist orglist   param parameters prod prodgroup prodrecap proto pubdate pubstmt raises   reference resolution returns revisiondesc scrap sequence slist   sourcedesc spec specref status struct table tbody tfoot thead tr   typedef ul ulist union vc vcnote wfc wfcnote"/>  

These two elements together indicate that boundary whitespace (whitespace that appears in whitespace-only text nodes) is to be retained for all elements except the long list of elements whose whitespace is to be stripped. The <xsl:preserve-space> element here is actually redundant, since the default is to preserve whitespace anyway. The elements listed for stripping are essentially those that do not allow mixed content in the DTD. It would be nice if there were an easier way of achieving this, but sadly there isn't, not even in XSLT 2.0.

  <xsl:param name="validity.hacks">1</xsl:param>   <xsl:param name="show.diff.markup">0</xsl:param>   <xsl:param name="additional.css"></xsl:param>   <xsl:param name="additional.title"></xsl:param>   <xsl:param name="called.by.diffspec">0</xsl:param>   <xsl:param name="show.ednotes">1</xsl:param>   <xsl:param name="tabular.examples">0</xsl:param>   <xsl:param name="toc.level" select="5"/>  

These global parameters allow the behavior of the stylesheet to be customized. Like many publishing organizations, W3C tries hard to maintain a consistent house-style for its publications, and the use of a common DTD and stylesheet goes a long way toward achieving this. However, different publications do have different requirements, so there is a need to manage variety. Sometimes, the authors needed to introduce a new feature in the stylesheet but didn't want to change the way existing documents were rendered, so they put in a parameter to control the new feature. Sometimes, the parameters reflect the needs of different stages in the publication cycle, for example the parameter «show.ednotes » controls whether editorial notes should be shown.

There's no good reason why the last of these parameters uses the select syntax while the others all place the value in the content of the <xsl:param> element. Generally, I encourage the use of select for simple-valued attributes. Placing the value in the content of the element means that the data type is not a simple number or string, but rather a temporary tree, which however much the XSLT processor optimizes it is likely to be a much more heavyweight data structure. The use of «0 » and «1 » as parameter values, rather than the more obvious true() and false() , can be justified by the fact that with many XSLT processors, there is no way of supplying boolean parameter values from the command line.

There are two ways these parameters can be set. Either the values can be supplied from the calling application (typically, from the command line), or the parameters can be overridden in an overlay stylesheet. An overlay stylesheet (we'll see examples later) is a stylesheet that imports the main xmlspec.xsl stylesheet, and makes modifications or extensions to it. If the parameters were designed to be set in this way only, they could have been defined using <xsl:variable> rather than <xsl:param> , but using <xsl:param> is more versatile because it allows either mechanism to be used.

  <xsl:key name="ids" match="*[@id]" use="@id"/>   <xsl:key name="specrefs" match="specref" use="@ref"/>  

The stylesheet uses two key definitions. These are designed to make hyperlinks within the document easier to follow. The first key matches any attribute named «id » , on any element, making it easy to find an element with a given «id » attribute. The DTD allows an «id » attribute on any element whatsoever. In fact, it defines the type of the attribute to be «ID » , so these elements could also be located using the id() function. (Sorry for the overloading of this term !) In fact, the stylesheet avoids the use of the id() function altogether, probably because id() works correctly only if the document is processed using a validating parser.

The second key definition is a little surprising. A <specref> is a cross-reference: it is used wherever the text says something like "See section 8.2." I wouldn't expect to see any code that needs to locate all the cross-references; a more natural usage would be to index the elements that act as the target of a cross-reference. But on examination, it turns out that this key definition is not used. No doubt it is the result of another experiment, and someone forgot to delete it. Again, it does no harm-the chances are that an XSLT processor will completely ignore a key definition if the key is never used.

  <xsl:output method="html"   encoding="ISO-8859-1"   doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"   indent="no"/>  

The <xsl:output> declaration indicates how the result tree should be serialized. The stylesheet uses HTML output, using ISO-8859-1 encoding (often called Latin-1). These definitions can again be changed in an overlay stylesheet, or in some cases from the command line (with Saxon, for example, specifying «!indent=yes » on the command line will override the <xsl:output> declaration).

  <xsl:strip-space elements="author"/>  

We've already specified <xsl:strip-space> for a long list of elements, including the <author> element, so this declaration has obviously been left in here by mistake. In fact, it's technically an error (and Saxon gives you a warning about it). The XSLT specifications (both 1.0 and 2.0) say that it's an error to have two <xsl:strip-space> or <xsl:preserve-space> declarations for the same element, even if they agree. However, it's one of those errors that the processor is allowed to recover from.

  <!-- Output a warning for unhandled elements! -->   <xsl:template match="*">   <xsl:message>   <xsl:text>No template matches </xsl:text>   <xsl:value-of select="name(.)"/>   <xsl:text>.</xsl:text>   </xsl:message>   <font color="red">   <xsl:text>&lt;</xsl:text>   <xsl:value-of select="name(.)"/>   <xsl:text>&gt;</xsl:text>   <xsl:apply-templates/>   <xsl:text>&lt;/</xsl:text>   <xsl:value-of select="name(.)"/>   <xsl:text>&gt;</xsl:text>   </font>   </xsl:template>  

This is a useful catchall template rule to make sure that the source document and the stylesheet are consistent with each other. In principle, validating the source document against a DTD should ensure that it contains no surprises . But in practice, DTDs change over time, and there's no way to be sure which version of the DTD was used-indeed, there's no way to be sure that the document was validated at all. So this template rule matches any element for which there is no other more specific template rule in the stylesheet. It produces a message (typically on the console) to indicate that an unexpected element was encountered , and it then copies the offending data to the result document in such a way that the start and end tags will show up visibly in the HTML (in red). This is a good way of helping document authors to correct the error.

  <!-- Template for the root node. Creation of <html> element could   go here, but that doesn't feel right. -->   <xsl:template match="/">   <xsl:apply-templates/>   </xsl:template>  

This template rule is superfluous: it does exactly the same as the built-in template rule for the document node. I don't know why the stylesheet author felt uneasy about including the code to generate the <html> element in this template rule. Perhaps, it was because the template rule for a document node is invoked when processing the root of any document tree, not only the principal source document. If the logic for creating the skeleton of the output HTML goes in the template rule for the outermost element (which in this case is called <spec> ) then it's less likely to be invoked by accident when temporary trees or secondary input documents are processed.

The remaining rules in the stylesheet are presented in alphabetical order, by element. This is a good way of making sure that any rule can be found quickly. Unfortunately, it also has a drawback, which is that rules that work closely together (for example, the rules for formatting the front matter, or the rules for outputting syntax productions ) can be widely separated in the source file. For the purposes of exposition, I've therefore regrouped them according to their logical function. The first group I will consider are the template rules that handle the general outline of the HTML output.