summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/man/man1/texutil.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf/doc/man/man1/texutil.1')
-rw-r--r--Master/texmf/doc/man/man1/texutil.1266
1 files changed, 266 insertions, 0 deletions
diff --git a/Master/texmf/doc/man/man1/texutil.1 b/Master/texmf/doc/man/man1/texutil.1
new file mode 100644
index 00000000000..5a6ea8d365e
--- /dev/null
+++ b/Master/texmf/doc/man/man1/texutil.1
@@ -0,0 +1,266 @@
+.TH TEXUTIL 1 UMFT
+.de EX
+.sp
+.in +5
+.nf
+.ft CW
+..
+.de EE
+.in -5
+.ft R
+.sp
+.fi
+..
+.TH "texutil" "1" "October 2000" "ConTeXt" "CONTEXT"
+.PP
+.SH "NAME"
+texutil \- ConTeXt auxiliary program
+.PP
+.SH "SYNOPSIS"
+\fBtexutil\fP [ \fIOPTION\fP\&.\&.\&. ] \fIFILENAME\fP[\&.\&.\&.]
+.PP
+.SH "DESCRIPTION"
+.PP
+When processing a source file, \fBConTeXt\fP (via \fBtexexec\fP(1))
+saves information (including table of contents, tables of figures and
+tables, index entries, cross-references) in a ``utility file\'\' called
+\fIFILENAME\fP\fI\&.tui\fP\&. After each successful run, this
+utility file is postprocessed by \fBtexutil\fP to organize the
+information for the next run\&.
+.PP
+\fBtexutil\fP performs a number of useful functions:
+.PP
+.IP o
+Postprocessing references, including sorting index and list
+entries (with \fB--references\fP)
+.IP o
+Extracting documentation and other types of information from
+\fBConTeXt\fP source files (with
+\fB--documents\fP)
+.IP o
+Logfile analysis (with \fB--logfile\fP)
+.IP o
+Collecting information about graphic files to help with
+typesetting (with \fB--figures\fP)
+.IP o
+Converting EPS files to a PDF format suitable for inclusion in
+PDF files generated with \fBpdftex\fP(1) (with
+--\fB--epspage\fP and
+\fB--epstopdf\fP)
+.PP
+.SH "OPTIONS"
+.PP
+All switches are specified here in full, but can be abbreviated to the
+shortest unique string\&. Thus, \fB--ver\fP works the same as
+\fB--verbose\fP provided that there is no other flag beginning with
+``\f(CWver\fP\'\'\&.
+.PP
+.SH "General Options"
+.PP
+.IP "\fB--help\fP"
+Print a usage summary to stdout\&.
+.IP "\fB--interface=\fP\fILANGUAGECODE\fP"
+Specify the language for
+messages\&. One of \fBen\fP (English), \fBde\fP (German), or
+\fBnl\fP (Dutch)\&. The default language is English\&.
+.IP "\fB--outputfile=\fP\fIFILENAME\fP"
+Specify the name of the
+output file\&.
+.IP "\fB--purge\fP [ \fIBASENAME\fP ]"
+Delete temporary files\&.
+Specifying an optional \fIBASENAME\fP will only
+affect the temporary files that begin with that
+\fIBASENAME\fP\&.
+.IP "\fB--silent\fP"
+Redirects stdout to the \fIlog\fP file
+(\fItexutil\&.log\fP, by default)\&. When used with
+\fB--verbose\fP, a summary is printed to stdout, while
+any other output is written to the \fIlog\fP file\&.
+.IP
+For example,
+.IP
+.EX
+\f(CWtexutil --figures --silent --verbose somefile\&.png\fP
+.EE
+.IP
+will output something like
+.IP
+.EX
+\f(CWn=somefile\&.png t=png x=0bp y=0bp w=443bp h=591bp\fP
+.EE
+.IP
+to stdout, placing other output into
+\fItexutil\&.log\fP\&. This information can be piped
+into another program for further processing\&.
+.IP "\fB--type=\fP\fISUFFIX\fP"
+Specify the \fISUFFIX\fP of the
+file you want \fBtexutil\fP to process\&.
+.IP "\fB--verbose\fP"
+Print diagnostic messages to the screen\&.
+.PP
+.SH "Postprocessing References"
+.PP
+The \fB--references\fP flag instructs \fBtexutil\fP to process
+information about cross-references, index entries, and other data
+requiring more than one pass to process in the \fBConTeXt\fP utility
+file\&.
+.PP
+Index and sorted list entries are sorted before being written out;
+redundant index entries are removed\&.
+.PP
+\fBtexutil\fP is called automatically by \fBtexexec\fP(1) during its
+processing runs unless you specify otherwise\&. \fBtexutil\fP can also
+be run by hand, using the form
+.PP
+.EX
+\f(CWtexutil --references\fP \fIFILENAME\fP
+.EE
+.PP
+This command would cause \fBtexutil\fP to load the utility file
+\fIFILENAME\fP\fI\&.tui\fP, sort and convert the contents of that
+file, and write the results to \fIFILENAME\fP\fI\&.tuo\fP\&.
+.PP
+Options specific to this mode are:
+.IP "\fB--ij\fP"
+Sort ``\f(CWIJ\fP\'\' as ``\f(CWY\fP\'\'\&. Often used when
+processing files written in Dutch\&.
+.IP "\fB--high\fP"
+Convert ``high\'\' ASCII values into equivalent TeX
+commands\&. This switch is provided for backward
+compatibility\&.
+.IP "\fB--quotes\fP"
+Take \fBtex\fP(1) accent commands into
+consideration when sorting\&. (Otherwise, quotes are
+considered to be boundary characters for strings\&.)
+.IP "\fB--tcxpath=\fP\fIPATH\fP"
+Specify path to \fItcx\fP
+filter files for translating
+between encodings\&.
+.PP
+.SH "Extracting Information from ConTeXt Source Files"
+.PP
+\fBConTeXt\fP source files often contain documentation (see
+USAGE for more information about the format) or other
+information that can be extracted by \fBtexutil\fP when called with the
+\fB--documents\fP flag:
+.PP
+.EX
+\f(CWtexutil --documents\fP \fIFILENAME\fP
+.EE
+.PP
+This command produces a file called \fIFILENAME\fP\fI\&.ted\fP
+from a ConTeXt file called \fIFILENAME\fP\fI\&.tex\fP\&.
+.PP
+The \fB--sources\fP flag does the opposite: Documentation lines are
+stripped out of the output, which is written to a file called
+\fIFILENAME\fP\fI\&.tes\fP\&.
+.PP
+Historically, \fBConTeXt\fP source files included other forms of
+information -- such as syntax definitions, macro definitions, and
+editor templates -- that can be extracted with the following flags:
+.PP
+.IP "\fB--infos\fP"
+Extract TeXEdit macro information
+(\fItex\fP->\fItud\fP -- see
+USAGE)
+.IP "\fB--setups\fP"
+Extract \fBConTeXt\fP syntax definitions
+(\fItex\fP->\fItexutil\&.tus\fP)
+.IP "\fB--templates\fP"
+Extract TeXEdit editor templates
+(\fItex\fP->\fItud\fP)
+.PP
+.SH "Analyzing Log Files"
+.PP
+Calling \fBtexutil\fP with the \fB--logfile\fP option allows you to
+extract information about problems with your \fBConTeXt\fP source file
+from the log file produced during a \fBtexexec\fP(1) run\&.
+.PP
+You can specify what information \fBtexutil\fP should report with the
+following options:
+.IP "\fB--box\fP"
+Extract information about overfull boxes\&. By
+default, this flag will cause \fBtexedit\fP to report both
+horizontal and vertical overfull boxes\&. If you\'re only
+interested in one kind, you can specify \fB--hbox\fP or
+\fB--vbox\fP instead\&.
+.IP "\fB--criterium=\fP\fISIZE\fP"
+Exclude reports about boxes that
+are less than \fISIZE\fP points too large\&.
+.IP "\fB--unknown\fP"
+Extract messages about missing references or
+figures\&.
+.PP
+.SH "Gathering Information about Figures"
+.PP
+The \fB--figures\fP flag tells \fBtexutil\fP to generate information
+about one or more (non-EPS) graphics files for use in typesetting\&.
+Called as, for example,
+.PP
+.EX
+\f(CWtexutil --figures *\&.png *\&.tif\fP
+.EE
+.PP
+\fBtexutil\fP 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
+\fItexutil\&.tuf\fP, which is consulted by \fBConTeXt\fP when
+typesetting a page with a non-EPS image file -- see the example given
+for the \fB--silent\fP flag for an alternative\&.
+.PP
+This flag is especially useful when you plan to typeset a file of
+previews of graphic files -- see the discussion of the
+\fB--figures\fP flag in the \fBtexexec\fP(1) manpage\&.
+.PP
+.SH "Converting EPS Files for PDF Inclusion"
+.PP
+\fBtexutil\fP can also convert EPS files to PDF format for inclusion in
+PDF files generated with \fBpdftex\fP(1) or \fBpdfetex\fP(1)\&.
+.PP
+.IP "\fB--epspage\fP"
+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\&.
+.IP "\fB--epstopdf\fP"
+Calls \fBgs\fP(1) to convert the specified
+EPS graphic files into PDF format\&.
+.PP
+.SH "USAGE"
+.PP
+.SH "Embedded Documentation Format"
+.PP
+Documentation lines included in \fBConTeXt\fP source files can be
+specified by beginning lines with the following strings:
+.IP "\f(CW%C\fP"
+Copyright information
+.IP "\f(CW%D\fP"
+Documentation lines
+.IP "\f(CW%I\fP"
+TeXEdit information lines (mostly in Dutch)
+.IP "\f(CW%M\fP"
+Macro code needed to processs the documentation
+.IP "\f(CW%S\fP"
+``Suppressed\'\' lines
+.PP
+The same forms can be used for Perl scripts, except that the
+``\f(CW%\fP\'\' characters are replaced by ``\f(CW#\fP\'\' characters\&. See
+the source for \fBtexutil\fP for an example\&.
+.PP
+.SH "SEE ALSO"
+.PP
+\fBgs\fP(1), \fBpdfetex\fP(1), \fBpdftex\fP(1),
+\fBtexexec\fP(1), \fBtexshow\fP(1)\&.
+.PP
+Web page: <http://www\&.pragma-ade\&.com/>
+.PP
+.SH "AUTHOR"
+.PP
+This manpage was written by C\&.M\&. Connelly
+<c@eskimo\&.com> and Tobias Burnus
+<burnus@gmx\&.de>\&. It is based on
+the \fBtexutil\fP manual written by Hans Hagen
+<pragma@wxs\&.nl>\&.
+.PP
+The PDF manual and \fBtexutil\fP itself can be obtained at
+<http://www\&.pragma-ade\&.com/pragma-ade/texutil\&.htm>\&.