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

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 n^th page in range, by a percent sign and increment after range (e.g., 1-100%5 for every 5^th 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 '

lsearch words