18.1 The Ox Documentation Tool

Although this book provides a glossary, it doesn't provide alphabetical references for XSLT and XPath, partly because the other books I recommend, such as those written by Doug Tidwell and Michael Kay, have already provided excellent reference material. Short of that, you can still easily get the reference information you need about XSLT and XPath by using the glossary in this book and the Ox documentation tool that is provided with this book's resources.

Ox is a small, extensible, open source command-line Java tool that quickly and easily provides brief, syntax-based documentation on a given topic. You can find the tool in the examples/Ox directory of the example archive that you downloaded with this book. Ox accepts one or more terms on a command line and then returns brief documentation on each term. At this time, Ox supports only XSLT 1.0 and XPath 1.0.

Give it a try. While in the directory examples/Ox, type the following command where the term is the name of an XSLT element. Ox is case sensitive, and all XSLT element names must be given in lowercase, as shown here:

java -jar ox.jar xsl:apply-templates

Ox will return the following information to you on standard output:

xsl:apply-templates XSLT instruction element  Applies templates, processing a node-set (the matching  node and its children, if any).     Attributes:  select = An expression [optional]  mode = The mode [optional]     Content:  template  <xsl:sort/> [optional]  <xsl:with-param/> [optional]     Example:  <xsl:template match="/">   <xsl:apply-templates/>  </xsl:template>     See Also: xsl:sort, xsl:value-of

You can also submit multiple terms to Ox, as shown in the following line:

java -jar ox.jar xsl:template xsl:apply-templates

This whitespace-separated list on the command line produces documentation on both terms:

xsl:template XSLT top-level element  Container for an XSLT template.     Example:  match = pattern [optional if name attribute present]  mode = QName for mode [optional]  name = QName for template [optional if match attribute present]  priority = number for template's priority, the higher the number,  the higher the priority [optional]     Content:  template  xsl:param [zero or more]     Examples:  <xsl:template match="/">   <xsl:apply-templates/>  </xsl:template>     See Also: xsl:apply-templates     ---------     xsl:apply-templates XSLT instruction element  Applies templates, processing a node-set (the matching  node and its children, if any).     Attributes:  select = An expression [optional]  mode = The mode [optional]     Content:  template  <xsl:sort/> [optional]  <xsl:with-param/> [optional]     Example:  <xsl:template match="/">   <xsl:apply-templates/>  </xsl:template>     See Also: xsl:sort, xsl:value-of

You can also submit one or more prefixed terms to Ox by using the -xsl switch:

java -jar ox.jar -xsl template apply-templates

This line will return the same output at the previous, prefixed example.

In addition to element names, you can also submit definitional terms to Ox, like XSLT:

java -jar ox.jar XSLT

Ox will return with:

XSLT  Extensible Stylesheet Language Transformations

Phrased terms that contain spaces must be enclosed in quotes, as shown in the following line:

java -jar ox.jar "literal result element"

With this term, Ox will give you:

XSLT literal result element  A non-XSLT element, defined literally in a template, that creates  an element in the result tree.

If you submit a term that Ox doesn't know, such as an XSLT 2.0 element name:

java -jar ox.jar xsl:result-document

Ox barks back, but also gives you a venue where to issue a complaint:

Term "xsl:result-document" not found.

If enough people show interest in Ox, it will grow and expand to meet the demand. Ox uses Java properties files to store its documentation. The Ox package includes a template (template.ox) that you can use to create your own documentation package or simply add terms on your own. All you have to do is add your properties file to the Ox JAR file (ox.jar), and you will have access to the terms from the command line.