texutil - ConTeXt auxiliary program

texutil [ OPTION... ] FILENAME[...]

When processing a source file, ConTeXt (via texexec(1)) saves information (including table of contents, tables of figures and tables, index entries, cross-references) in a ``utility file'' called FILENAME.tui. After each successful run, this utility file is postprocessed by texutil to organize the information for the next run.

texutil performs a number of useful functions:

o

Postprocessing references, including sorting index and list entries (with --references)

o

Extracting documentation and other types of information from ConTeXt source files (with --documents)

o

Logfile analysis (with --logfile)

o

Collecting information about graphic files to help with typesetting (with --figures)

o

Converting EPS files to a PDF format suitable for inclusion in PDF files generated with pdftex(1) (with ----epspage and --epstopdf)

All switches are specified here in full, but can be abbreviated to the shortest unique string. Thus, --ver works the same as --verbose provided that there is no other flag beginning with ``CWver''.

--help

Print a usage summary to stdout.

--interface=LANGUAGECODE

Specify the language for messages. One of en (English), de (German), or nl (Dutch). The default language is English.

--outputfile=FILENAME

Specify the name of the output file.

--purge [ BASENAME ]

Delete temporary files. Specifying an optional BASENAME will only affect the temporary files that begin with that BASENAME.

--silent

Redirects stdout to the log file (texutil.log, by default). When used with --verbose, a summary is printed to stdout, while any other output is written to the log file.

For example,

CWtexutil --figures --silent --verbose somefile.png

will output something like

CWn=somefile.png t=png x=0bp y=0bp w=443bp h=591bp

to stdout, placing other output into texutil.log. This information can be piped into another program for further processing.

--type=SUFFIX

Specify the SUFFIX of the file you want texutil to process.

--verbose

Print diagnostic messages to the screen.

The --references flag instructs texutil to process information about cross-references, index entries, and other data requiring more than one pass to process in the ConTeXt utility file.

Index and sorted list entries are sorted before being written out; redundant index entries are removed.

texutil is called automatically by texexec(1) during its processing runs unless you specify otherwise. texutil can also be run by hand, using the form

CWtexutil --references FILENAME

This command would cause texutil to load the utility file FILENAME.tui, sort and convert the contents of that file, and write the results to FILENAME.tuo.

Options specific to this mode are:

--ij

Sort ``CWIJ'' as ``CWY''. Often used when processing files written in Dutch.

--high

Convert ``high'' ASCII values into equivalent TeX commands. This switch is provided for backward compatibility.

--quotes

Take tex(1) accent commands into consideration when sorting. (Otherwise, quotes are considered to be boundary characters for strings.)

--tcxpath=PATH

Specify path to tcx filter files for translating between encodings.

ConTeXt source files often contain documentation (see USAGE for more information about the format) or other information that can be extracted by texutil when called with the --documents flag:

CWtexutil --documents FILENAME

This command produces a file called FILENAME.ted from a ConTeXt file called FILENAME.tex.

The --sources flag does the opposite: Documentation lines are stripped out of the output, which is written to a file called FILENAME.tes.

Historically, ConTeXt source files included other forms of information -- such as syntax definitions, macro definitions, and editor templates -- that can be extracted with the following flags:

--infos

Extract TeXEdit macro information (tex->tud -- see USAGE)

--setups

Extract ConTeXt syntax definitions (tex->texutil.tus)

--templates

Extract TeXEdit editor templates (tex->tud)

Calling texutil with the --logfile option allows you to extract information about problems with your ConTeXt source file from the log file produced during a texexec(1) run.

You can specify what information texutil should report with the following options:

--box

Extract information about overfull boxes. By default, this flag will cause texedit to report both horizontal and vertical overfull boxes. If you're only interested in one kind, you can specify --hbox or --vbox instead.

--criterium=SIZE

Exclude reports about boxes that are less than SIZE points too large.

--unknown

Extract messages about missing references or figures.

The --figures flag tells texutil to generate information about one or more (non-EPS) graphics files for use in typesetting. Called as, for example,

CWtexutil --figures *.png *.tif

texutil will scan the current directory for PNG and TIFF files and extract some useful information about their sizes and types. By default, this information is stored in a file called texutil.tuf, which is consulted by ConTeXt when typesetting a page with a non-EPS image file -- see the example given for the --silent flag for an alternative.

This flag is especially useful when you plan to typeset a file of previews of graphic files -- see the discussion of the --figures flag in the texexec(1) manpage.

texutil can also convert EPS files to PDF format for inclusion in PDF files generated with pdftex(1) or pdfetex(1).

--epspage

Adjust the bounding box of an EPS file to the dimensions of the output page. This option also removes some redundant information and marks files as converted so that they will not be affected by subsequent runs.

--epstopdf

Calls gs(1) to convert the specified EPS graphic files into PDF format.

Documentation lines included in ConTeXt source files can be specified by beginning lines with the following strings:

CW%C

Copyright information

CW%D

Documentation lines

CW%I

TeXEdit information lines (mostly in Dutch)

CW%M

Macro code needed to processs the documentation

CW%S

``Suppressed'' lines

The same forms can be used for Perl scripts, except that the ``CW%'' characters are replaced by ``CW#'' characters. See the source for texutil for an example.

gs(1), pdfetex(1), pdftex(1), texexec(1), texshow(1).

Web page: <http://www.pragma-ade.com/>

This manpage was written by C.M. Connelly <c@eskimo.com> and Tobias Burnus <burnus@gmx.de>. It is based on the texutil manual written by Hans Hagen <pragma@wxs.nl>.

The PDF manual and texutil itself can be obtained at <http://www.pragma-ade.com/pragma-ade/texutil.htm>.