texexec(1) ConTeXt texexec(1)NAMEtexexec - ConTeXt and PDF auxiliary program and batch processor
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 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 (simi‐
lar 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
--helpoptvar(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 pro‐
cesses the file as many times as necessary to sort out all ref‐
erences, 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/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 tex‐
exec´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 contents of tex‐
exec.ini.
Processing ConTeXt Source Files
Including specifying paper sizes, formats, and so forth.
--arrange
Don´t perform page rearrangements (e.g., for producing a book‐
let) until the last run.
--batch
Process the file in batch mode -- continue to typeset the docu‐
ment 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 pro‐
cessing. 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.
texexec--pdf --mode=A4 --result=pdftex-a pdftex-t
texexec--pdf --mode=letter --result=pdftex-l pdftex-t
texexec--pdf --mode=screen --result=pdftex-s pdftex-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 specified with the --print switch.
--pdf Shorthand for --output=pdftex.
--print=KEY
Specify the layout of the final output. KEY can be up, result‐
ing 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.
--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 attrac‐
tive 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 addi‐
tional 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 --combina‐
tion switch.
--pdfselect
Extract pages from a file. Use in combination with the --selec‐
tion 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 --pdfar‐
range 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.
--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 bound‐
ing 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 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 chang‐
ing 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 type‐
set 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 pdf‐
tex(1)). You can also be more specific about what drivers tex‐
exec 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 instruc‐
tions.
After an error-free run, texexec will run texutil(1) to deter‐
mine 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 configura‐
tion 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 spe‐
cial 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 nec‐
essary 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 tex‐
exec.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 algo‐
rithms.
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 encod‐
ings, 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.
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 <burnus@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/texexec.htm>
ConTeXt October 2000 texexec(1)
