DocBook Extensions For XSLT Stylesheet Documentation

Steve Ball

$Id: docbook-extensions.html,v 1.9 2004/10/10 06:18:57 balls Exp $


Table of Contents

Introduction
Documenting XSLT Stylesheets
XML Namespace
Toplevel Documentation Element
Documenting Templates
Reference

Introduction

XSLTSL requires that all stylesheets and templates are documented using DocBook, a widely-used electronic documentation standard. Norm Walsh introduced some extensions to DocBook to facilitate documenting XSLT stylesheets, and the stylesheets for DocBook itself are documented using this extension.

Further elements have been added to the extension vocabulary for the purpose of documenting XSLTSL stylesheets. The entire extension vocabulary is documented here.

Documenting XSLT Stylesheets

This section explains how an XSLT stylesheet is documented, with examples.

XML Namespace

The XSLT stylesheet must declare an XML Namespace with the namespace URI http://xsltsl.org/xsl/documentation/1.0. The prefix used should then be excluded from the result. For example:

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0">

</xsl:stylesheet>

Toplevel Documentation Element

Major documentation components of the library are contained within the book (for the top level) or chapter (for lower-level components) elements. Individual stylesheets are contained within the reference.

These elements must be qualified within the stylesheet, but for convenience, the default XML Namespace is redefined so that descendant elements need not be qualified. Within the book and reference elements all standard DocBook elements are permitted.

An example of library documentation:

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0">

  <doc:book xmlns="">
    <bookinfo>
      <title>Stylesheet Module For XSLT Standard Library</title>
      <!-- &#36;Id&#36; -->

      <author>
	<surname>Ball</surname>
	<firstname>Steve</firstname>
      </author>
      <copyright>
	<year>2001</year>
	<holder>Steve Ball</holder>
      </copyright>
    </bookinfo>

    <preface>
      <para><ulink url="http://www.w3.org/Style/XSL">XSLT</ulink> is an <ulink url="http://www.w3.org/Markup/XML/">XML</ulink>-based language for transforming XML documents.</para>
    </preface>

    <chapter>
      <title>Reference</title>

      <para>Stylesheets are documented as DocBook <sgmltag>reference</sgmltag> elements.</para>
    </chapter>
  </doc:book>

</xsl:stylesheet>

An example of stylesheet documentation:

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:doc="http://xsltsl.org/xsl/documentation/1.0"
  exclude-result-prefixes="doc"
  version="1.0">

  <doc:reference xmlns="">
    <referenceinfo>
      <releaseinfo role="meta">
	&#36;Id&#36;
      </releaseinfo>
      <author>
	<surname>Ball</surname>
	<firstname>Steve</firstname>
      </author>
      <copyright>
	<year>2001</year>
	<holder>Steve Ball</holder>
      </copyright>
    </referenceinfo>

    <title>String Processing</title>

    <partintro>
      <section>
	<title>Introduction</title>

	<para>This module provides templates for manipulating strings.</para>

      </section>
    </partintro>

  </doc:reference>

The keyword $Id: docbook-extensions.html,v 1.9 2004/10/10 06:18:57 balls Exp $ is used by CVS to insert version and author information.

Documenting Templates

Within each stylesheet, each individual template is documented using a separate toplevel element, template. As for toplevel documentation elements, redeclaring the null XML Namespace allows DocBook elements to be used without qualification. A number of extension elements are used to document XSLT templates. An example of template documentation:

  <doc:template name="str:to-upper" xmlns="">
    <refpurpose>Make string uppercase</refpurpose>

    <refdescription>
      <para>Converts all lowercase letters to uppercase.</para>
    </refdescription>

    <refparameter>
      <variablelist>
	<varlistentry>
	  <term>text</term>
	  <listitem>
	    <para>The string to be converted</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refparameter>

    <refreturn>
      <para>Returns string with all uppercase letters.</para>
    </refreturn>
  </doc:template>

  <xsl:template name="str:to-upper">
    <xsl:param name="text"/>

    <xsl:value-of select="translate($text, $str:lower, $str:upper)"/>
  </xsl:template>

Reference

Reference documentation for all extension elements.


Name

Refdescription — A description of the topic of a reference entry

Synopsis

Element Content Model
refdescription ::=
(para|...)
Attributes Common attributes
Parameter Entities    
None    

Description

A description of a reference entry.

Processing Expectations

Formatted as a block.

See Also

refdescriptor

Examples

    <refdescription>
      <para>Converts all lowercase letters to uppercase.</para>
    </refdescription>


Name

Refparameter — A description of a template parameter.

Synopsis

Element Content Model
refparameter ::=
(variablelist)
Attributes Common attributes
Parameter Entities    
None    

Description

A list of the parameters accepted by a stylesheet template. Each varlistentry in the list names the parameter in its term child element, and a description of the parameter in its listitem child element.

Processing Expectations

Formatted as a block.

See Also

refreturn

Examples

    <refparameter>
      <variablelist>
	<varlistentry>
	  <term>text</term>
	  <listitem>
	    <para>The string to be converted</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refparameter>


Name

Parametername — A parameter name.

Synopsis

Mixed Content Model
Parametername ::=
(#PCDATA)
Attributes Common attributes
Parameter Entities    
None    

Description

A parameter name occurring in running text.

Processing Expectations

Formatted inline.

See Also

refparameter

Examples

<para>A parameter which contains a string value is named <parametername>text</parametername>.</para>


Name

Refreturn — The return result of a template.

Synopsis

Element Content Model
refparameter ::=
(para+)
Attributes Common attributes
Parameter Entities    
None    

Description

Describes the return result of the stylesheet template.

Processing Expectations

Formatted as a block.

See Also

refparameter, refreturn,

Examples

    <refreturn>
      <para>Returns string with all uppercase letters.</para>
    </refreturn>


Name

Refexception, Refthrows — An exception generated by the template.

Synopsis

Element Content Model
refparameter ::=
(para+)
Attributes Common attributes
Parameter Entities    
None    

Description

Describes any exceptions generated by the stylesheet template.

Processing Expectations

Formatted as a block.

See Also

refreturn

Examples

    <refexception>
      <para>An error exception is generated if the nodeset is empty.</para>
    </refexception>