This is Info file web2c.info, produced by Makeinfo version 1.68 from
the input file web2c.texi.
INFO-DIR-SECTION TeX
START-INFO-DIR-ENTRY
* Web2c: (web2c). TeX, Metafont, and companion programs.
* bibtex: (web2c)bibtex invocation. Maintaining bibliographies.
* dmp: (web2c)dmp invocation. Troff->MPX (MetaPost pictures).
* dvicopy: (web2c)dvicopy invocation. Virtual font expansion
* dvitomp: (web2c)dvitomp invocation. DVI to MPX (MetaPost pictures).
* dvitype: (web2c)dvitype invocation. DVI to human-readable text.
* gftodvi: (web2c)gftodvi invocation. Generic font proofsheets.
* gftopk: (web2c)gftopk invocation. Generic to packed fonts.
* gftype: (web2c)gftype invocation. GF to human-readable text.
* inimf: (web2c)inimf invocation. Initial Metafont.
* inimpost: (web2c)inimpost invocation. Initial MetaPost.
* initex: (web2c)initex invocation. Initial TeX.
* makempx: (web2c)makempx invocation. MetaPost label typesetting.
* mf: (web2c)mf invocation. Creating typeface families.
* mft: (web2c)mft invocation. Prettyprinting Metafont source.
* mltex: (web2c)MLTeX. Multi-lingual TeX.
* mpost: (web2c)mpost invocation. Creating technical diagrams.
* mpto: (web2c)mpto invocation. MetaPost label extraction.
* newer: (web2c)newer invocation. Compare modification times.
* patgen: (web2c)patgen invocation. Creating hyphenation patterns.
* pktogf: (web2c)pktogf invocation. Packed to generic fonts.
* pktype: (web2c)pktype invocation. PK to human-readable text.
* pltotf: (web2c)pltotf invocation. Property list to TFM.
* pooltype: (web2c)pooltype invocation. Display WEB pool files.
* tangle: (web2c)tangle invocation. WEB to Pascal.
* tex: (web2c)tex invocation. Typesetting.
* tftopl: (web2c)tftopl invocation. TFM -> property list.
* vftovp: (web2c)vftovp invocation. Virtual font -> virtual pl.
* virmf: (web2c)virmf invocation. Virgin Metafont.
* virmpost: (web2c)virmpost invocation. Virgin MetaPost.
* virtex: (web2c)virtex invocation. Virgin TeX.
* vptovf: (web2c)vptovf invocation. Virtual pl -> virtual font.
* weave: (web2c)weave invocation. WEB to TeX.
END-INFO-DIR-ENTRY
This file documents the installation and use of the programs in Web2c,
an implementation of Donald Knuth's TeX system.
Copyright (C) 1996, 97 K. Berry & O. Weber.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation
File: web2c.info, Node: Top, Next: Introduction, Up: (dir)
Web2c
*****
This document describes how to install and use the programs in the
Web2c implementation of the TeX system, especially for Unix systems. It
corresponds to Web2c version 7.2, released in November 1997.
* Menu:
* Introduction:: A brief introduction.
* Installation:: How to compile and install Web2c.
* Commonalities:: Option syntax, standard options, memory dumps.
* TeX:: Typesetting.
* Metafont:: Typeface design.
* MetaPost:: Technical illustrations.
* BibTeX:: Reusable bibliographies.
* WEB:: Literate programming.
* DVI utilities:: DVI expansion.
* Font utilities:: Font format conversion.
* Legalisms:: Blah blah blah.
* References:: Books and such.
* Index:: General index.
File: web2c.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
Introduction
************
This manual corresponds to version 7.2 of Web2c, released in
November 1997.
"Web2c" is the name of a TeX implementation, originally for Unix, but
now also running under DOS, Amiga, and other operating systems. By "TeX
implementation", we mean all of the standard programs developed by the
Stanford TeX project directed by Donald E. Knuth: Metafont, DVItype,
GFtoDVI, BibTeX, Tangle, etc., as well as TeX itself. Other programs
are also included: DVIcopy, written by Peter Breitenlohner, MetaPost
and its utilities (derived from Metafont), by John Hobby, etc.
General strategy: Web2c works, as its name implies, by translating the
WEB source in which TeX is written into C source code. Its output is
not self-contained, however; it makes extensive use of many macros and
functions in a library (the `web2c/lib' directory in the sources).
Therefore, it will not work without change on an arbitrary WEB program.
Availability: All of Web2c is freely available--"free" both in the
sense of no cost (free ice cream) and of having the source code to
modify and/or redistribute (free speech). (*Note unixtex.ftp:
(kpathsea)unixtex.ftp, for the practical details of how to obtain
Web2c.) Different parts of the Web2c distribution have different
licensing terms, however, reflecting the different circumstances of
their creation; consult each source file for exact details. The main
practical implication for redistributors of Web2c is that the
executables are covered by the GNU Public License, and therefore anyone
who gets a binary distribution must also get the sources, as explained
by the terms of the GPL (*note Copying: (kpathsea)Copying.). The GPL
covers the Web2c executables, including `tex', because the Free
Software Foundation sponsored the initial development of the Kpathsea
library that Web2c uses. The basic source files from Stanford, however,
have their own copyright terms or are in the public domain, and are not
covered by the GPL.
History: Tomas Rokicki originated the TeX-to-C system in 1987,
working from the first change files for TeX under Unix, which were done
primarily by Howard Trickey and Pavel Curtis. Tim Morgan then took over
development and maintenance for a number of years; the name changed to
Web-to-C somewhere in there. In 1990, Karl Berry became the
maintainer. He made many changes to the original sources, and started
using the shorter name Web2c. In 1997, Olaf Weber took over. Dozens of
other people have contributed; their names are listed in the
`ChangeLog' files.
Other acknowledgements: The University of Massachusetts at Boston
(particularly Rick Martin and Bob Morris) has provided computers and ftp
access to me for many years. Richard Stallman at the Free Software
Foundation employed me while I wrote the original path searching library
(for the GNU font utilities). (rms also gave us Emacs, GDB, and GCC,
without which I cannot imagine developing Web2c.) And, of course, TeX
would not exist in the first place without Donald E. Knuth.
Further reading: *Note References::.
File: web2c.info, Node: Installation, Next: Commonalities, Prev: Introduction, Up: Top
Installation
************
(A copy of this chapter is in the distribution file `web2c/INSTALL'.)
Installing Web2c is mostly the same as installing any other
Kpathsea-using program. Therefore, for the basic steps involved, see
*Note Installation: (kpathsea)Installation. (A copy is in the file
`kpathsea/INSTALL'.)
One peculiarity to Web2c is that the source distribution comes in two
files: `web.tar.gz' and `web2c.tar.gz'. You must retrieve and unpack
them both. (We have two because the former archive contains the very
large and seldom-changing original WEB source files.) *Note
unixtex.ftp: (kpathsea)unixtex.ftp.
Another peculiarity is the MetaPost program. Although it has been
installed previously as `mp', as of Web2c 7.0 the installed name is now
`mpost', to avoid conflict with the `mp' program that does
prettyprinting. This approach was recommended by the MetaPost author,
John Hobby. If you as the TeX administrator wish to make it available
under its shorter name as well, you will have to set up a link or some
such yourself. And of course individual users can do the same.
For solutions to common installation problems and information on how
to report a bug, see the file `kpathsea/BUGS' (*note Bugs:
(kpathsea)Bugs.). See also the Web2c home page,
`http://www.tug.org/web2c'.
Points worth repeating:
* Before starting the standard compilation and installation you must
install the basic fonts, macros, and other library files. *Note
Installation: (kpathsea)Installation.
* If you do not wish to use the standard file locations, see *Note
Changing search paths: (kpathsea)Changing search paths.
* Some Web2c features are enabled or disabled at `configure' time,
as described in the first section below.
* Menu:
* configure options:: Especially -with and -enable.
* Compile-time options:: Unusual -D's.
* Additional targets:: Breaking down the task.
* Triptrap:: Running the torture tests.
* Runtime options:: Array sizes and the like.
File: web2c.info, Node: configure options, Next: Compile-time options, Up: Installation
`configure' options
===================
This section gives pointers to descriptions of the `--with' and
`--enable' `configure' arguments that Web2c accepts. Some are specific
to Web2c, others are generic to all Kpathsea-using programs.
For a list of all the options `configure' accepts, run `configure
--help'. The generic options are listed first, and the
package-specific options come last.
For a description of the generic options (which mainly allow you to
specify installation directories) and basic `configure' usage, see
*Note Running `configure' scripts: (autoconf)Invoking configure, a copy
is in the file `kpathsea/CONFIGURE'.
`--disable-dump-share'
Do not make fmt/base/mem files sharable across different endian
architectures. *Note Hardware and memory dumps::.
`--without-maketexmf-default'
`--without-maketexpk-default'
`--without-maketextfm-default'
`--with-maketextex-default'
Enable or disable the dynamic generation programs. *Note mktex
configuration: (kpathsea)mktex configuration. The defaults are
the inverse of the options, i.e., everything is enabled except
`mktextex'.
`--enable-auto-core'
Dump `core' if the input file is
`HackyInputFileNameForCoreDump.tex'. *Note Preloaded
executables::.
`--enable-shared'
Build Kpathsea as a shared library. *Note Shared library:
(kpathsea)Shared library.
`--with-editor=CMD'
Change the default editor invoked by the `e' interactive command.
*Note Editor invocation::.
`--with-epsfwin'
`--with-hp2627win'
`--with-mftalkwin'
`--with-nextwin'
`--with-regiswin'
`--with-suntoolswin'
`--with-tektronixwin'
`--with-unitermwin'
`--with-x'
`--with-x-toolkit=KIT'
`--with-x11win'
`--with-x11'
Define Metafont graphics support; by default, no graphics support
is enabled. *Note Online Metafont graphics::.
`--x-includes=DIR'
`--x-libraries=DIR'
Define the locations of the X11 include files and libraries; by
default, `configure' does its best to guess). *Note Optional
Features: (autoconf)Optional Features. A copy is in
`kpathsea/CONFIGURE'.
File: web2c.info, Node: Compile-time options, Next: Additional targets, Prev: configure options, Up: Installation
Compile-time options
====================
In addition to the `configure' options listed in the previous
section, there are a few things that can be affected at compile-time
with C definitions, rather than with `configure'. Using any of these
is unusual.
To specify extra compiler flags (`-DNAME' in this case), the simplest
thing to do is:
make XCFLAGS="CCOPTIONS"
You can also set the `CFLAGS' environment variable before running
`configure'. *Note configure environment: (kpathsea)configure
environment.
Anyway, here are the possibilities:
`-DFIXPT'
`-DNO_MF_ASM'
Use the original WEB fixed-point routines for Metafont and MetaPost
arithmetic calculations regarding fractions. By default,
assembly-language routines are used on x86 hardware with GNU C
(unless `NO_MF_ASM' is defined), and floating-point routines are
used otherwise.
`-DIPC_DEBUG'
Report on various interprocess communication activities. *Note
IPC and TeX: IPC and TeX.
File: web2c.info, Node: Additional targets, Next: Triptrap, Prev: Compile-time options, Up: Installation
Additional targets
==================
Web2c has several Make targets besides the standard ones. You can
invoke these either in the top level directory of the source
distribution (the one containing `kpathsea/' and `web2c/'), or in the
`web2c/' directory.
`c-sources'
Make only the C files, translated from the Web sources, presumably
because you want to take them to a non-Unix machine.
`formats'
`install-formats'
Make or install all the memory dumps (*note Memory dumps::.). By
default, the standard plain formats plus `latex.fmt' are made. You
can add other formats by redefining the `fmts', `bases', and
`mems' variables. See the top of `web2c/Makefile' for the
possibilities.
`fmts'
`install-fmts'
Make or install the TeX `.fmt' files. *Note initex invocation::.
`bases'
`install-bases'
Make or install the Metafont `.base' files. *Note inimf
invocation::.
`mems'
`install-mems'
Make or install the MetaPost `.mem' files. *Note inimpost
invocation::.
`triptrap'
`trip'
`trap'
`mptrap'
To run the torture tests for TeX, Metafont, and MetaPost
(respectively). See the next section.
File: web2c.info, Node: Triptrap, Next: Runtime options, Prev: Additional targets, Up: Installation
Trip, trap, and mptrap: Torture tests
=====================================
To validate your TeX, Metafont, and MetaPost executables, run `make
triptrap'. This runs the trip, trap, and mptrap "torture tests". See
the files `triptrap/tripman.tex', `triptrap/trapman.tex', and
`triptrap/mptrap.readme' for detailed information and background on the
tests.
The differences between your executables' behavior and the standard
values will show up on your terminal. The usual differences (these are
all acceptable) are:
* string usage and table sizes;
* glue set ratios;
* `down4', `right4', and `y4' commands in DVItype output;
* dates and times.
Any other differences are trouble. The most common culprit in the past
has been compiler bugs, especially when optimizing. *Note TeX or
Metafont failing: (kpathsea)TeX or Metafont failing.
The files `trip.diffs', `mftrap.diffs', and `mptrap.diffs' in the
`triptrap' directory show the standard diffs against the original
output. If you diff your diffs against these files, you should come up
clean. For example
make trip >&mytrip.diffs
diff triptrap/trip.diffs mytrip.diffs
To run the tests separately, use the targets `trip', `trap', and
`mptrap'.
To run simple tests for all the programs as well as the torture tests,
run `make check'. You can compare the output to the distributed file
`tests/check.log' if you like.
File: web2c.info, Node: Runtime options, Prev: Triptrap, Up: Installation
Runtime options
===============
Besides the configure- and compile-time options described in the
previous sections, you can control a number of parameters (in
particular, array sizes) in the `texmf.cnf' runtime file read by
Kpathsea (*note Config files: (kpathsea)Config files.).
Rather than exhaustively listing them here, please see the last
section of the distributed `kpathsea/texmf.cnf'. Some of the more
interesting values:
`main_memory'
Total words of memory available, for TeX, Metafont, and MetaPost.
Must remake the format file after changing.
`extra_mem_bot'
Extra space for "large" TeX data structures: boxes, glue,
breakpoints, et al. If you use PiCTeX, you may well want to set
this.
`font_mem_size'
Words of font info available for TeX; this is approximately the
total size of all TFM files read.
`hash_extra'
Additional space for the hash table of control sequence names.
Approximately 10,000 control sequences can be stored in the main
hash table; if you have a large book with numerous
cross-references, this might not be enough, and thus you will want
to set `hash_extra'.
Of course, ideally all arrays would be dynamically expanded as
necessary, so the only limiting factor would be the amount of swap space
available. Unfortunately, implementing this is extremely difficult, as
the fixed size of arrays is assumed in many places throughout the source
code. These runtime limits are a practical compromise between the
compile-time limits in previous versions, and truly dynamic arrays. (On
the other hand, the Web2c BibTeX implementation does do dynamic
reallocation of some arrays.)
File: web2c.info, Node: Commonalities, Next: TeX, Prev: Installation, Up: Top
Commonalities
*************
Many aspects of the TeX system are the same among more than one
program, so we describe all those pieces together, here.
* Menu:
* Option conventions:: Order doesn't matter, - or -, = or ` ' for values.
* Common options:: -help -version -verbose, and TeX/MF/MP options.
* Path searching:: Features of the common path searching library.
* Output file location:: TEXMFOUTPUT allows output in places other than `.'.
* Three programs:: TeX, Metafont, and MetaPost have a lot in common.
File: web2c.info, Node: Option conventions, Next: Common options, Up: Commonalities
Option conventions
==================
To provide a clean and consistent behavior, we chose to have all these
programs use the GNU function `getopt_long_only' to parse command lines.
As a result, you can:
* give the options in any order, interspersed as you wish with
non-option arguments;
* use `-' or `--' to start an option name;
* use any unambiguous abbreviation for an option name;
* separate option names and values with either `=' or one or more
spaces;
* use filenames that would otherwise look like options by putting
them after an option `--'.
By convention, non-option arguments, if specified, generally define
the name of an input file, as documented for each program.
If a particular option with a value is given more than once, it is the
last value that counts.
For example, the following command line specifies the options `foo',
`bar', and `verbose'; gives the value `baz' to the `abc' option, and
the value `xyz' to the `quux' option; and specifies the filename
`-myfile-'.
-foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile-
File: web2c.info, Node: Common options, Next: Path searching, Prev: Option conventions, Up: Commonalities
Common options
==============
All of these programs accept the standard GNU `--help' and
`--version' options, and several programs accept `--verbose'. Rather
than writing identical descriptions in every node, they are described
here.
`--help'
Print a usage message listing basic usage and all available
options to standard output, then exit successfully.
`--verbose'
Print progress reports to standard output.
`--version'
Print the version number to standard output, then exit
successfully.
TeX, Metafont, and MetaPost have additional options in common:
`-kpathsea-debug=NUMBER'
Set path searching debugging flags according to the bits of NUMBER
(*note Debugging: (kpathsea)Debugging.). You can also specify
this in `KPATHSEA_DEBUG' environment variable (for all Web2c
programs). (The command line value overrides.) The most useful
value is `-1', to get all available output.
`-ini'
Enable the "initial" form of the program (*note Initial and
virgin::.). This is implicitly set if the program name is `initex'
resp. `inimf' resp. `inimpost'.
`-interaction=STRING'
Set the interaction mode from the command line. The STRING must
be one of `batchmode', `nonstopmode', `scrollmode', or
`errorstopmode'.
`-fmt=DUMPNAME'
`-base=DUMPNAME'
`-mem=DUMPNAME'
Use DUMPNAME instead of the program name or a `%&' line to
determine the name of the memory dump file read (`fmt' for TeX,
`base' for Metafont, `mem' for MetaPost). *Note Memory dumps::.
Also set the program name to DUMPNAME. When creating a dump, this
option will also set the name of the dump file.
`-progname=STRING'
Set program (and memory dump) name to STRING. This may affect the
search paths and other values used (*note Config files:
(kpathsea)Config files.). Using this option is equivalent to
making a link named STRING to the binary and then invoking the
binary under that name. *Note Memory dumps::.
File: web2c.info, Node: Path searching, Next: Output file location, Prev: Common options, Up: Commonalities
Path searching
==============
All of the Web2c programs, including TeX, which do path searching use
the Kpathsea routines to do so. The precise names of the environment
and configuration file variables which get searched for particular file
formatted are therefore documented in the Kpathsea manual (*note
Supported file formats: (kpathsea)Supported file formats.). Reading
`texmf.cnf' (*note Config files: (kpathsea)Config files.), invoking
`mktex...' scripts (*note mktex scripts: (kpathsea)mktex scripts.), and
so on are all handled by Kpathsea.
The programs which read fonts make use of another Kpathsea feature:
`texfonts.map', which allows arbitrary aliases for the actual names of
font files; for example, `Times-Roman' for `ptmr8r.tfm'. The
distributed (and installed by default) `texfonts.map' includes aliases
for many widely available PostScript fonts by their PostScript names.
File: web2c.info, Node: Output file location, Next: Three programs, Prev: Path searching, Up: Commonalities
Output file location
====================
All the programs generally follow the usual convention for output
files. Namely, they are placed in the directory current when the
program is run, regardless of any input file location; or, in a few
cases, output is to standard output.
For example, if you run `tex /tmp/foo', for example, the output will
be in `./foo.dvi' and `./foo.log', not `/tmp/foo.dvi' and
`/tmp/foo.log'.
However, if the current directory is not writable, the main programs
(TeX, Metafont, MetaPost, and BibTeX) make an exception: if the
environment variable or config file value `TEXMFOUTPUT' is set (it is
not by default), output files are written to the directory specified.
This is useful when you are in some read-only distribution directory,
perhaps on a CD-ROM, and want to TeX some documentation, for example.
File: web2c.info, Node: Three programs, Prev: Output file location, Up: Commonalities
Three programs: Metafont, MetaPost, and TeX
===========================================
TeX, Metafont, and MetaPost have a number of features in common.
Besides the ones here, the common command-line options are described in
the previous section. The configuration file options that let you
control some array sizes and other features are described in *Note
Runtime options::.
* Menu:
* Initial and virgin:: Making memory dumps vs. production runs.
* Memory dumps:: .fmt/.base/.mem files for fast startup.
* Editor invocation:: The `e' response at errors.
* \input filenames:: ~ and $ expansion in TeX/MF/MP.
File: web2c.info, Node: Initial and virgin, Next: Memory dumps, Up: Three programs
Initial and virgin
------------------
The TeX, Metafont, and MetaPost programs each have two main variants,
called initial and virgin. As of Web2c 7, one executable suffices for
both variants.
The initial form is enabled if:
1. the `-ini' option was specified; or
2. the program name is `initex' resp. `inimf' resp. `inimpost'; or
3. the first line of the main input file is `%&ini';
otherwise, the virgin form is used.
The "virgin" form is the one generally invoked for production use.
The first thing it does is read a memory dump (*note Determining the
memory dump to use::.), and then proceeds on with the main job.
The "initial" form is generally used only to create memory dumps (see
the next section). It starts up more slowly than the virgin form,
because it must do lengthy initializations that are encapsulated in the
memory dump file.
In the past, there was a third form, "preloaded" executables. This
is no longer recommended or widely used; but see the section below if
you're interested anyway. In this case, the memory dump file was read
in to the virgin form, a core dump of the running executable was done,
and the `undump' program run to create a new binary. Nowadays, reading
memory dumps is fast enough that this is generally no longer worth the
cost in disk space and unshared executables.
* Menu:
* Preloaded executables::
File: web2c.info, Node: Preloaded executables, Up: Initial and virgin
Preloaded executables
.....................
Specifying `--enable-auto-core' to `configure' tells TeX, Metafont,
and MetaPost to suicide with a `SIGQUIT' on an input filename of
`HackyInputFileNameForCoreDump.tex' (all three programs use the `.tex'
suffix). This produces a memory dump of the running executable in a
file `core'. (This is unrelated to the standard memory dump feature in
these programs; *note Memory dumps::.).
You don't actually need to do this to produce a core dump. Just
typing your quit character (usually <CTRL-\>) when the program is
waiting for input (at `**') will have the same result. But a few sites
want to reliably generate a core dump without human intervention; that's
what `--enable-auto-core' is for.
With the program `undump', you can use `core' to reconstitute a
"preloaded" executable, which does not need to read a `.fmt' file to
get started. Although preloaded executables save startup time, they
have a big disadvantage: neither the disk space to store them nor their
code segments (at runtime) can be shared. Therefore, if both `tex' and
`latex' are running, twice as much memory will be consumed, to the
general detriment of performance.
The `undump' program is not part of the Web2c distribution, but you
can get it from the CTAN archives as `CTAN:/support/undump', and it is
included in several TeX distributions (*note unixtex.ftp:
(kpathsea)unixtex.ftp.).
File: web2c.info, Node: Memory dumps, Next: Editor invocation, Prev: Initial and virgin, Up: Three programs
Memory dumps
------------
In typical use, TeX, Metafont, and MetaPost require a large number of
macros to be predefined; therefore, they support "memory dump" files,
which can be read much more efficiently than ordinary source code.
* Menu:
* Creating memory dumps::
* Determining the memory dump to use::
* Hardware and memory dumps::
File: web2c.info, Node: Creating memory dumps, Next: Determining the memory dump to use, Up: Memory dumps
Creating memory dumps
.....................
The programs all create memory dumps in slightly idiosyncratic
(thought substantially similar) way, so we describe the details in
separate sections (references below). The basic idea is to run the
initial version of the program (*note Initial and virgin::.), read the
source file to define the macros, and then execute the `\dump'
primitive.
Also, each program uses a different filename extension for its memory
dumps, since although they are completely analogous they are not
interchangeable (TeX cannot read a Metafont memory dump, for example).
Here is a list of filename extensions with references to examples of
creating memory dumps:
TeX
(`.fmt') *Note initex invocation::.
Metafont
(`.base') *Note inimf invocation::.
MetaPost
(`.mem') *Note inimpost invocation::.
When making memory dumps, the programs read environment variables and
configuration files for path searching and other values as usual. If
you are making a new installation and have environment variables
pointing to an old one, for example, you will probably run into
difficulties.
File: web2c.info, Node: Determining the memory dump to use, Next: Hardware and memory dumps, Prev: Creating memory dumps, Up: Memory dumps
Determining the memory dump to use
..................................
The virgin form (*note Initial and virgin::.) of each program always
reads a memory dump before processing normal source input. All three
programs determine the memory dump to use in the same way:
1. If the first non-option command-line argument begins with `&', the
program uses the remainder of that argument as the memory dump
name. For example, running `tex \&super' reads `super.fmt'. (The
backslash protects the `&' against interpretation by the shell.)
2. If the `-fmt' resp. `-base' resp. `-mem' option is specified, its
value is used.
3. If the `-progname' option is specified, its value is used.
4. If the first line of the main input file (which must be specified
on the command line, not in response to `**') is `%&DUMP', and
DUMP is an existing memory dump of the appropriate type, DUMP is
used. As a special case, `%&ini' means the initial form of the
program (*note Initial and virgin::.).
5. Otherwise, the program uses the program invocation name, most
commonly `tex' resp. `mf' resp. `mpost'. For example, if `latex'
is a link to `tex', and the user runs `latex foo', `latex.fmt'
will be used.
File: web2c.info, Node: Hardware and memory dumps, Prev: Determining the memory dump to use, Up: Memory dumps
Hardware and memory dumps
.........................
By default, memory dump files are generally sharable between
architectures of different types; specifically, on machines of different
endianness (*note Byte order: (libc)Byte order.). (This is a feature
of the Web2c implementation, and is not true of all TeX
implementations.) If you specify `--disable-dump-share' to
`configure', however, memory dumps will be endian-dependent.
The reason to do this is speed. To achieve endian-independence, the
reading of memory dumps on LittleEndian architectures, such as PC's and
DEC architectures, is somewhat slowed (all the multibyte values have to
be swapped). Usually, this is not noticeable, and the advantage of
being able to share memory dumps across all platforms at a site far
outweighs the speed loss. But if you're installing Web2c for use on
LittleEndian machines only, perhaps on a PC being used only by you, you
may wish to get maximum speed.
TeXnically, even without `--disable-dump-share', sharing of `.fmt'
files cannot be guaranteed to work. Floating-point values are always
written in native format, and hence will generally not be readable
across platforms. Fortunately, TeX uses floating point only to
represent glue ratios, and all common formats (plain, LaTeX, AMSTeX,
...) do not do any glue setting at `.fmt'-creation time. Metafont and
MetaPost do not use floating point in any dumped value at all.
Incidentally, different memory dump files will never compare equal
byte-for-byte, because the program always dumps the current date and
time. So don't be alarmed by just a few bytes difference.
If you don't know what endianness your machine is, and you're curious,
here is a little C program to tell you. (The `configure' script
contains a similar program.) This is from the book `C: A Reference
Manual', by Samuel P. Harbison and Guy L. Steele Jr. (*note
References::.).
main ()
{
/* Are we little or big endian? From Harbison&Steele. */
union
{
long l;
char c[sizeof (long)];
} u;
u.l = 1;
if (u.c[0] == 1)
printf ("LittleEndian\n");
else if (u.c[sizeof (long) - 1] == 1)
printf ("BigEndian\n");
else
printf ("unknownEndian");
exit (u.c[sizeof (long) - 1] == 1);
}
File: web2c.info, Node: Editor invocation, Next: \input filenames, Prev: Memory dumps, Up: Three programs
Editor invocation
-----------------
TeX, Metafont, and MetaPost all (by default) stop and ask for user
intervention at an error. If the user responds with `e' or `E', the
program invokes an editor.
Specifying `--with-editor=CMD' to `configure' sets the default editor
command string to CMD. The environment variables/configuration values
`TEXEDIT', `MFEDIT', and `MPEDIT' (respectively) override this. If
`--with-editor' is not specified, the default is `vi +%d %s'.
In this string, `%d' is replaced by the line number of the error, and
`%s' is replaced by the name of the current input file.
File: web2c.info, Node: \input filenames, Prev: Editor invocation, Up: Three programs
`\input' filenames
------------------
TeX, Metafont, and MetaPost source programs can all read other source
files with the `\input' (TeX) and `input' (MF and MP) primitives:
\input NAME % in TeX
The file NAME can always be terminated with whitespace; for Metafont
and MetaPost, the statement terminator `;' also works. (LaTeX and
other macro packages provide other interfaces to `\input' that allow
different notation; here we are concerned only with the primitive
operation.) This means that `\input' filenames cannot directly contain
whitespace, even though Unix has no trouble. Sorry.
On the other hand, various C library routines and Unix itself use the
null byte (character code zero, ASCII NUL) to terminate strings. So
filenames in Web2c cannot contain nulls, even though TeX itself does
not treat NUL specially.
Furthermore, some older Unix variants do not allow eight-bit
characters (codes 128-255) in filenames.
For maximal portability of your document across systems, use only the
characters `a'-`z', `0'-`9', and `.', and restrict your filenames to at
most eight characters (not including the extension), and at most a
three-character extension. Do not use anything but simple filenames,
since directory separators vary among systems; instead, add the
necessary directories to the appropriate search path.
Finally, the present Web2c implementation does `~' and `$' expansion
on NAME, unlike Knuth's original implementation and older versions of
Web2c. Thus:
\input ~jsmith/$foo.bar
will dereference the environment variable or Kpathsea config file
value `foo' and read that file extended with `.bar' in user `jsmith''s
home directory. (You can also use braces, as in `${foo}bar' if you
want to follow the variable name with a letter, numeral, or `_'.)
(So you could define an environment variable value including
whitespace and get the program to read such a filename that way, if you
need to.)
In all the common TeX formats (plain TeX, LaTeX, AMSTeX), the
characters `~' and `~' have special category codes, so to actually use
these in a document you have to change their catcodes or use `\string'.
(The result is unportable anyway, see the suggestions above.) The
place where they are most likely to be useful is when typing
interactively.
File: web2c.info, Node: TeX, Next: Metafont, Prev: Commonalities, Up: Top
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' (*note
References::.). Many other books on TeX, introductory and otherwise,
are available.
* Menu:
* 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.
File: web2c.info, Node: tex invocation, Next: initex invocation, Up: TeX
`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' (*note References::.).
TeX, Metafont, and MetaPost process the command line (described here)
and determine their memory dump (fmt) file in the same way (*note
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 (*note
Supported file formats: (kpathsea)Supported file formats.), 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
(*note Introduction: (dvipsk)Top.) 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 (*note mktex configuration:
(kpathsea)mktex configuration.). 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' (*note Common options::.):
`-kpathsea-debug=NUMBER'
`-ini'
`-fmt=FMTNAME'
`-progname=STRING'
These options are common to TeX, Metafont, and MetaPost. *Note
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. *Note IPC and
TeX: 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' (*note Initial and virgin::.), enable MLTeX extensions
such as `\charsubdef'. Implicitly set if the program name is
`mltex'. *Note MLTeX: MLTeX.
`-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'.)
File: web2c.info, Node: initex invocation, Next: virtex invocation, Prev: tex invocation, Up: TeX
`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 (*note Memory dumps::.). For a
detailed comparison of virgin and initial forms, *note Initial and
virgin::..
For a list of options and other information, *note 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, *note 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. *Note Formats::, for more details
on TeX formats.
File: web2c.info, Node: virtex invocation, Next: Formats, Prev: initex invocation, Up: TeX
`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, *note Initial and virgin::..
For a list of options and other information, see *Note tex
invocation::.
File: web2c.info, Node: Formats, Next: Languages and hyphenation, Prev: virtex invocation, Up: TeX
Formats
=======
TeX "formats" are large collections of macros, possibly dumped into a
`.fmt' file (*note Memory dumps::.) by `initex' (*note 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, *note
unixtex.ftp: (kpathsea)unixtex.ftp.). 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.
File: web2c.info, Node: Languages and hyphenation, Next: IPC and TeX, Prev: Formats, Up: TeX
Languages and hyphenation
=========================
TeX supports most natural languages. See also *Note TeX extensions:
TeX extensions.
* Menu:
* MLTeX:: Multi-lingual TeX.
* patgen invocation:: Creating hyphenation patterns.
File: web2c.info, Node: MLTeX, Next: patgen invocation, Up: Languages and hyphenation
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.
* Menu:
* \charsubdef:: Character substitution definitions.
* \tracingcharsubdef:: Tracing substitutions.
File: web2c.info, Node: \charsubdef, Next: \tracingcharsubdef, Up: MLTeX
`\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.)
File: web2c.info, Node: \tracingcharsubdef, Prev: \charsubdef, Up: MLTeX
`\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.
File: web2c.info, Node: patgen invocation, Prev: MLTeX, Up: Languages and hyphenation
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 (*note References::.), and also the `patgen.web' source file.
The only options are `-help' and `-version' (*note Common options::.).
File: web2c.info, Node: IPC and TeX, Next: TeX extensions, Prev: Languages and hyphenation, Up: TeX
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 (*note
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.
|
