Running JCite

JCite can be run either stand-alone, or as an Ant task. In both cases, it recognizes the following command-line arguments.

--input <file/pattern> / -i <file/pattern>: specifies the input file(s) JCite should process. This is typically the name of an HTML file. If it is a pattern containing wildcard characters (* and ?), then all files matching the pattern are processed. You can specify the -i option multiple times if you must specify more than one path. (Note: Mimicking Unix shells, java.exe expands the wildcards before passing them to the main function unless you enclose the pattern in double quotes.)
--output <file/folder> / -o <file/folder>: specifies the output file or folder that JCite should write to. For a single input file, this must be the name of the output file. It can be the same file as the input file. If the input is a file pattern, then this must be an output folder.
--recursive / -r: specifies that JCite should recursively descend into subfolders of the input pattern.
--source-path <path> / -sp <path>: specifies a source path to search when looking for source files to cite from. You can specify the -sp option multiple times if you must specify more than one path.
--project-path <path> / -pp <path>: specifies the project root path which is stripped from cited paths.
--tripwire-path <dbpath> / -tw <dbpath>: Maintains the tripwire database in the given path as a folder of small files.
--tripwire-file <dbfile> / -twf <dbfile>: Maintains the tripwire database in the given file.
--accept-changes / -ac: Accepts changed citations and updates the tripwire database accordingly.
--diff-path <path> / -dp <path>: Emits both the old and new version of citations for tripwire trip-ups to the given path. Use this to run a diff against them. But see below for how to automate this.
--differ <command>: Runs the given command with the two citation versions (as files) causing a trip-up. So, on Linux, you might use --differ /usr/bin/diff.
--quiet / -q: Run quietly, i.e. don’t print header information.
--verbose / -v: Verbose, i.e. give detailed information about citations processed.
-tt: emits HTML TT tags instead of PRE tags around the Java source fragments. Use this to have automatic line wrapping.

Command Line

Run JCite from the command line as follows (put everything on one line).

Single File

...(path to jcite).../bin/jcite
  -sp ../test
  -i java.html
  -o java.html

Multiple Files

...(path to jcite).../bin/jcite
  -sp ../test
  -i "in/*.html" 
  -o out

Note the double quotes around the pattern, "in/*.html", to prevent java.exe from expanding them itself.

Ant Task

To run JCite 1.0 from within Ant, you can either use Ant’s Java task, or the proper Ant task for JCite. Here’s how to use the Java task:

<java classname="ch.arrenbrecht.jcite.JCite" classpath="${run.classpath}" failonerror="yes">
  <arg value="-sp" />
  <arg path="${src.test.dir}" />
  <arg value="-i" />
  <arg file="${src.doc.dir}/java.html" />
  <arg value="-o" />
  <arg file="${doc.dir}/java.html" />
</java>

The proper Ant task works like this (excerpt from JCite’s own build.xml):

<taskdef name="jcite" classname="ch.arrenbrecht.jcite.JCiteTask" classpathref="run.classpath" />
<jcite srcdir="${build.doc.dir}" destdir="${doc.dir}" projectpath="${basedir}">
  <sourcepath>
    <pathelement location="${src.examples.dir}" />
    <pathelement location="${src.test.dir}" />
    <pathelement location="${src.test.dir}/data" />
  </sourcepath>
  <include name="**/*.htm*" />
</jcite>

Class Path

In both cases, the class path (here ${run.classpath}) should include all jars from

...(path to jcite).../build/*.jar
...(path to jcite).../lib/*.jar

separated by ; (Windows) or : (Unix).

Parameters

We have the following mapping to the ordinary parameters:

srcDir: replaces --input, together with the embedded <include...> directives. The --recursive option is not supported as you can instead use Ant’s **/* notation.
destDir: replaces --output.
projectPath: replaces --project-path.
sourcePath: replaces --source-path.
tripwirePath: replaces --tripwire-path.
tripwireFile: replaces --tripwire-file.
acceptChanges: replaces --accept-changes.
diffPath: replaces --diff-path.
differ: same as --differ.
usePRE: opposite of -tt.
verbose: same as --verbose.