texexec - ConTeXt and PDF auxiliary program and batch processor
SYNOPSIS
texexec [ OPTION ... ] FILE [ ... ]
DESCRIPTION
texexec is a Perl script that provides several functions:
o
Process a TeX file. This includes performing as many runs as
necessary of tex(1), texutil(1), and
metapost(1). Options allow you to select the output
format, the pages to process, paper size, and so forth.
o
Create new ConTeXt formats (with --format).
o
Post-process existing PDF files, including merging multiple
files, and extracting and rearranging pages within a file
(similar to the functions provided by psnup(1) and
pdfmerge(1)).
o
Extract or strip documentation from com{ConTeXt} source files
(using texutil(1)).
o
Run METAPOST (mpost(1)) to generate figures from METAPOST
source.
o
Produce ``proof sheets'' of figures used in a ConTeXt source
file.
OPTIONS
All switches are specified in full, but can be abbreviated to the
shortest unique string. Thus, --ver works the same as
--verbose.
General Options
--alone
Avoid calling other programs when possible. For
example, --alone will prevent texexec from
using fmtutil(1) to generate formats (which can
be handy when tracing installation problems).
--environment=ENVIRONMENT
Specify a ConTeXt
ENVIRONMENT to use when processing the file.
This option can be useful when converting from
non-ConTeXt file formats where no environment or layout
settings are present in the file.
--help [ SWITCH ]
Produce a summary of switches
and arguments. Many switches have additional
information that can be seen by typing ``texexec
--help optvar(SWITCH)''.
--interface=LANGUAGE
Specify the language
ConTeXt should use to communicate with you.
Options are
en
US English
nl
Dutch
de
German
uk
British English
cz
Czech
it
Italian
--once
Process a file once and only once. (By default,
texexec processes the file as many times as
necessary to sort out all references, typeset
METAPOST code, and so forth.)
--output=DRIVER
Specify the output DRIVER
for use with \special primitives. Defaults to the setting in
the local cont-sys.tex file, but can be set to one of
There may be other supported drivers -- check the most
recent ConTeXt documentation.
--pages=PAGENUMBERLIST
Specify the pages or page
range to appear in the output file.
PAGENUMBERLIST may be the keyword odd
or even; one or more pages separated by commas
(x,y); or a page range in the form :z.
--passon=STRING
Pass additional command-line
switches and arguments to the tex(1) process
run by texexec.
For example, the MikTeX TeX system (for
DOS/Windows) can embed information in the DVI file that
will allow you to find the line in a source code file
corresponding to the line in the typeset output. It
uses a switch called ``--src'' to activate this
functionality, and can be used from texexec as
texexec --passon="--src" somefile
The double quotes (") are required to prevent
texexec from using the switch itself.
--program
The name of the TeX program to use
(tex(1), by default).
--result=FILENAME
Allows you to change the
basename of the output file. See
--mode for an example.
--runs=NUMBER
Specify the number of runs to
perform on a file. Overrides
texexec's calculations.
--silent
Suppress diagnostic and progress messages.
--suffix=SUFFIX
Specify the suffix of the output file.
--tex=PROGRAMNAME
Allows you specify the program
to use instead of tex(1). Useful for trying
different versions of tex(1) installed on the
same machine.
Output diagnostic information, including the
contents of texexec.ini.
Processing ConTeXt Source Files
Including specifying paper sizes, formats, and so forth.
--arrange
Don't perform page rearrangements (e.g., for
producing a booklet) until the last run.
--batch
Process the file in batch mode -- continue to
typeset the document after finding errors. More
imformation about batch mode can be found in Donald
E. Knuth's TeXbook.
--bodyfont
The name of a font to preload for use in
setting the body of the text.
--centerpage
Center the document image on the page.
--color
Turn on color mode. Color mode can also be set by
commands embedded in the document. These commands
override the --color option.
--convert=FORMAT
Convert the input file to
ConTeXt format from FORMAT before
processing. In most cases, this conversion will result
in a TeX file. Currently supported input
FORMATs are xml and
sgml.
--dvi
Shortcut for --output=dvi.
--fast
Typeset the document(s) as fast as possible without
causing problems.
--final
Perform a final run without skipping anything.
This option is typically used with --fast.
--language=LANGUAGE
Set the language for
hyphenation. Can be specified in your source file.
Options are the same as those for --interface.
--mode=MODELIST
Allows you to change the mode
(page size and resolution) of the output file.
Here the mode switch tells ConTeXt to obey
the mode directives in the layout specifications. The
--result flag allows you to
rename the output file.
--noarrange
Ignore arrangement commands in the source
file.
--paper=KEY
For typesetting multiple pages on a
single piece of paper. KEY can be a4a3
(for printing A4 pages on A3 paper) or a5a4
(for printing A5 pages on A4 paper). The actual layout
of the pages is specified with the
--print switch.
--pdf
Shorthand for --output=pdftex.
--print=KEY
Specify the layout of the final
output. KEY can be up, resulting in 2
pages per sheet, double sided, or down, resulting
in 2 rotated pages per sheet, double sided. Use the
--paper switch to specify the original page
and sheet size.
Creating ConTeXt Format Files
--format=FORMATFILE
Specify a FORMATFILE
to use when typesetting. texexec will prepend the
string cont- to the name you give, so you can
type plain instead of cont-plain, as in
texexec --format=plain --program=pdftex
somefile
--make
Generate a ConTeXt format file.
Postprocess PDF Files
--combination=ROWS*COLS
Specify
the number of pages to show on a single page. Use with
--pdfcombine.
This command creates an A5 booklet from a PDF file
foo.pdf. --pdfarrange is used in
conjunction with the following switches:
--paperoffset
Adjust the space between the
edge of the pages and the beginning of the text block.
--backspace
Adjust the inside (``gutter'')
margins.
--topspace
Adjust the top and bottom
margin.
--markings
Add crop marks.
--addempty=PAGES
Add empty pages
after the pages specified in PAGES. (Useful
for, among other things, adding blank pages after a
table of contents.)
--textwidth=WIDTH
Set the width of
the original text. Specifying this parameter with a
single-sided original will allow ConTeXt to adjust
the page layout for double-sided output, producing much
more attractive results.
With the --pdfarrange flag, specifying more
than one file will result in all of the files being
combined in the final result, allowing you to add title
pages, decorated part separators, and so forth.
You can also do more complex manipulations, such as
adding additional text to the page by setting up a
small file with layout definitions and a simple figure
insertion loop.
--pdfcombine
Combine multiple pages. Requires you to
specify the
--combination
switch.
--pdfselect
Extract pages from a file. Use in combination with
the --selection switch, as
in
which extracts pages 1, 9, and 14 from
file-1.pdf, and places them in
texexec.pdf (the default output filename if
an output file isn't specified).
See --pdfarrange for other
options.
--selection=PAGES
Specify pages to be affected by
another option. See --pdfarrange and
--pdfselect for examples.
Extract or Strip Out Documentation
--listing
Produce a typeset version of the source code in
FILE. You can specify the form of the output
file, as in
texexec --listing --pdf readme.now
which will produce a PDF file called
texexec.pdf. Without the
--pdf flag, texexec will
produce a DVI file.
See also --backspace and
--topspace.
--module
Create documentation for ConTeXt,
MetaPost (see mpost(1)), and Perl modules.
Converts the documentation to ConTeXt format and
then typesets that documentation. See
texutil(1) for more information about the
format of the documentation strings.
Process METAPOST Figures
--mpformat
The name of a MetaPost format file.
--mptex
Strips out and typesets TeX code embedded in a
MetaPost file.
texexec uses texutil(1) to obtain the list
of figures to process.
USAGE
o
Each ConTeXt user interface (language) has its own format. The
following command generates two formats, one using the English
interface for typesetting in English, and one for Dutch:
texexec --make en nl
By default, the language used for typesetting matches the
user-interface language (set with
--interface. It's possible to use one
language for typesetting and another for messages by changing the
relevant settings in cont-usr.tex, but these languages can
also be changed on the command line with a command such as
texexec --make --language=pl,cz,sk --bodyfont=plr en
That command generates a ConTeXt format file with an English user
interface, and the main language set to Polish (pl). The
default body font is the Polish version of Computer Modern Roman
(plr). Czech and Slovak hyphenation patterns are also loaded
so that Czech and Slovak text included in a source file will be
typeset properly (cz and sk).
o
When the appropriate formats are present, a file can be typeset
by typing
texexec test
texexec tries to determine what interface it should use to
typeset test.tex by looking for a line such as
% interface=en tex=pdfetex output=pdftex
at the top of the file (i.e., on the very first line). This line is
equivalent to TeX's format line, ``&FORMAT'').
By default, texexec will produce a DVI file. The
--pdf flag tells texexec to produce a PDF
file, instead (by running pdftex(1)). You can also be more
specific about what drivers texexec should use, by specifying a
command line such as
texexec --output=dvips,acrobat test
which specifies the use of the dvips driver (which is the
default), combined with the use of Acrobat-specific PDF instructions.
After an error-free run, texexec will run texutil(1) to
determine whether additional runs of tex(1) (or
pdftex(1)) or any utility programs (e.g., bibtex(1),
makeindex(1)) are necessary. You can suppress these
additional runs by specifying the --once or
--runs flags:
texexec --once test texexec --runs=2 test
INITIALIZATION
When starting, texexec first looks for the file
texexec.ini, which specifies the location of various
programs and configuration files, and specifies the programs to use.
The --verbose flag causes texexec to print
the information in texexec.ini to the terminal and the log
file.
texexec requires Perl. On Unix and Unix-like systems, no special
steps have to be taken to get texexec to work beyond installing
Perl and having the perl(1) binary in your path. On Windows
systems, however, you may need to run Perl by typing commands such as
``perl texexec.pl optvar(ARGS)''.
The fpTeX distribution comes with a program called
runperl.exe that can be copied and renamed to texexec.exe.
You will also have to rename a copy to texutil.exe (see
texutil(1)). The teTeX and fpTeX distributions, at
least, should perform the necessary steps as part of their
installation sequence -- if you have problems, however, you may need
to follow the advice given here.
The file texexec.rme contains default configuration
information. If no file texexec.ini exists (in
TEXMF/context/config/, you should copy texexec.rme
to that directory and rename it to texexec.ini. Make any
necessary changes to this file to reflect the layout of programs and
directories on your system.
ENCODINGS
Some languages require specific character encodings to represent their
alphabets (beyond the basic ASCII encoding). Although you can use TeX
commands to represent these characters, such as ``\.z'', it's
easier to use a text editor that includes direct support for these
characters and let ConTeXt translate them to the necessary TeX
commands. For some languages, this approach can also improve the
performance of TeX's hyphenation algorithms.
ConTeXt supports several of the most commonly used encodings.
Check the files beginning with enco-, lang-, and
font- in the ConTeXt distribution for more information.
web2c distributions (such as teTeX) support a mechanism to
map document encodings to ConTeXt's internal encoding, font
encodings, and hyphenation patterns. texexec provides a document
option and a command-line flag to pass the necessary information to
tex(1) or pdftex(1). You can add lines such as
%& --translate-file=cp1250pl
or
% --translate=cp1250pl
to the beginning of your document, or specify the --translate
flag on the command line, as
texexec --translate=il2pl somefile
Note that using language-specific encodings will make your file less
portable than using ASCII. It may not be possible for other people to
typeset your documents on their systems.
This manpage was written by Tobias Burnus
<burnus@gmx.de> and C.M. Connelly
<c@eskimo.com>. It is based on
the TeXExec manual written by Hans Hagen
<pragma@wxs.nl>.