diff options
Diffstat (limited to 'Master/texmf/doc/man/man1/texexec.1')
-rw-r--r-- | Master/texmf/doc/man/man1/texexec.1 | 574 |
1 files changed, 574 insertions, 0 deletions
diff --git a/Master/texmf/doc/man/man1/texexec.1 b/Master/texmf/doc/man/man1/texexec.1 new file mode 100644 index 00000000000..2d8593b674c --- /dev/null +++ b/Master/texmf/doc/man/man1/texexec.1 @@ -0,0 +1,574 @@ +.de EX +.sp +.in +5 +.nf +.ft CW +.. +.de EE +.in -5 +.ft R +.sp +.fi +.. +.TH "texexec" "1" "October 2000" "ConTeXt" "ConTeXt" +.PP +.SH "NAME" +texexec \- ConTeXt and PDF auxiliary program and batch processor +.PP +.SH "SYNOPSIS" +\fBtexexec\fP [ \fIOPTION\fP \&.\&.\&. ] \fIFILE\fP [ \&.\&.\&. ] +.PP +.SH "DESCRIPTION" +.PP +\fBtexexec\fP is a Perl script that provides several functions: +.IP o +Process a TeX file\&. This includes performing as many runs as +necessary of \fBtex\fP(1), \fBtexutil\fP(1), and +\fBmetapost\fP(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 \fB--format\fP)\&. +.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 \fBpsnup\fP(1) and +\fBpdfmerge\fP(1))\&. +.IP o +Extract or strip documentation from com{ConTeXt} source files +(using \fBtexutil\fP(1))\&. +.IP o +Run METAPOST (\fBmpost\fP(1)) to generate figures from METAPOST +source\&. +.IP o +Produce ``proof sheets\'\' of figures used in a \fBConTeXt\fP source +file\&. +.IP +.PP +.SH "OPTIONS" +.PP +All switches are specified in full, but can be abbreviated to the +shortest unique string\&. Thus, \fB--ver\fP works the same as +\fB--verbose\fP\&. +.PP +.SH "General Options" +.PP +.IP "\fB--alone\fP" +Avoid calling other programs when possible\&. For +example, \fB--alone\fP will prevent \fBtexexec\fP from +using \fBfmtutil\fP(1) to generate formats (which can +be handy when tracing installation problems)\&. +.IP "\fB--environment=\fP\fIENVIRONMENT\fP" +Specify a ConTeXt +\fIENVIRONMENT\fP 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\&. +.IP "\fB--help\fP [ \fISWITCH\fP ]" +Produce a summary of switches +and arguments\&. Many switches have additional +information that can be seen by typing ``\f(CWtexexec +--help optvar(SWITCH)\fP\'\'\&. +.IP "\fB--interface=\fP\fILANGUAGE\fP" +Specify the language +\fBConTeXt\fP should use to communicate with you\&. +Options are +.IP +.RS +.IP "\fBen\fP" +US English +.IP "\fBnl\fP" +Dutch +.IP "\fBde\fP" +German +.IP "\fBuk\fP" +British English +.IP "\fBcz\fP" +Czech +.IP "\fBit\fP" +Italian +.RE +.IP "\fB--once\fP" +Process a file once and only once\&. (By default, +\fBtexexec\fP processes the file as many times as +necessary to sort out all references, typeset +\fBMETAPOST\fP code, and so forth\&.) +.IP "\fB--output=\fP\fIDRIVER\fP" +Specify the output \fIDRIVER\fP +for use with \f(CW\especial\fP primitives\&. Defaults to the setting in +the local \fIcont-sys\&.tex\fP file, but can be set to one of +.IP +.RS +.IP "\fBpdftex\fP" +Native \fBpdftex\fP(1) code +.IP "\fBdvips\fP" +For \fBdvips\fP(1) (the default) +.IP "\fBdvipsone\fP" +For \fBdvipsone\fP +.IP "\fBdviwindo\fP" +For \fBdviwindo\fP, the oldest +\fBConTeXt\fP drivers +.IP "\fBdviview\fP" +For \fBdviview\fP (experimental) +.IP +.RE +.IP +There may be other supported drivers -- check the most +recent \fBConTeXt\fP documentation\&. +.IP "\fB--pages=\fP\fIPAGENUMBERLIST\fP" +Specify the pages or page +range to appear in the output file\&. +\fIPAGENUMBERLIST\fP may be the keyword \fBodd\fP +or \fBeven\fP; one or more pages separated by commas +(\f(CWx,y\fP); or a page range in the form \f(CW:z\fP\&. +.IP "\fB--passon=\fP\fISTRING\fP" +Pass additional command-line +switches and arguments to the \fBtex\fP(1) process +run by \fBtexexec\fP\&. +.IP +For example, the \fBMikTeX\fP 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 \fBtexexec\fP as +.IP +.EX +\f(CWtexexec --passon="--src" somefile\fP +.EE +.IP +The double quotes (\f(CW"\fP) are required to prevent +\fBtexexec\fP from using the switch itself\&. +.IP "\fB--program\fP" +The name of the TeX program to use +(\fBtex\fP(1), by default)\&. +.IP "\fB--result=\fP\fIFILENAME\fP" +Allows you to change the +basename of the output file\&. See +\fB--mode\fP for an example\&. +.IP "\fB--runs=\fP\fINUMBER\fP" +Specify the number of runs to +perform on a file\&. Overrides +\fBtexexec\fP\'s calculations\&. +.IP "\fB--silent\fP" +Suppress diagnostic and progress messages\&. +.IP "\fB--suffix=\fP\fISUFFIX\fP" +Specify the suffix of the output file\&. +.IP "\fB--tex=\fP\fIPROGRAMNAME\fP" +Allows you specify the program +to use instead of \fBtex\fP(1)\&. Useful for trying +different versions of \fBtex\fP(1) installed on the +same machine\&. +.IP "\fB--texutil\fP" +Force a run of \fBtexutil\fP(1)\&. +.IP "\fB--verbose\fP" +Output diagnostic information, including the +contents of \fItexexec\&.ini\fP\&. +.IP +.PP +.SH "Processing \fBConTeXt\fP Source Files" +.PP +Including specifying paper sizes, formats, and so forth\&. +.PP +.IP "\fB--arrange\fP" +Don\'t perform page rearrangements (e\&.g\&., for +producing a booklet) until the last run\&. +.IP "\fB--batch\fP" +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 \fITeXbook\fP\&. +.IP "\fB--bodyfont\fP" +The name of a font to preload for use in +setting the body of the text\&. +.IP "\fB--centerpage\fP" +Center the document image on the page\&. +.IP "\fB--color\fP" +Turn on color mode\&. Color mode can also be set by +commands embedded in the document\&. These commands +override the \fB--color\fP option\&. +.IP "\fB--convert=\fP\fIFORMAT\fP" +Convert the input file to +ConTeXt format from \fIFORMAT\fP before +processing\&. In most cases, this conversion will result +in a TeX file\&. Currently supported input +\fIFORMAT\fPs are \fBxml\fP and +\fBsgml\fP\&. +.IP "\fB--dvi\fP" +Shortcut for \fB--output=dvi\fP\&. +.IP "\fB--fast\fP" +Typeset the document(s) as fast as possible without +causing problems\&. +.IP "\fB--final\fP" +Perform a final run without skipping anything\&. +This option is typically used with \fB--fast\fP\&. +.IP "\fB--language=\fP\fILANGUAGE\fP" +Set the language for +hyphenation\&. Can be specified in your source file\&. +Options are the same as those for \fB--interface\fP\&. +.IP "\fB--mode=\fP\fIMODELIST\fP" +Allows you to change the mode +(page size and resolution) of the output file\&. +.IP +.EX +\f(CWtexexec --pdf --mode=A4 --result=pdftex-a pdftex-t\fP +\f(CWtexexec --pdf --mode=letter --result=pdftex-l pdftex-t\fP +\f(CWtexexec --pdf --mode=screen --result=pdftex-s pdftex-t\fP +.EE +.IP +Here the mode switch tells \fBConTeXt\fP to obey +the mode directives in the layout specifications\&. The +\fB--result\fP flag allows you to +rename the output file\&. +.IP "\fB--noarrange\fP" +Ignore arrangement commands in the source +file\&. +.IP "\fB--paper=\fP\fIKEY\fP" +For typesetting multiple pages on a +single piece of paper\&. \fIKEY\fP can be \fBa4a3\fP +(for printing A4 pages on A3 paper) or \fBa5a4\fP +(for printing A5 pages on A4 paper)\&. The actual layout +of the pages is specified with the +\fB--print\fP switch\&. +.IP "\fB--pdf\fP" +Shorthand for \fB--output=pdftex\fP\&. +.IP "\fB--print=\fP\fIKEY\fP" +Specify the layout of the final +output\&. \fIKEY\fP can be \fBup\fP, resulting in 2 +pages per sheet, double sided, or \fBdown\fP, resulting +in 2 rotated pages per sheet, double sided\&. Use the +--paper switch to specify the original page +and sheet size\&. +.IP +.PP +.SH "Creating \fBConTeXt\fP Format Files" +.PP +.IP "\fB--format=\fP\fIFORMATFILE\fP" +Specify a \fIFORMATFILE\fP +to use when typesetting\&. \fBtexexec\fP will prepend 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 +.IP +.EX +\f(CWtexexec --format=plain --program=pdftex somefile\fP +.EE +.IP "\fB--make\fP" +Generate a \fBConTeXt\fP format file\&. +.PP +.SH "Postprocess PDF Files" +.PP +.IP "\fB--combination=\fP\fIROWS\fP\fB*\fP\fICOLS\fP" +Specify +the number of pages to show on a single page\&. Use with +\fB--pdfcombine\fP\&. +.IP "\fB--pdfarrange\fP" +For rearranging pages in PDF files\&. +.IP +.EX +\f(CWtexexec --pdfarrange --paper=a5a4 --print=up foo\&.pdf\fP +.EE +.IP +This command creates an A5 booklet from a PDF file +\fIfoo\&.pdf\fP\&. \fB--pdfarrange\fP is used in +conjunction with the following switches: +.IP "\fB--paperoffset\fP" +Adjust the space between the +edge of the pages and the beginning of the text block\&. +.IP "\fB--backspace\fP" +Adjust the inside (``gutter\'\') +margins\&. +.IP "\fB--topspace\fP" +Adjust the top and bottom +margin\&. +.IP "\fB--markings\fP" +Add crop marks\&. +.IP "\fB--addempty=\fP\fIPAGES\fP" +Add empty pages +after the pages specified in \fIPAGES\fP\&. (Useful +for, among other things, adding blank pages after a +table of contents\&.) +.IP "\fB--textwidth=\fP\fIWIDTH\fP" +Set the width of +the original text\&. Specifying this parameter with a +single-sided original will allow \fBConTeXt\fP to adjust +the page layout for double-sided output, producing much +more attractive results\&. +.IP +With the \fB--pdfarrange\fP 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\&. +.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\&. +.IP "\fB--pdfcombine\fP" +Combine multiple pages\&. Requires you to +specify the +\fB--combination\fP +switch\&. +.IP "\fB--pdfselect\fP" +Extract pages from a file\&. Use in combination with +the \fB--selection\fP switch, as +in +.IP +.RS +\f(CWtexexec --pdfselect --paper=S6 +--selection=1,9,14 file-1\fP +.RE +.IP +which extracts pages 1, 9, and 14 from +\fIfile-1\&.pdf\fP, and places them in +\fItexexec\&.pdf\fP (the default output filename if +an output file isn\'t specified)\&. +.IP +See \fB--pdfarrange\fP for other +options\&. +.IP "\fB--selection=\fP\fIPAGES\fP" +Specify pages to be affected by +another option\&. See \fB--pdfarrange\fP and +\fB--pdfselect\fP for examples\&. +.PP +.SH "Extract or Strip Out Documentation" +.PP +.IP "\fB--listing\fP" +Produce a typeset version of the source code in +\fIFILE\fP\&. You can specify the form of the output +file, as in +.RS +\f(CWtexexec --listing --pdf readme\&.now\fP +.RE +.IP +which will produce a PDF file called +\fItexexec\&.pdf\fP\&. Without the +\fB--pdf\fP flag, \fBtexexec\fP will +produce a DVI file\&. +.IP +See also \fB--backspace\fP and +\fB--topspace\fP\&. +.IP "\fB--module\fP" +Create documentation for \fBConTeXt\fP, +\fBMetaPost\fP (see \fBmpost\fP(1)), and Perl modules\&. +Converts the documentation to \fBConTeXt\fP format and +then typesets that documentation\&. See +\fBtexutil\fP(1) for more information about the +format of the documentation strings\&. +.PP +.SH "Process METAPOST Figures" +.PP +.IP "\fB--mpformat\fP" +The name of a \fBMetaPost\fP format file\&. +.IP "\fB--mptex\fP" +Strips out and typesets TeX code embedded in a +\fBMetaPost\fP file\&. +.IP "\fB--nomp\fP" +Do not run \fBMetaPost\fP, even if needed\&. +.IP "\fB--nomprun\fP" +Do not run \fBmpost\fP(1) on embedded +\fBMetaPost\fP code\&. +.PP +.SH "Producing Proof Sheets of Figures" +.PP +.IP "\fB--figures=\fP\fIALTERNATIVE\fP" +Specify one of three +options to produce a document containing the images +used in the source file: +.IP +.RS +.IP "\fBa\fP" +A proof sheet with additional +information provided for each figure +.IP "\fBb\fP" +A proof sheet with the graphics only +.IP "\fBc\fP" +One figure per page, with the page +clipped to the bounding box of the +figure +.IP +See also \fB--paperoffset\fP, +which allows you to specify an offset to be added to +the page, as in +.IP +.EX +\f(CWtexexec --figures=c --paperoffset=\&.5cm *\&.pdf +*\&.png *\&.jpg\fP +.EE +.IP +.RE +.IP +\fBtexexec\fP uses \fBtexutil\fP(1) to obtain the list +of figures to process\&. +.PP +.SH "USAGE" +.PP +.IP o +Each \fBConTeXt\fP 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: +.IP +.EX +\f(CWtexexec --make en nl\fP +.EE +.IP +By default, the language used for typesetting matches the +user-interface language (set with +\fB--interface\fP\&. It\'s possible to use one +language for typesetting and another for messages by changing the +relevant settings in \fIcont-usr\&.tex\fP, but these languages can +also be changed on the command line with a command such as +.IP +.RS +\f(CWtexexec --make --language=pl,cz,sk --bodyfont=plr en\fP +.RE +.IP +That command generates a \fBConTeXt\fP format file with an English user +interface, and the main language set to Polish (\fBpl\fP)\&. The +default body font is the Polish version of Computer Modern Roman +(\fBplr\fP)\&. Czech and Slovak hyphenation patterns are also loaded +so that Czech and Slovak text included in a source file will be +typeset properly (\fBcz\fP and \fBsk\fP)\&. +.IP o +When the appropriate formats are present, a file can be typeset +by typing +.IP +.EX +\f(CWtexexec test\fP +.EE +.IP +\fBtexexec\fP tries to determine what interface it should use to +typeset \fItest\&.tex\fP by looking for a line such as +.IP +.EX +\f(CW% interface=en tex=pdfetex output=pdftex\fP +.EE +.IP +at the top of the file (i\&.e\&., on the very first line)\&. This line is +equivalent to \fBTeX\fP\'s format line, ``&\fIFORMAT\fP\'\')\&. +.IP +By default, \fBtexexec\fP will produce a DVI file\&. The +\fB--pdf\fP flag tells \fBtexexec\fP to produce a PDF +file, instead (by running \fBpdftex\fP(1))\&. You can also be more +specific about what drivers \fBtexexec\fP should use, by specifying a +command line such as +.IP +.EX +\f(CWtexexec --output=dvips,acrobat test\fP +.EE +.IP +which specifies the use of the \fBdvips\fP driver (which is the +default), combined with the use of Acrobat-specific PDF instructions\&. +.IP +After an error-free run, \fBtexexec\fP will run \fBtexutil\fP(1) to +determine whether additional runs of \fBtex\fP(1) (or +\fBpdftex\fP(1)) or any utility programs (e\&.g\&., \fBbibtex\fP(1), +\fBmakeindex\fP(1)) are necessary\&. You can suppress these +additional runs by specifying the \fB--once\fP or +\fB--runs\fP flags: +.IP +.EX +\f(CWtexexec --once test\fP +\f(CWtexexec --runs=2 test\fP +.EE +.IP +.SH "INITIALIZATION" +.IP +When starting, \fBtexexec\fP first looks for the file +\fItexexec\&.ini\fP, which specifies the location of various +programs and configuration files, and specifies the programs to use\&. +The \fB--verbose\fP flag causes \fBtexexec\fP to print +the information in \fItexexec\&.ini\fP to the terminal and the log +file\&. +.IP +\fBtexexec\fP requires Perl\&. On Unix and Unix-like systems, no special +steps have to be taken to get \fBtexexec\fP to work beyond installing +Perl and having the \fBperl\fP(1) binary in your path\&. On Windows +systems, however, you may need to run Perl by typing commands such as +``\f(CWperl texexec\&.pl optvar(ARGS)\fP\'\'\&. +.IP +The \fBfpTeX\fP distribution comes with a program called +\fBrunperl\&.exe\fP that can be copied and renamed to \fBtexexec\&.exe\fP\&. +You will also have to rename a copy to \fBtexutil\&.exe\fP (see +\fBtexutil\fP(1))\&. The \fBteTeX\fP and \fBfpTeX\fP 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\&. +.IP +The file \fItexexec\&.rme\fP contains default configuration +information\&. If no file \fItexexec\&.ini\fP exists (in +\fITEXMF/context/config/\fP, you should copy \fItexexec\&.rme\fP +to that directory and rename it to \fItexexec\&.ini\fP\&. Make any +necessary changes to this file to reflect the layout of programs and +directories on your system\&. +.SH "ENCODINGS" +.IP +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\'s +easier to use a text editor that includes direct support for these +characters and let \fBConTeXt\fP translate them to the necessary TeX +commands\&. For some languages, this approach can also improve the +performance of TeX\'s hyphenation algorithms\&. +.IP +\fBConTeXt\fP supports several of the most commonly used encodings\&. +Check the files beginning with \fIenco-\fP, \fIlang-\fP, and +\fIfont-\fP in the \fBConTeXt\fP distribution for more information\&. +.IP +\fBweb2c\fP distributions (such as \fBteTeX\fP) support a mechanism to +map document encodings to \fBConTeXt\fP\'s internal encoding, font +encodings, and hyphenation patterns\&. \fBtexexec\fP provides a document +option and a command-line flag to pass the necessary information to +\fBtex\fP(1) or \fBpdftex\fP(1)\&. You can add lines such as +.IP +.EX +\f(CW%& --translate-file=cp1250pl\fP +.EE +or +.IP +.EX +\f(CW% --translate=cp1250pl\fP +.EE +.IP +to the beginning of your document, or specify the \fB--translate\fP +flag on the command line, as +.IP +.EX +\f(CWtexexec --translate=il2pl somefile\fP +.EE +.IP +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\&. +.SH "FILES" +.IP +.IP "\fITEXMF/context/config/texexec\&.ini\fP" +TeXExec configuration file +.IP "\fITEXMF/context/config/texexec\&.rme\fP" +TeXExec configuration file defaults +.IP +.SH "SEE ALSO" +.IP +\fBbibtex\fP(1), \fBdvips\fP(1), \fBfmtutil\fP(1), +\fBmakeindex\fP(1), \fBmetapost\fP(1), \fBmpost\fP(1), +\fBpdfetex\fP(1), \fBpdfmerge\fP(1), \fBpdftex\fP(1), +\fBperl\fP(1), \fBpsnup\fP(1), \fBtex\fP(1), \fBtexshow\fP(1), +\fBtexutil\fP(1)\&. +.IP +The TeXExec manual, \fImtexexec\&.pdf\fP\&. +.IP +The TeXExec configuration README files: +.IP o +\fITEXMF/context/config/texexec\&.rme\fP +.IP o +\fITEXMF/context/perltk/texexec\&.rme\fP +.IP +Donald E\&. Knuth\'s \fIThe TeXbook\fP\&. +.SH "AUTHOR" +.IP +This manpage was written by Tobias Burnus +<burnus@gmx\&.de> and C\&.M\&. Connelly +<c@eskimo\&.com>\&. It is based on +the \fBTeXExec\fP manual written by Hans Hagen +<pragma@wxs\&.nl>\&. +.IP +The PDF manual and \fBtexexec\fP itself can be obtained from +<http://www\&.pragma-ade\&.com/pragma-ade/texexec\&.htm> |