⟦f0a079bde⟧

TextFile

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

This distribution (release number is in "CHANGES") contains a collection of
change files and programs which can convert TeX, Metafont, and the TeXware
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 translator's 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 values to be printed to (long).  I doubt
that anyone will actually have to make either of these changes.

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

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.

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 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.

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 again touch tangle.c.  Now type "make" and it should compile
tangle.c and tanext.c and link them into an executable tangle.


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

If you are not running under SunOS 3.2, you can probably use the program
"regfix".  This will cause it 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 (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.  It appears that on the
Sun-4, it doesn't matter whether regfix is used or not.  To enable
the use of regfix, #define the variable REGFIX in "site.h".  It's
undefined by default.

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 compiling on a machine on which this distribution has not
been tested, you should run the trip test.  Type "make triptex".
Assuming this works, cd to the 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 -O4 optimization level seems to work
		on both Sun-3's and Sun-4's.  With gcc 1.21 (and possibly
		other versions), you must define "schar" as "int" in site.h
		to avoid optimizer bugs (and then the speed and size are
		comparable to the code produced by cc).  With gcc 1.24,
		changing schar is not necessary, at least with Big TeX.
	Sun-4, SunOS 3.2-4, using cc -O, and SunOS 4.0FCS with cc -O4.
	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 :-(.
	Vaxen running 4.2, 4.3BSD, and Ultrix, using cc.  gcc 1.17 (and
		possibly later versions) incorrectly compiles the
		"makemathaccent" routine, but generally produces
		*much* faster code.  Use cc on the module containing
		makemathaccent and gcc on others, to get a much faster
		TeX.  Its data segment will be bigger, however, because
		gcc apparently packs the structure fourquarters very
		unoptimally (this may have been fixed in later versions).
	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.
	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.
	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.

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 it in both TeX and the MF library.

The changefile and the web2c conversion generate code containing
conditionally compiled code.  Two of the symbols are INITEX and TRIP
(TRAP for Metafont).  The other two are STAT and DEBUG.  By default,
STAT will always be defined, and DEBUG will be undefined.  INITEX 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 faster systems, 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.  Here are some interesting
statistics from Ken Yap at Rochester, running on 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.
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 systems 32-bit systems, I would recommend building a 32-bit
initex and virtex, but not preload them with various macro packages.
Shell scripts or aliases can be used.  Also, with version 2.17,
virtex now 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".  Naturally, since this is Unix, the matching
process is case-sensitive.

One further note: When you have a "big" TeX, the memoryword structure
is going to be at least 64 bits.  Therefore, on most systems, you
can change the typedef for glueratio from float to double.  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.  This change can be made in "site.h".

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 gftype, pktype, gftopk and pktogf
are available; mft will shortly be added.  The command-line syntax of
all these programs has been changed to make them run in a more
Unix-like manner.  See the man pages.  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 find
some utilities in MFpxl/CMFpxlware.  You will need gftype if you're
going to run one part of the trap test, using the command line:

gftype -m -i trap.72270gf

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.


Credits
-------

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

Many people 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!
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦f0a079bde⟧ TextFile

Derivation

TextFile
