Menu

The Ox Documentation Tool

January 28, 2004

Michael Fitzgerald

Ox is a simple documentation tool for people who regularly work at the shell or command-prompt level. It's a command-line Java program that accepts a keyword or term as input and then returns documentation for that term. It's free, open source software (BSD license), and because it uses Java properties, it's easily extensible by non-programmers. This article shows you how to get and use Ox, as well as detail on how the Ox code works and how you can extend it.

If you prefer pointing and clicking to get documentation off the Web, then Ox is likely not for you. Ox works for lazy folks like me who don't want to lift their fingers off the keyboard while working at the command prompt. If you're that kind of person, read on. On the other hand, Ox isn't the greatest medium for providing large amounts of information on a given topic. HTML, XHTML, or PDF are better for that. Ox is best used, I think, for brief documentation, when you are looking for a few specifics on syntax, for example.

Currently, Ox only provides documentation for XSLT 1.0 and XPath 1.0, as well as general XML terms. I wrote Ox to include in a book I wrote about XSLT and XPath called Learning XSLT (O'Reilly, 2003). If there is enough interest in Ox, beyond its life in the book, I'll probably expand it to support other XML-related specs; nevertheless, even if Ox doesn't take off on its own, you are free to munge it as you like.

Ox hasn't reached 1.0 yet, and that's where I could use your help. You can report errors, suggest improvements, add definitions, and offer code fixes by email to . One thing that I am having trouble with is getting Ox to see the properties files in the JAR when the JAR is not in the current directory (tried and true classpath hacks don't seem to work). If the answer is obvious to you, let me know; any help would be appreciated.

Getting Ox

You can download a zip archive of Ox from http://www.wyeast.net/ox.zip. This archive contains Ox source and binary files (a JAR file), Ant build and properties files, a README file, a few scripts, and Ox properties files. Once you download ox.zip and unzip it in a working directory, you are ready to go to work.

Ox uses the JAR method, meaning that the main class (the only class in this case) is identified in the JAR's manifest file, so you can invoke Ox in your working directory with the -jar switch:


java -jar ox.jar 

This command will return usage information:


Ox Documentation Tool version 0.56 2004-01-14

Usage: java -jar ox.jar [ -all | -help | -l ] | [ term(s) ]

The -all switch prints all available terms to standard output (currently more that 250), while the -help switch provides some detail on command options. The -l option prints a BSD-style license to standard output.

Coming to Terms

Now try a term in Ox. Enter this command:


java -jar ox.jar xml

You get the following response:


Extensible Markup Language (XML)

 XML is a language that allows you to create

 your own markup language. It has an

 inherent, logical structure that you can

 use to label document content and data.

 This, in turn, makes XML an ideal language

 for storing interoperable data. In

 addition, XML is open, nonproprietary,

 platform independent, and license free.

 See http://www.w3.org/TR/REC-xml.html.

Ox terms are not case-sensitive, so entering xml, XML, or even xMl will get you the same output.

XSLT elements are displayed in a concise format. Try this line for an example:


java -jar ox.jar xsl:element

Here's the output:


xsl:element instruction element

 Creates an element in a result tree. May contain a template.



Attributes:

 name = An element name [required]

 namespace = A namespace name (URI) for the element [optional]

 use-attribute-sets = Name of attribute set/list of sets [optional]



Content: template



Example:

 <xsl:template match="name">

  <xsl:element name="given">Joe</xsl:element>

  <xsl:element name="family">Jackson</xsl:element>

 </xsl:template>



See Also: xsl:attribute, xsl:attribute-set, xsl:comment,

          xsl:processing-instruction, xsl:text

The xsl: prefix is used to help distinguish XSLT element names. In this format, the element is defined first, followed by a list of attributes (if any). Each attribute is marked as either optional or required. The element's allowed content is noted, and an example of the element in context is provided along with cross-references.

XSLT and XPath functions also have a distinct format. Here is an example using the function-available() function:


java -jar ox.jar function-available()

The pair of parentheses at the end of the function name is essential. This command produces:


function-available() XSLT function

 Checks to see if a function is available. Used for extension functions.



Return type: boolean



Arguments:

 string = QName of extension function [required]



Example:

 <xsl:value-of select="function-available('saxon:tokenize()')"/>

A brief definition is given for the function, followed by a return type, a list of arguments (if applicable), and a notation as to whether the argument is required or not. An example call to the function is also provided.

You can submit more than one term at a time to Ox. For example, the following command:


java -jar ox.jar xsl:element xsl:attribute xsl:attribute-set

will list documentation for all three XSLT elements, separated by a string hyphens. You must use the prefix with XSLT element names; however, you use the -xsl switch to set off a list of XSLT element names, as show in this line:


java -jar ox.jar -xsl element attribute attribute-set

This command will give you the same result as using the xsl: prefix with each of the three element names.

If you submit a term that Ox doesn't recognize, Ox lets you know. For example, if you submitted the term blech:


java -jar ox.jar blech

You will get this response:


Term "blech" not found.



Suggest a term at ox@wyeast.net.

Feel free to offer corrections, improvements, or missing terms to ox@wyeast.net.

For your convenience, the Ox archive contains a pair of scripts that help reduce typing. There is one for Windows and another for Unix systems. The ox.bat batch file for Windows looks like this:


@echo off

rem run Ox documentation tool on Windows

rem use replaceable parameters %1 %2 %3 %4 %5 %6 %7 %8 %9

rem if not NT/2000/XP

java -jar ox.jar %*

The replaceable parameter %* allows you to use any number of parameters on the command line. If you are not running Windows NT, 2000, or XP, however, you must use %1 through %9 instead. This batch file reduces your typing. For example, you can use a command that invokes a switch:


ox -help

Or like this one that grabs a term:


ox xsl:element

The ox.sh shell script works identically to ox.bat but in a Unix environment:


#! /bin/sh

# run Ox documentation tool in a shell

java -jar ox.jar $*

How Ox Works

A Java property associates a key with a value. Such properties can be created directly in code or stored as strings in external files. Here is a simple example of a property definition as it would appear in a file:


hello=How are you?

The key hello is associated using the equals sign with the value How are you?. Java can load this property from an external file and use the value where desired. This allows things like configuration attributes to be easily updated without having to touch the code. (There's certainly more to properties, but that's the general idea.)

Ox takes advantage of this technique to allow you to change or update documentation without forcing you to monkey with the code. The Ox jar file ox.jar contains three Java properties files, gloss.ox, xslt.ox, and xpath.ox. The Ox property files contain the terms (keys) and definitions (values) that Ox accesses.

The Ox code (Ox.java) allows you to add properties files to ox.jar using your own definitions, even if you don't know a lick of Java. The code will pick up any properties files that exist in the JAR. Here is the snippet of code, the function getFiles(), that does the magic:


/* Get properties files */

private SequenceInputStream getFiles() throws IOException {



    JarFile jf = new JarFile(jarFile);

    JarEntry je = null;

    SequenceInputStream sis = null;

    Vector sl = new Vector();

    Enumeration entries = jf.entries();

    while(entries.hasMoreElements()) {

        je = (JarEntry) entries.nextElement();

        if (je.getName().endsWith(".ox")) {

            sl.addElement(jf.getInputStream(je));

        }

        Enumeration ve = sl.elements();

        sis = new SequenceInputStream(ve);

    }

    return sis;



}

This code identifies a JAR file (JarFile) and marches through the entries looking for files with the suffix .ox, in other words, it is looking for Ox property files. When it finds these files, it places them file in a Vector whose elements are assigned to an Enumeration and then to a SequenceInputStream.

Try adding a new properties file to ox.jar yourself. First, create a little text file containing:


reply=I am fine!

and name it myox.ox. Now use the JAR utility to add myox.ox to ox.jar using this command line:


jar uvf ox.jar myox.ox

This command should return:


adding: myox.ox(in = 19) (out= 21)(deflated -10%) 

If you get an error, you likely don't have the JAR utility available on the command line. You can get it by dowloading a recent Java software development kit from Sun's Java site. Now test your new addition by typing this command:


java -jar ox.jar reply 

The response should be:


I am fine!

By the way, the Ox archive (ox.zip) contains a template file called template.ox. Make a copy of this file if you want to create documentation that duplicates the format used for XSLT elements in xslt.ox.

It is possible that with all this free rein, Ox could wind up with identical key terms with different values in separate properties files. If this occurs, only the last key term in the last properties file in the JAR will have its value returned (earlier keys are ignored). So if you add terms that may produce conflicts, (1) use a conventional namespace prefix, if applicable, as I did with XSLT elements (xsl:); or (2) combine the terms so that you will get two or more definitions on the same term.

Conclusion

Ox may not be for everybody, but it's a handy tool for those who go to the command line frequently and who want succinct information on a topic quickly. It's easy to update and augment, even for non-programmers, so I hope you find it useful.