Introduction
------------

This distribution (the release number is at the end of the "CHANGES" file)
contains a collection of change files and programs which can convert TeX,
Metafont, and the TeXware and MFware programs from WEB source code to C
source code.  The C code generated by the translator is intended to be
as portable as possible.  If you find bugs or portability problems with
this code (or the C code it generates), please report them to me
<morgan@ics.uci.edu>.  If you successfully port this code to a machine,
operating system, or compiler not listed below, I'd appreciate hearing
that as well, so I can add it to the list.

The generated code assumes that the type short has at least the
range of values -32768..32767 and unsigned short the range 0..65535.
If this isn't the case for your compiler, then you'll have to modify
the translator.  Also, if you have to change the type of "integer" in
site.h to something other than "long", which is assumed to have at least
the range -2^31..2^31-1, you will also have to modify the fixwrites.c
program, since it generates code to do integer output using the printf
format "%ld", and casts all integral values to be printed to (long).  I
doubt that anyone will actually have to make either of these changes.

You will need to supply the WEB source code for each program you wish to
build.  On ics.uci.edu and orion.cf.uci.edu, I've put all the .web files
into a separate tar image which can be untarred
on top of this distribution, putting all the files in the right
places.


Getting Started
---------------

To make and install TeX and friends, edit "./site.h" and change things
to match your local environment.  The comments in this file should be
self-explanatory.  You may also want to adjust the paths and libraries
specified in "./Makefile".  If you want to make all of the TeXware
programs, you should cd to texware/ and type "make all".  The default will
be to make tangle only, since only it is required for building TeX,
MF, etc.  You'll also need dvitype if you're going to run the trip test.
Similarly, if you want bibtex or MFware programs, you must cd to
their respective directories and make the programs you need; the top-level
Makefile doesn't know about these programs.

Note: Defining SYSV or BSD in site.h affects the web2c process itself.
Running web2c on any machine is intended to produce C code for TeX,
MF, or whatever, which is system independent.  The same C code for
TeX and friends should therefore be portable to any other machine as well
as the machine on which it was originally generated. 

Depending on your C compiler, you may receive warning messages when
compiling TeX and Metafont saying that there are unreached statements.
This is normal.  Some compilers have a limit on the number of cases
allowed in a switch statement which is too small to compile TeX and dvitype.
If your compiler doesn't allow you to increase this limit, then you'll
have to edit tex8.c and dvitype.c to use a default case or otherwise
get around the problem.

When making web2c, you will receive a message from yacc saying that
there is one shift/reduce conflict in web2c.yacc.  This is normal.

If you are using a Sequent, you may want to take advantage of the
parallel Make facility.  To do so, type the following command
before starting:

	make parallel

Some of the conversion scripts (all Bourne shell-based) make use of
Unix utilities: awk, sed, cp, basename, etc.  As far as I know, the
functions utilized are available on all Unix systems (post V7, anyway).

The top-level Makefile defines a variable SITEDIR as "..".  SITEDIR
specifies the directory where site.h can be found, relative to the
subdirectories ctex, cmf, bibtex, etc.  Thus, ".." indicates the
current directory.  If you want to have a separate site.h in a
subdirectory "mysite", for example, then SITEDIR would be defined as
"../mysite".  Most sites won't have to change SITEDIR.


Bootstrapping Tangle
--------------------

You don't need a running tangle or even tangle.web to bootstrap
this distribution.  If you don't have tangle.web, you should create
an empty file of this name in the texware/ directory, then touch
tangle.c so its last write date is more recent than that of tangle.web.
If you do have tangle.web, copy it into the texware/ directory,
and then touch tangle.c.  Now type "make" to compile
tangle.c and tanext.c and link them into an executable tangle.


Building TeX
------------

If you are not running under SunOS 3.2 through 3.4, you can probably use the
program "regfix".  This will cause web2c to generate code which puts local
variables into registers, which on some machines causes TeX to run
about 10% faster.  On Suns running SunOS 3.2 through 3.4 (and perhaps some
earlier versions of SunOS), doing this will exercise a compiler bug, and
the resulting C code won't pass the trip test.  With smarter compilers,
such as those supplied with SunOS 4.0, it doesn't matter whether regfix
is used or not.  To disable the use of regfix, #undef the variable REGFIX
in "site.h".  It's defined (enabled) by default.

If you are compiling on a machine or with a compiler or OS version
on which this distribution has not been tested, you should run the
"trip" and "trap" tests to verify that TeX and MF are working correctly.
To run the trip test, you first build a special version of TeX by
typing "make triptex" at the top level.  Assuming this works, cd to
ctex/trip/ and follow the instructions in the README file found there.
This distribution (or slight variations) has passed the test on the
following systems:

	Sun-3, SunOS 3.2 (no register variables), SunOS 3.4, 3.5, 4.0FCS
		(with register variables), all using the Sun-supplied C
		compiler, cc.  The -O optimization level seems to work
		on both Sun-3's and Sun-4's in SunOS 4.0 for TeX, but
		not -O4.  With some early versions of gcc, you must
		define "shar" as "int" in site.h to avoid optimizer bugs
		(and then TeX's speed and size are comparable to the code
		produced by cc).  With recent versions of gcc, changing
		schar is not necessary.  In particular, I've just
		tested gcc 1.35 on SunOS 4.0.1, and it passes the trip test.
	Sun-4, SunOS 3.2-4, using cc -O, and SunOS 4.0FCS with cc -O.
		Gcc 1.28 also passes the trip test, but the execution
		time of the resulting program is the same or slower than
		that compiled with cc.  Gcc 1.30 seems to produce code
		which fails the trip test, while 1.35 passes with no
		problems.
	Sun-386i, SunOS 4.0, cc -O, gargantuan version.
	Sequent Balance, Dynix 2.1.1, using cc, in both the Berkeley
		and ATT universes.  Gcc 1.21 and earlier failed even to
		produce assembly code which would assemble, much less execute.
		1.22's supposed to have this fixed, but the compiler dies
		with an unexpected signal :-(.
	Sequent Symmetry, Dynix 3.0.12, using cc -O.
	Vaxen running 4.2, 4.3BSD, and Ultrix, using cc.
		The web2c 2.40 works with gcc 1.35 under 4.3BSD, for both
		TeX 2.991 and MF 1.7.
	Convex: Everything works, but -O breaks web2c itself, so don't use it
		when compiling that program; it's ok for TeX etc.
	Amdahl running UTS (SysV).  The type "schar" must be "short".
	Apollo, SR9.7 and SR10.0 (beta).
	Ridge 32 running ROS 3.5 and C compiler version 2.1B
	UNIXpc (aka 3b1 or PC7300) running System V version 3.51.
	MIPS R/1000, compiler version 1.21
	Iris workstation (model and OS version not specified).
	Celerity C1260, UNIX version 3.4.78, without -O.  The optimizer
		bug has been reported to Celerity (now part of FPS).
	Pyramid 98x, OSx64Q 4.0-870901, C Compiler CCOMP_4.0, large or
		small TeX's.
	AT&T 6386 WGS, running System V Release 3.1.1
	Interactive 386/ix Version 1.0.5 (Unix System V Release 3.1) running
		on an i386 machine.  See patches in the directory 386-ix.
	IBM RT/PC running AOS 4.3 (without -O with one compiler version;
		see README.RT for another).  Also, you may have to define
		schar (in site.h) as "short" instead of "char".
	HP 9000/350.  HP's version of lex, and possibly others, types
		yytext as unsigned char instead of char.  Appropriate
		changes will have to be made in web2c on such systems.
		See the file "./README.HP" for a list of diffs.
	AT&T 3b2, small TeX, using the fpcc compiler.  The files tex8.c
		and dvitype.c had to be modified because each contained
		a case statement too large for the compiler to handle.
		It may be necessary to remove the "-s" flag when loading
		virtex if you're going to use undump.
	ICL Clan 7 running System V (really a CCI Power6/32).
	HP 9000/840, compiled without "-O" and with "-lmalloc", both big
		and small versions of TeX.  The 9000/850 is supposed to
		be object-code compatible, but it was not tested.
	Cromemco System 300 running Unixsoft System V.2 (TeX only).
	Sony News Workstation, 4.2BSD Unix Release 2.2, using both the
		native C compiler and gcc (both TeX and MF).
	Counterpoint System-19K, C-XIX 3.0.
	Sperry 7000/40 (Tahoe architecture) running 4.3BSD.
	Encore Multimax (32332's) running Umax 4.2 release 3.3.
	NeXT, system version 0.8.
	DECstation 3100.  Currently tex4.c must be compiled without -O.
	Harris 8CX9 running HCX-UX.  Type schar was defined as short,
		and the #include of <fcntl.h> was removed from ctex/extra.c.
	Tektronix 4337 workstation rujnning U-Tek 3.1, with REGFIX and
		all window options undefined in site.h, and compiling
		without -O.  [Sugato Ganguly <ganguly@wurobot.wustl.edu>]
	NCR Tower32/200 (Rel 1.00) and Tower32/600 (Rel. 2.00).  This was
		web2c release 2.21.
	A DOS port is in progress.  For now, you should ignore any
		references to MS_DOS in the code.

In SunOS 4.0 (possibly in 4.3bsd and others), the type of the second
argument and return value from signal(3) has changed to (void *);
lint will complain about this.  If it makes a difference on your
system, you'll have to change the calls to and declarations of signal()
in both TeX and the MF library.

The changefile and the web2c conversion generate code which makes use
of conditional compilation.  Two of the symbols are INITEX (INIMF in MF)
and TRIP (TRAP).  The other two are STAT and DEBUG.  By default,
STAT will always be defined, and DEBUG will be undefined.  INITEX/INIMF
is defined only when making initex, and the code dependent on that cpp
variable is isolated into one or two modules which the Makefile knows
about.  The conversion process and the Makefile also arrange that TRIP
will be defined when making triptex.  If you feel the need to change
the values of STAT and DEBUG for some reason, you should edit the file
"ctex/orig_texd.h".  You should not change "ctex/trip_texd.h", since any
change there could make verifying the trip test results extremely difficult.
The most likely thing you might want to do would be to turn off STAT,
to make virtex and/or initex smaller.  Similar comments apply to
Metafont.  See "TeX: The Program" and "Metafont: The Program" for details.

One more note on porting TeX: in ctex/extra.c, there are two
system-dependent routines, clearterminal() and wakeupterminal().
There are comments which tell what the routines are supposed
to do, and BSD-specific code to do it.  You may wish to supply
code for your own system if it's not BSD-compatible.  TeX will
work without these routines, but they make things nicer.


Preloaded TeX, undump, big TeX, etc.
------------------------------------
As you may know, TeX can be "undumped" on many systems to avoid
reading the .fmt file at run time.  Recent measurements indicate
that with the C version on reasonably fast machines, there is no real
savings in startup time in doing this, while there is a significant
penalty in disk space.  Also, if one person is running plain TeX
while another is running LaTeX, the code (text) segment will
not be shared if they are running two different preloaded binaries.
Therefore, I recommend not preloading.  The following indented
material is from Ken Yap at Rochester, who was using a Sun 3/60 with
SunOS 3.4:

    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, inspite 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)

Note that the 32-bit TeX's have a smaller text segment and run faster,
because they don't have to convert frequently between 16 and 32-bit
integers.  A further advantage of a 32-bit TeX is that it's very unlikely
that a TeX user will run out of TeX memory space when loading several
macro packages, doing complex pictures, etc.

Thus on most 32-bit systems with large addres spaces, I would recommend
building a "big" initex and virtex, but not preload them with various
macro packages.  To build a "big" version of TeX, apply the patch
texdir/BIGTEX.PATCH to texdir/ctex.ch; see the file ./README.PATCHES
for further information.

Shell scripts or aliases can be used to create commands
"tex", "latex", etc.  An example of such a script is ctex/tex.script.
Virtex checks argv[0], and if its name is, for example, "latex",
it will attempt to preload "latex.fmt", which should be a link
to "lplain.fmt".  The same approach can be used for each .fmt file you
have.  Naturally, the matching process is case-sensitive.

Note that when you have a "big" TeX, the memoryword structure
is going to be at least 64 bits.  Therefore, on most systems, you
can make the typedef for glueratio be double instead of float.  This
will make TeX's glue ratio calculations that much more precise,
and it'll avoid generating the code to convert between float and
double, which will make TeX that much faster.  The type glueratio is
defined in "site.h".  Metafont does no floating point calculations
whatsoever, so this applies only to TeX.

One final note: Different machines will have different formats
for the .fmt file.  Thus, sites with heterogenious machines with
filesharing capabilities will have to have a different
file for each unique architecture.


Building Metafont
-----------------

C Metafont has the capability to support several different windowing
systems for previewing fonts.  The Makefiles are set up to include
these capabilities only in virmf, not in inimf.  When editing site.h,
there are some #define's which select which windowing system(s) will
be supported.  It is also necessary to specify which libraries need to
be linked against when building the executable virmf.  These libraries
are specified in the Makefile in the current directory.  Modify the
line defining WLIBS to include $(XLIBS) if you're including X10
support, $(X11LIBS) if you're including X11 support, and $(SUNLIBS) if
you're including SunView support.  No special libraries are needed for
the Tektronix and HP2627 support modules.  You can support as many of
these windowing systems in the same executable as you wish, except
that you cannot have both X10 and X11 support simultaneously because
some of the library routine names conflict.

If you want to make the MFware programs, you should cd to mfware/ and
type "make all".  At this writing only gftopk, pktogf, gftype,
and pktype are available.  Donald Knuth has
announced that he is rewriting gftodvi, and it seems best to wait for
the new version, but if you really need gftodvi it should not be too
hard to hack a change file on the model of gftopk.ch.  No
effort is planned for change files to deal with the pxl-related
programs.  You will need gftype if you're going to run the trap test.

As with TeX, if you're compiling C Metafont on a system on which it
has not been tested, please run the trap test by making trapmf, then
following the directions in cmf/trap/README.  Most other comments
above about TeX also apply to Metafont.

You can build a "gargantuan" Metafont to go along with a gargantuan
TeX :-).  Just apply the mfdir/BIGMF.PATCH to mfdir/cmf.ch before building
Metafont, following the same instructions which apply to BIGTEX.PATCH
(see "./README.PATCHES").


Credits
-------

Tomas Rokicki, for writing the original TeX to C program and making it
  domain public.

Probably a hundred people have contributed to this release, by contributing
  changes to help convert new programs (especially Metafont) or by acting as
  beta test sites.  There are too many to list, but you know who you are!

If you have problems or port TeX to a new machine or operating system,
please send mail to <bug-tex@ics.uci.edu> or ucbvax!ucivax!bug-tex.


				Tim Morgan
				12/11/88
