[tex-live] man page for mptopdf

[Werner LEMBERG]

> Very nice!  It contains a lot of typographical buglets -- and a main
> one, namely that `mptopdf' isn't mentioned at all.

Uh, oh, this man page doesn't handle mptopdf at all...

Do you have something better?

> I'll fix these and send it to this list so that it can be included
> in TeXLive, ConTeXt, and Debian.

Anyway, here is the revised version.


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