Go to the first, previous, next, last section, table of contents.

# 4. TeX: Typesetting

TeX is a typesetting system: it was especially designed to handle complex mathematics, as well as most ordinary text typesetting.

TeX is a batch language, like C or Pascal, and not an interactive "word processor": you compile a TeX input file into a corresponding device-independent (DVI) file (and then translate the DVI file to the commands for a particular output device). This approach has both considerable disadvantages and considerable advantages. For a complete description of the TeX language, see The TeXbook (see section B. References). Many other books on TeX, introductory and otherwise, are available.

- tex invocation: Invoking TeX.
- initex invocation: Initial TeX.
- virtex invocation: Virgin TeX.
- Formats: Major TeX macro packages.
- Languages and hyphenation: TeX supports many human languages.
- IPC and TeX: DVI output to a socket.
- TeX extensions: Changes to the TeX language.

## 4.1 `tex` invocation

TeX (usually invoked as `tex`) formats the given text and commands, and outputs a corresponding device-independent representation of the typeset document. This section merely describes the options available in the Web2c implementation. For a complete description of the TeX typesetting language, see The TeXbook (see section B. References).

TeX, Metafont, and MetaPost process the command line (described here) and determine their memory dump (fmt) file in the same way (see section 3.5.2 Memory dumps). Synopses:

    tex [option]... [texname[.tex]] [tex-commands]
    tex [option]... \first-line
    tex [option]... &fmt args

TeX searches the usual places for the main input file texname (see section `Supported file formats' in Kpathsea), extending texname with ``.tex'` if necessary. To see all the relevant paths, set the environment variable `KPATHSEA_DEBUG` to ``-1'` before running the program.

After texname is read, TeX processes any remaining tex-commands on the command line as regular TeX input. Also, if the first non-option argument begins with a TeX escape character (usually `\`), TeX processes all non-option command-line arguments as a line of regular TeX input.

If no arguments or options are specified, TeX prompts for an input file name with ``**'`.

TeX writes the main DVI output to the file ``basetexname.dvi'`, where basetexname is the basename of texname, or ``texput'` if no input file was specified. A DVI file is a device-independent binary representation of your TeX document. The idea is that after running TeX, you translate the DVI file using a separate program to the commands for a particular output device, such as a PostScript printer (see section `Introduction' in Dvips) or an X Window System display (see xdvi(1)).

TeX also reads TFM files for any fonts you load in your document with the `\font` primitive. By default, it runs an external program named ``mktextfm'` to create any nonexistent TFM files. You can disable this at configure-time or runtime (see section `mktex configuration' in Kpathsea). This is enabled mostly for the sake of the EC fonts, which can be generated at any size.

TeX can write output files, via the `\openout` primitive; this opens a security hole vulnerable to Trojan horse attack: an unwitting user could run a TeX program that overwrites, say, ``~/.rhosts'`. (MetaPost has a `write` primitive with similar implications). To alleviate this, there is a configuration variable `openout_any`, which selects one of three levels of security. When it is set to ``a'` (for "any"), no restrictions are imposed. When it is set to ``r'` (for "restricted"), filenames beginning with ``.'` are disallowed (except ``.tex'` because LaTeX needs it). When it is set to ``p'` (for "paranoid") additional restrictions are imposed: an absolute filename must refer to a file in (a subdirectory) of `TEXMFOUTPUT`, and any attempt to go up a directory level is forbidden (that is, paths may not contain a ``..'` component). The paranoid setting is the default. (For backwards compatibility, ``y'` and ``1'` are synonyms of ``a'`, while ``n'` and ``0'` are synonyms for ``r'`.)

In any case, all `\openout` filenames are recorded in the log file, except those opened on the first line of input, which is processed when the log file has not yet been opened. (If you as a TeX administrator wish to implement more stringent rules on `\openout`, modifying the function `openoutnameok` in ``web2c/lib/texmfmp.c'` is intended to suffice.)

The program accepts the following options, as well as the standard ``-help'` and ``-version'` (see section 3.2 Common options):

``-kpathsea-debug=number'`
``-ini'`
``-fmt=fmtname'`
``-progname=string'`
``-translate-file=tcxfile'`
  These options are common to TeX, Metafont, and MetaPost. See section 3.2 Common options.
``-ipc'`
``-ipc-start'`
  With either option, TeX writes its DVI output to a socket as well as to the usual ``.dvi'` file. With ``-ipc-start'`, TeX also opens a server program at the other end to read the output. See section 4.6 IPC and TeX. These options are available only if the ``--enable-ipc'` option was specified to `configure` during installation of Web2c.
``-mktex=filetype'`
``-no-mktex=filetype'`
  Turn on or off the ``mktex'` script associated with filetype. The only values that make sense for filetype are ``tex'` and ``tfm'`,
``-mltex'`
  If `INITEX` (see section 3.5.1 Initial and virgin), enable MLTeX extensions such as `\charsubdef`. Implicitly set if the program name is `mltex`. See section 4.5.1 MLTeX: Multi-lingual TeX.
``-output-comment=string'`
  Use string as the DVI file comment. Ordinarily, this comment records the date and time of the TeX run, but if you are doing regression testing, you may not want the DVI file to have this spurious difference. This is also taken from the environment variable and config file value ``output_comment'`.
``-shell-escape'`
  Enable the ``\write18{shell-command}'` feature. This is also enabled if the environment variable or config file value ``shell_escape'` is set to ``t'`. (For backwards compatibility, ``y'` and ``1'` are accepted as synonyms of ``t'`). It is disabled by default to avoid security problems. When enabled, the shell-command string (which first undergoes the usual TeX expansions, just as in ``\special'`) is passed to the command shell (via the C library function ``system'`). The output of shell-command is not diverted anywhere, so it will not appear in the log file. The system call either happens at ``\output'` time or right away, according to the absence or presence of the ``\immediate'` prefix, as usual for `\write`. (If you as a TeX administrator wish to implement more stringent rules on what can be executed, you will need to modify ``tex.ch'`.)
``-src-specials'`
``-src-specials=string'`
  This option makes TeX output specific source information using ``\special'` commands in the DVI file. These ``\special'` track the current file name and line number. Using the first form of this option, the ``\special'` are inserted automatically. In the second form of the option, string is a comma separated list of the following values: ``cr'`, ``display'`, ``hbox'`, ``math'`, ``par'`, ``parend'`, ``vbox'`. You can use this list to specify where you want TeX to output such commands. By example, ``-src-specials=cr,math'` will output source information every line and every math formula. These commands can be used with the appropriate DVI viewer and text editor to switch from the current position in the editor to the same position in the viewer and back from the viewer to the editor. Note that this option works by inserting ``\special'` commands into the token stream, and that these additional tokens can in principle be recovered by the right macros. If you run across a case, let us know, because this counts as a bug. However, these bugs are very hard to fix without making significant changes to TeX, so please don't count on them being fixed. Redefining ``\special'` will not affect the functioning of this option. The commands we insert into the token stream have been hard-coded to always be the ``\special'` primitive. Also note that TeX does not pass the trip test when this option is enabled.

## 4.2 `initex` invocation

`initex` is the "initial" form of TeX, which does lengthy initializations avoided by the "virgin" (`vir`) form, so as to be capable of dumping ``.fmt'` files (see section 3.5.2 Memory dumps). For a detailed comparison of virgin and initial forms, see section 3.5.1 Initial and virgin.

For a list of options and other information, see section 4.1 `tex` invocation.

Unlike Metafont and MetaPost, many format files are commonly used with TeX. The standard one implementing the features described in the TeXbook is ``plain.fmt'`, also known as ``tex.fmt'` (again, see section 3.5.2 Memory dumps). It is created by default during installation, but you can also do so by hand if necessary (e.g., if an update to ``plain.tex'` is issued):

    initex '\input plain \dump'

(The quotes prevent interpretation of the backslashes from the shell.) Then install the resulting ``plain.fmt'` in ``$(fmtdir)'` (``/usr/local/share/texmf/web2c'` by default), and link ``tex.fmt'` to it.

The necessary invocation for generating a format file differs for each format, so instructions that come with the format should explain. The top-level ``web2c'` Makefile has targets for making most common formats: `plain latex amstex texinfo eplain`. See section 4.4 Formats, for more details on TeX formats.

## 4.3 `virtex` invocation

`virtex` is the "virgin" form of TeX, which avoids the lengthy initializations done by the "initial" (`ini`) form, and is thus what is generally used for production work. For a detailed comparison of virgin and initial forms, see section 3.5.1 Initial and virgin.

For a list of options and other information, see section 4.1 `tex` invocation.

## 4.4 Formats

TeX formats are large collections of macros, possibly dumped into a ``.fmt'` file (see section 3.5.2 Memory dumps) by `initex` (see section 4.2 `initex` invocation). A number of formats are in reasonably widespread use, and the Web2c Makefile has targets to make the versions current at the time of release. You can change which formats are automatically built by setting the `fmts` Make variable; by default, only the ``plain'` and ``latex'` formats are made.

You can get the latest versions of most of these formats from the CTAN archives in subdirectories of ``CTAN:/macros'` (for CTAN info, see section `unixtex.ftp' in Kpathsea). The archive ftp://ftp.tug.org/tex/lib.tar.gz (also available from CTAN) contains most of these formats (although perhaps not the absolute latest version), among other things.

`latex`
  The most widely used format. The current release is named `LaTeX 2e'; new versions are released approximately every six months, with patches issued as needed. The old release was called `LaTeX 2.09', and is no longer maintained or supported. LaTeX attempts to provide generic markup instructions, such as "emphasize", instead of specific typesetting instructions, such as "use the 10pt Computer Modern italic font".
`amstex`
  The official typesetting system of the American Mathematical Society, used to produce nearly all of its publications, e.g., Mathematical Reviews. Like LaTeX, it encourages generic markup commands. The AMS also provides a LaTeX package for authors who prefer LaTeX (see the ``amslatex'` item below).
`texinfo`
  The documentation system developed and maintained by the Free Software Foundation for their software manuals. It can be automatically converted into plain text, a machine-readable on-line format called `info', HTML, etc.
`eplain`
  The "expanded plain" format provides various common features (e.g., symbolic cross-referencing, tables of contents, indexing, citations using BibTeX), for those authors who prefer to handle their own high-level formatting.
`lamstex`
  Augments AMSTeX with LaTeX-like features.
`amslatex`
  An LaTeX package (see ``latex'` item above), that augments LaTeX with AMSTeX-like features.
`slitex`
  An obsolete LaTeX 2.09 format for making slides. It is replaced by the ``slides'` document class.

## 4.5 Languages and hyphenation

TeX supports most natural languages. See also section 4.7 TeX extensions.

- MLTeX: Multi-lingual TeX.
- patgen invocation: Creating hyphenation patterns.
- TCX files: Support for different character sets & fonts.

### 4.5.1 MLTeX: Multi-lingual TeX

Multi-lingual TeX (`mltex`) is an extension of TeX originally written by Michael Ferguson and now updated and maintained by Bernd Raichle. It allows the use of non-existing glyphs in a font by declaring glyph substitutions. These are restricted to substitutions of an accented character glyph, which need not be defined in the current font, by its appropriate `\accent` construction using a base and accent character glyph, which do have to exist in the current font. This substitution is automatically done behind the scenes, if necessary, and thus MLTeX additionally supports hyphenation of words containing an accented character glyph for fonts missing this glyph (e.g., Computer Modern). Standard TeX suppresses hyphenation in this case.

MLTeX works at ``.fmt'`-creation time: the basic idea is to specify the ``-mltex'` option to TeX when you `\dump` a format. Then, when you subsequently invoke TeX and read that `.fmt` file, the MLTeX features described below will be enabled.

Generally, you use special macro files to create an MLTeX `.fmt` file. See:

    CTAN:/systems/generic/mltex
    ftp://ftp.univ-rennes1.fr/pub/GUTenberg/french/

The sections below describe the two new primitives that MLTeX defines. Aside from these, MLTeX is completely compatible with standard TeX.

- \charsubdef: Character substitution definitions.
- \tracingcharsubdef: Tracing substitutions.

#### 4.5.1.1 `\charsubdef`: Character substitutions

The most important primitive MLTeX adds is `\charsubdef`, used in a way reminiscent of `\chardef`:

    \charsubdef composite [=] accent base

Each of composite, accent, and base are font glyph numbers, expressed in the usual TeX syntax: ``\e` symbolically, `'145` for octal, `"65` for hex, `101` for decimal.

MLTeX's `\charsubdef` declares how to construct an accented character glyph (not necessarily existing in the current font) using two character glyphs (that do exist). Thus it defines whether a character glyph code, either typed as a single character or using the `\char` primitive, will be mapped to a font glyph or to an `\accent` glyph construction.

For example, if you assume glyph code 138 (decimal) for an e-circumflex and you are using the Computer Modern fonts, which have the circumflex accent in position 18 and lowercase `e' in the usual ASCII position 101 decimal, you would use `\charsubdef` as follows:

    \charsubdef 138 = 18 101

For the plain TeX format to make use of this substitution, you have to redefine the circumflex accent macro `\^` in such a way that if its argument is character `e' the expansion `\char138` is used instead of `\accent18 e`. Similar `\charsubdef` declaration and macro redefinitions have to be done for all other accented characters.

To disable a previous `\charsubdef c`, redefine c as a pair of zeros. For example:

    \charsubdef '321 = 0 0  % disable N tilde

(Octal `'321` is the ISO Latin-1 value for the Spanish N tilde.)

`\charsubdef` commands should only be given once. Although in principle you can use `\charsubdef` at any time, the result is unspecified. If `\charsubdef` declarations are changed, usually either incorrect character dimensions will be used or MLTeX will output missing character warnings. (The substitution of a `\charsubdef` is used by TeX when appending the character node to the current horizontal list, to compute the width of a horizontal box when the box gets packed, and when building the `\accent` construction at `\shipout`-time. In summary, the substitution is accessed often, so changing it is not desirable, nor generally useful.)

#### 4.5.1.2 `\tracingcharsubdef`: Substitution diagnostics

To help diagnose problems with ``\charsubdef'`, MLTeX provides a new primitive parameter, `\tracingcharsubdef`. If positive, every use of `\charsubdef` will be reported. This can help track down when a character is redefined.

In addition, if the TeX parameter `\tracinglostchars` is 100 or more, the character substitutions actually performed at `\shipout`-time will be recorded.

### 4.5.2 TCX files: Character translations

TCX (TeX character translation) files help TeX support direct input of 8-bit international characters if fonts containing those characters are being used. Specifically, they map an input (keyboard) character code to the internal TeX character code (a superset of ASCII).

Of the various proposals for handling more than one input encoding, TCX files were chosen because they follow Knuth's original ideas for the use of the ``xhcr'` and ``xord'` tables. He ventured that these would be changed in the WEB source in order to adjust the actual version to a given environment. It turned out, however, that recompiling the WEB sources is not as simple task as Knuth predicted; therefore, TCX files, providing the possibility of changing of the conversion tables on on-the-fly, has been implemented instead.

This approach limits the portability of TeX documents, as some implementations do not support it (or use a different method for input-internal reencoding). It may also be problematic to determine the encoding to use for a TeX document of unknown provenance; in the worst case, failure to do so correctly may result in subtle errors in the typeset output.

While TCX files can be used with any format, using them breaks the LaTeX ``inputenc'` package. This is why you should either use tcxfile or ``inputenc'` in LaTeX files, but never both.

This is entirely independent of the MLTeX extension (see section 4.5.1 MLTeX: Multi-lingual TeX): whereas a TCX file defines how an input keyboard character is mapped to TeX's internal code, MLTeX defines substitutions for a non-existing character glyph in a font with a `\accent` construction made out of two separate character glyphs. TCX files involve no new primitives; it is not possible to specify that an input (keyboard) character maps to more than one character.

Specifying TCX files:

- You can specify a TCX file to be used for a particular TeX run by specifying the command-line option ``-translate-file=tcxfile'` or (preferably) specifying it explicitly in the first line of the main document ``%& -translate-file=tcxfile'`.
- TCX files are searched for along the `WEB2C` path.
- `INITEX` ignores TCX files.

The Web2c distribution comes with at least two TCX files, ``il1-t1.tcx'` and ``il2-t1.tcx'`. These support ISO Latin 1 and ISO Latin 2, respectively, with Cork-encoded fonts (a.k.a. the T1 encoding). TCX files for Czech, Polish, and Slovak are also provided.

Syntax of TCX files:

1. Line-oriented. Blank lines are ignored.
2. Whitespace is ignored except as a separator.
3. Comments start with ``%'` and continue to the end of the line.
4. Otherwise, a line consists of one or two character codes:

       src [dest]

5. Each character code may be specified in octal with a leading ``0'`, hexadecimal with a leading ``0x'`, or decimal otherwise. Values must be between 0 and 255, inclusive (decimal).
6. If the dest code is not specified, it is taken to be the same as src.
7. If the same src code is specified more than once, it is the last definition that counts.

Finally, here's what happens: when TeX sees an input character with code src, it 1) changes src to dest; and 2) makes code the dest "printable", i.e., printed as-is in diagnostics and the log file instead of in ``^^'` notation.

By default, no characters are translated, and character codes between 32 and 126 inclusive (decimal) are printable. It is not possible to make these (or any) characters unprintable.

Specifying translations for the printable ASCII characters (codes 32--127) will yield unpredictable results. Additionally you shouldn't make the following characters printable: `^^I` (TAB), `^^J` (line feed), `^^M` (carriage return), and `^^?` (delete), since TeX uses them in various ways.

Thus, the idea is to specify the input (keyboard) character code for src, and the output (font) character code for dest.

### 4.5.3 Patgen: Creating hyphenation patterns

Patgen creates hyphenation patterns from dictionary files for use with TeX. Synopsis:

    patgen dictionary patterns output translate

Each argument is a filename. No path searching is done. The output is written to the file output.

In addition, Patgen prompts interactively for other values.

For more information, see Word hy-phen-a-tion by com-puter by Frank Liang (see section B. References), and also the ``patgen.web'` source file.

The only options are ``-help'` and ``-version'` (see section 3.2 Common options).

## 4.6 IPC and TeX

(Sorry, but I'm not going to write this unless someone actually uses this feature. Let me know.)

This functionality is available only if the ``--enable-ipc'` option was specified to `configure` during installation of Web2c (see section 2. Installation).

If you define `IPC_DEBUG` before compilation (e.g., with ``make XCFLAGS=-DIPC_DEBUG'`), TeX will print messages to standard error about its socket operations. This may be helpful if you are, well, debugging.

## 4.7 TeX extensions

The base TeX program has been extended in many ways. Here's a partial list. Please send information on extensions not listed here to the address in section `Reporting bugs' in Kpathsea.

e-TeX
  Adds many new primitives, including right-to-left typesetting. Available from http://www.vms.rhbnc.ac.uk/e-TeX/ and ``CTAN:/systems/e-tex'`.
Omega
  Adds Unicode support, right-to-left typesetting, and more. Available from http://www.ens.fr/omega and ``CTAN:/systems/omega'`.
pdfTeX
  A variant of TeX that produces PDF instead of DVI files. It also includes primitives for hypertext. Available from ``CTAN:/systems/pdftex'`.
``TeX--XeT'`
  Adds primitives and DVI opcodes for right-to-left typesetting (as used in Arabic, for example). An old version for TeX 3.1415 is available from ``CTAN:/systems/knuth/tex--xet'`. A newer version is included in e-TeX.
File-handling TeX
  Adds primitives for creating multiple DVI files in a single run; and appending to output files as well as overwriting. Web2c implementation available in the distribution file ``web2c/contrib/file-handling-tex'`.

Go to the first, previous, next, last section, table of contents.