Debian Codegraph @

texmf-dist/doc/man/man1/tex.1

raw
1 .TH TEX 1 "24 January 2026" "Web2C 2026"
2 .\"=====================================================================
3 .if t .ds TX \fRT\\h'-0.10m'\\v'0.17v'E\\v'-0.17v'\\h'-0.06m'X\fP
4 .if n .ds TX TeX
5 .\" OX for oblique/italic TeX logo
6 .ie t .ds OX \fIT\h'-0.17m'\v'+0.21m'E\v'-0.21m'\h'-0.04m'X\fP
7 .el .ds OX TeX
8 .\" LX definition must follow TX so LX can use TX
9 .if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
10 .if n .ds LX LaTeX
11 .\" OX for oblique LaTeX
12 .if t .ds OL \fIL\\h'-0.19m'\\v'-0.15v'\s-2A\s0\\h'-0.09m'\\v'0.15v'\fP\*(OX
13 .if n .ds OL LaTeX
14 .\"=====================================================================
15 .SH NAME
16 tex, initex \- text formatting and typesetting
17 .SH SYNOPSIS
18 .B tex
19 .RI [ options ]
20 .RI [ \fB&\fPformat ]
21 \h'.25' [ \fIfile\fP [ \fImore-input\fP ] \h'.5'|\h'.5' [ \fB\e\fP\fImore-input\fP ]
22 .\"=====================================================================
23 .SH DESCRIPTION
24 Run the \*(TX typesetter on
25 .IR file [.tex],
26 usually creating
27 .IR file.dvi .
28 If the file argument has no extension, ".tex" will be appended to it.
29 .PP
30 The normal usage is to run
31 .IP
32 tex paper
33 .PP
34 to process \fIpaper.tex\fP with \*(TX.
35 The name
36 .I paper
37 will be the so-called "jobname", and is used in forming
38 output filenames.
39 If \*(TX doesn't get a filename in the first line, the jobname is
40 .IR texput .
41 When looking for a file, \*(TX looks for the name with and without the
42 default extension
43 .RI ( .tex )
44 appended, unless the name already contains that extension. If
45 .I paper
46 is the jobname,
47 a log of error messages, with rather more detail than normally appears
48 on the screen, will be written to
49 .IR paper.log ,
50 and the output file will be
51 .IR paper.dvi .
52 The \fB--jobname\fP option sets the jobname explicitly.
53 .PP
54 \*(TX
55 formats the interspersed text and commands contained in the input
56 and outputs a so-called
57 .I DVI
58 file, which is short for
59 .IR "DeV\h'.02'ice Independent" .
60 DVI files are a device-independent binary representation of the pages in
61 the output document. They can be displayed online (e.g.,
62 .BR xdvi (1)),
63 translated to PDF
64 .RB ( dvipdfmx (1)),
65 PostScript
66 .RB ( dvips (1)),
67 or otherwise manipulated. Other engines
68 .RB ( pdftex (1),
69 .BR luatex (1)),
70 descendants of original \*(TX, can output PDF directly.
71 .PP
72 \*(TX's capabilities and language are described in many places (see the
73 references), including Donald Knuth's original book,
74 .IR "The \*(OXbook" .
75 \*(TX is normally used with a large body of precompiled macros, called a
76 format. Knuth's original format is named \fIplain\fP. Other formats,
77 notably \fBlatex\fP(1), are much larger, but still implemented entirely
78 as \*(TX macros.
79 .PP
80 .B Command line processing
81 .PP
82 To process the command line, after first reading any \fIoption\fR(s)
83 (listed below), if the first non-option argument does not begin with an
84 escape character (normally a backslash), \*(TX internally prepends
85 \fB\einput\fP to the non-option arguments. Whether the \fB\einput\fP was
86 prepended or not, \*(TX then processes the text as normal \*(TX input,
87 including macro expansion.
88 .PP
89 With no non-option arguments, \*(TX gives you a \fB**\fP interactive
90 prompt; whatever text you enter is processed in exactly the same way as
91 non-option command line arguments.
92 .PP
93 Examples:
94 .TP
95 .B tex foo
96 executes "\einput foo".
97 .TP
98 .B tex foo bar
99 executes "\einput foo bar", which inputs
100 \fIfoo.tex\fP and then typesets the string "bar".
101 .TP
102 .B tex \e\eend
103 executes \eend; here the double backslash is one common way of escaping
104 the backslash for the shell. \*(TX must see only one backslash.
105 .PP
106 To reiterate, the text of an input filename, as well as any text
107 following a filename, is subject to \*(TX's macro expansion. As a
108 result, a ~ character is normally not usable within a filename, since ~
109 is conventionally defined to be an active character that expands into
110 several primitive tokens, which can't be part of a filename. You can
111 usually use \estring~ to get a literal ~ character. More on input
112 filenames: https://tug.org/texinfohtml/web2c.html#Input-filenames
113 .PP
114 .B Format (.fmt) selection
115 .PP
116 With an argument
117 \fB&\fIformat\fR, \*(TX reads the set of precompiled commands
118 contained in the (binary) file
119 .IR format .fmt
120 instead of the default tex.fmt (searched for using the TEXFORMATS path; see
121 environment section below). This is sometimes more convenient than the
122 .B -fmt
123 .I format
124 option, which is equivalent.
125 .PP
126 The \*(TX implementation in \*(TX Live (a.k.a. Web2C) looks at
127 its command line to find the name it was invoked as. When called as
128 .BR initex
129 (or when the
130 .B -ini
131 option is given, which is equivalent) it can be used to precompile
132 macros into a
133 .I .fmt
134 file. When called as
135 .B virtex
136 it will use the
137 .I plain
138 format. Nowadays, if either or both of the executables
139 .B initex
140 and
141 .B virtex
142 exist, they are symbolic links to the
143 .B tex
144 executable; the
145 .B virtex
146 symlink is not made by default in \*(TX Live.
147 .PP
148 When invoked as any other name, \*(TX will use that name as
149 the name of the format to use. Most notably, when invoked as
150 .B tex
151 the format file
152 .I tex.fmt
153 is read, which is identical to the
154 .I plain
155 format. The commands defined by the
156 .I plain
157 format are described in Appendix\~B of
158 .IR "The \*(OXbook" ,
159 among other places (see references below). The other \*(TX engines
160 follow the same convention; for example, the
161 .B latex
162 command is a symlink to the
163 .B pdftex
164 binary, and reads \fIlatex.fmt\fP.
165 .PP
166 This implementation of \*(TX can look in the first line of the file
167 .I paper.tex
168 to see if it begins with the magic two-character sequence
169 .IR %& .
170 If the first line begins with
171 .BI %& format
172 .BI -translate-file \ tcxname
173 then \*(TX will use the named format and (if specified) translation table
174 .I tcxname
175 to process the source file. Either the format name or the
176 .B -translate-file
177 specification may be omitted, but not both. This overrides the
178 format selection based on the name by which the program is invoked.
179 The
180 .B -parse-first-line
181 option or the
182 .I parse_first_line
183 configuration variable controls whether this behavior is enabled. It is
184 disabled for the original \*(TX, and enabled for all other engines.
185 .PP
186 .B Input encodings
187 .PP
188 \*(TX, predating Unicode as it does, reads input byte by byte, and has
189 no native recognition for UTF-8 or any other encoding. This is also the
190 case for pdf\*(TX. However, to a large extent, UTF-8 can be parsed at
191 the \*(TX macro level, and packages have been developed for this. For
192 native recognition of Unicode, the engines
193 .BR luatex (1)
194 and
195 .BR xetex (1)
196 are available, with corresponding formats.
197 .PP
198 .B Error handling
199 .PP
200 \*(TX's error messages can be rather unfortunately cryptic. As general
201 advice, sometimes only the first error matters, so it's worth trying to
202 fix that first. Cutting down the input file can be helpful if mysteries
203 remain. For more advice, including on a few specific problems:
204 https://texfaq.org/index#errors
205 .PP
206 A convenient file in most distributions is
207 .IR null.tex ,
208 containing nothing.
209 When \*(TX can't find a file it thinks you want to input, it keeps
210 asking you for another filename; responding "null" gets you out
211 of the loop if you don't want to input anything. You can also type your
212 EOF character (usually control-D).
213 .PP
214 When \*(TX reports an error, by default it puts you into an interactive
215 dialog with a ? prompt. Responding with another ? shows you
216 the available responses, for example, \fIx\fP quits immediately. The
217 .I e
218 response to \*(TX's error prompt causes the system default editor to
219 start up at the current line of the current file. The environment
220 variable TEXEDIT can be used to change the editor used. It may contain a
221 string with "%s" indicating where the filename goes and "%d" indicating
222 where the decimal line number (if any) goes. For example, a TEXEDIT
223 string specifying emacs to be run can be set like this (in Bourne shell
224 syntax):
225 .IP
226 TEXEDIT="emacs +%d %s"; export TEXEDIT
227 .PP
228 To debug problems with finding files, see the \fB--kpathsea-debug\fP
229 option below.
230 .\"=====================================================================
231 .SH OPTIONS
232 \*(TX (in \*(TX Live and Web2C) understands the following command line
233 options. Most of these options are also supported by the derived
234 engines.
235 .PP
236 Options can be started with either - or --; in this and other
237 documentation, we use "-" and "--" interchangeably. Options can be
238 separated from their values with either an = character or whitespace.
239 Put filenames or other non-options that start with a dash after an
240 option --. All the programs in the \*(TX family (and many non-\*(TX
241 programs; this command-line parsing comes originally from the GNU
242 getopt_long_only(3) library function) follow these conventions.
243 .PP
244 In \*(TX and the other engines, all options must precede any non-option
245 arguments, due to the peculiarities of \*(TX's first-line parsing
246 described above. For the \*(TX utilities, options and non-options can be
247 given in any order.
248 .TP
249 .B -help
250 Print help message and exit.
251 .TP
252 .BI -cnf-line \ string
253 Parse
254 .I string
255 as a
256 .I texmf.cnf
257 configuration line. See the Kpathsea manual.
258 .TP
259 .B -enc
260 Enable the enc\*(TX extensions. This option is only effective in
261 combination with
262 .BR -ini .
263 For documentation of the enc\*(TX extensions see
264 http://www.olsak.net/enctex.html.
265 .TP
266 .B -[no-]file-line-error
267 Print error messages in the form
268 .I file:line:error
269 which is similar to the way many other compilers format them. By
270 default, or with \fB-no-\fP, \*(TX's default error format is used,
271 usually starting with an ! character.
272 .TP
273 .B -file-line-error-style
274 This is the old name of the
275 .B -file-line-error
276 option.
277 .TP
278 .BI -fmt \ format
279 Use
280 .I format
281 as the name of the format to be used, instead of the name by which
282 \*(TX was called or a
283 .I %&
284 line. (See above and below for more on formats.)
285 .TP
286 .B -halt-on-error
287 Exit with an error code when an error is encountered during processing.
288 .TP
289 .B -ini
290 Start in
291 .I INI
292 mode, which is used to dump formats. The
293 .I INI
294 mode can be used for typesetting, but no format is preloaded, and
295 basic initializations like setting catcodes may be required.
296 .TP
297 .BI -interaction \ mode
298 Sets the interaction mode. The mode can be either
299 .IR batchmode ,
300 .IR nonstopmode ,
301 .IR scrollmode ,
302 and
303 .IR errorstopmode .
304 The meaning of these modes is the same as that of the corresponding
305 \ecommands.
306 .TP
307 .B -ipc
308 Send DVI output to a socket as well as the usual output file. Whether
309 this option is available is the choice of the installer.
310 .TP
311 .B -ipc-start
312 As
313 .BR -ipc ,
314 and starts the server at the other end as well. Whether this option
315 is available is the choice of the installer.
316 .TP
317 .BI -jobname \ name
318 Use
319 .I name
320 for the job name, instead of deriving it from the name of the input file.
321 (See above.)
322 .TP
323 .BI -kpathsea-debug \ bitmask
324 Sets path searching debugging flags according to the bitmask. See the
325 .I Kpathsea
326 manual for details: https://tug.org/texinfohtml/kpathsea.html#Debugging
327 .TP
328 .BI -[no-]mktex \ fmt
329 Enable (disable)
330 .RI mktex fmt ,
331 where
332 .I fmt
333 must be
334 .IF fmt ,
335 .IR tex ,
336 or
337 .IR tfm .
338 See the Kpathsea manual: https://tug.org/texinfohtml/kpathsea.html#mktex-scripts
339 .TP
340 .B -mltex
341 Enable ML\*(TX (Multi-lingual \*(TX) extensions. Only effective in
342 combination with
343 .BR -ini .
344 More info: https://tug.org/texinfohtml/web2c.html#MLTeX
345 .TP
346 .BI -output-comment \ string
347 Use
348 .I string
349 for the
350 .I DVI
351 file comment instead of the date.
352 .TP
353 .BI -output-directory \ directory
354 Write output files in
355 .I directory
356 instead of the current directory. Look up input files in
357 .I directory
358 first, then along the normal search path. See also the description below
359 of the TEXMFOUTPUT environment variable.
360 .TP
361 .B -[no-]parse-first-line
362 Enable (or disable) checking the first line of the main input file
363 for
364 .I %&
365 and, if so, parsing it to look for a format name or a
366 .B -translate-file
367 option.
368 .TP
369 .BI -progname \ name
370 Pretend to be program \fIname\fP for purposes of Kpathsea lookups. This
371 affects both the format used and the search paths.
372 .TP
373 .B -recorder
374 Enable the filename recorder. This outputs a machine-readable trace of
375 all files opened for input and output in a file with the usual jobname
376 and extension
377 .IR .fls .
378 .TP
379 .B -[no-]shell-escape
380 Allow (or disallow) documents to execute arbitrary shell commands via the
381 .BI \ewrite18{ command }
382 construct. This feature is normally restricted for security reasons to a
383 very few known-safe programs. You should use this option, which enables
384 execution of any command at all, only for trusted documents. More on
385 shell escapes: https://tug.org/texinfohtml/web2c.html#Shell-escapes
386 .TP
387 .B -src-specials
388 Insert source specials into the dvi file. This is used for
389 .BR synctex (1).
390 In editors that support Sync\*(TX, you can click in the output window
391 and get back to the corresponding location in the source.
392 .TP
393 .BI -src-specials \ where
394 Insert source specials in certain places of the
395 .I DVI
396 file;
397 .I where
398 is a comma-separated value list:
399 .IR cr ,
400 .IR display ,
401 .IR hbox ,
402 .IR math ,
403 .IR par ,
404 .IR parent ,
405 or
406 .IR vbox .
407 .TP
408 .BI -translate-file \ tcxname
409 Use the
410 translation table in the file
411 .I tcxname
412 to set the mapping of input characters and
413 re-mapping of output characters.
414 .TP
415 .BI -default-translate-file \ tcxname
416 Like
417 .B -translate-file
418 except that a
419 .I %&
420 line can override this setting.
421 .TP
422 .B -8bit
423 Make all characters printable by default.
424 .TP
425 .B -version
426 Print version information and exit.
427 .\"=====================================================================
428 .SH ENVIRONMENT
429 Numerous environment variables can be used to find files. A few are
430 mentioned here, but see the Kpathsea(rch) library documentation (e.g.,
431 https://tug.org/texinfohtml/kpathsea.html#TeX-support) for a more
432 comprehensive list, and how they are used. The
433 .BR kpsewhich (1)
434 utility can be used to query the values of the variables. In Kpathsea
435 specifications, "//" means to search subdirectories recursively.
436 .PP
437 Every variable setting in \fItexmf.cnf\fR can be overridden by the
438 environment variable of the same (or associated) name, as explained
439 tersely at the top of \fItexmf.cnf\fR, and more completely in the
440 Kpathsea documentation.
441 .TP
442 .B TEXMFOUTPUT
443 Normally, \*(TX puts its output files in the current directory. If
444 any output file cannot be opened there, it tries to open it in the
445 directory specified in the environment variable TEXMFOUTPUT.
446 There is no default value for that variable. For example, if you say
447 .I tex paper
448 and the current directory is not writable, if TEXMFOUTPUT has
449 the value
450 .IR /tmp ,
451 \*(TX attempts to create
452 .I /tmp/paper.log
453 (and
454 .IR /tmp/paper.dvi ,
455 if any output is produced.) TEXMFOUTPUT is also checked for input
456 files, as \*(TX often generates files that need to be subsequently
457 read; for input, no suffixes (such as ".tex") are added;
458 the input name is simply checked as given.
459 .PP
460 If the \fB-output-directory\fP option is given, \*(TX sets TEXMFOUTPUT
461 in the environment to its value, so that programs invoked by \*(TX have
462 it available.
463 .PP
464 More on output file location:
465 https://tug.org/texinfohtml/web2c.html#Output-file-location
466 .TP
467 .B TEXINPUTS
468 Search path for
469 .I \einput
470 and
471 .I \eopenin
472 files. By default, this starts with . (a period, meaning the current
473 directory as usual), so that user files are found before system files.
474 An empty path component will be replaced with the paths defined in the
475 .I texmf.cnf
476 file. For example, set TEXINPUTS to ".:/home/user/tex:" to prepend the
477 current directory and "/home/user/tex" to the standard search path.
478 .TP
479 .B TEXMFDOTDIR
480 In \*(TX Live's \fItexmf.cnf\fP, TEXINPUTS and other paths don't start
481 literally with ".", but rather with $TEXMFDOTDIR, which in turn
482 defaults to ".". This indirection makes it easy to, for example, search
483 the current directory and all its subdirectories for everything: set
484 TEXMFDOTDIR to ".//".
485 .TP
486 .B TEXFORMATS
487 Search path for format files (\fI.fmt\fP). They are typically stored
488 under the TEXMFSYSVAR directory. You can find the exact location
489 of \fItex.fmt\fP (for example) with this kpsewhich invocation:
490 .br
491 kpsewhich -engine=/ -all tex.fmt
492 .TP
493 .B TEXPOOL
494 Search path for \*(TX's internal strings (\fI.pool\fP); this is only
495 relevant for original \*(TX; the extended engines all have the strings
496 compiled into the binary.
497 .TP
498 .B TFMFONTS
499 Search path for font metric
500 .RI ( .tfm )
501 files.
502 .TP
503 .B TEXEDIT
504 Command template for switching to editor (see above). The default, usually
505 .BR vi ,
506 is set when \*(TX is compiled.
507 .\"=====================================================================
508 .SH FILES
509 The locations of the files mentioned below varies from system to
510 system. Use the
511 .B kpsewhich
512 utility to find their locations.
513 .TP
514 .I texmf.cnf
515 Configuration file. This contains definitions of search paths as well
516 as other configuration parameters like
517 .IR parse_first_line .
518 .TP
519 .I tex.pool
520 Text file containing \*(TX's internal strings.
521 .TP
522 .I *.tfm
523 Metric files for \*(TX's fonts.
524 .TP
525 .I *.fmt
526 Predigested \*(TX format (.\|fmt) files.
527 .TP
528 .I $TEXMFMAIN/tex/plain/base/plain.tex
529 The basic macro package described in \fIThe \*(OXbook\fP.
530 .TP
531 .I $TEXMFMAIN/tex/plain/config/tex.ini
532 The driver file that builds the plain format file, \fItex.fmt\fP, in
533 \*(TX Live.
534 .\"=====================================================================
535 .SH BUGS
536 This version of \*(TX implements a number of extensions, which
537 technically conflict with the definition of original \*(TX (although
538 almost never make a difference in practice). When such extensions are
539 enabled, the banner printed when \*(TX starts is changed to print "TeXk"
540 instead of "TeX".
541 .PP
542 This version of \*(TX fails to trap arithmetic overflow when dimensions
543 are added or subtracted. Cases where this occurs are rare, but when it
544 does the program may crash, and/or the generated DVI file will be
545 invalid. Patches to catch such overflow cases would be welcome.
546 .PP
547 Knuth still accepts new bug reports for \*(TX, but only reviews them
548 every several years. They are vetted in advance by a small group of
549 experienced volunteers. For a list of submitted reports and other
550 information: https://tug.org/texmfbug.
551 .PP
552 Naturally, bugs in engines other than original \*(TX should be directed
553 to their respective mailing lists and maintainers.
554 .\"=====================================================================
555 .SH "SEE ALSO"
556 .BR mf (1),
557 .BR pdftex (1),
558 .BR latex (1),
559 .BR luatex (1),
560 and plenty more.
561 .br
562 Donald E. Knuth,
563 .IR "The \*(OXbook" ,
564 Addison-Wesley.
565 .br
566 Leslie Lamport,
567 .IR "\*(OL: A Document Preparation System" ,
568 Addison-Wesley.
569 .PP
570 Some free documentation on the \*(TX language:
571 .br
572 Petr Olsak, \*(TX in a Nutshell:
573 https://ctan.org/pkg/tex-nutshell
574 .br
575 Plain \*(TX documentation topic on CTAN:
576 https://ctan.org/topic/tut-plaintex
577 .br
578 Victor Eijkhout,
579 .IR "\*(OX By Topic" ,
580 A \*(TXnician's reference:
581 https://www.eijkhout.net/tex/tex-by-topic.html
582 .br
583 Paul W. Abrahams, Kathryn Hargreaves, Karl Berry,
584 .IR "\*(OX for the Impatient" ,
585 on \*(TX, plain \*(TX, and
586 .BR eplain (1);
587 available in French and Chinese translations:
588 https://ctan.org/pkg/impatient
589 .PP
590 Some online information:
591 .br
592 Getting Started with TeX, LaTeX, and friends,
593 a short web page with selected resources:
594 https://tug.org/begin
595 .br
596 David Bausum, \*(TX primitive control sequences:
597 https://tug.org/utilities/plain/cseq.html
598 .br
599 Levels of \*(TX, briefly describing the various engines and formats:
600 https://tug.org/levels
601 .br
602 \*(TX Live web pages:
603 https://tug.org/texlive
604 .br
605 Web2C Texinfo manual and web page:
606 https://tug.org/web2c
607 .br
608 Kpathsea Texinfo manual and web page:
609 https://tug.org/kpathsea
610 .br
611 Sources for the \*(TX-world literate programs, as pdf:
612 https://ctan.org/pkg/knuth-pdf
613 .br
614 .I TUGboat
615 (the journal of the \*(TX Users Group; submissions welcome):
616 https://tug.org/TUGboat
617 .PP
618 If you find \*(TX useful, please consider joining or supporting the
619 \*(TX Users Group, or another user group in your area:
620 .br
621 https://tug.org
622 .br
623 https://tug.org/usergroups.html
624 .\"=====================================================================
625 .SH TRIVIA
626 \*(TX, pronounced properly, rhymes with ``blecchhh''. The proper
627 spelling in typewriter-like fonts is ``TeX'' and not ``TEX'' or ``tex''.
628 .\"=====================================================================
629 .SH AUTHORS
630 \*(TX was created by Donald E. Knuth, who implemented it using his WEB
631 system for Pascal programs. It was ported to Unix at Stanford by Howard
632 Trickey, and at Cornell by Pavel Curtis. The version now included in
633 \*(TX Live, the current Unix \*(TX distribution, is generated by the
634 Web2C system originally written by Tomas Rokicki and Tim Morgan.
635 .PP
636 Bug reports in original \*(TX (exceedingly rare): https://tug.org/texmfbug
637 .br
638 Public mailing list for implementation questions and reports:
639 https://lists.tug.org/tex-k
640 .br
641 Public discussion list for \*(TX Live:
642 https://lists.tug.org/tex-live
643 .br
644 Public discussion list for all things \*(TX (and \*(LX):
645 https://lists.tug.org/texhax