The Ox Documentation Tool
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.
- Ox hasn't reached 1.0
2004-11-02 01:05:08 niq - Ox hasn't reached 1.0
2010-08-25 19:02:24 maokuang - Vectors, arg!
2004-02-04 13:58:06 S Martin - Vectors, arg!
2004-02-05 09:07:32 Mike Fitzgerald - Vectors, arg!
2004-02-24 14:22:39 Mike Fitzgerald - Improving ox.sh
2004-02-02 18:21:04 Mike Fitzgerald
