INTRODUCTION This file is README.TeX3.14159 for users of the Unix TeX distribution. Contents: INTRODUCTION NO WARRANTY statement Acknowledgements Organization of the Unix TeX 3.14159 distribution tape Installing TeX3.14159 (web2c-6.1e) on a UNIX System Making a .fmt file Font Notes (1): What do tfm, pk, gf, pxl, pl, mf, vf, and vp mean? Font Notes (2): More About Rastered Fonts DAT and 1/4-inch cartridges were written on Sun 3 systems. For instructions on installing TeX, see "Installing TeX3.14159 on a UNIX System," below. Information on running TeX may be found in the man page (./TeX3.14159/web2c/man/tex.man, on the tape). Documentation for the TeX language may be found in "The TeXbook," by Donald Knuth, published by Addison Wesley (ISBN 0-201-13448-9). The older manual, "TeX and Metafont, New Directions in Typesetting," published by Digital Press and the AMS, is obsolete. Documentation for LaTeX 2.09 may be found in "LaTeX: A Document Preparation System," by Leslie Lamport, published by Addison Wesley (ISBN 0-201-15790-X). Documentation for LaTeX 2e is scheduled to appear in 1994 with a new edition of Leslie Lamport's book, as well as with "The LaTeX Companion" by Goossens, Mittelbach, and Samarin, also published by Addison Wesley. All of these books were typeset with the system they describe. Serious users of the TeX and Metafont system should invest in the 5-volume set "Computers and Typesetting," published by Addison Wesley; and all users should invest in a membership in the TeX Users Group (P.O. Box 869, Santa Barbara, CA 93102; phone: 805-963-1338; email: tug@tug.org) to keep up to date on new developments. Your attention is directed to the file COPYING.UnixTeX which is a statement of our policy on redistributing Unix TeX. Please also see README.SCORE which contains additional information about the Generic TeX distribution and conditions which apply to this distribution, as well. (The electronic mail addresses, phone numbers and addresses listed in README.SCORE are likely to be out-of-date; please do not rely on them.) The distribution is continually being changed, and such changes inevitably result in errors and minor confusion. We ask for your tolerance. Please feel free to inform us if there are difficulties. Pierre MacKay MacKay@CS.WASHINGTON.EDU University of Washington, DH-10 Seattle, WA 98195 U.S.A. Tel: (206) 543-2268 NO WARRANTY BECAUSE ALL THE SOFTWARE COLLECTED INTO THE UNIX TeX DISTRIBUTION, FROM WHATEVER SOURCE IT MAY ORIGINATE, IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, THE UNIVERSITY OF WASHINGTON, THE NORTHWEST COMPUTING SUPPORT CENTER, AND ALL PARTIES WHO HAVE JOINED IN CONTRIBUTING TO THIS SOFTWARE DISTRIBUTION PROVIDE TeX, Metafont, AND ALL ASSOCIATED PROGRAMS, FONTS, DOCUMENTATION AND EXAMPLES ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD TeX, OR ANY OF THE ASSOCIATED PROGRAMS IN THE UNIX TeX SOFTWARE DISTRIBUTION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT, UNLESS REQUIRED BY APPLICABLE LAW, WILL THE UNIVERSITY OF WASHINGTON, THE NORTHWEST COMPUTING SUPPORT CENTER AND/OR ANY OTHER PARTY WHO MAY MODIFY AND REDISTRIBUTE THIS SOFTWARE AS PERMITTED IN ACCORDANCE WITH THE PROVISIONS IN THE FILE COPYING.UnixTeX, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY US) THE PROGRAM, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. Acknowledgements ================ I'm sure I'm going to leave someone off this list. If I do, don't hesitate to complain. Pascal-related work (superseded by WEB-to-C; but acknowledgements are still in order): The initial TeX Unix ports were independently developed by Howard Trickey of Stanford and Pavel Curtis of Cornell. Howard was responsible for most of the bugfixes, enhancements, and updates over the first few years. The SUN TeX port was independently carried out by people at three locations: Mike Harrison and Charles Perkins at U.C. Berkeley, Rusty Wright at U.C. San Diego, and Steve Correll of Lawrence Livermore Laboratories. The Pascal System V port for the 3B2 was contributed by Lou Salkind of NYU. As for Metafont, the vast majority of the work on Pascal compilation was done by Paul Richards of the University of Illinois, and most of the original MFlib library (now merged into web2c's lib directory) is his. WEB-to-C was begun and developed by Tomas Rokicki, and further developed by Tim Morgan. It has superseded the Pascal-related work mentioned above. The major overhaul for TeX 3.0 was handled by Karl Berry (karl@cs.umb.edu), current Unix System Coordination Chair for TUG. Special thanks to him for heading the team of WEB-to-C wizards, and for continuing to develop, improve, and maintain WEB-to-C. Many other individuals have been involved with the device drivers and other software. We've tried to mention these people in "ORIGIN" or "NOTE" files in the various subdirectories. Again, apologies to anyone we missed. Locally, we are grateful to the University of Washington's Computing Services for the expertise of their consultants and the use of checkout space possible on their machines. We are also very grateful to the Dept. of Computer Science for its support over the years. Among institutions, very special thanks to The American Mathematical Society and to Electronic Technical Publishing Services Company for their generous help. There are also many people who, over the years, have helped improve the quality of the distribution with bug alerts, fixes, comments, suggestions for improvements, and with information about the installation of TeX and Metafont on new machines. Since it is impossible to name each of you, we wish to acknowledge and to thank you here as a group. In addition to our thanks for all of the technical aid we have received, we would like to make special mention of those who support the Unix TeX distribution: the two ftp-retrievers who sent in checks out of their own pockets, the ftp-retriever who arranged to have his company send in a purchase order, people who have added extra amounts to their payment, to Mr. Winnewisser of Germany, and each and every one of you who have sent in an order for a distribution tape: our thanks. ===================================================================== Organization of the Unix TeX 3.14159 distribution tape ==================================================== COPYING.UnixTeX copying policy for the Unix Tex distribution JOIN.TUG please read this: we encourage you to join TUG NO_WARRANTY no_warranty statement for this distribution README.TeX3.14159 this file tug-institutional-form.tex TeX Users Group institutional membership form tug-membership-form.tex TeX Users Group individual membership form There are eight top-level directories: texmf This is the installation tree, ready to be tarred over to wherever you wish to root it. With this current release you get a complete set of executables for sparc-sun-solaris2.[3-5] the format and base files for TeX, LaTeX and METAFONT. (Command line invocations tex, latex and mf.) An ls-R database is included, which covers this tree as shipped. See below for instructions on refreshing ls-R. If you root this ./texmf tree as /opt/texmf it should be possible to add /opt/texmf/bin to your path and begin running right away. If you root the directory anywhere else, you will have to provide a LD_LIBRARY_PATH to the shared object libraries in ./texmf/sparc-sun-solaris2.5/web2c-6.1e/lib We strongly advise against moving these libraries into the Sun Software release library areas, but you can if you know what you are doing. The input and tfm files that are necessary for dumping the default formats and bases (Plain TeX, LaTeX2e, Plain Metafont) have already been placed in this tree. [texmf/doc/general/tds this directory contains the current [draft of] the TeX Directory Standard, which is meant to provide a compatible organization of TeX and METAFONT support files over a wide variety of operating systems. This distribution is only partly TDS-conformant, but we are working on it.] archive-tools bsdtar: For Sys_V machines with 14-character filename limit; handles long filenames during extraction. gzip: standard compress/uncompress utilities for software that is distributed free of licensing restrictions. We encourage you to make this set of excellent utilities. In order to fit as much as we can on the tape, we have gzipped many files. TeX3.14159 This is the core of the distribution. The sources for TeX, Metafont, Tangle, Weave, GFtoDVI, GFtoPK, TFtoPL, etc., are all here to be compiled via web2c. The device driver programs dviljk and dvipsk (for HPLaserJet and PostScript devices), and the X windows previewer xdvik, have been edited by Karl Berry to use the same path-searching library used by the family of TeX programs compiled via web2c. They are in this directory because Karl has made it possible to compile all of the kpathsea-using programs in a single make. Subdirectories with names that begin with lower-case letters are directly involved in the compilation of programs using Karl's kpathsea path-searching library. Subdirectories beginning with upper-case letters are major macro packages (AMS, Eplain, LAMS-TeX, LaTeX) for which formats may be dumped; or, in the case of DVItools (dviselect and dvipaste) and TeXspell, they contain basic utilities. MFdoc and TeXdoc contain basic Knuth documents such as his manuals on WEB and on the trip and trap tests. 00HELP contains a handful of files that may be useful should you run into difficulty during the main compilation. contributions Subdirectories LaTeXcontrib, MFcontrib, TeXcontrib, TeXgraphics, and WEBcontrib are full of useful programs and macros. We encourage you to browse these subdirectories. LaTeX users: sources for the makeindex program are bundled in the LaTeXcontrib subdirectory; we encourage you to make this program. The Unsupported subdirectory contains pktopx, pxtopk, and pxtogf, for sites that may still have *.pxl fonts around, or have need to convert back to them. dviware Device drivers to print *.dvi files to a screen or printer: commonly used VDTs, SunView, and text-only terminals; Imagen, Kyocera, LN03, QMS and line printers. As mentioned above, an X windows previewer and drivers for HPLaserJet and PostScript devices are now in the top-level TeX3.14159 directory. language For typesetting Arabic, Devanagari, Dutch, German, Greek, Hebrew, Portuguese, Swedish, Telugu, Turkish; the INRS-TeX macros are also in this directory. (Cyrillic: mf sources for the scyrillic fonts have been placed in the texmf installation tree in ${TEXMFROOT}/fonts/public/scyrillic/src; the Washington cyrillic fonts, part of the AMS-TeX package, have also been placed in the texmf installation tree in ${TEXMFROOT}/fonts/ams/cyrillic.) freedom Files pertaining to the League for Programming Freedom; the issues are important. Installing TeX3.14159 (web2c-6.1e) on a Unix System ================================================= Our thanks to Karl Berry for his work on web2c. It converts Donald Knuth's WEB code into C for the compilation of TeX and Metafont. WEB is the macro language in which the whole of the TeX package, including Metafont, is written. (For details about this language, see the manual "The WEB System of Structured Documentation" (./TeX3.14159/TeXdoc/webman.tex). During the making of TeX and Metafont, the macro processor tangle converts WEB files into Pascal-language files. WEB-to-C takes this Pascal output, and converts it into C. Thanks to Karl also for his work on getting the device driver programs dviljk and dvipsk, as well as the X windows previewer xdvik, to use the same path-searching algorithm as the family of TeX programs. Making and installing these programs on a Unix machine is much easier now than it used to be, thanks to his efforts. All installations nonetheless still require knowledge of your system and compiler, as well as attention to detail. Make haste slowly to increase your chances of success. There is quite a bit to attend to before you type the "make" command to make all of the programs. We encourage you to go carefully through the files that govern the make, before you begin the make. 1. Choose a directory on your system into which you will be reading the top-level files and directories from the distribution tape. For a plug and play installation on a Sparc Solaris platform, /opt/texmf is the preferred place for the ./texmf tree. This root will hereafter be known as TEXMF. The printed output from "du", sent with your tape, shows in kilobytes, the amount of space the directories on the tape will take. The total size of the current distribution is printed at the end. In addition to that amount of space, it is recommended that you have another fifty megabytes free to do the main compilation and installation comfortably. (By "main compilation", we mean the programs that are made using Karl Berry's kpathsea path-searching library: dviljk (HPLaserJet driver), dvips (PostScript driver), xdvik (X windows previewer), and the family of TeX programs compiled via web2c.) If you are very short on space, you may selectively extract files. The directories necessary for the main compilation are ./TeX3.14159 and ./texmf. 2. Create a pseudo-user in your password file as the owner of the $TEXMF directory tree. (I use texmf as the name of this user.) The pseudo-user's home directory should be $TEXMF, and all following actions should be done after su or login to this pseudo-user. For security, the best plan may be to provide the pseudo-user with no usable password ( either * or NP depending on your system) and require entry by su from root. Remember that a few small parts of the tree (such as $TEXMF/fonts/tmp) may have to be world writeable, unless you mke other arrangements. (By editing both MakeTeXPK and texmf.cnf you can arrange for the temporary storage of PKs in other places, e.g. /var/...) Otherwise the entire tree need only be world-readable and occasionally world executable. Read the contents of the tape onto your system. If your are ready to use the Solaris2.x compilation, go back to the description of the ./texmf directory above. If you don't have a Solaris platform or if and when you decide to develop your own compilation, change to the $TEXMF/TeX3.14159 directory. Everything in the TeX3.14159 directory is what we consider likely to be essential or extremely useful in a basic TeX set-up. The core of this directory is Karl Berry's cluster of programs using the kpathsea path-searching library. We have arranged the material so that all of his programs can be made in a single make, if desired. We have updated the kpathsea bundled with web2c-6.1e so that all programs will be made with the same version of the path-searching library. The versions in this distribution are kpathsea-2.6, dviljk-2.5, dvipsk-5.58f, web2c-6.1e, and xdvik-1.8. Subdirectories with names that begin with lower-case letters are involved in the main compilation. They are: dviljk/ dvipsk/ kpathsea/ web2c/ xdvik/ ps2pkm/ The subdirectory ./kpathsea contains the path-searching library required in the compilation of the programs in ./dviljk, ./dvipsk, ./web2c, and ./xdvik. Each subdirectory contains its own INSTALL, MACHINES, and README files by Karl. We recommend having them on hand and consulting them for the extra details they provide. Please keep in mind, however, that the INSTALL and README files in the subdirectories assume that each program will be made separately in separate makes. Our instructions here will address making all of the programs in a single make, with the exception of the crucial trip and trap tests which determine whether or not the TeX and Metafont compiled on your system are genuine. The MACHINES file in each subdirectory contain system-dependent information, and may be useful when setting Makefile compilation flags in Step 7 below. 3. Look at the top-level Makefile.in (the template for the Makefile that will be generated for your system by "configure".) Note the programs that are defined at the beginning of the file, and the sequence in which they will be made. Edit this line if necessary for your site. For example, if you are not running X windows, comment out xdvik; if you do not have an HPLaserJet, make a copy of the line, comment out the original line, and remove "dviljk" from the new line that defines the programs to be made. Look at the makefile fragments in ./TeX3.14159/make. These will be added to your Makefiles by the "configure" operation. Of particular interest, is the file paths.make. The distribution tape has been adjusted to provide for a compilation rooted in "/opt/texmf". This will have to be set up by running configure with the correct options. If you wish to use the more traditional /usr/local/lib, you may need to change "datadir", "infodir" and "mandir" in paths.make. 4. Next, look at the file web2c/lib/c-auto.h.in. This is the template from which a web2c/lib/c-auto.h for your site will be generated (via "configure"). If you will be installing TeX on different systems, you will be running configure each time you move from one system to another. If there are settings in web2c/lib/c-auto.h.in that you wish to preserve through these different runs of configure, edit web2c/lib/c-auto.h.in. Otherwise, wait until you run configure, then edit the web2c/lib/c-auto.h file that is generated for your current system. The web2c/lib/c-auto.h.in file: a. The section beginning about line 18 allows you to choose the size of the TeX/Metafont/BibTeX you will be making. We recommend that -- unless you know for certain that your system is unable to accommodate the large versions of TeX, Metafont, and BibTeX -- the SMALL versions be left undefined. The default compilation produces a Big TeX with large hyphenation trie, Big Metafont, and Big BibTeX. This size is useful when you must use two or three large macro packages at the same time, for compiling large documents with complex pages and inserts, for accommodating several hyphenation tables at once. We recommend that you retain the default settings here. For more information, see Karl's section on "Changing constants" in web2c/README. b. The section beginning after line 30 allows you to define what kind of Metafont windowing support you want. Define whatever is appropriate for your system. A Metafont window is an instance of one of the window styles in your windowing system. You will find it useful if you are developing Metafont typefaces. Otherwise, not. This is important to know for your own peace of mind in the event that your system is one of those on which making an MFwindow is problematic. If you are not designing a metafont, you will not miss this function. Sites defining SUNWIN: If you are running SunTools (rather than SunView) on an old Sun, "cd mf/MFwindow" and create a hard link from sun_gfx.c to sun.c before running the make. c. Check the remaining pre-compilation choices, through line 137. Configure usually does a good job of figuring out the rest. There are c-auto.h.in files in each of the other subdirectories involved in the main compilation; for most sites, it is necessary only to attend to the settings in the first half of the web2c/lib/c-auto.h.in file. The configure script tends to do a good job of defining the settings for the remainder. 5. Look at the file kpathsea/paths.h.in. This is the template file from which a kpathsea/paths.h file will be generated (via "configure") for your system. The paths defined here are the search paths the compiled programs will be using to find input and font files. If you are installing TeX for the first time on your system, the defaults should serve you well. The texmf directory (parallel to the directory TeX3.14159 on the tape) has been organized to function as the default installation tree, using the default path settings of kpathsea/paths.h.in. 6. Run the script "configure" by typing "sh configure" at your prompt. To re-define the "prefix" for your site, type: % configure -prefix= To retain the organization with which this tape was made up % configure -prefix=/opt -exec-prefix=/opt/texmf For other options and details on running "configure", see Section 2.2 of the printed manual for the Kpathsearch library sent with your tape; kpathsea/INSTALL also contains information on running "configure". If you do not define "prefix", the script will search your system for an executable called "tex"; and if it finds one, will define "prefix" as the parent of the directory in which the program resides. If it does not find such an executable, it will use the default definition of "/usr/local". 7. Double-check the following files generated by "configure" for your system: the top-level Makefile The path definitions set in this file for the installation directories will govern what happens in the subdirectories. dviljk/Makefile Since the installation directories are defined in the top-level Makefile, you need not be concerned about their definitions here. For compilation options to DEFS or CFLAGS, see dviljk/INSTALL, Step 2. dviljk/c-auto.h dvipsk/Makefile Since the installation directories are defined in the top-level Makefile, you need not be concerned about their definitions here. For compilation options to DEFS or CFLAGS, see dvipsk/INSTALL, Step 2. Many sites find the MakeTeXPK script extremely useful; unless you have clear reasons for not using it, we recommend defining -DMAKETEXPK_BY_DEFAULT. dvipsk/MakeTeXPK This is the script that will invoke Metafont to generate bitmapped fonts for your printer if the fonts are not found in the installed texmf tree. Check the path definitions carefully, especially for DESTDIR which is where the newly-generated fonts will be placed. Also check to see that there is a mode_def for your printer; if there is not, check the modes.mf file in the texmf installation tree, in texmf/mf; it contains a list of all known mode_defs in use. The MakeTeXPK script is run by the executable, so that if the settings are not absolutely correct, corrections to the installed copy may be made without recompiling the program. dvipsk/c-auto.h dvipsk/config.ps Edit the definitions in this file for your printer. If you are not certain how much memory your printer has, print memory.ps. Be sure to check the setting for the default resolution and for the Metafont mode for your printer. Again, like MakeTeXPK, this file is consulted by the executable, so that corrections may be made to the installed copy without recompiling the program. If you wish to have more information at this stage, however, we provide ready-to-print postscript files of the dvipsk manual in texmf/doc/ready/TeX3.14159; the dvips.ps file has been split into sections of four pages each to accommodate printers at all sites. dvipsk/PSfonts/Makefile.in No editing is necessary here, but LaTeX users should be informed of the fact that the PostScript style files distributed with dvips are intended to be used with LaTeX 2.09. We have therefore altered this Makefile so that the style files will be installed into the ${TEXMFROOT}/latex209 tree rather than the ${TEXMFROOT}/tex/latex tree (the default texinputs area for latex). In addition, we have placed the necessary config.* and *.map files for the basic 35-font Laser printer package into ${TEXMFROOT}/tex/dvips ready to be used with the LaTeX 2e postscript style files in ${TEXMFROOT}/tex/latex/psnfss. These changes should ensure that both LaTeX 2.09 and LaTeX 2e users will be able to use postscript fonts with dvips. kpathsea/paths.h This file is important. It defines the paths that will be used by the compiled programs to find input and font files. If, during or after compilation, a program complains that a certain file cannot be found, chances are that a search path in this file has been misdefined. The default settings should serve for most sites; it is important to know that the texmf installation tree we provide assumes that the defaults will be used. All of the definitions, however, can be overridden by setting environment variables; for further details, see kpathsea/INSTALL and the printed copy of the Kpathsearch library sent with your tape. If it is necessary to override the kpathsea defaults, a good way to do it is with a .TeXrc file, a sample of which is provided in TeX3.14159/00HELP. web2c/Makefile The installation paths set in the top-level Makefile will govern the make that is run in this sub-directory, so you need not be concerned with the settings here. We only wish to point out that the Metafont bases dumped by default are defined as mf.base and cmmf.base; unless you have reasons for doing otherwise, we recommend leaving the "bases=" line unchanged. The formats that will be dumped are defined on the "fmts=" line; the default is "tex.fmt". For further information about dumping a LaTeX2e format, see the prepared documentation in $TEXMF/doc/latex. If you are interested only in having plain tex, "tex.fmt" is all you need to define; as the basic format, however, it should be retained even if you are making other formats. The LaTeX that will be made by default is LaTeX 2e, the official version as of June 1994. LaTeX users: it is important to make the distinction between LaTeX 2e and LaTeX 2.09. For the duration of the transition, we are providing the basic files for both. (SliTeX users: with LaTeX 2e, it is no longer necessary to dump a separate format for slitex, now called via the command "\documentclass{slides}".) If you wish to make a format for LaTeX 2.09, we recommend that it be done in addition to LaTeX 2e, and that the format be dumped separately after the main installation is done. Instructions are provided in TeX3.14159/LaTeX209/NOTE. If you wish to dump formats for amstex or etex (eplain), define them at this time. The necessary files have already been placed in the texmf installation tree, and no further work is necessary (although, we do recommend that you examine the AMS-TeX and Eplain packages in the directories listed below, for user documentation). If you wish to make any of the other formats (excluding picplus) that are listed in the Makefile, you will have to place the required macro files into the texmf tree. Unless you are already familiar with the contents of the macro packages, we recommend that the additional formats be made after the main installation is done. Karl's web2c/README contains brief descriptions of each format. The macros for all but one are on the distribution tape in the directories listed below. We recommend that the documentation accompanying each of the macros be read before proceeding with a dump (dumping a format may not be desirable in all cases). amstex texmf/ams/amstex; TeX3.14159/AMS amslatex TeX3.14159/AMS etex texmf/tex/plain; TeX3.14159/Eplain inrstex language/inrstex picplus get in touch with the TeX Users Group texinfo contributions/TeXcontrib/texinfo We recommend that you leave "localmodes" defined as it is, unless you have clear reasons for doing otherwise. The most recent version of "modes.mf" is on the tape in the texmf installation tree, in the directory texmf/mf. Make sure that the definitions for optimization and arguments to your compiler are appropriate for your system. This is where the system-specific flags and options that may be specified in either the MACHINES or PROBLEMS file may be useful. web2c/lib/c-auto.h xdvik/Makefile As before, the top-level Makefile will determine the paths for the installation directories. For DEFS or CFLAGS, see Step 2 of xdvik/INSTALL; we recommend consulting the file. xdvik/c-auto.h 8. Decide whether to apply patches. Patches and notes are provided in the PROBLEMS file in each subdirectory (dviljk, dvipsk, kpathsea, xdvik, and web2c). Some patches are system-specific, others are not. The non-system-specific patches have not yet been incorporated into the official versions, but we encourage you to look at them and to consider applying them at this point. (The current versions do not appear to require patching as of July 1995.) 9. Prepare the areas for compilation. We assume that you will be using the default search path definitions as they are set in kpathsea/paths.h. The texmf directory (parallel to TeX3.14159) on the distribution tape, is the installation tree. Karl's file kpathsea/HIER contains an overview of the tree as it was originally conceived. The texmf installation tree is intended to be rooted in the texmf pseudo-user's home directory. (For example: /opt texmf, or /usr/local/lib/texmf.) 10. Before continuing, inspect ${TEXMF}/mf/modes.mf. It contains Metafont mode definitions (mode_defs) for output devices (printer/screen) for which you will be generating bitmapped fonts. Check to see that "localfont := " (near the end of the file) defines the mode for your primary output device. The default is "CanonCX" (a 300dpi write-black print engine used in several laser-printers). If necessary, edit this line. Remember that write-white devices take special care. The Ricoh 4080 print engine is one such device; try the RicohFourZeroEightZero mode_def; see help/README.WRITE-W for more details. If you have a device at a resolution not listed in modes.mf, you can usually get a good idea of how to start writing one by looking at the various device-support sections of this file. The blacker and fillin values are the most difficult to set, and you may wish to make several tries at different settings on a range of magsteps before you decide on the values. (To learn more about mode_defs, see The METAFONTbook.) (After your installation is complete, you will be able to pretty-print modes.mf using "mft", "tex", and your previewer or printer driver program, using the following commands: % mft modes[.mf] [generates modes.tex] % tex modes[.tex] [generates modes.dvi] You can then preview or print modes.dvi. If you are updating the TeX installation at your site, you should be able to do this immediately, if you wish. Typographical oddities here and there in the pretty-printed version will be corrected as time allows; the file is first-and-foremost intended for Metafont.) 11. Double-check to see that you are still in TeX3.14159. It is time to make and run the trip and trap torture tests to verify that the TeX and Metafont built on your system will be genuine, and have the right to be called "TeX" and "Metafont". [RS/6000 and MIPS sites: see files in TeX3.14159/00HELP before proceeding.] The command % make triptrap will build the necessary programs. % make run-triptrap will run the trip and trap tests. The output of "make run-triptrap" is a diff file. It is important to examine it. It should not be very long. As Step 6 of web2c/INSTALL states, the acceptable diffs are: * glue setting being rounded differently in the TeX log; * string space and maximum values of tables; * the `down4' and `right4' commands in the dvitype output; * the dates and times. If the diff file is acceptable (that is, if trip and trap have passed), % make clean-triptrap It is important that "make clean-triptrap" is run before you proceed to "make all". 12. You are now ready to % make all >& all.history & The above command line is for the C-shell; it creates a log file of the make, which can be useful for tracking down problems that may arise during the make or later. See the directory HISTORIES for some exmples of successful compilation. The "make all" command will build the programs in each of the subdirectories named on the line defining "programs" in your top-level Makefile. In the subdirectory web2c, the make will build tangle, initex, virtex, tex.pool, as well as inimf, virmf, mf.pool and the utilities in ./dviutil and ./fontutil. It will also build bibtex. It will dump the tex (plain) format file (and, if you have left latex.fmt and slitex.fmt on the line defining formats in the web2c/Makefile, those two formats for LaTeX 2.09 will also be dumped). The make will also dump the mf and cmmf base files, and make the man pages. [If the make halts at any point so that it is necessary to clean up a failed compilation, the target "mostlyclean" should suffice. In the web2c directories, the target "mostlyclean" retains the .c files so that convert will not have to create them again. If "ld" complains about undefined symbols, try using the "-static" flag for gcc, "-Bstatic" for cc compilations.] 13. If you now type % make install the programs, pool files, formats, bases, and man pages will be installed in the directories defined by you in the Makefile. In your bindir, virtex will be linked to the names of the formats you have installed; virmf will be linked to the names of the bases you have installed. [Ultrix sites: if "make install" halts, try "make -i install".] For a general understanding of how the current TeX loads a format file, we recommend that you read the tex man-page. Since TeX now looks at its own command line to determine what name it is being called under, if you invoke it as tex, it will "look" at its own name, attach the .fmt suffix to it, and will load a format file having that name. Since the plain.fmt file has been linked to tex.fmt, TeX invoked as tex is ready to go. Do read the man page for tex so that you understand how this works and will know what other options are open to you. 14. Type rehash (if you are in the C shell), or do whatever you must do, to make accessible to you these newly installed programs. The primary compilation and installation of programs using the Kpathsearch library is complete. In addition to one or both device drivers and the X windows previewer, the following programs belonging to the TeX family have been made and installed on your system: the web utilities tangle, weave, and pooltype; the typesetting and font-making programs tex and metafont (mf); the hyphenation pattern generation utility patgen; the dviutil utilities dvicopy and dvitype; the fontutil utilities gftodvi, gftopk, gftype, mft, pktogf, pktype, pltotf, tftopl, vftovp, and vptovf; and the bibliography-making utility bibtex. NOTE:: To expedite path searching, create the ls-R database in $TEXMF. % cd $TEXMF ; ls -LR $TEXMF > ls-R See the documentation for kpathsea, section 4.7. For best results you should arrange for a regular refreshing of this database through a nightly crontab entry owned by the texmf pseudo-user You should now be able to run tex on your .tex files to produce .dvi files; if you are running X windows, you should be able to preview your .dvi files; if you have an HPLaserJet or a PostScript printer, you should be able to print your .dvi files. If you are running SunView, or a dumb terminal, or require a driver for another printer, please browse through the dviware directory. We encourage all sites to browse through the printed file listing sent with your tape, to see what else might interest you in the contributions, dviware, help, and language subdirectories. If you are new to TeX and Metafont, we recommend that you go over the very brief note below concerning the use of Metafont, and to browse through "Font Notes (1)" and "Font Notes (2)" at the end of this README.TeX3.14159 file, to familiarize yourself with the kinds of fonts required by previewer and printer driver programs, and to get acquainted with the idea of using Metafont for generating *.tfm fonts that may not be on the tape, as well as for generating bitmapped fonts at specific resolutions and magnifications for specific devices. ----------------------------------------------------------------------------- Note: When would you use Metafont to generate a font? Say that you have a document in which the cmbx12 typeface at magstep 2 is required. TeX will scale this font to that magnification, using the cmbx12.tfm font file, and it will produce a dvi file. In order to print the dvi file on, say, a 300dpi printer, your device will require the bitmapped font cmbx12.432pk. While cmbx12.300pk (the cmbx12 typeface at magstep 0) is on the tape, cmbx12.432pk (the same typeface at magstep 2) is not. You will then have to generate that rastered font via Metafont. Be sure to refer to the mf man page. ================================================================== Installing TeX3.14159 on a Unix System: Making a .fmt file: ======================================================== You should be aware that there are three kinds of TeXs in use. These are represented by initex, virtex, and tex. Initex is used to install TeX, starting from scratch. Initex loads font data, hyphenation data, and macro packages, and then dumps its entire internal state into a .fmt file when given the \dump command. Virtex is able to read the information in this .fmt file back in, making its internal state the same as initex's when the \dump occurred. Like initex, virtex can also load font data and macro packages. However, virtex cannot read in the hyphenation patterns. The name tex is conventionally applied to a virtex with the format named plain.fmt loaded. If you need to make a new format file (say a new myown.fmt) do the following: % initex myown '\dump' This is TeX, C Version n.nnn (INITEX) ... Initex will process the file myown.tex and then create the myown.fmt file (printing informative messages on your terminal as the process is carried out). For plain TeX, plain is dumped to plain.fmt; for LaTeX and SliTeX, lplain and splain are dumped respectively to lplain.fmt and splain.fmt. (For more information, see the section on "Format files and preloading" in web2c/README.) Incidentally, if you get the virtex error, "Fatal Format Error, I'm Stymied," particularly after you've changed things around, try remaking the .fmt file as a first attempt to solving the problem. --------------------------------------------------------------------- Please be aware that creating a macro package to be turned into a preloaded TeX is a task for experts and may not work for all possible macros. For example, an \everyjob token stream if present in a macro package being preloaded will be executed before the \read happens. Consequently, if you want to preload macro packages which you have created, you should take care that \everyjob's don't do anything to cause the log file to be opened. For example, referring the \jobname does this, so don't do \everyjob{\message{\jobname}} in your macro package (this would always produce the uninteresting message, "texput," anyway). In case you are now worried, rest assured that the plain and latex macro packages do not have problems like the one just described. ==================================================================== Font Notes (1): What do tfm, pk, gf, pxl, pl, mf, vf, and vp mean? =================================================================== Font files come in several varieties, with suffixes like: .tfm .*pk .*gf .*pxl (obsolete) .pl .mf .vf .vp A .tfm (TeX Font Metric) file is a compact binary file that contains information about each character in a font, about combinations of characters within that font, and about the font as a whole. The font metric data contained in .tfm files and given in device- independent units, are used by TeX to format the page and produce .dvi (device-independent) files. Unlike bit-mapped (rastered) fonts, *.tfm font files contain no information about the shapes of characters belonging to the font. They decribe rectangular areas of blank space, but do not specify what goes into that space. Since TeX does scaling calculations, one .tfm file serves for all magnifications of a given typeface. In order to print these .dvi files on real devices, you need rastered font files containing digitized character shapes and other data needed by previewers and printer-driver programs that will take your .dvi files and convert them into something usable by your terminal or printer. Rastered fonts come with suffixes like .*pk, .*gf, and .*pxl. The "*" stands for the horizontal dots-per-inch resolution of the font (unless the font has been magnified). The letters "pk," "gf," and "pxl" stand for different font formats. Fonts in pk format are in the tightly packed format that is pretty much the standard for printers and printer-drivers today. They take up less space than fonts in gf (generic font) format--the format in which Metafont generates fonts, and far less space than fonts in pxl format. Fonts in pxl format take up gross amounts of disk space and permit only 128 characters. They are considered obsolete, and we discourage their use. Font files with the .pl (Property List) suffix, are the ASCII (human-readable) analog of binary .tfm files. To convert .tfm files into human-readable .pl (property-list) files, use the texware routine tftopl. To convert in the other direction, use pltotf. Font files with the .mf suffix are in Metafont source format. These are the files used by Metafont to generate rastered fonts for specific typefaces at specific magnifications for the specific resolution and type of mapping used by your print engine. The extension .vf identifies a file written in virtual font file format. The fontutil routine vftovp converts .vf font files into human-readable .vp (virtual font property-list) files; the companion utility is vptovf. For Donald Knuth's discussion of these fonts, see help/README.vf. * * * * * * * * * * * The .tfm files for Donald Knuth's Computer Modern fonts are provided on the tape in the texmf installation tree, along with the .tfm files for LaTeX 2.09, SliTeX, and AMS fonts. Browse through the texmf/fonts tree in the print out of the file listing sent with your tape to get an idea of what fonts are available to you in what forms. To generate bitmapped fonts for LaTeX 2.09, see the Makefile and the README file in the directory texmf/fonts/public/latex/src. ==================================================================== Font Notes (2): More About Rastered Fonts ========================================== As noted above, the *.tfm files are all that TeX needs to make a .dvi file; and you only need one to cover all magnifications for any specific typeface. This is not true for rastered fonts that will actually print on real devices. For these, you need a distinct file for each resolution, for each print engine, and for each magnification. This is to say that, in order to typeset a document calling for the typeface cmbx12 at magsteps 0, 1, and 2, you need only have the cmbx12.tfm file on your system. In order to print that document, however, you will need three different rastered font files--cmbx12.300pk, cmbx12.360pk, and cmbx12.432pk. But while you must load all of the .tfm files that plain.tex, lfonts.tex, or sfonts.tex may ask for, you need only load fonts at the actual .*[gf, pk] magnifications that you really expect to use, at the actual resolution in dots-per-inch of your printer, and for the type of mapping used by the particular type of print engine you have. This means that if you never print a document calling for cmbx12 at magstep 3, you need never have the bitmapped font cmbx12.518pk onto your system. Installing rastered fonts: -------------------------- The goal of producing a cross-platform directory structure makes the placing of rasterized fonts particularly difficult, owing to the crippled naming conventions of DOS, Windows and other similar Operating systems which cannot use the NNNpk suffix. Open directories have been provided for a TDS-comformant arrangement, and the Computer modern fonts have actually been moved into a TDS directory tree. If you have no need to accommodate non-Unix systems, use the organization shown below. Otherwise read the TDS draft standard provided in $TEXMF/doc/tds. Bitmapped fonts in pk format are now placed in directories named according to the mode_def by which they were generated. In the texmf tree, the generic structure of the path to these fonts is as follows: ${TEXMF}/fonts///pk// If you have used the CanonCX mode_def to generate a bitmapped Computer Modern font in pk format -- say, cmbx12.518pk -- for a 300dpi write-black device, its place in the texmf installation tree would be: ${TEXMF}/fonts/public/cm/pk/cx/cmbx12.518pk