Overview
Run the TeX typesetter on file[.tex], usually creating file.dvi. If the file argument has no extension, ".tex" will be appended to it.
The normal usage is to run
to process paper.tex with TeX. The name paper will be the so-called "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 be written to paper.log, and the output file will be paper.dvi. The --jobname option sets the jobname explicitly.
TeX formats the interspersed text and commands contained in the input and outputs a so-called DVI file, which is short for DeV ice Independent. DVI files are a device-independent binary representation of the pages in the output document. They can be displayed online (e.g., xdvi(1)), translated to PDF (dvipdfmx(1)), PostScript (dvips(1)), or otherwise manipulated. Other engines (pdftex(1), luatex(1)), descendants of original TeX, can output PDF directly.
TeX's capabilities and language are described in many places (see the references), including Donald Knuth's original book, The TeXbook. TeX is normally used with a large body of precompiled macros, called a format. Knuth's original format is named plain. Other formats, notably latex(1), are much larger, but still implemented entirely as TeX macros.
Command line processing
To process the command line, after first reading any option(s) (listed below), if the first non-option argument does not begin with an escape character (normally a backslash), TeX internally prepends \input to the non-option arguments. Whether the \input was prepended or not, TeX then processes the text as normal TeX input, including macro expansion.
With no non-option arguments, TeX gives you a ** interactive prompt; whatever text you enter is processed in exactly the same way as non-option command line arguments.
Examples:
- tex foo
-
executes "\input foo".
- tex foo bar
-
executes "\input foo bar", which inputs foo.tex and then typesets the string "bar".
- tex \\end
-
executes \end; here the double backslash is one common way of escaping the backslash for the shell. TeX must see only one backslash.
To reiterate, the text of an input filename, as well as any text following a filename, is subject to TeX's macro expansion. As a result, a ~ character is normally not usable within a filename, since ~ is conventionally defined to be an active character that expands into several primitive tokens, which can't be part of a filename. You can usually use \string~ to get a literal ~ character. More on input filenames: https://tug.org/texinfohtml/web2c.html#Input-filenames
Format (.fmt) selection
With an argument &format, TeX reads the set of precompiled commands contained in the (binary) file format.fmt instead of the default tex.fmt (searched for using the TEXFORMATS path; see environment section below). This is sometimes more convenient than the -fmt format option, which is equivalent.
The TeX implementation in TeX Live (a.k.a. Web2C) looks at its command line to find the name it was invoked as. When called as initex (or when the -ini option is given, which is equivalent) it can be used to precompile macros into a .fmt file. When called as virtex it will use the plain format. Nowadays, if either or both of the executables initex and virtex exist, they are symbolic links to the tex executable; the virtex symlink is not made by default in TeX Live.
When invoked as any other name, TeX will use that name as the name of the format to use. Most notably, when invoked as tex the format file tex.fmt is read, which is identical to the plain format. The commands defined by the plain format are described in Appendix B of The TeXbook, among other places (see references below). The other TeX engines follow the same convention; for example, the latex command is a symlink to the pdftex binary, and reads latex.fmt.
This implementation of TeX can look in the first line of the file paper.tex to see if it begins with the magic two-character sequence %&. If the first line begins with %&format -translate-file tcxname then TeX will use the named format and (if specified) translation 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 controls whether this behavior is enabled. It is disabled for the original TeX, and enabled for all other engines.
Input encodings
TeX, predating Unicode as it does, reads input byte by byte, and has no native recognition for UTF-8 or any other encoding. This is also the case for pdfTeX. However, to a large extent, UTF-8 can be parsed at the TeX macro level, and packages have been developed for this. For native recognition of Unicode, the engines luatex(1) and xetex(1) are available, with corresponding formats.
Error handling
TeX's error messages can be rather unfortunately cryptic. As general advice, sometimes only the first error matters, so it's worth trying to fix that first. Cutting down the input file can be helpful if mysteries remain. For more advice, including on a few specific problems: https://texfaq.org/index#errors
A convenient file in most distributions 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; responding "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).
When TeX reports an error, by default it puts you into an interactive dialog with a ? prompt. Responding with another ? shows you the available responses, for example, x quits immediately. The e response to TeX's error prompt causes the system default editor to start up at the current line of the current 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" indicating where the decimal line number (if any) goes. For example, a TEXEDIT string specifying emacs to be run can be set like this (in Bourne shell syntax):
-
TEXEDIT="emacs +%d %s"; export TEXEDIT
To debug problems with finding files, see the --kpathsea-debug option below.