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 . Tomas Rokicki wrote the original TeX to C program. Pierre Mackay wrote the original change files for most of the Metafontware programs. Karl Berry 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 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. 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. 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 ) 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 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 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) 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. 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.