1TEX(1)                      General Commands Manual                     TEX(1)
2
3
4

NAME

6       tex, initex - text formatting and typesetting
7

SYNOPSIS

9       tex [options] [&format] [file|\commands]
10

DESCRIPTION

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
19       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
26       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
37       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
44       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
55       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
65       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
73       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

OPTIONS

80       This version of TeX understands the following command line options.
81
82       -cnf-line string
83              Parse  string as a texmf.cnf configuration line.  See the Kpath‐
84              sea manual.
85
86       -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
90       -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
94       -no-file-line-error
95              Disable printing error messages in the file:line:error style.
96
97       -file-line-error-style
98              This is the old name of the -file-line-error option.
99
100       -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
104       -halt-on-error
105              Exit with an error code when an error is encountered during pro‐
106              cessing.
107
108       -help  Print help message and exit.
109
110       -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
114       -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
119       -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
122       -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
126       -jobname name
127              Use  name for the job name, instead of deriving it from the name
128              of the input file.
129
130       -kpathsea-debug bitmask
131              Sets path searching debugging flags according  to  the  bitmask.
132              See the Kpathsea manual for details.
133
134       -mktex fmt
135              Enable mktexfmt, where fmt must be either tex or tfm.
136
137       -mltex Enable  MLTeX  extensions.   Only  effective in combination with
138              -ini.
139
140       -no-mktex fmt
141              Disable mktexfmt, where fmt must be either tex or tfm.
142
143       -output-comment string
144              Use string for the DVI file comment instead of the date.
145
146       -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
152       -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
156       -no-parse-first-line
157              Disable parsing of the first line of the main input file.
158
159       -progname name
160              Pretend to be program name.  This affects both the  format  used
161              and the search paths.
162
163       -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
167       -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
172       -no-shell-escape
173              Disable the \write18{command} construct, even if it  is  enabled
174              in the texmf.cnf file.
175
176       -src-specials
177              Insert source specials into the DVI file.
178
179       -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
184       -translate-file tcxname
185              Use  the  tcxname  translation table to set the mapping of input
186              characters and re-mapping of output characters.
187
188       -default-translate-file tcxname
189              Like -translate-file except that a %&  line  can  overrule  this
190              setting.
191
192       -version
193              Print version information and exit.
194

ENVIRONMENT

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
200       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
205       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
218       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
226       TEXFORMATS
227              Search path for format files.
228
229       TEXPOOL
230              search path for tex internal strings.
231
232       TEXEDIT
233              Command  template for switching to editor.  The default, usually
234              vi, is set when TeX is compiled.
235
236       TFMFONTS
237              Search path for font metric (.tfm) files.
238

FILES

240       The location of the files mentioned below varies from system to system.
241       Use the kpsewhich utility to find their locations.
242
243       texmf.cnf
244              Configuration  file.   This contains definitions of search paths
245              as well as other configuration parameters like parse_first_line.
246
247       tex.pool
248              Text file containing TeX's internal strings.
249
250       texfonts.map
251              Filename mapping definitions.
252
253       *.tfm  Metric files for TeX's fonts.
254
255       *.fmt  Predigested TeX format (.fmt) files.
256
257       $TEXMFMAIN/tex/plain/base/plain.tex
258              The basic macro package described in the TeXbook.
259

NOTES

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

BUGS

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
271       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

SEE ALSO

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

TRIVIA

286       TeX,  pronounced properly, rhymes with ``blecchhh.''  The proper spell‐
287       ing in typewriter-like fonts is ``TeX'' and not ``TEX'' or ``tex.''
288

AUTHORS

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
296       The encTeX extensions were written by Petr Olsak.
297
298
299
300Web2C 2023                       6 August 2019                          TEX(1)
Impressum