The Ox Documentation Tool
January 28, 2004
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
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.