1texexec(1) ConTeXt texexec(1)
2
6 texexec - ConTeXt and PDF auxiliary program and batch processor
7
9 texexec [ OPTION ... ] FILE [ ... ]
10
12 texexec is a Perl script that provides several functions:
13 o Process a TeX file. This includes performing as many runs as
15 necessary of tex(1), texutil(1), and metapost(1). Options
16 allow you to select the output format, the pages to process,
17 paper size, and so forth.
18 o Create new ConTeXt formats (with --format).
20 o Post-process existing PDF files, including merging multiple
22 files, and extracting and rearranging pages within a file (simi‐
23 lar to the functions provided by psnup(1) and pdfmerge(1)).
24 o Extract or strip documentation from com{ConTeXt} source files
26 (using texutil(1)).
27 o Run METAPOST (mpost(1)) to generate figures from METAPOST
29 source.
30 o Produce ``proof sheets´´ of figures used in a ConTeXt source
32 file.
33
35 All switches are specified in full, but can be abbreviated to the
36 shortest unique string. Thus, --ver works the same as --verbose.
37
39 --alone
40 Avoid calling other programs when possible. For example,
41 --alone will prevent texexec from using fmtutil(1) to generate
42 formats (which can be handy when tracing installation problems).
43 --environment=ENVIRONMENT
45 Specify a ConTeXt ENVIRONMENT to use when processing the file.
46 This option can be useful when converting from non-ConTeXt file
47 formats where no environment or layout settings are present in
48 the file.
49 --help [ SWITCH ]
51 Produce a summary of switches and arguments. Many switches have
52 additional information that can be seen by typing ``texexec
53 --help optvar(SWITCH)´´.
54 --interface=LANGUAGE
56 Specify the language ConTeXt should use to communicate with you.
57 Options are
58 en US English
60 nl Dutch
62 de German
64 uk British English
66 cz Czech
68 it Italian
70 --once Process a file once and only once. (By default, texexec pro‐
72 cesses the file as many times as necessary to sort out all ref‐
73 erences, typeset METAPOST code, and so forth.)
74 --output=DRIVER
76 Specify the output DRIVER for use with \special primitives.
77 Defaults to the setting in the local cont-sys.tex file, but can
78 be set to one of
79 pdftex Native pdftex(1) code
81 dvips For dvips(1) (the default)
83 dvipsone
85 For dvipsone
86 dviwindo
88 For dviwindo, the oldest ConTeXt drivers
89 dviview
91 For dviview (experimental)
92 There may be other supported drivers -- check the most recent
94 ConTeXt documentation.
95 --pages=PAGENUMBERLIST
97 Specify the pages or page range to appear in the output file.
98 PAGENUMBERLIST may be the keyword odd or even; one or more pages
99 separated by commas (x,y); or a page range in the form :z.
100 --passon=STRING
102 Pass additional command-line switches and arguments to the
103 tex(1) process run by texexec.
104 For example, the MikTeX TeX system (for DOS/Windows) can embed
106 information in the DVI file that will allow you to find the line
107 in a source code file corresponding to the line in the typeset
108 output. It uses a switch called ``--src´´ to activate this
109 functionality, and can be used from texexec as
110 texexec --passon="--src" somefile
112 The double quotes (") are required to prevent texexec from using
114 the switch itself.
115 --program
117 The name of the TeX program to use (tex(1), by default).
118 --result=FILENAME
120 Allows you to change the basename of the output file. See
121 --mode for an example.
122 --runs=NUMBER
124 Specify the number of runs to perform on a file. Overrides tex‐
125 exec´s calculations.
126 --silent
128 Suppress diagnostic and progress messages.
129 --suffix=SUFFIX
131 Specify the suffix of the output file.
132 --tex=PROGRAMNAME
134 Allows you specify the program to use instead of tex(1). Useful
135 for trying different versions of tex(1) installed on the same
136 machine.
137 --texutil
139 Force a run of texutil(1).
140 --verbose
142 Output diagnostic information, including the contents of tex‐
143 exec.ini.
144
146 Including specifying paper sizes, formats, and so forth.
147 --arrange
149 Don´t perform page rearrangements (e.g., for producing a book‐
150 let) until the last run.
151 --batch
153 Process the file in batch mode -- continue to typeset the docu‐
154 ment after finding errors. More imformation about batch mode
155 can be found in Donald E. Knuth´s TeXbook.
156 --bodyfont
158 The name of a font to preload for use in setting the body of the
159 text.
160 --centerpage
162 Center the document image on the page.
163 --color
165 Turn on color mode. Color mode can also be set by commands
166 embedded in the document. These commands override the --color
167 option.
168 --convert=FORMAT
170 Convert the input file to ConTeXt format from FORMAT before pro‐
171 cessing. In most cases, this conversion will result in a TeX
172 file. Currently supported input FORMATs are xml and sgml.
173 --dvi Shortcut for --output=dvi.
175 --fast Typeset the document(s) as fast as possible without causing
177 problems.
178 --final
180 Perform a final run without skipping anything. This option is
181 typically used with --fast.
182 --language=LANGUAGE
184 Set the language for hyphenation. Can be specified in your
185 source file. Options are the same as those for --interface.
186 --mode=MODELIST
188 Allows you to change the mode (page size and resolution) of the
189 output file.
190 texexec --pdf --mode=A4 --result=pdftex-a pdftex-t
192 texexec --pdf --mode=letter --result=pdftex-l pdftex-t
193 texexec --pdf --mode=screen --result=pdftex-s pdftex-t
194 Here the mode switch tells ConTeXt to obey the mode directives
196 in the layout specifications. The --result flag allows you to
197 rename the output file.
198 --noarrange
200 Ignore arrangement commands in the source file.
201 --paper=KEY
203 For typesetting multiple pages on a single piece of paper. KEY
204 can be a4a3 (for printing A4 pages on A3 paper) or a5a4 (for
205 printing A5 pages on A4 paper). The actual layout of the pages
206 is specified with the --print switch.
207 --pdf Shorthand for --output=pdftex.
209 --print=KEY
211 Specify the layout of the final output. KEY can be up, result‐
212 ing in 2 pages per sheet, double sided, or down, resulting in 2
213 rotated pages per sheet, double sided. Use the --paper switch
214 to specify the original page and sheet size.
215
217 --format=FORMATFILE
218 Specify a FORMATFILE to use when typesetting. texexec will
219 prepend the string cont- to the name you give, so you can type
220 plain instead of cont-plain, as in
221 texexec --format=plain --program=pdftex somefile
223 --make Generate a ConTeXt format file.
225
227 --combination=ROWS*COLS
228 Specify the number of pages to show on a single page. Use with
229 --pdfcombine.
230 --pdfarrange
232 For rearranging pages in PDF files.
233 texexec --pdfarrange --paper=a5a4 --print=up foo.pdf
235 This command creates an A5 booklet from a PDF file foo.pdf.
237 --pdfarrange is used in conjunction with the following switches:
238 --paperoffset
240 Adjust the space between the edge of the pages and the beginning
241 of the text block.
242 --backspace
244 Adjust the inside (``gutter´´) margins.
245 --topspace
247 Adjust the top and bottom margin.
248 --markings
250 Add crop marks.
251 --addempty=PAGES
253 Add empty pages after the pages specified in PAGES. (Useful
254 for, among other things, adding blank pages after a table of
255 contents.)
256 --textwidth=WIDTH
258 Set the width of the original text. Specifying this parameter
259 with a single-sided original will allow ConTeXt to adjust the
260 page layout for double-sided output, producing much more attrac‐
261 tive results.
262 With the --pdfarrange flag, specifying more than one file will
264 result in all of the files being combined in the final result,
265 allowing you to add title pages, decorated part separators, and
266 so forth.
267 You can also do more complex manipulations, such as adding addi‐
269 tional text to the page by setting up a small file with layout
270 definitions and a simple figure insertion loop.
271 --pdfcombine
273 Combine multiple pages. Requires you to specify the --combina‐
274 tion switch.
275 --pdfselect
277 Extract pages from a file. Use in combination with the --selec‐
278 tion switch, as in
279 texexec --pdfselect --paper=S6 --selection=1,9,14 file-1
281 which extracts pages 1, 9, and 14 from file-1.pdf, and places
283 them in texexec.pdf (the default output filename if an output
284 file isn´t specified).
285 See --pdfarrange for other options.
287 --selection=PAGES
289 Specify pages to be affected by another option. See --pdfar‐
290 range and --pdfselect for examples.
291
293 --listing
294 Produce a typeset version of the source code in FILE. You can
295 specify the form of the output file, as in
296 texexec --listing --pdf readme.now
297 which will produce a PDF file called texexec.pdf. Without the
299 --pdf flag, texexec will produce a DVI file.
300 See also --backspace and --topspace.
302 --module
304 Create documentation for ConTeXt, MetaPost (see mpost(1)), and
305 Perl modules. Converts the documentation to ConTeXt format and
306 then typesets that documentation. See texutil(1) for more
307 information about the format of the documentation strings.
308
310 --mpformat
311 The name of a MetaPost format file.
312 --mptex
314 Strips out and typesets TeX code embedded in a MetaPost file.
315 --nomp Do not run MetaPost, even if needed.
317 --nomprun
319 Do not run mpost(1) on embedded MetaPost code.
320
322 --figures=ALTERNATIVE
323 Specify one of three options to produce a document containing
324 the images used in the source file:
325 a A proof sheet with additional information provided for
327 each figure
328 b A proof sheet with the graphics only
330 c One figure per page, with the page clipped to the bound‐
332 ing box of the figure
333 See also --paperoffset, which allows you to specify an
335 offset to be added to the page, as in
336 texexec --figures=c --paperoffset=.5cm *.pdf
338 *.png *.jpg
339 texexec uses texutil(1) to obtain the list of figures to
341 process.
342
344 o Each ConTeXt user interface (language) has its own format. The
345 following command generates two formats, one using the English
346 interface for typesetting in English, and one for Dutch:
347 texexec --make en nl
349 By default, the language used for typesetting matches the user-
351 interface language (set with --interface. It´s possible to use
352 one language for typesetting and another for messages by chang‐
353 ing the relevant settings in cont-usr.tex, but these languages
354 can also be changed on the command line with a command such as
355 texexec --make --language=pl,cz,sk --bodyfont=plr en
357 That command generates a ConTeXt format file with an English
359 user interface, and the main language set to Polish (pl). The
360 default body font is the Polish version of Computer Modern Roman
361 (plr). Czech and Slovak hyphenation patterns are also loaded so
362 that Czech and Slovak text included in a source file will be
363 typeset properly (cz and sk).
364 o When the appropriate formats are present, a file can be typeset
366 by typing
367 texexec test
369 texexec tries to determine what interface it should use to type‐
371 set test.tex by looking for a line such as
372 % interface=en tex=pdfetex output=pdftex
374 at the top of the file (i.e., on the very first line). This
376 line is equivalent to TeX´s format line, ``&FORMAT´´).
377 By default, texexec will produce a DVI file. The --pdf flag
379 tells texexec to produce a PDF file, instead (by running pdf‐
380 tex(1)). You can also be more specific about what drivers tex‐
381 exec should use, by specifying a command line such as
382 texexec --output=dvips,acrobat test
384 which specifies the use of the dvips driver (which is the
386 default), combined with the use of Acrobat-specific PDF instruc‐
387 tions.
388 After an error-free run, texexec will run texutil(1) to deter‐
390 mine whether additional runs of tex(1) (or pdftex(1)) or any
391 utility programs (e.g., bibtex(1), makeindex(1)) are necessary.
392 You can suppress these additional runs by specifying the --once
393 or --runs flags:
394 texexec --once test
396 texexec --runs=2 test
397
399 When starting, texexec first looks for the file texexec.ini,
400 which specifies the location of various programs and configura‐
401 tion files, and specifies the programs to use. The --verbose
402 flag causes texexec to print the information in texexec.ini to
403 the terminal and the log file.
404 texexec requires Perl. On Unix and Unix-like systems, no spe‐
406 cial steps have to be taken to get texexec to work beyond
407 installing Perl and having the perl(1) binary in your path. On
408 Windows systems, however, you may need to run Perl by typing
409 commands such as ``perl texexec.pl optvar(ARGS)´´.
410 The fpTeX distribution comes with a program called runperl.exe
412 that can be copied and renamed to texexec.exe. You will also
413 have to rename a copy to texutil.exe (see texutil(1)). The
414 teTeX and fpTeX distributions, at least, should perform the nec‐
415 essary steps as part of their installation sequence -- if you
416 have problems, however, you may need to follow the advice given
417 here.
418 The file texexec.rme contains default configuration information.
420 If no file texexec.ini exists (in TEXMF/context/config/, you
421 should copy texexec.rme to that directory and rename it to tex‐
422 exec.ini. Make any necessary changes to this file to reflect
423 the layout of programs and directories on your system.
424
426 Some languages require specific character encodings to represent
427 their alphabets (beyond the basic ASCII encoding). Although you
428 can use TeX commands to represent these characters, such as
429 ``\.z´´, it´s easier to use a text editor that includes direct
430 support for these characters and let ConTeXt translate them to
431 the necessary TeX commands. For some languages, this approach
432 can also improve the performance of TeX´s hyphenation algo‐
433 rithms.
434 ConTeXt supports several of the most commonly used encodings.
436 Check the files beginning with enco-, lang-, and font- in the
437 ConTeXt distribution for more information.
438 web2c distributions (such as teTeX) support a mechanism to map
440 document encodings to ConTeXt´s internal encoding, font encod‐
441 ings, and hyphenation patterns. texexec provides a document
442 option and a command-line flag to pass the necessary information
443 to tex(1) or pdftex(1). You can add lines such as
444 %& --translate-file=cp1250pl
446 or
447 % --translate=cp1250pl
449 to the beginning of your document, or specify the --translate
451 flag on the command line, as
452 texexec --translate=il2pl somefile
454 Note that using language-specific encodings will make your file
456 less portable than using ASCII. It may not be possible for
457 other people to typeset your documents on their systems.
458
460 TEXMF/context/config/texexec.ini
461 TeXExec configuration file
462 TEXMF/context/config/texexec.rme
464 TeXExec configuration file defaults
465
467 bibtex(1), dvips(1), fmtutil(1), makeindex(1), metapost(1),
468 mpost(1), pdfetex(1), pdfmerge(1), pdftex(1), perl(1), psnup(1),
469 tex(1), texshow(1), texutil(1).
470 The TeXExec manual, mtexexec.pdf.
472 The TeXExec configuration README files:
474 o TEXMF/context/config/texexec.rme
476 o TEXMF/context/perltk/texexec.rme
478 Donald E. Knuth´s The TeXbook.
480
482 This manpage was written by Tobias Burnus <burnus@gmx.de> and
483 C.M. Connelly <c@eskimo.com>. It is based on the TeXExec manual
484 written by Hans Hagen <pragma@wxs.nl>.
485 The PDF manual and texexec itself can be obtained from
487 <http://www.pragma-ade.com/pragma-ade/texexec.htm>
488ConTeXt October 2000 texexec(1)