1TEX(1) General Commands Manual TEX(1)
2
6 tex, initex - text formatting and typesetting
7
9 tex [options] [&format] [file|\commands]
10
12 Run the TeX typesetter on file, usually creating file.dvi. If the file
13 argument has no extension, ".tex" will be appended to it. Instead of a
14 filename, a set of TeX commands can be given, the first of which must
15 start with a backslash. With a &format argument TeX uses a different
16 set of precompiled commands, contained in format.fmt; it is usually
17 better to use the -fmt format option instead.
18 TeX formats the interspersed text and commands contained in the named
20 files and outputs a typesetter independent file (called DVI, which is
21 short for DeVice Independent). TeX's capabilities and language are de‐
22 scribed in The TeXbook. TeX is normally used with a large body of pre‐
23 compiled macros, and there are several specific formatting systems,
24 such as LaTeX, which require the support of several macro files.
25 This version of TeX looks at its command line to see what name it was
27 called under. If they exist, then both initex and virtex are symbolic
28 links to the tex executable. When called as initex (or when the -ini
29 option is given) it can be used to precompile macros into a .fmt file.
30 When called as virtex it will use the plain format. When called under
31 any other name, TeX will use that name as the name of the format to
32 use. For example, when called as tex the tex format is used, which is
33 identical to the plain format. The commands defined by the plain for‐
34 mat are documented in The TeXbook. Other formats that are often avail‐
35 able include latex and amstex.
36 The non-option command line arguments to the TeX program are passed to
38 it as the first input line. (But it is often easier to type extended
39 arguments as the first input line, since UNIX shells tend to gobble up
40 or misinterpret TeX's favorite symbols, like backslashes, unless you
41 quote them.) As described in The TeXbook, that first line should begin
42 with a filename, a \controlsequence, or a &formatname.
43 The normal usage is to say
45 tex paper
46 to start processing paper.tex. The name paper will be the ``jobname'',
47 and is used in forming output filenames. If TeX doesn't get a filename
48 in the first line, the jobname is texput. When looking for a file, TeX
49 looks for the name with and without the default extension (.tex) ap‐
50 pended, unless the name already contains that extension. If paper is
51 the ``jobname'', a log of error messages, with rather more detail than
52 normally appears on the screen, will appear in paper.log, and the out‐
53 put file will be in paper.dvi.
54 This version of TeX can look in the first line of the file paper.tex to
56 see if it begins with the magic sequence %&. If the first line begins
57 with %&format -translate-file tcxname then TeX will use the named for‐
58 mat and translation table tcxname to process the source file. Either
59 the format name or the -translate-file specification may be omitted,
60 but not both. This overrides the format selection based on the name by
61 which the program is invoked. The -parse-first-line option or the
62 parse_first_line configuration variable controls whether this behaviour
63 is enabled.
64 The e response to TeX's error prompt causes the system default editor
66 to start up at the current line of the current file. The environment
67 variable TEXEDIT can be used to change the editor used. It may contain
68 a string with "%s" indicating where the filename goes and "%d" indicat‐
69 ing where the decimal line number (if any) goes. For example, a
70 TEXEDIT string for emacs can be set with the sh command
71 TEXEDIT="emacs +%d %s"; export TEXEDIT
72 A convenient file in the library is null.tex, containing nothing. When
74 TeX can't find a file it thinks you want to input, it keeps asking you
75 for another filename; responding `null' gets you out of the loop if you
76 don't want to input anything. You can also type your EOF character
77 (usually control-D).
78
80 This version of TeX understands the following command line options.
81 -cnf-line string
83 Parse string as a texmf.cnf configuration line. See the Kpath‐
84 sea manual.
85 -enc Enable the encTeX extensions. This option is only effective in
87 combination with -ini. For documentation of the encTeX exten‐
88 sions see http://www.olsak.net/enctex.html.
89 -file-line-error
91 Print error messages in the form file:line:error which is simi‐
92 lar to the way many compilers format them.
93 -no-file-line-error
95 Disable printing error messages in the file:line:error style.
96 -file-line-error-style
98 This is the old name of the -file-line-error option.
99 -fmt format
101 Use format as the name of the format to be used, instead of the
102 name by which TeX was called or a %& line.
103 -halt-on-error
105 Exit with an error code when an error is encountered during pro‐
106 cessing.
107 -help Print help message and exit.
109 -ini Start in INI mode, which is used to dump formats. The INI mode
111 can be used for typesetting, but no format is preloaded, and ba‐
112 sic initializations like setting catcodes may be required.
113 -interaction mode
115 Sets the interaction mode. The mode can be either batchmode,
116 nonstopmode, scrollmode, and errorstopmode. The meaning of
117 these modes is the same as that of the corresponding \commands.
118 -ipc Send DVI output to a socket as well as the usual output file.
120 Whether this option is available is the choice of the installer.
121 -ipc-start
123 As -ipc, and starts the server at the other end as well.
124 Whether this option is available is the choice of the installer.
125 -jobname name
127 Use name for the job name, instead of deriving it from the name
128 of the input file.
129 -kpathsea-debug bitmask
131 Sets path searching debugging flags according to the bitmask.
132 See the Kpathsea manual for details.
133 -mktex fmt
135 Enable mktexfmt, where fmt must be either tex or tfm.
136 -mltex Enable MLTeX extensions. Only effective in combination with
138 -ini.
139 -no-mktex fmt
141 Disable mktexfmt, where fmt must be either tex or tfm.
142 -output-comment string
144 Use string for the DVI file comment instead of the date.
145 -output-directory directory
147 Write output files in directory instead of the current direc‐
148 tory. Look up input files in directory first, then along the
149 normal search path. See also description of the TEXMFOUTPUT en‐
150 vironment variable.
151 -parse-first-line
153 If the first line of the main input file begins with %& parse it
154 to look for a dump name or a -translate-file option.
155 -no-parse-first-line
157 Disable parsing of the first line of the main input file.
158 -progname name
160 Pretend to be program name. This affects both the format used
161 and the search paths.
162 -recorder
164 Enable the filename recorder. This leaves a trace of the files
165 opened for input and output in a file with extension .fls.
166 -shell-escape
168 Enable the \write18{command} construct. The command can be any
169 shell command. This construct is normally disallowed for secu‐
170 rity reasons.
171 -no-shell-escape
173 Disable the \write18{command} construct, even if it is enabled
174 in the texmf.cnf file.
175 -src-specials
177 Insert source specials into the DVI file.
178 -src-specials where
180 Insert source specials in certain places of the DVI file. where
181 is a comma-separated value list: cr, display, hbox, math, par,
182 parent, or vbox.
183 -translate-file tcxname
185 Use the tcxname translation table to set the mapping of input
186 characters and re-mapping of output characters.
187 -default-translate-file tcxname
189 Like -translate-file except that a %& line can overrule this
190 setting.
191 -version
193 Print version information and exit.
194
196 See the Kpathsearch library documentation (the `Path specifications'
197 node) for precise details of how the environment variables are used.
198 The kpsewhich utility can be used to query the values of the variables.
199 One caveat: In most TeX formats, you cannot use ~ in a filename you
201 give directly to TeX, because ~ is an active character, and hence is
202 expanded, not taken as part of the filename. Other programs, such as
203 Metafont, do not have this problem.
204 TEXMFOUTPUT
206 Normally, TeX puts its output files in the current directory.
207 If any output file cannot be opened there, it tries to open it
208 in the directory specified in the environment variable TEXMFOUT‐
209 PUT. There is no default value for that variable. For example,
210 if you say tex paper and the current directory is not writable,
211 if TEXMFOUTPUT has the value /tmp, TeX attempts to create
212 /tmp/paper.log (and /tmp/paper.dvi, if any output is produced.)
213 TEXMFOUTPUT is also checked for input files, as TeX often gener‐
214 ates files that need to be subsequently read; for input, no suf‐
215 fixes (such as ``.tex'') are added by default, the input name is
216 simply checked as given.
217 TEXINPUTS
219 Search path for \input and \openin files. This should probably
220 start with ``.'', so that user files are found before system
221 files. An empty path component will be replaced with the paths
222 defined in the texmf.cnf file. For example, set TEXINPUTS to
223 ".:/home/user/tex:" to prepend the current directory and
224 ``/home/user/tex'' to the standard search path.
225 TEXFORMATS
227 Search path for format files.
228 TEXPOOL
230 search path for tex internal strings.
231 TEXEDIT
233 Command template for switching to editor. The default, usually
234 vi, is set when TeX is compiled.
235 TFMFONTS
237 Search path for font metric (.tfm) files.
238
240 The location of the files mentioned below varies from system to system.
241 Use the kpsewhich utility to find their locations.
242 texmf.cnf
244 Configuration file. This contains definitions of search paths
245 as well as other configuration parameters like parse_first_line.
246 tex.pool
248 Text file containing TeX's internal strings.
249 texfonts.map
251 Filename mapping definitions.
252 *.tfm Metric files for TeX's fonts.
254 *.fmt Predigested TeX format (.fmt) files.
256 $TEXMFMAIN/tex/plain/base/plain.tex
258 The basic macro package described in the TeXbook.
259
261 This manual page is not meant to be exhaustive. The complete documen‐
262 tation for this version of TeX can be found in the info manual Web2C: A
263 TeX implementation.
264
266 This version of TeX implements a number of optional extensions. In
267 fact, many of these extensions conflict to a greater or lesser extent
268 with the definition of TeX. When such extensions are enabled, the ban‐
269 ner printed when TeX starts is changed to print TeXk instead of TeX.
270 This version of TeX fails to trap arithmetic overflow when dimensions
272 are added or subtracted. Cases where this occurs are rare, but when it
273 does the generated DVI file will be invalid.
274
276 mf(1),
277 Donald E. Knuth, The TeXbook, Addison-Wesley, 1986, ISBN 0-201-13447-0.
278 Leslie Lamport, LaTeX - A Document Preparation System, Addison-Wesley,
279 1985, ISBN 0-201-15790-X.
280 K. Berry, Eplain: Expanded plain TeX, https://tug.org/eplain
281 Michael Spivak, The Joy of TeX, 2nd edition, Addison-Wesley, 1990, ISBN
282 0-8218-2997-1.
283 TUGboat (the journal of the TeX Users Group). https://tug.org/TUGboat
284
286 TeX, pronounced properly, rhymes with ``blecchhh.'' The proper spell‐
287 ing in typewriter-like fonts is ``TeX'' and not ``TEX'' or ``tex.''
288
290 TeX was created by Donald E. Knuth, who implemented it using his Web
291 system for Pascal programs. It was ported to Unix at Stanford by
292 Howard Trickey, and at Cornell by Pavel Curtis. The version now of‐
293 fered with the Unix TeX distribution is that generated by the Web to C
294 system (web2c), originally written by Tomas Rokicki and Tim Morgan.
295 The encTeX extensions were written by Petr Olsak.
297Web2C 2023 6 August 2019 TEX(1)