TEX(1)TEX(1)NAME
tex, virtex, initex - text formatting and typesetting
SYNOPSIStex [options] [commands]
DESCRIPTION
This manual page is not meant to be exhaustive. The com-
plete documentation for this version of TeX can be found
in the info file or manual Web2C: A TeX implementation.
TeX formats the interspersed text and commands contained
in the named files and outputs a typesetter independent
file (called DVI, which is short for DeVice Independent).
TeX's capabilities and language are described in The TeX-
book. TeX is normally used with a large body of precom-
piled macros, and there are several specific formatting
systems, such as LaTeX, which require the support of sev-
eral macro files.
This version of TeX looks at its command line to see what
name it was called under. Both initex and virtex are sym-
links to the tex executable. When called as initex (or
when the --ini option is given) it can be used to precom-
pile macros into a .fmt file. When called as virtex it
will use the plain format. When called under any other
name, TeX will use that name as the name of the format to
use. For example, when called as tex the tex format is
used, which is identical to the plain format. The com-
mands defined by the plain format are documented in The
TeXbook. Other formats that are often available include
latex and amstex.
The commands given on the command line to the TeX program
are passed to it as the first input line. (But it is
often easier to type extended arguments as the first input
line, since UNIX shells tend to gobble up or misinterpret
TeX's favorite symbols, like backslashes, unless you quote
them.) As described in The TeXbook, that first line
should begin with a filename, a \controlsequence, or a
&formatname.
The normal usage is to say
tex paper
to start processing paper.tex. The name paper will be the
``jobname'', and is used in forming output filenames. If
TeX doesn't get a filename in the first line, the jobname
is texput. When looking for a file, TeX looks for the
name with and without the default extension (.tex)
appended, unless the name already contains that extension.
If paper is the ``jobname'', a log of error messages, with
rather more detail than normally appears on the screen,
will appear in paper.log, and the output file will be in
paper.dvi.
This version of TeX can look in the first line of the file
paper.tex to see if it begins with the magic sequence %&.
If the first line begins with %&format --translate-
file tcxname then TeX will use the named format and tran-
sation table tcxname to process the source file. Either
the format name or the --translate-file specification may
be omitted, but not both. This overrides the format
selection based on the name by which the program is
invoked. The --parse-first-line option or the
parse_first_line configuration variable control whether
this behaviour is enabled.
The e response to TeX's error prompt causes the system
default editor to start up at the current line of the cur-
rent file. The environment variable TEXEDIT can be used
to change the editor used. It may contain a string with
"%s" indicating where the filename goes and "%d" indicat-
ing where the decimal line number (if any) goes. For
example, a TEXEDIT string for emacs can be set with the sh
command
TEXEDIT="emacs +%d %s"; export TEXEDIT
A convenient file in the library is null.tex, containing
nothing. When TeX can't find a file it thinks you want to
input, it keeps asking you for another filename; respond-
ing `null' gets you out of the loop if you don't want to
input anything. You can also type your EOF character
(usually control-D).
OPTIONS
This version of TeX understands the following command line
options.
--file-line-error-style
Print error messages in the form file:line:error
which is similar to the way many compilers format
them.
--fmt format
Use format as the name of the format to be used,
instead of the name by which TeX was called or a %&
line.
--help Print help message and exit.
--ini Be initex, for dumping formats; this is implicitly
true if the program is called as initex.
--interaction mode
Sets the interaction mode. The mode can be one of
batchmode, nonstopmode, scrollmode, and errorstop-
mode. The meaning of these modes is the same as
that of the corresponding \commands.
--ipc Send DVI output to a socket as well as the usual
output file. Whether this option is available is
the choice of the installer.
--ipc-start
As --ipc, and starts the server at the other end as
well. Whether this option is available is the
choice of the installer.
--jobname name
Use name for the job name, instead of deriving it
from the name of the input file.
--kpathsea-debug bitmask
Sets path searching debugging flags according to
the bitmask. See the Kpathsea manual for details.
--maketex fmt
Enable mktexfmt, where fmt must be one of tex or
tfm.
--mltex
Enable MLTeX extensions.
--no-maketex fmt
Disable mktexfmt, where fmt must be one of tex or
tfm.
--output-comment string
Use string for the DVI file comment instead of the
date.
--parse-first-line
If the first line of the main input file begins
with %& parse it to look for a dump name or a
--translate-file option.
--progname name
Pretend to be program name. This affects both the
format used and the search paths.
--recorder
Enable the filename recorder. This leaves a trace
of the files opened for input and output in a file
with extension .fls.
--shell-escape
Enable the \write18{command} construct. The com-
mand can be any Bourne shell command. This con-
struct is normally disallowed for security reasons.
--translate-file tcxname
Use the tcxname translation table.
--version
Print version information and exit.
ENVIRONMENT
See the Kpathsearch library documentation (the `Path spec-
ifications' node) for precise details of how the environ-
ment variables are used. The kpsewhich utility can be
used to query the values of the variables.
One caveat: In most TeX formats, you cannot use ~ in a
filename you give directly to TeX, because ~ is an active
character, and hence is expanded, not taken as part of the
filename. Other programs, such as Metafont, do not have
this problem.
TEXMFOUTPUT
Normally, TeX puts its output files in the current
directory. If any output file cannot be opened
there, it tries to open it in the directory speci-
fied in the environment variable TEXMFOUTPUT.
There is no default value for that variable. For
example, if you say tex paper and the current
directory is not writable, if TEXMFOUTPUT has the
value /tmp, TeX attempts to create /tmp/paper.log
(and /tmp/paper.dvi, if any output is produced.)
TEXINPUTS
Search path for \input and \openin files. This
should probably start with ``.'', so that user
files are found before system files. An empty path
component will be replaced with the paths defined
in the texmf.cnf file. For example, set TEXINPUTS
to ".:/home/usr/tex:" to prepend the current
direcory and ``/home/user/tex'' to the standard
search path.
TEXEDIT
Command template for switching to editor. The
default, usually vi, is set when TeX is compiled.
FILES
The location of the files mentioned below varies from sys-
tem to system. Use the kpsewhich utility to find their
locations.
texmf.cnf
Configuration file. This contains definitions of
search paths as well as other configuration parame-
ters like parse_first_line.
tex.pool
Encoded text of TeX's messages.
texfonts.map
Filename mapping definitions.
*.tfm Metric files for TeX's fonts.
*.fmt Predigested TeX format (.fmt) files.
$TEXMFMAIN/tex/plain/base/plain.tex
The basic macro package described in the TeXbook.
BUGS
This version of TeX implements a number of optional exten-
sions. In fact, many of these extensions conflict to a
greater or lesser extent with the definition of TeX. When
such extensions are enabled, the banner printed when TeX
starts is changed to print TeXk instead of TeX.
This version of TeX fails to trap arithmetic overflow when
dimensions are added or subtracted. Cases where this
occurs are rare, but when it does the generated DVI file
will be invalid.
SEE ALSOmf(1),
Donald E. Knuth, The TeXbook, Addison-Wesley, 1986, ISBN
0-201-13447-0.
Leslie Lamport, LaTeX - A Document Preparation System,
Addison-Wesley, 1985, ISBN 0-201-15790-X.
K. Berry, Eplain: Expanded plain TeX,
ftp://ftp.cs.umb.edu/pub/tex/eplain/doc.
Michael Spivak, The Joy of TeX, 2nd edition, Addison-Wes-
ley, 1990, ISBN 0-8218-2997-1.
TUGboat (the journal of the TeX Users Group).
TRIVIA
TeX, pronounced properly, rhymes with ``blecchhh.'' The
proper spelling in typewriter-like fonts is ``TeX'' and
not ``TEX'' or ``tex.''
AUTHORS
TeX was designed by Donald E. Knuth, who implemented it
using his Web system for Pascal programs. It was ported
to Unix at Stanford by Howard Trickey, and at Cornell by
Pavel Curtis. The version now offered with the Unix TeX
distribution is that generated by the Web to C system
(web2c), originally written by Tomas Rokicki and Tim Mor-
gan.
Web2C 7.4.5 10 November 2001 TEX(1)