Try the XML version of this page. If you have problems with it, consult the compatibility page.

Parameter Documentation

The Select Parameters Utility involves documenting the parameters in your stylesheet. Naturally enough, this documentation is written in XML; this page describes the schema that is used for documenting parameters.

Namespace
Structure
DTD
XML Schema

Namespace

The namespace for the parameter documentation is:

http://www.jenitennison.com/xslt/doc

This namespace should be declared within your stylesheet, preferably on the xsl:stylesheet start tag, and you should make sure that the prefix you use is declared as being an extension-element prefix:

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:doc="http://www.jenitennison.com/xslt/doc"
                extension-element-prefixes="doc">
   ...
</xsl:stylesheet>

Structure

The top-most element for the parameter documentation is the 'doc:param' element. The doc:param element takes a 'name' attribute that should be the same as the name of the parameter that it is documenting. For example:

<doc:param name="lang">
   ...
</doc:param>
<xsl:param name="lang" select="'en'" />

Within the 'doc:param' element, you can firstly give some general descriptors for the parameter. These are:

doc:label: A human-readable label for the parameter. Multiple labels can be specified for the parameter, each of which may should have a different 'xml:lang' attribute to specify the language for the label.
doc:desc: A human-readable description of the parameter and the effect that its value has on the processing of the XML source.

You can also specify various other constraints on the parameter value. There are four types of parameter values that you can define:

parameters that can take one of a number of values: specify doc:choice descriptors for each
parameters that can take a list of values: specify doc:option descriptors for each
numeric parameters: specify minimum and maximum values
free parameters

Mutually exclusive values for parameters are specified within doc:choice elements. Each doc:choice element should contain a doc:value and may contain any number of doc:label elements, each of which should have a different value for its xml:lang attribute.

<doc:param name="lang" xml:lang="en">
   <doc:label>Language</doc:label>
   <doc:desc>The language that the text within the page should be shown in.</doc:desc>
   <doc:choice>
      <doc:value>en</doc:value>
      <doc:label>English</doc:label>
      <doc:label xml:lang="fr">Anglais</doc:label>
   </doc:choice>
   <doc:choice>
      <doc:value>fr</doc:value>
      <doc:label>French</doc:label>
      <doc:label xml:lang="fr">Fran&#231;ais</doc:label>
   </doc:choice>
   <!-- and so on -->
</doc:param>
<xsl:param name="lang" select="'en'" />

Lists of values are specified within doc:option elements. Within the parameter value, the selected options are separated with '::'s. For each of the options, as with the choices, a value and any number of labels (in different languages) can be specified.

<doc:param name="lang" xml:lang="en">
   <doc:label>Language</doc:label>
   <doc:desc>The languages that the text within the page should be shown in, in order of preference.</doc:desc>
   <doc:option>
      <doc:value>en</doc:value>
      <doc:label>English</doc:label>
      <doc:label xml:lang="fr">Anglais</doc:label>
   </doc:option>
   <doc:option>
      <doc:value>fr</doc:value>
      <doc:label>French</doc:label>
      <doc:label xml:lang="fr">Fran&#231;ais</doc:label>
   </doc:option>
   <!-- and so on -->
</doc:param>
<xsl:param name="lang" select="'en::fr'" />

Numeric parameters can be constrained with doc:min and/or doc:max to give minimum and maximum values for the parameter.

<doc:param name="rows">
   <doc:label>Rows</doc:label>
   <doc:desc>The number of rows to show.</doc:desc>
   <doc:min>5</doc:min>
   <doc:max>50</doc:max>
   <!-- and so on -->
</doc:param>
<xsl:param name="rows" select="'15'" />

DTD

The DTD for the parameter documentation dialect is as follows:

<!ELEMENT doc:param (doc:label*, doc:desc*, (doc:choice* | doc:option* | (doc:min?, doc:max?))>

<!ELEMENT doc:label (#PCDATA)>
<!ATTLIST doc:label
   xml:lang    CDATA    #IMPLIED
   >

<!ELEMENT doc:desc ANY>
<!ATTLIST doc:desc
   xml:lang    CDATA    #IMPLIED
   >

<!ELEMENT doc:value (#PCDATA)>

<!ELEMENT doc:choice (doc:value, doc:label*, doc:desc*)>
<!ELEMENT doc:option (doc:value, doc:label*, doc:desc*)>

<!ELEMENT doc:min (#PCDATA)>
<!ELEMENT doc:max (#PCDATA)>

XML Schema

The XML Schema for the parameter documentation dialect is as follows:

<schema xmlns="http://www.w3.org/2000/10/XMLSchema"
        targetNamespace="http://www.jenitennison.com/xslt/doc"
        xmlns:doc="http://www.jenitennison.com/xslt/doc"
        elementFormDefault="qualified">

<complexType name="label">
   <simpleContent>
      <extension base="string">
         <attribute ref="xml:lang" />
      </extension>
   </simpleContent>
</complexType>

<complexType name="desc" mixed="true">
   <choice>
      <any namespace="http://www.w3.org/1999/xhtml" minOccurs="0" maxOccurs="unbounded" />
   </choice>
   <attribute ref="xml:lang" />
</complexType>

<complexType name="choice">
   <sequence>
      <element name="value" type="string" />
      <element name="label" type="doc:label" minOccurs="0" maxOccurs="unbounded" />
      <element name="desc" type="doc:desc" minOccurs="0" maxOccurs="unbounded" />
   </sequence>
</complexType>

<complexType name="option-value">
   <simpleContent>
      <restriction base="string">
         <annotation>option values should not contain double '::'s</annotation>
         <pattern value="([^:]:?)*" />
      </restriction>
   </simpleContent>
</complexType>

<complexType name="option">
   <sequence>
      <element name="value" type="doc:value" />
      <element name="label" type="doc:label" minOccurs="0" maxOccurs="unbounded" />
      <element name="desc" type="doc:desc" minOccurs="0" maxOccurs="unbounded" />
   </sequence>
</complexType>

<simpleType name="positiveNumber">
   <restriction base="decimal">
      <minInclusive value="0" />
   </restriction>
</simpleType>

<complexType name="param">
   <sequence>
      <element name="label" type="doc:label" minOccurs="0" maxOccurs="unbounded" />
      <element name="desc" type="doc:desc" minOccurs="0" maxOccurs="unbounded" />
      <choice>
         <element name="choice" type="doc:choice" minOccurs="0" maxOccurs="unbounded" />
         <element name="option" type="doc:option" minOccurs="0" maxOccurs="unbounded" />
         <sequence>
            <element name="min" type="doc:positiveNumber" minOccurs="0" />
            <element name="max" type="doc:positiveNumber" minOccurs="0" />
         </sequence>
      </choice>
   </sequence>
</complexType>

<element name="param" type="doc:param" />

</schema>

More Information

Instructions

A Simple Example

How it Works

/xslt/utilities/paramDoc.xml by Jeni Tennison; generated using SAXON 6.5 from Michael Kay