1TEXEXEC(1) ConTeXt TEXEXEC(1)
2
6 texexec - front end to the ConTeXt typesetting system
7
10 texexec [ OPTION ... ] FILE [ ... ]
11
14 texexec, a ruby(1) script, is the command-line front end to the ConTeXt
15 typesetting system, an extensive macro package built on the tex(1) fam‐
16 ily of typesetting programs. texexec provides several facilties:
17 · Process a ConTeXt source file, performing as many runs as neces‐
19 sary of tex(1), texutil(1), and MetaPost (mpost(1)). Options
20 control the output format, the pages to process, paper size, and
21 so forth.
22 · Create new ConTeXt formats, useful during installation.
24 · Post-process existing PDF files, including merging multiple
26 files, and extracting and rearranging pages within a file, simi‐
27 lar to the facilities provided for PostScript files by psnup(1)
28 or for PDF files by pdftk(1).
29 · Extract or strip documentation from ConTeXt source files using
31 texutil(1).
32 · Run MetaPost (mpost(1)) to generate figures from MetaPost
34 source.
35 · Produce proof sheets of figures used in a ConTeXt source file.
37
39 All switches are specified in full here but can be abbreviated to the
40 shortest unique prefix. Thus, --env works the same as --environment.
41 With no options, texexec assumes that the file on the command line is a
42 ConTeXt source file, i.e. a TeX file in the ConTeXt dialect, and pro‐
43 duces a PDF file using the source file.
44 General Options
47 --alone
48 Avoid calling other programs when possible. For example,
49 --alone will prevent texexec from using fmtutil(1) to generate
50 formats (this prevention can be handy when tracing installation
51 problems).
52 --environments=file[,file[,...]]
54 Specify ConTeXt environment file(s), separated by commas, to use
55 when processing the source file. This option is useful when
56 converting from non-ConTeXt file formats without environment or
57 layout settings.
58 --help Produce a summary of switches and arguments. A more detailed
60 help is produced by including --all.
61 --interface=language
63 Specify the language ConTeXt should use to communicate with you.
64 Options are
65 en US English
67 nl Dutch
69 de German
71 uk British English
73 cz Czech
75 it Italian
77 --keep Preserve a few of the temporary files generated while processing
79 by appending .keep to their name. For example, after
80 texexec --keep document.tex
81 you will find (besides document.pdf) document.log.keep and docu‐
82 ment.top.keep. The document.top file is where texexec wraps
83 document.tex with the proper ConTeXt macro commands to set the
84 output format, etc.
85 --once Process a file exactly once. (By default, texexec processes the
87 file as many times as necessary to sort out all references,
88 typeset MetaPost code, and so forth.)
89 --purge
91 Get rid of most temporary files generated while processing the
92 source file. For example,
93 texexec --purge somefile.tex
94 will generate somefile.pdf, cleaning up after itself and leaving
95 only one extra file, somefile.tuo. See also the --purge
96 option of ctxtools(1)
97 --purgeall
99 Get rid of all temporary files generated while processing the
100 source file, including the filename.tuo file. See also the
101 --purge --all option combination of ctxtools(1)
102 --randomseed=NNNN
104 Set the random seed.
105 --result=FILENAME
107 Allows you to change the basename of the output file. See
108 --mode for an example.
109 --runs=NUMBER
111 Specify the number of runs to perform on a file. Overrides tex‐
112 exec's calculations.
113 --separation
115 Perform color separations.
116 --silent
118 Suppress a few diagnostic and progress messages.
119 --timeout=NNN
121 Abort the run if a subprocess waits for more than NNN seconds;
122 e.g. while waiting for user input when tex reports an undefined
123 control sequence. Useful for automated testing scripts, to make
124 sure the runs finish.
125 --usemodules=module1[,module2,[...]]
127 Use the comma-separated list of modules. For example, to type‐
128 set document.tex using the bib and units modules:
129 texexec --usemodules=bib,units document.tex
130 --verbose
132 Output extra diagnostic information.
133 --version
135 Print the version number.
136 Processing ConTeXt Source Files
138 Including specifying paper sizes, formats, and so forth.
139 --arrange
142 Perform page rearrangements, which are used to produce booklets.
143 This option tells ConTeXt to the first n-1 runs without taking
144 account of arrangements, then on the last run to pay attention
145 to the arrangement commands in the source file.
146 --batchmode
148 Process the file in batchmode, which means to typeset the whole
149 document even if there are errors. More imformation about
150 batchmode can be found in Donald E. Knuth's TeXbook.
151 --nonstopmode
153 Process the file in nonstopmode, which means to typeset the doc‐
154 ument and report errors, but not to stop at any error. It is
155 similar to batchmode but more verbose. More imformation about
156 nonstopmode can be found in Donald E. Knuth's TeXbook.
157 --bodyfont=font
159 The name of a font to preload for use in setting the body of the
160 text (OBSOLETE).
161 --centerpage
163 Center the document on the page.
164 --color
166 Turn on color mode. Color mode can also be set by commands
167 embedded in the document. These commands override the --color
168 option.
169 --convert=FORMAT
171 Convert the input file to ConTeXt format from FORMAT before pro‐
172 cessing. In most cases, this conversion will result in a TeX
173 file. Currently supported input FORMATs are xml and sgml.
174 --dvipdfmx, --dvipdfm, --dpx, --dpm
176 Use the TeX engine (e.g. pdftex or pdfetex) to make a DVI file
177 and dvipdfmx(1) to turn it into PDF.
178 --dvi, --ps, --dvips
180 Use the TeX engine (e.g. pdftex or pdfetex) to make a DVI file
181 and dvips(1) to turn it into PostScript. It's counterintuitive
182 that --dvi produces a PostScript file in addition to the DVI
183 file. But that's because --dvi is shorthand for --dvips; adding
184 the --nobackend option prevents texexec's running dvips(1). See
185 also the --engine option.
186 --fast Typeset the document(s) as fast as possible without causing
188 problems.
189 --final
191 Perform a final run without skipping anything. This option is
192 typically used with --fast.
193 --language=LANGUAGE
195 Set the language for hyphenation. Can be specified in your
196 source file. Options are the same as those for --interface.
197 --mode=MODELIST, --modes=MODELIST
199 Allows you to change the mode used while typesetting the source
200 file. The MODELIST is a comma separated list of modes. Modes
201 are a conditional-compilation facility like #ifdef in C. So one
202 source file can be used to produce several typeset documents:
203 one for A4 paper, one for screen display in full color, one for
204 letter paper, etc. For example:
205 texexec --pdf --mode=A4 --result=manual-a manual-t.tex
207 texexec --pdf --mode=letter --result=manual-l manual-t.tex
208 texexec --pdf --mode=screen --result=manual-s manual-t.tex
209 Here the --mode tells ConTeXt which mode directives to use when
211 typesetting the source file. The --result option tells ConTeXt
212 where to put the output file.
213 --modefile=file
215 Load this file before most of the usual processing; usually used
216 for mode-related material.
217 --noarrange
219 Ignore arrangement commands in the source file.
220 --nobackend
222 Do not run the backend, e.g. dvips(1) or dvipdfmx(1). See the
223 --dvips or --dvipdfmx options. Why would you give one of those
224 options to choose a backend, yet tell texexec not to run the
225 backend? Because each backend has its own syntax for \special
226 calls. Specifying the backend allows the ConTeXt macros to use
227 the correct syntax so that when you later run the backend to
228 produce PostScript or PDF, the specials will be interpreted cor‐
229 rectly.
230 --pages=PAGENUMBERLIST
232 Specify the pages or page range to appear in the output file.
233 PAGENUMBERLIST may be the keyword odd or even; or one or more
234 pages or page ranges separated by commas. For example,
235 texexec --pages=1,7,8-11,14 somefile.tex
236 --paperformat=KEY
238 For typesetting multiple pages on a single piece of paper. KEY
239 has the form a4a3 (for printing A4 pages on A3 paper), a5a4 (for
240 printing A5 pages on A4 paper), or in general aMaN. The actual
241 layout of the pages is specified with the --printformat option.
242 --pdf, --pdftex
244 Use pdftex(1) to produce a pdf document (the default).
245 --printformat=KEY
247 Specify the layout of the final output. KEY can be up, result‐
248 ing in 2 pages per sheet, double sided; or down, resulting in 2
249 rotated pages per sheet, double sided. Use the --paperformat
250 option to specify the original page and sheet size.
251 --utfbom
253 Turn on UTF-8 encoding.
254 --xetex, --xtx
256 Use xetex(1) to produce a pdf document.
257 Creating ConTeXt Format Files
259 --make Generate a ConTeXt format file. For example, to make cont-
260 en.fmt and have it placed in a default format directory:
261 texexec --make de
262 The most common invocation, which is used by scripts that
263 install a new version of ConTeXt (see ctxtools(1)), uses --all
264 so that texexec makes the usual formats:
265 texexec --make --all
266 --local
268 When searching for TeX or MetaPost formats, look in the current
269 directory rather than in the location set by the kpse library.
270 See kpathsea(1) for more information on path searching.
271 --check
273 Check and report information about the ConTeXt version, the dis‐
274 tribution, the TeX engine, and the language interfaces/formats.
275 Expert options
278 You should know what you're doing if you use these options!
279 --alpha
281 Use the TEXMFALPHA environment variable to find and run an alpha
282 release of ConTeXt.
283 --beta Use the TEXMFBETA environment variable to find and run a beta
285 release of ConTeXt.
286 --distribution=dist
288 Usually one of standard, web2c, or miktex. texexec should fig‐
289 ure it out automatically, and you shouldn't need to use this
290 option.
291 --engine=texengine
293 Specify the program to do the hard work of typesetting. Cur‐
294 rently either pdftex (the default), xetex, or aleph. The luatex
295 value is experimental. The --engine option is not usually
296 needed. Instead, let texexec figure out the setting based on
297 other command-line information. See for example the --xetex or
298 --pdf switches.
299 Postprocess PDF Files
302 --combination=ROWS*COLS
303 Specify the number of pages to show on a single page. Use with
304 --pdfcombine.
305 --pdfarrange
307 For rearranging pages in PDF files.
308 texexec --pdfarrange --paperformat=a5a4 --printformat=up foo.pdf
309 This command creates an A5 booklet from a PDF file foo.pdf.
310 --pdfarrange is used in conjunction with the following options.
311 --pdfcopy
313 Copy and perhaps process pages from the pdf file. The resulting
314 file is texexec.pdf by default, but you can change that using
315 --result. Use the --scale option to magnify or demagnify the
316 original pages and the --pages option to select the pages to
317 copy. Here is an example using all these options:
318 texexec --pages=4-7 --pdfcopy --scale=750 --result=one images.pdf
319 It takes pages 4-7 from images.pdf, scales them by 75%, and
320 copies them to one.pdf.
321 --scale=integer
323 If the integer is less than 10, then it is taken as an (integer)
324 magnification factor. Otherwise, it is taken as a magnification
325 factor in TeX terms, i.e. with 1000 meaning full scale.
326 --paperoffset=dimen
328 Specify the space between the edge of the pages and the begin‐
329 ning of the text block.
330 --backspace=dimen
332 Specify the inside (gutter) margins.
333 --topspace=dimen
335 Specify the top and bottom margin.
336 --markings
338 Add crop marks.
339 --addempty=PAGES
341 Add empty pages after the pages specified in PAGES. (Useful
342 for, among other things, adding blank pages after a table of
343 contents.)
344 --textwidth=WIDTH
346 Set the width of the original text. Specifying this parameter
347 with a single-sided original will allow ConTeXt to adjust the
348 page layout for double-sided output, producing much more attrac‐
349 tive results.
350 With the --pdfarrange flag, specifying more than one file will
352 result in all of the files being combined in the final result,
353 allowing you to add title pages, decorated part separators, and
354 so forth.
355 You can also do more complex manipulations, such as adding addi‐
357 tional text to the page by setting up a small file with layout
358 definitions and a simple figure insertion loop.
359 --pdfcombine
361 Combine multiple pages. Requires the --combination option.
362 --pdfselect
364 Extract pages from a file. Use in combination with the --selec‐
365 tion switch, as in
366 texexec --pdfselect --paperformat=S6
367 --selection=1,9,14 file-1
368 which extracts pages 1, 9, and 14 from file-1.pdf, and places
369 them in texexec.pdf (the default output filename if an output
370 file isn't specified).
371 See --pdfarrange for other options.
373 --selection=PAGES
375 Specify pages to be affected by another option. See --pdfar‐
376 range and --pdfselect for examples.
377 XML handling
380 --filters=filter1[,filter2[,...]]
381 Specify XML filters to use.
382 Extract or Strip Out Documentation
385 --listing
386 Produce a typeset version of the source code in FILE. You can
387 specify the format of the output file. For example, use
388 texexec --ps --listing readme.now
389 to produce a PostScript file called texexec.ps.
390 See also --backspace, --topspace, and --result.
392 --module
394 Create documentation for ConTeXt, MetaPost (see mpost(1)),
395 perl(1), and ruby(1) modules. Converts the documentation to
396 ConTeXt format and then typesets a documentated version of the
397 source file.
398 Documentation lines in ConTeXt source files are specified by
400 beginning lines with these strings:
401 %C : Copyright information
403 %D : Documentation lines
405 %I : TeXEdit information lines (mostly in Dutch)
407 %M : Macro code needed to processs the documentation
409 %S : Suppressed lines
411 The same forms can be used for Perl or ruby scripts, except that
413 the % character (the TeX comment character) is replaced by #
414 (the Perl comment character).
415 See also the --documentation option to ctxtools(1).
417 Process MetaPost Figures
420 --mpsformats=name
421 The name of a MetaPost format file, e.g. metafun (the default).
422 --mptex
424 Strips out and typesets TeX code embedded in a MetaPost file.
425 --nomp Do not run mpost(1), even if needed.
427 --nomprun
429 Do not run mpost(1) on embedded MetaPost code.
430 Producing Proof Sheets of Figures
433 Generate information and proof sheets of one or more (non-EPS) graphics
434 files. For example,
435 texexec --figures *.png *.jpg
436 scans the current directory for PNG and JPG files and extracts useful
437 information about their sizes and types. By default, this information
438 is stored in rlxtools.rli. Then the given figures are made into a
439 proof sheet (by default texexec.pdf) according to the method specified
440 by the --method option. Note that newer versions of pdftex(1) do not
441 support TIFF inclusion.
442 --method=ALTERNATIVE
444 Specify one of three options to produce the document containing
445 the images used in the source file:
446 a : A proof sheet with additional information provided for each
448 figure (the default)
449 b : A proof sheet with the graphics only
451 c : One figure per page, with the page clipped to the bounding
453 box of the figure
454 See also --paperoffset, which allows you to specify an offset to
456 be added to the page, as in
457 texexec --figures --method=c --paperoffset=.5cm *.pdf *.png *.jpg
458
461 Each ConTeXt user interface (language) has its own format. The follow‐
462 ing command generates two formats, one using the English interface for
463 typesetting in English, and one for Dutch:
464 texexec --make en nl
465 By default, the language used for typesetting matches the user-inter‐
467 face language (set with --interface. It is possible to use one lan‐
468 guage for typesetting and another for messages by changing the relevant
469 settings in cont-usr.tex. These languages can also be changed on the
470 command line with a command such as
471 texexec --make --language=pl,cz,sk en
473 That command generates a ConTeXt format file with an English
475 user interface, and the main language set to Polish (pl). Czech
476 and Slovak hyphenation patterns are also loaded so that Czech
477 and Slovak text included in a source file will be typeset prop‐
478 erly (cz and sk).
479 o When the appropriate formats are present, a file can be typeset
481 by typing
482 texexec test
483 texexec tries to determine what interface it should use to type‐
485 set test.tex by looking for a line such as
486 % interface=en tex=pdftex output=pdftex
488 at the top of the file (i.e., on the very first line). This
490 line is equivalent to TeX's format line, ``&FORMAT'').
491 By default, texexec will produce a PDF file using pdftex(1).
493 The --dvips flag tells texexec to produce a PostScript file
494 instead.
495 After an error-free run, texexec will run texutil(1) to deter‐
497 mine whether additional runs of tex(1) (or pdftex(1)) or any
498 utility programs (e.g., bibtex(1), makeindex(1)) are necessary.
499 You can suppress these additional runs by specifying the --once
500 or --runs flags:
501 texexec --once test
503 texexec --runs=2 test
504
506 Produce PDF from ConTeXt source (the .tex extension is optional):
507 texexec file.tex
508 Same as the above but without rerunning for crossreferences, etc.:
510 texexec --once file.tex
511 Produce PostScript from ConTeXt source:
513 texexec --ps file.tex
514 Produce file-a4.pdf using conditional compilation (modes):
516 texexec --mode=a4 --result=file-a4 file.tex
517 Generate format (.fmt) files used by ConTeXt (used during installa‐
519 tion):
520 texexec --make --all
521
525 texexec requires ruby. On Unix and Unix-like systems, no spe‐
526 cial steps have to be taken to get texexec to work beyond
527 installing ruby and having the ruby(1) binary in your path.
528
531 bibtex(1), ctxtools(1), dvipdfmx(1), dvips(1), fmtutil(1), makein‐
532 dex(1), mpost(1), mptopdf(1), pdftex(1), pdftk(1), ruby(1), psnup(1),
533 tex(1), texfont(1), texmfstart(1), texshow(1), texutil(1), xetex(1).
534 The texexec manual mtexexec.pdf, available from PRAGMA ADE ⟨http://
536 www.pragma-ade.com/dir/general/manuals/⟩.
537 Donald E. Knuth's The TeXbook.
539 ConTeXt wiki ⟨http://www.contextgarden.net⟩.
541
544 This manpage was written by Tobias Burnus <burnus@gmx.de> and C.M. Con‐
545 nelly <c@eskimo.com> and updated by Sanjoy Mahajan <sanjoy@mit.edu>.
546 It is based on the mtexexec.pdf manual written by Hans Hagen
547 <pragma@wxs.nl>.
548texexec 6.2 December 2006 TEXEXEC(1)