texexec(1)

NAME
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

    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 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 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.

        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, 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.

--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 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

    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 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 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 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.

FILES

TEXMF/context/config/texexec.ini
    TeXExec configuration file

TEXMF/context/config/texexec.rme
    TeXExec configuration file defaults

SEE ALSO

    bibtex(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>