$Id: docbook-extensions.html,v 1.9 2004/10/10 06:18:57 balls Exp $
Copyright © 2001 Steve Ball
Table of Contents
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.
This section explains how an XSLT stylesheet is documented, with examples.
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>
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>
<!-- $Id$ -->
<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">
$Id$
</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.
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 documentation for all extension elements.
Refdescription — A description of the topic of a reference entry
| Element Content Model | ||
refdescription ::= (para|...) | ||
| Attributes | Common attributes | |
| Parameter Entities | ||
| None | ||
Refparameter — A description of a template parameter.
| Element Content Model | ||
refparameter ::= (variablelist) | ||
| Attributes | Common attributes | |
| Parameter Entities | ||
| None | ||
Parametername — A parameter name.
| Mixed Content Model | ||
Parametername ::= (#PCDATA) | ||
| Attributes | Common attributes | |
| Parameter Entities | ||
| None | ||
Refreturn — The return result of a template.
| Element Content Model | ||
refparameter ::= (para+) | ||
| Attributes | Common attributes | |
| Parameter Entities | ||
| None | ||