texexec(1) ConTeXt texexec(1)NAMEtexexec - ConTeXt and PDF auxiliary program and batch pro-
cessor
SYNOPSIStexexec [ OPTION ... ] FILE [ ... ]
DESCRIPTIONtexexec 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 out-
put 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 pro-
vided 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 Con-
TeXt 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 process-
ing the file. This option can be useful when con-
verting 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 --helpoptvar(SWITCH)''.
--interface=LANGUAGE
Specify the language ConTeXt should use to communi-
cate 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 neces-
sary 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
pdftex Native pdftex(1) code
dvips For dvips(1) (the default)
dvipsone
For dvipsone
dviwindo
For dviwindo, the oldest ConTeXt drivers
dviview
For dviview (experimental)
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/Win-
dows) 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 out-
put. 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 tex-
exec 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.
--texutil
Force a run of texutil(1).
--verbose
Output diagnostic information, including the con-
tents of texexec.ini.
Processing ConTeXt Source Files
Including specifying paper sizes, formats, and so forth.
--arrange
Don't perform page rearrangements (e.g., for pro-
ducing 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 FOR-
MAT before processing. In most cases, this conver-
sion will result in a TeX file. Currently sup-
ported 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 reso-
lution) of the output file.
texexec--pdf --mode=A4 --result=pdftex-a pdf-
tex-t
texexec--pdf --mode=letter --result=pdftex-l pdf-
tex-t
texexec--pdf --mode=screen --result=pdftex-s pdf-
tex-t
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 speci-
fied 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. tex-
exec 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.
--pdfarrange
For rearranging pages in PDF files.
texexec--pdfarrange --paper=a5a4 --print=up
foo.pdf
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 com-
bined 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
texexec--pdfselect --paper=S6 --selection=1,9,14
file-1
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 documen-
tation 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.
--nomp Do not run MetaPost, even if needed.
--nomprun
Do not run mpost(1) on embedded MetaPost code.
Producing Proof Sheets of Figures
--figures=ALTERNATIVE
Specify one of three options to produce a document
containing the images used in the source file:
a A proof sheet with additional information
provided for each figure
b A proof sheet with the graphics only
c One figure per page, with the page clipped
to the bounding box of the figure
See also --paperoffset, which allows you to
specify an offset to be added to the page,
as in
texexec --figures=c --paperoffset=.5cm *.pdf
*.png *.jpg
texexec uses texutil(1) to obtain the list of fig-
ures to process.
USAGE
o Each ConTeXt user interface (language) has its own
format. The following command generates two for-
mats, one using the English interface for typeset-
ting 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 texu-
til(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 vari-
ous 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 sys-
tems, no special steps have to be taken to get tex-
exec 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 com-
mands such as ``perl texexec.pl optvar(ARGS)''.
The fpTeX distribution comes with a program called
runperl.exe that can be copied and renamed to tex-
exec.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 neces-
sary 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 sys-
tem.
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 mech-
anism to map document encodings to ConTeXt's inter-
nal encoding, font encodings, and hyphenation pat-
terns. 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.
FILES
TEXMF/context/config/texexec.ini
TeXExec configuration file
TEXMF/context/config/texexec.rme
TeXExec configuration file defaults
SEE ALSObibtex(1), dvips(1), fmtutil(1), makeindex(1),
metapost(1), mpost(1), pdfetex(1), pdfmerge(1),
pdftex(1), perl(1), psnup(1), tex(1), texshow(1),
texutil(1).
The TeXExec manual, mtexexec.pdf.
The TeXExec configuration README files:
o TEXMF/context/config/texexec.rme
o TEXMF/context/perltk/texexec.rme
Donald E. Knuth's The TeXbook.
AUTHOR
This manpage was written by Tobias Burnus <bur-
nus@gmx.de> and C.M. Connelly <c@eskimo.com>. It
is based on the TeXExec manual written by Hans
Hagen <pragma@wxs.nl>.
The PDF manual and texexec itself can be obtained
from <http://www.pragma-ade.com/pragma-ade/tex-
exec.htm>
ConTeXt October 2000 texexec(1)
