| blob | 445ab949c10971088d5cf06fb4536da7ac71f075 |
1 .TH TEX 1 "16 June 2015" "Web2C @VERSION@"
2 .\"=====================================================================
3 .if n .ds MF Metafont
4 .if t .ds MF Metafont
5 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
6 .if n .ds TX TeX
7 .ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
8 .el .ds OX TeX
9 .\" BX definition must follow TX so BX can use TX
10 .if t .ds BX \fRB\s-2IB\s0\fP\*(TX
11 .if n .ds BX BibTeX
12 .\" LX definition must follow TX so LX can use TX
13 .if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
14 .if n .ds LX LaTeX
15 .if n .ds WB Web
16 .if t .ds WB W\s-2EB\s0
17 .\" EX and EE are used for displays that are pure code
18 .de EX
19 .nf
20 .ft CW
21 ..
22 .de EE
23 .ft R
24 .fi
25 ..
26 .\"=====================================================================
27 .SH NAME
28 tex, initex \- text formatting and typesetting
29 .SH SYNOPSIS
30 .B tex
31 .RI [ options ]
32 .RI [ \fB&\fPformat ]
33 .RI [ file | \fB\e\fPcommands ]
34 .\"=====================================================================
35 .SH DESCRIPTION
36 Run the \*(TX typesetter on
37 .IR file ,
38 usually creating
39 .IR file.dvi .
40 If the file argument has no extension, ".tex" will be appended to it.
41 Instead of a filename, a set of \*(TX commands can be given, the first
42 of which must start with a backslash.
43 With a
44 .BI & format
45 argument \*(TX uses a different set of precompiled commands,
46 contained in
47 .IR format\fB.fmt\fP ;
48 it is usually better to use the
49 .B -fmt
50 .I format
51 option instead.
52 .PP
53 \*(TX
54 formats the interspersed text and commands contained in the named
55 files
56 and outputs a typesetter independent file (called
57 .IR DVI ,
58 which is short for
59 .IR "DeVice Independent" ).
60 \*(TX's capabilities and language are described in
61 .IR "The \*(OXbook" .
62 \*(TX
63 is normally used with a large body of precompiled macros,
64 and there are several specific formatting systems, such as
65 \*(LX,
66 which require the support of several macro files.
67 .PP
68 This version of \*(TX looks at its command line to see what name it
69 was called under. If they exist, then both
70 .B initex
71 and
72 .B virtex
73 are symbolic links to the
74 .B tex
75 executable. When called as
76 .BR initex
77 (or when the
78 .B -ini
79 option is given) it can be used to precompile macros into a
80 .I .fmt
81 file. When called as
82 .B virtex
83 it will use the
84 .I plain
85 format. When called under any other name, \*(TX will use that name as
86 the name of the format to use. For example, when called as
87 .B tex
88 the
89 .I tex
90 format is used, which is identical to the
91 .I plain
92 format. The commands defined by the
93 .I plain
94 format are documented in
95 .IR "The \*(OXbook" .
96 Other formats that are often available include
97 .I latex
98 and
99 .IR amstex .
100 .PP
101 The non-option command line arguments to the
102 \*(TX
103 program are passed to it as the first input line. (But it is often
104 easier to type extended arguments as the first input line, since UNIX
105 shells tend to gobble up or misinterpret \*(TX's favorite symbols,
106 like backslashes, unless you quote them.)
107 As described in
108 .IR "The \*(OXbook" ,
109 that first line should begin with a filename, a
110 .IR \econtrolsequence ,
111 or a
112 .IR &formatname .
113 .PP
114 The normal usage is to say
115 .EX
116 tex paper
117 .EE
118 to start processing
119 .IR paper.tex .
120 The name
121 .I paper
122 will be the ``jobname'', and is used in forming
123 output filenames.
124 If \*(TX doesn't get a filename in the first line, the jobname is
125 .IR texput .
126 When looking for a file, \*(TX looks for the name with and without the
127 default extension
128 .RI ( .tex )
129 appended, unless the name already contains that extension. If
130 .I paper
131 is the ``jobname'',
132 a log of error messages, with rather more detail than normally appears
133 on the screen, will appear in
134 .IR paper.log ,
135 and the output file will be in
136 .IR paper.dvi .
137 .PP
138 This version of \*(TX can look in the first line of the file
139 .I paper.tex
140 to see if it begins with the magic sequence
141 .IR %& .
142 If the first line begins with
143 .BI %& format
144 .BI -translate-file \ tcxname
145 then \*(TX will use the named format and translation table
146 .I tcxname
147 to process the source file. Either the format name or the
148 .B -translate-file
149 specification may be omitted, but not both. This overrides the
150 format selection based on the name by which the program is invoked.
151 The
152 .B -parse-first-line
153 option or the
154 .B parse_first_line
155 configuration variable controls whether this behaviour is enabled.
156 .PP
157 The
158 .I e
159 response to \*(TX's error prompt causes the system default editor to
160 start up at the current line of the current file. The environment
161 variable TEXEDIT can be used to change the editor used. It may
162 contain a string with "%s" indicating where the filename goes and "%d"
163 indicating where the decimal line number (if any) goes. For example,
164 a TEXEDIT string for
165 .B emacs
166 can be set with the
167 .B sh
168 command
169 .EX
170 \fITEXEDIT="emacs +%d %s"; export TEXEDIT\fP
171 .EE
172 .PP
173 A convenient file in the library is
174 .IR null.tex ,
175 containing nothing.
176 When \*(TX can't find a file it thinks you want to input, it keeps
177 asking you for another filename; responding `null' gets you out
178 of the loop if you don't want to input anything. You can also type your
179 EOF character (usually control-D).
180 .PP
181 .\"=====================================================================
182 .SH OPTIONS
183 This version of \*(TX understands the following command line options.
184 .TP
185 .B -enc
186 Enable the enc\*(TX extensions. This option is only effective in
187 combination with
188 .BR -ini .
189 For documentation of the enc\*(TX extensions see
190 .BR http://www.olsak.net/enctex.html .
191 .TP
192 .B -file-line-error
193 Print error messages in the form
194 .I file:line:error
195 which is similar to the way many compilers format them.
196 .TP
197 .B -no-file-line-error
198 Disable printing error messages in the
199 .I file:line:error
200 style.
201 .TP
202 .B -file-line-error-style
203 This is the old name of the
204 .B -file-line-error
205 option.
206 .TP
207 .BI -fmt \ format
208 Use
209 .I format
210 as the name of the format to be used, instead of the name by which
211 \*(TX was called or a
212 .I %&
213 line.
214 .TP
215 .B -halt-on-error
216 Exit with an error code when an error is encountered during processing.
217 .TP
218 .B -help
219 Print help message and exit.
220 .TP
221 .B -ini
222 Start in
223 .I INI
224 mode, which is used to dump formats. The
225 .I INI
226 mode can be used for typesetting, but no format is preloaded, and
227 basic initializations like setting catcodes may be required.
228 .TP
229 .BI -interaction \ mode
230 Sets the interaction mode. The mode can be either
231 .IR batchmode ,
232 .IR nonstopmode ,
233 .IR scrollmode ,
234 and
235 .IR errorstopmode .
236 The meaning of these modes is the same as that of the corresponding
237 \ecommands.
238 .TP
239 .B -ipc
240 Send DVI output to a socket as well as the usual output file. Whether
241 this option is available is the choice of the installer.
242 .TP
243 .B -ipc-start
244 As
245 .BR -ipc ,
246 and starts the server at the other end as well. Whether this option
247 is available is the choice of the installer.
248 .TP
249 .BI -jobname \ name
250 Use
251 .I name
252 for the job name, instead of deriving it from the name of the input file.
253 .TP
254 .BI -kpathsea-debug \ bitmask
255 Sets path searching debugging flags according to the bitmask. See the
256 .I Kpathsea
257 manual for details.
258 .TP
259 .BI -mktex \ fmt
260 Enable
261 .RI mktex fmt ,
262 where
263 .I fmt
264 must be either
265 .I tex
266 or
267 .IR tfm .
268 .TP
269 .B -mltex
270 Enable ML\*(TX extensions. Only effective in combination with
271 .BR -ini .
272 .TP
273 .BI -no-mktex \ fmt
274 Disable
275 .RI mktex fmt ,
276 where
277 .I fmt
278 must be either
279 .I tex
280 or
281 .IR tfm .
282 .TP
283 .BI -output-comment \ string
284 Use
285 .I string
286 for the
287 .I DVI
288 file comment instead of the date.
289 .TP
290 .BI -output-directory \ directory
291 Write output files in
292 .I directory
293 instead of the current directory. Look up input files in
294 .I directory
295 first, then along the normal search path. See also description of the
296 TEXMFOUTPUT environment variable.
297 .TP
298 .B -parse-first-line
299 If the first line of the main input file begins with
300 .I %&
301 parse it to look for a dump name or a
302 .B -translate-file
303 option.
304 .TP
305 .B -no-parse-first-line
306 Disable parsing of the first line of the main input file.
307 .TP
308 .BI -progname \ name
309 Pretend to be program
310 .IR name .
311 This affects both the format used and the search paths.
312 .TP
313 .B -recorder
314 Enable the filename recorder. This leaves a trace of the files opened
315 for input and output in a file with extension
316 .IR .fls .
317 .TP
318 .B -shell-escape
319 Enable the
320 .BI \ewrite18{ command }
321 construct. The
322 .I command
323 can be any shell command. This construct is normally
324 disallowed for security reasons.
325 .TP
326 .B -no-shell-escape
327 Disable the
328 .BI \ewrite18{ command }
329 construct, even if it is enabled in the
330 .I texmf.cnf
331 file.
332 .TP
333 .B -src-specials
334 Insert source specials into the
335 .I DVI
336 file.
337 .TP
338 .BI -src-specials \ where
339 Insert source specials in certain places of the
340 .I DVI
341 file.
342 .I where
343 is a comma-separated value list:
344 .IR cr ,
345 .IR display ,
346 .IR hbox ,
347 .IR math ,
348 .IR par ,
349 .IR parent ,
350 or
351 .IR vbox .
352 .TP
353 .BI -translate-file \ tcxname
354 Use the
355 .I tcxname
356 translation table to set the mapping of input characters and
357 re-mapping of output characters.
358 .TP
359 .BI -default-translate-file \ tcxname
360 Like
361 .B -translate-file
362 except that a
363 .I %&
364 line can overrule this setting.
365 .TP
366 .B -version
367 Print version information and exit.
368 .\"=====================================================================
369 .SH ENVIRONMENT
370 See the Kpathsearch library documentation (the `Path specifications'
371 node) for precise details of how the environment variables are used.
372 The
373 .B kpsewhich
374 utility can be used to query the values of the variables.
375 .PP
376 One caveat: In most \*(TX formats, you cannot use ~ in a filename you
377 give directly to \*(TX, because ~ is an active character, and hence is
378 expanded, not taken as part of the filename. Other programs, such as
379 \*(MF, do not have this problem.
380 .PP
381 .TP
382 .B TEXMFOUTPUT
383 Normally, \*(TX puts its output files in the current directory. If
384 any output file cannot be opened there, it tries to open it in the
385 directory specified in the environment variable TEXMFOUTPUT.
386 There is no default value for that variable. For example, if you say
387 .I tex paper
388 and the current directory is not writable, if TEXMFOUTPUT has
389 the value
390 .IR /tmp ,
391 \*(TX attempts to create
392 .I /tmp/paper.log
393 (and
394 .IR /tmp/paper.dvi ,
395 if any output is produced.) TEXMFOUTPUT is also checked for input
396 files, as \*(TX often generates files that need to be subsequently
397 read; for input, no suffixes (such as ``.tex'') are added by default,
398 the input name is simply checked as given.
399 .TP
400 .B TEXINPUTS
401 Search path for
402 .I \einput
403 and
404 .I \eopenin
405 files.
406 This probably start with ``.'', so
407 that user files are found before system files. An empty path
408 component will be replaced with the paths defined in the
409 .I texmf.cnf
410 file. For example, set TEXINPUTS to ".:/home/user/tex:" to prepend the
411 current directory and ``/home/user/tex'' to the standard search path.
412 .TP
413 .B TEXFORMATS
414 Search path for format files.
415 .TP
416 .B TEXPOOL
417 search path for
418 .B tex
419 internal strings.
420 .TP
421 .B TEXEDIT
422 Command template for switching to editor. The default, usually
423 .BR vi ,
424 is set when \*(TX is compiled.
425 .TP
426 .B TFMFONTS
427 Search path for font metric
428 .RI ( .tfm )
429 files.
430 .\"=====================================================================
431 .SH FILES
432 The location of the files mentioned below varies from system to
433 system. Use the
434 .B kpsewhich
435 utility to find their locations.
436 .TP
437 .I texmf.cnf
438 Configuration file. This contains definitions of search paths as well
439 as other configuration parameters like
440 .BR parse_first_line .
441 .TP
442 .I tex.pool
443 Text file containing \*(TX's internal strings.
444 .TP
445 .I texfonts.map
446 Filename mapping definitions.
447 .TP
448 .I *.tfm
449 Metric files for \*(TX's fonts.
450 .TP
451 .I *.fmt
452 Predigested \*(TX format (.\|fmt) files.
453 .TP
454 .I $TEXMFMAIN/tex/plain/base/plain.tex
455 The basic macro package described in the \*(OXbook.
456 .br
457 .\"=====================================================================
458 .SH NOTES
459 This manual page is not meant to be exhaustive. The complete
460 documentation for this version of \*(TX can be found in the info manual
461 .IR "Web2C: A TeX implementation" .
462 .\"=====================================================================
463 .SH BUGS
464 This version of \*(TX implements a number of optional extensions.
465 In fact, many of these extensions conflict to a greater or lesser
466 extent with the definition of \*(TX. When such extensions are
467 enabled, the banner printed when \*(TX starts is changed to print
468 .B TeXk
469 instead of
470 .BR TeX .
471 .PP
472 This version of \*(TX fails to trap arithmetic overflow when
473 dimensions are added or subtracted. Cases where this occurs are rare,
474 but when it does the generated
475 .I DVI
476 file will be invalid.
477 .\"=====================================================================
478 .SH "SEE ALSO"
479 .BR mf (1),
480 .br
481 Donald E. Knuth,
482 .IR "The \*(OXbook" ,
483 Addison-Wesley, 1986, ISBN 0-201-13447-0.
484 .br
485 Leslie Lamport,
486 .IR "\*(LX \- A Document Preparation System" ,
487 Addison-Wesley, 1985, ISBN 0-201-15790-X.
488 .br
489 K. Berry,
490 .IR "Eplain: Expanded plain \*(TX" ,
491 ftp://ftp.cs.umb.edu/pub/tex/eplain/doc.
492 .br
493 Michael Spivak,
494 .IR "The Joy of \*(OX" ,
495 2nd edition, Addison-Wesley, 1990, ISBN 0-8218-2997-1.
496 .br
497 .I TUGboat
498 (the journal of the \*(TX Users Group).
499 .\"=====================================================================
500 .SH TRIVIA
501 \*(TX, pronounced properly, rhymes with ``blecchhh.'' The proper
502 spelling in typewriter-like fonts is ``TeX'' and not ``TEX'' or ``tex.''
503 .\"=====================================================================
504 .SH AUTHORS
505 \*(TX was created by Donald E. Knuth,
506 who implemented it using his \*(WB system for Pascal programs.
507 It was ported to Unix at Stanford by Howard Trickey, and
508 at Cornell by Pavel Curtis.
509 The version now offered with the Unix \*(TX distribution is that
510 generated by the \*(WB to C system
511 .RB ( web2c ),
512 originally written by Tomas Rokicki and Tim Morgan.
513 .PP
514 The enc\*(TX extensions were written by Petr Olsak.