Jeni's XSLT Utilities: Parameter Documentation
Copyright (c) 2000 Dr Jeni Tennison.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
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.
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:
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:
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ç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ç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: