⟦a769766a1⟧

TextFile

This file describes web2c, a system which converts TeX, Metafont, and
other products of the Stanford TeX project to C.  (It is definitely not
a general-purpose Pascal-to-C translator.)

web2c is primarily the product of Tim Morgan <morgan@ics.uci.edu>.
Tomas Rokicki wrote the original TeX to C program.  Pierre Mackay
<mackay@cs.washington.edu> wrote the original change files for most
of the Metafontware programs.  Karl Berry <karl@cs.umb.edu> made everything
work with the new ``8-bit'' release, and is probably to blame for things
that don't work now, but used to.  And over a hundred more people
have contributed in other ways.

The file ./MACHINES contains a list of known configurations that have
passed the trip and trap test.  If your configuration is not on this
list, you should build triptex and trapmf (instructions below), and then
send mail to Karl with the vital statistics, and, of course, any changes
you made, preferably in the form of context diffs.

The file ./ChangeLog records changes to web2c.  The current version number
of web2c can be found at the beginning of that file.

The file ./PROJECTS describes some improvements to the current setup
that would be nice to have.

The file ./PROBLEMS describes various difficulties people have
encountered.  If you have trouble getting the distribution up, look here
first.

We try to keep web2c up-to-date with respect to the master versions of
the WEB files.  But we can't, always.  The web-*.tar.Z holds the
versions that we know to work with these change files.  If you get
different versions and encounter any problems, please write to us.

Here is a table of contents for the rest of this file:
   Bootstrapping tangle
   Installation
   Changing constants
   Preloading
   Online output from Metafont
   Portability


\f


Bootstrapping tangle
%%%%%%%%%%%%%%%%%%%%
If you have an already working tangle, you need do nothing special.
If you don't, the Makefile in web/ will attempt to compile a boostrap
version. This step can fail and go into a loop. If this happens you
need to fix the problem manually. Possible problems and remedies:

tangle fails tangling tangle.web
	tangle.ch may not match tangle.web; get the correct versions.

tangleboot.c or tanglext.c does not compile
	Make C sources acceptable to your compiler and retry.

Shell cannot find tangle, current directory not in search path
	Add . to search path or edit web/Makefile to invoke
	./tangle on tangle.web.

\f


Installation
%%%%%%%%%%%%
Here is the procedure for getting things running.

1. Edit ./site.h and ./Makefile to set up your local paths, compiler, etc.
   The symbols BSD and SYSV affect the conversion from WEB to C, not
   just the compilation of the C files.  Therefore, you must recompile
   web2c if you change the definition of these symbols.  (The Makefile 
   does that automatically if you change site.h, but you should be aware
   of this, anyway.)  If you move ./site.h to another directory (i.e.,
   change SITEDIR in Makefile), move ./defaults.h there, also.
2. `make triptrap' to build triptex and trapmf (and some of the other 
   programs that are needed to run the tests).
3. `make run-triptrap' to run the tests.  The differences (and many
   error messages) will show up on your terminal.  If you have a
   question about whether the differences are OK or not, consult the
   trip/trap manuals.
4. `make clean-triptrap' to get rid of those programs and output.  You
   need to do this before making the working versions.
5. `make' to make the working versions of every program in this
   hierarchy.  If you wish to make a `big' TeX or Metafont, now is the
   time to set up for it.  See below.
6. cd into `tex' and make the format files you want.
7. cd into `mf' and make the base files you want.  It is also a good
   idea to try to draw something online (if you intend to support that),
   before installing Metafont, as this often fails to work right on the
   first try.  See the `Running Metafont' chapter in the Metafontbook.
8. TeX uses the name it was invoked as the name of the format file to
   read.  Therefore, you have set up links in two places:
   (1) In the binary directory, links to virtex named `latex', `slitex',
       `texinfo', or whatever versions of TeX you are going to provide.
   (2) In the format directory, a link to plain.fmt named `tex.fmt',
       and, if you like, a link to lplain.fmt named `latex.fmt', etc.
       The important thing is that a .fmt file with the same name as the
       binary exists.
   This goes for Metafont, too.
9. `make install' to do the obvious.  texware/pooltype and
   texware/patgen are not installed by default, since most sites would
   never want to run them.
10. `make clean' if you intend to compile the programs on another
   architecture.  Since the .c files are intended to be portable across
   architectures, they are not removed by this.
11. `make veryclean' when you're all done.  This removes everything that
   was not in the original distribution (and more besides).

If you wish to make just TeX or Metafont, the top-level Makefile has
targets named `TeX' and `MF' which make {ini,vir}{tex,mf}, and nothing
else.

web2c.yacc has one shift/reduce conflict, so expect that message.

Ordinarily, you don't need to ever `make' anything in subdirectories,
but only from the top-level directory.  If you ever do run `make' in a
subdirectory, you should be aware that they all define their own CC,
OPT, etc. -- and so you will probably want to change them.


\f


Changing constants
%%%%%%%%%%%%%%%%%%
The files tex/bigtex.diff and mf/bigmf.diff contain patches to build
versions of TeX and Metafont with much more memory, pool space, etc.
You should apply the patches before beginning to compile the programs.
The 32-bit TeX that results (all of this goes for Metafont, too) will
have a smaller text segment and run faster, because it doesn't have to
convert frequently between 16-bit and 32-bit integers.  It is therefore
a good idea to build such a TeX if possible.

You should also change the type |glue_ratio| in site.h from |float| to
|double| if you do this.

You can obtain the patch program (written by Larry Wall
<lwall@jpl-devvax.jpl.nasa.gov>) from a comp.sources.unix archive, or by
ftp from his machine.

You should first save the original c{tex,mf}.ch as ctex16.ch or some
such, because `make veryclean' removes files whose names end in ~, etc.,
which could wipe out the originals.
Then apply the patches by saying, e.g.,
% cd tex; patch < bigtex.diff


\f


Preloading
%%%%%%%%%%
It is possible to ``preload'' TeX (and Metafont), i.e., avoid reading
the .fmt file at runtime.  However, on most modern machines, you don't
gain a lot of startup time, and you lose a lot of disk space.
Furthermore, different flavors of TeX will not have their code segments
shared.  Therefore, it is probably best not to preload, unless, of
course, you try that and the response is horrible.

TeX uses the name it was invoked with to figure out what format file to
read.  Therefore, for each format file, you should create a link to the
virtex executable named the name of the format file.  For example:

% cd $(bindir)
% ln virtex tex
% ln virtex latex
% ln virtex texinfo

Then, when you invoke, say,
% texinfo

TeX looks for texinfo.fmt.

All of this goes for Metafont, too, as usual.

Here is some data collected by Ken Yap <ken@cs.rochester.edu> on a
Sun 3/60 running Sun Unix 3.4 on preloaded vs. non-preloaded, and also
16-bit vs. 32-bit.

    16 bit, unloaded:  42.1u 1.4s 0:50 86% 10+29k 72+17io 0pf+0w
    16 bit, preloaded: 41.7u 0.9s 0:46 90% 10+27k 4+17io 80pf+0w
    32 bit, unloaded:  42.4u 1.7s 0:47 92% 10+52k 95+17io 0pf+0w
    32 bit, preloaded: 41.6u 1.2s 0:48 88% 10+47k 5+17io 102pf+0w

    It is interesting that i/o is traded off with page faulting, as is to
    be expected. Also 32 bit unloaded runs slightly faster than 16 bit
    unloaded, in spite of more i/o.

    Sizes:
    text    data    bss     dec     hex
    180224  16384   587868  784476  bf85c   virtex (16 bit)
    180224  630784  0       811008  c6000   latex (32 bit)
    172032  16384   3110692 3299108 325724  virtex (32 bit)
    172032  3153920 0       3325952 32c000  latex (32 bit)

    File sizes:
    -rwxr-xr-x  1 ken        196608 Jun 29 15:57 virtex (16 bit)
    -rwxr-xr-x  1 ken        811008 Jun 29 15:58 latex (32 bit)
    -rwxr-xr-x  1 ken        188416 Jun 29 15:34 virtex (32 bit)
    -rwxr-xr-x  1 ken       3325952 Jun 29 15:36 latex (32 bit)


\f


Online output from Metafont
%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Metafont in C can be compiled to support multiple window systems. 
You say which you want via definitions in site.h.  You also have to say
which system libraries should be linked into the library in the
top-level Makefile.

There are two versions of the X11 support in mf/MFwindow.  One is based
on Xt, one on Xlib.  The Xt version is faster and has more
functionality, so if it works on your system, you should use it.  It is
the default.  But if it fails, you can try the Xlib version.

Defining more devices is fairly straightforward.  A file should be put
in mf/MFwindow to support the actual interface routines, all of which
are described in the Metafont source.  Then you need to add another
entry to the tables in mf/extra.c; that should be it.


\f


Portability
%%%%%%%%%%%
The C code generated by the web2c translator is intended to be as
portable as possible (for any given set of definitions in site.h).  If
you find bugs or portability programs with the generated code, report
them to Tim.

The generated code assumes that the type |short| has at least the range
-32768..32767, and that |unsigned short| has at least the range
0..65535.  If this isn't the case, the translator will have to be
modified.

Also, if you change the type of |integer| in site.h to something other
than |long|, you will have to modify web2c/fixwrites.c, since it
generates code to integer output using "%ld", and casts all integral
values to be printed to |long|.

The file tex/extra.c contains the routines `clearterminal' and
`wakeupterminal' written for machines running BSD.  If you're not on
such a machine, you may wish to write your own version of the routines
(and please send them to Tim).

On another front, various of the `convert' scripts assume some basic
Unix utilities: basename, cat, cp, diff, ln, make, mv, rm, sed, and touch.
The Bourne shell is also assumed.  If your system versions are broken,
you can try the GNU versions, available from prep.ai.mit.edu in pub/gnu,
among other places.  The GNU C compiler is also better than many
versions of pcc, so you might want to get that.  For more information
about the GNU project, write to gnu@prep.ai.mit.edu.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦a769766a1⟧ TextFile

Derivation

TextFile
