This file is ./mf84/READ_ME. It describes installation procedures for compiling and preloading METAFONT on 4.2/3BSD Unix machines. This file has been largely rewritten from an earlier version supplied during the development of METAFONT by Paul Richards, who did nearly all the major work on the Unix port. This is the port of METAFONT 84 for Berkeley 4.2 Unix and other systems based on 4.2BSD Unix. It is currently set up for 4.2 Unix on DEC Vax computers and SUN Microsystems version 1.2 of 4.2BSD. As of September, 1986, we have heard of successful compilations on SUN3 running version 3.0 of the Sun OS. Version 3.1 apparently requires a change file with the (*$C+*) compiler flag turned off. (Bug in the range checking code.) We have chosen to effect this by turning off the |debug| code altogether in the change file dist_inimf.ch. METAFONT is probably beyond the point where debug help is normally needed even for inimf. The absence of debug code does not affect the validity of the ``trap'' test. At the time (October, 1986) of writing SUN2 running Version 3.0 of Sun OS would compile but not run. At least one major bug was found in the indices of large arrays in the compilation produced by Version 3.0 for the 68010. A fix to the SUN2 pc is promised with Version 3.2 of the Sun OS. 1. Components This distribution contains the following programs: metafont version 1.2 gftodvi version 1.7 gftopk version 1.1 gftopxl version 2.1 gftype version 2.2 pktopx version 2.2 pktype version 2.1 pxtopk version 2.2 mft version 0.3 The root directory of this distribution should have the same parent as the "tex82" directory of the Unix TeX distribution. This is so the "h00vars.h" and "texpaths.h" include files can be accessed by the C modules which are part of the METAFONT port. If for some reason this is impractical, the Makefile in this directory should be edited to change the CFLAGS definition so as to indicate where the tex82 directory is located. The following subdirectories contain utilities and files needed to run METAFONT 84: ./mf84/MFfonts/bases: Contains the "base" definitions for METAFONT. Currently, only the PLAIN base is included, although there is a copy of the "WAITS.MF" file that is used at Stanford to provide device dependent modedefs when building a preloaded base. (The PLAIN base is analogous to the PLAIN macro set under TeX --- it is a set of low-level definitions that are useful for developing fonts, and are described in the METAFONTbook) ./mf84/MFdoc: Contains a copy of an older document, "syntax.tex", which describes the syntax of the new METAFONT language. This file is out of date with the current implementation, but not excessively so to make it obsolete. A much better document to use when learning METAFONT is the METAFONTbook, (ISBN 0-201-13445-4 or ISBN 0-201-13444-6 [soft]) published by Addison Wesley, (Reading, Mass./Menlo Park, Calif. 1986). To conserve space, almost all the documentation is compressed If you don't have the compress utility on your system, see the ./compress directory on this distribution. ./mf84/MFfonts: Contains the subdirectories, "gray", "black" and "slant." These fonts are used by the gftodvi utility to produce font proof sheets containing a magnified image (one per page) of the characters in a font. Look in gray.mf to see how to tailor it and produce a gray font for your specific output devices. Additional subdirectories are "logo", "cm", "mfbook", "half" and "committee." The "logo" fonts are for the characters in the trademarked form of the name METAFONT. The "cm" directory contains testbed mf files for designers. (For the cm production files, see ./cmfonts/mf.) The "mfbook" directory contains some of the examples from the METAFONTbook. The "half" directory provides a font for halftones. The "committee" font is the end product of the font-design class held at Stanford in the spring of 1984 (described in second issue of Volume 5 (1984) of TUGboat). It is included to be an example of how the new METAFONT language is used. It does NOT require the PLAIN base to be loaded --- it has its own base (font1base.mf) file to work from, and needs to be edited to set it up for a specific output device resolution and point size, or to produce proof sheets. ./mf84/MFutils: Contains the files for GF-file and PK-file utilities. gftype, gftopxl, and gftodvi. - gftype is a program to mnemonically display the contents of a "GF" (Generic Font) file, similar to DVItype for TeX. - gftopxl is a program that takes a GF file (the output from METAFONT) and produces a PXL formatted file for use by various output filters for TeX to produce printed pages on laser printers. - gftodvi is used to produce proof sheets for fonts. It can operate in two modes: producing "normal" proof sheets (using a "gray" font to produce a stippled pattern where the character is black), or producing "smoke" proofs, which are solid black where the character is black. The characters are printed one per page, magnified by however much the gray/ black fonts expand one pixel (e.g. a 4x4 pattern representing one pixel in a gray font will cause the proof sheet to appear magnified linearly 4 times in each dimension). Optionally, normal proof sheets can have labels printed marking the path points used to construct the character. These options are all controlled by special directives embedded in the GF file -- look at plain.mf to see where "special" directives are used. The output of gftodvi is a DVI formatted file ready for post- processing by for your favorite output device. PK-files pack font information better (but at the price of losing the "specials"). Their names are self-explanatory. ./mf84/MFtexfiles: Contains the file "testfont.tex", used to print font sample sheets and display some typical inter-character spacing combinations that usually need adjustment when designing fonts. Also the macro files for the mft formatter which can produce typeset versions of mf input files. ./mf84/MFtrap: Contains the TRAP acceptance test for METAFONT 84. VAX and SUN and Pyramid versions have passed this test. METAFONT Installation Guide. (SPECIAL NOTE---IF you are running a write-white machine, such as the Imagen 24/300 or the DEC LN03, make sure you read README.WRITE-WHITE after this.) The procedures for installing METAFONT are closely modelled on those for TeX, but reflect certain essential differences in the nature and use of the program. You should begin by loading the entire ./mf84 directory structure into your system. In the root of this structure, you will find the configure script. In preparation for running this you need to consider what you will do with the environment variables MFPOOL, MFINPUTS and MFBASES. [ Directories: ./mf84/MFconfig ./mf84/MFconfig/mf84 ./mf84/MFconfig/mflib ./mf84/MFconfig/mfutils ] Here are the results of an actual run which accepted all defaults # Configured on Fri Sep 12 09:57:23 PDT 1986 OPTIONS./mf84/MFfonts"MACHINE BINDIR MFINPUTS MFBASES MFPOOL TEXFONTS TEXSRCDIR WINDOWS WIN\ DEFS WINLIBS " MACHINE./mf84/MFfonts"VAX4_3" BINDIR./mf84/MFfonts"/usr/local" MFINPUTS./mf84/MFfonts".:MFsrc:/usr/lib/mf84/bases" MFBASES./mf84/MFfonts"/usr/lib/mf84/bases" MFPOOL./mf84/MFfonts"/usr/lib/mf84" TEXFONTS./mf84/MFfonts".:/usr/lib/tex82/fonts" TEXSRCDIR./mf84/MFfonts"../tex82" WINDOWS./mf84/MFfonts"none" WINDEFS./mf84/MFfonts"" WINLIBS./mf84/MFfonts"" MFPOOL contains the path to mf.pool which is produced by compilation and is needed only for the execution of inimf. Compilation will produce a file named inimf.pool (or virmf.pool) and this must be copied or renamed to mf.pool. Each version of mf.pool is likely to be unique to each recompilation of METAFONT, and there is little reason to keep several versions unless they contain unique diagnostic messages (e.g., in languages other than English). The file is not large, and can share a directory with other files. One common choice is to put it in the same directory as the executable binaries. MFINPUTS is where inimf and virmf expect to find *.mf files. The basic sets of these are in directories ./cmfonts/mf and ./LaTeXfonts/mf at the root level of this distribution. You will find some others in ./mf84/cm notably the special files for gray, black, slant and halftone fonts. Most active users of METAFONT will have special paths in their MFINPUTS environment variable. [ Directories: ./mf84/MFfonts/black ./mf84/MFfonts/gray ./mf84/MFfonts/half ./mf84/MFfonts/slant ] MFBASES contains the path to *.base files, which are predigested macro files analogous to the *.fmt files used by TeX. They are produced when the command |dump| is issued during a run of inimf. A site which makes active use of METAFONT as a design tool should expect to have a number of *.base files available, far more than the normal two or three *.fmt files which are needed for TeX. You will probably want a separate directory for these, but they could also share a directory with TEXFORMATS or MFINPUTS. [ Directories: ./mf84/MFfonts/bases ] Compile inimf and virmf using the Makefile generated by the configure script, and then copy the file waits.mf from ./mf84/MFfonts/bases to your own choice of *.mf name in whatever you have chosen as your primary MFINPUTS directory. You should inspect this file to see whether it includes an output device corresponding with what you will be using--remember that write-white devices take special care--and if you are lucky in this respect you can use the file more or less unchanged. If you have another device at another resolution, you can usually get a good idea where to start by looking at the various device-support sections of waits.mf. 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. In the following sections we will call this file device.mf. You will need a number of short driver files to create the *.base files for various styles of font generation. These driver files contain nothing but a list of input commands. Give the driver files informational names and those names will be applied to the resulting base file. For example: the file utilityfont.mf could be used to generate the base for gray, black, and slant fonts for proof sheets, and for the halftone font for your local device. The utilityfont.mf driver file will contain only two statements: input plain input device [ Directories: ./mf84/MFfonts/bases ] The logofont.mf driver file for producing the METAFONT logo characters will contain: input plain input device input logobase (NOTE: logobase.mf has disappeared from the Stanford archive, and may no longer be necessary) [ Directories: ./mf84/MFfonts/bases ./mf84/MFfonts/logo ] and the cmplain.mf driver file will contain: input plain input device input cmbase [ Directories: ./mf84/MFfonts/bases ./cmfonts/mf ] To create a base file such as utilityfont.base, run inimf with the command line % inimf utilityfont and when you receive the * prompt, type dump. The resultant file can be used by virmf with the & convention (the backslash is the csh quote in this case): % virmf \&utilityfont after which other *.mf files can be input, but the output will in that case be named mfput.*gf. To get output named after your first *.mf driver file (e.g., cmr10.mf --> cmr10.2602gf) you must preload METAFONT. Before you attempt this, please read carefully the instructions for preloading TeX in ./tex82/README and be sure you understand why the \read16 to\blort line is used where it is. Preloading METAFONT is closely analogous, but it is actually somewhat simpler. Give only the program name on the command line, and when you get the ** prompt (which expects a base) supply the name of your chosen base, followed by an impossible input file--some name that you know cannot be found: % virmf This is METAFONT, Version 1.0 for Berkeley UNIX (no base preloaded) **&plain xyxyxy ! I can't find file `xyxyxy.mf'. <*> &plain xyxyxy Please type another input file name: ^\ (with whatever base you are choosing for this preload) Wait for the error message and then immediately key in the Unix quit character, which is usually a ^\. Reformat the core dump using undump. If you have room you can keep several preloaded METAFONTs around, but they are rather large, and you will probably not want to do that. The most generally useful is the one with cmbase preloaded, which can be distinguished by naming it cmmf. Run the cmplain driver file through inimf, then use the resultant base with virmf, and finally run undump: % undump cmmf virmf core to get the preloaded cmmf. [ Directories: ./undump ] A typical command line to produce a font--in this case we shall assume that one of the logo fonts is wanted--is % logomf \\mode=localfont\; \\mag=magstep?\; input logo10 Notice the backslashes. The first of each pair is the csh quote character. the second is a METAFONT convention which masks words such as |mode| that might otherwise be read as the initial input file. In the Bourne shell, you can run METAFONT more naturally, and you will probably want to use this for any production shell scripts. If you use backslashes appropriately, your output will be named by the name of the first ``input'' file. NOTE: If you do not supply a mode, or if localfont, or any other name fails to evaluate to a valid constant, mode will be set to 0 and you will get proof copy. Proof copy can be recognized by the gf suffix specific to proof files .2602gf. If you see this suffix unexpectedly, you can be pretty sure that you have specified an invalid mode. This is all you need except a copy of the METAFONTbook if you are writing for a write-black engine. If you are writing for a write-white engine, go on to README.WRITE-WHITE. Additional Notes If you are running on a SUN workstation, support is provided to use the graphics display while running METAFONT. In this case, it is recommended you run METAFONT from within a graphics tool (gfxtool) subwindow of SUNTOOLS. The default window dimensions specified by PLAIN.MF for on-the-fly character display don't exactly match the initial graphics sub-window size put up by the graphics tool; you can either increase the size of the sub-window with the graphics tool, or alter the default window dimension in an additional file loaded after plain.mf but before dumping to plain.base. (I have noted that the graphics subwindow routines of SUNTOOLS don't really care if they have a graphics sub-window available for use. If they don't (e.g. you are running from a terminal or from the console but not under SUNTOOLS), they just grab the entire bit-mapped display for their own use. If this happens while you are running on the console, just suspend METAFONT via ^Z and kill it or type blindly at it -- the text part of the screen is overlaid by the graphics display and will reappear when METAFONT exits. I consider this a bug in the SUNTOOLS implementation.) All of the utilities have been tested both on the VAX and SUN, and seem to work fine. At this point in time, I know of no bugs related to the porting process. If you encounter unusual behavior when trying to get things going on either a SUN or VAX (or port it to some other 4.2 system), I'd like to hear about it. Good luck. Paul Richards University of Illinois at Urbana-Champaign, Dept of Comp Sci USNAIL: 222 Digital Computer Lab 1304 W. Springfield Ave Urbana, IL 61801 UUCP: {pur-ee,convex,inhp4}!uiucdcs!richards ARPA: richards@uiuc.arpa CSNET: richards%uiuc@csnet-relay MABELL: (217) 333-8740