## How to Run Tools

All tools run from the command line in a shell with the following syntax:

> `java tool.XXX [options] files`

Tools all live in the file `Multivalent.jar`, and that file is made visible to Java by adding its path to your `CLASSPATH` environment variable. For example, for UNIX (including Mac OS X and Linux), depending on your shell, `setenv CLASSPATH $CLASSPATH:/path/to/Multivalent.jar` or `export CLASSPATH=$CLASSPATH:/path/to/Multivalent.jar`. Alternatively, you can set the classpath explicitly as an option, as in

> `java -classpath /path/to/Multivalent.jar tool.XXX [options] files`

A third way is to put `Multivalent.jar` in Java's `lib/ext` directory.

If a tools stops with an `OutOfMemoryError`, it might have a perversely large object (such as an 8500x8500 pixel image -- 1000ppi!), so try boosting memory, as in:

> `java -Xmx192m tool.XXX [options] files`

### Common Options

In the documentation for each command, the set of options is described in a bullet list. In addition to tool-specific options, all tools support the following:

- -verbose -- There is a normal level of informative messages. This option reports in greater detail.
- -quiet -- to limit output to essential information. (This option is not the opposite of -verbose.)
- -version -- to show version of individual tool, which is different than the overall Multivalent version
- -help -- to show the tool's syntax and options available

Other options and concepts are popular:

- file-or-directory -- Most tools that accept filenames also take directories and recursively process all files in those directories.
- range or page-range -- list of numbers or pages
  - single page by specifying page number (e.g., `10`), with first page numbered `1` (not `0`)
  - special name for last page (`last` or `end`) and first page (`first`)
  - range of consecutive numbers/pages by separating single pages with hyphen (e.g., `1-10`, or `37-last`)
  - logical groups: `all` pages, all `odd` or `even` pages, or all pages in `reverse` order
  - range in reverse order (e.g., `10-1`, `end-25`, `1-10%reverse`, `odd%reverse`)
  - every nth page in range, by a percent sign and increment after range (e.g., `1-100%5` for every 5th page, `1000-1%100`, `1-100%odd`, `1-100%even`)
  - multiple copies of single page, by a star and count after single page (e.g., `last*5`)
  - multiple pages or ranges separated with a comma (e.g., `1-3,5,1,odd,7-20`).

  If tool, such as `tool.pdf.Split`, supports multiple groups:

  - separate groups with semicolon (e.g., `1-10,last;1,11-20,last`)
  - group by every n pages with slash and page count at end of range (e.g., `/1` bursts into single pages, and `1-100/20` is short for `1-20;21-40;41-60;61-80;81-100`)

  Advanced

  - back map from preexisting range to an order that will restore the original order. This applies to the entire series of ranges. For example, `odd,even` gives `1,3,5,7,9,2,4,6,8,10` on a ten page document, so `odd,even,backmap` gives `1,6,2,7,3,8,4,9,5,10`. When pages preexisting in the order `1,3,5,7,9,2,4,6,8,10` are selected in the order `1,6,2,7,3,8,4,9,5,10`, we recover the original order `1,2,3,4,5,6,7,8,9,10`.
- length -- lengths can be given with the following suffixes and units
  - metric: `m` (meters), `cm` (centimeters), `mm` (millimeters)
  - English: `in` (inches), `ft` (feet), `mile` (miles)
  - printers: `pt` (points -- 72.27/in), `sp` (scaled points -- TeX), `bp` (big points -- 72/in), `pc` (picas), `dd` (didot points), and `cc` (ciceros)
  - screen: `px` (pixel -- according to current screen)
- paper-size -- paper size can be given by name from the following list:
  - American: `US` or `letter` (8.5x11in), `legal` (8.5x14in)
  - ISO: `A0` - `A10`, `B0` - `B10`, `C0` - `C10`
  - `foolscap` (13.5x17in)
  - explicit dimensions: `widthxheight`, with lengths as above
  Paper sizes can also be given as explicit dimensions, in the following syntax: widthxheight units, where units is one of the length units given above.
- image-format -- images can be written in any of the following formats:
  - `JPEG`
  - `PNG`
  - `JPEG2000`, `TIFF`, `PNM` and others -- if Java Advanced Imaging is installed
  - `BMP` and `WBMP` are available with Java 1.5 or Java Advanced Imaging
- size -- suffixes:
  - `k` / K / KB - kilobyte
  - `m` / M / MB - megabyte
  - `g` / G / GB - gigabyte
  - `t` / T / TB - terabyte

### Shortcuts

The lengthy syntax can be reduced to look like other commands by using your shell's aliasing capability. For instance, for UNIX shell tcsh the following command

> `alias lsearch 'java -classpath /path/to/Multivalent.jar tool.lucene.Search -index /path/to/index '`

makes full-text search available with the short

> `lsearch words`