🚀 go-pugleaf

METAFONT for Beginners.    Sun, 6 Sep 1992.    Geoffrey Tobin.
-----------------------

It's a common experience to have initial (and medial and final :-)
difficulty with running MetaFont, and not all "TeXperts" are as
familiar with MF as they are with TeX.  So let's be of good cheer,
and get down to work.


1.  Overview.


1a.  Base files and Modes.

Plain Metafont loads a so-called "base" file, "plain.base", when it
starts.  The plain base defines all sorts of useful things.  (See
Appendix B of "The METAFONTbook", if you have it around - maybe a
library has it - I'm learning from a copy I've borrowed from the
local university's library.)

The plain base is made from a Metafont file named "plain.mf" and,
commonly, from some other file, often called "local.mf" or "modes.mf".

To each printer, the local or modes file associates a fontmaking
"mode", which is a description of some refinements that must be made
in order to produce good-looking output.  For example, how dark to
make the characters.

Base files are "precompiled binaries" that MetaFont loads faster than
it loads font source files like "plain.mf" and "local.mf".

If you want to make a base, you need a variant of the MetaFont program
called "inimf".  (See The METAFONTbook, p 279.)  For example,
"plain.base" can be made in unix by typing:

    inimf 'plain; input local; dump'

If using the emTeX version of MetaFont for a PC, type:

    mf/i plain; input local; dump


1b.  Proof Mode.

The first obstacle to beware of is that Metafont uses "proof" mode by
default.  That means writing unmagnified font files with a resolution
of 2601.72 dots per inch (dpi); that's 36 pixels per point.  (One
point is 1/72.27 of an inch.)  Proof mode does NOT produce a TFM file.

What good is proof mode, and why is it the default?  Proofs are blown
up copies of characters used by font designers to judge whether they
like the results of their work.  Naturally, proofs come first, and
normal sized character production later - if you're a font designer.

So there are two clues that proof mode is on:  font files with
extensions like ".2602gf" (or on DOS, ".260"), and the "failure" to
produce any TFM file.


1c.  Localfont Mode.

When using a stable font, we don't want proof mode, we want our local
printer's mode.  Usually, Metafont is installed with a "localfont"
assigned in the local/modes file.  On our department's Sun Network, we
have assigned "localfont:=CanonCX".  We use Karl Berry's "modes.mf",
which contains modes for many, many printers.  We chose the CanonCX
mode because "modes.mf" recommends it for Apple Laserwriters and HP
Laserjets, which we use.

On some installations of Metafont, if the name of a Metafont source
file is typed on the command line, then "localfont" will be used:

    mf myfont10

This processes file "myfont.mf", and should produce a GF font file,
"myfont10.300gf" and a TFM file, "myfont10.tfm".

But other installations need the local font specified.  On unix:

    mf '\mode=localfont; input pics'

On MS-DOS, type it without the apostrophes:

    mf \mode=localfont; input pics

These command lines are a bit long, very often used, and rather
intolerant of mistakes (see section 2c below), so you might type the
repetitive parts into a unix shell script or a DOS batch file, as
appropriate.


1d.  Font Naming.

By the way, if you plan to modify a CM font, you must give it a new
name.  This is an honest practice, and will avoid later confusion.


1e.  Using a New Font in TeX.

To use a new font in a TeX document, select it specifically.  Example:
in a TeX macro file, or in a LaTeX style file, to define "\mine" as
a font-selection command for "myfont.tfm", say:

    \font\mine=myfont10

Then to typeset "Mary had a little lamb," in the "myfont10" font, and
then to revert to the previous font, type

    {\mine Mary had a little lamb,}


1f.  Magnification (and Resolution).

Now suppose that you want myfont10 to be magnified, say to magstep 1
(magnified by 1.2), for a "jumbo" printer.  Assuming that the
local/modes file has a mode for the jumbo printer, you need then to
run Metafont as follows.  On DOS:

    mf \mode=jumbo; mag=magstep(1); input myfont10

to produce "myfile10.tfm" (again!) and a GF font, "myfile10.360".

On unix, the csh and sh interpret semicolons, backslashes and
parentheses specially, so these will have to be 'quoted'.  Either

    mf '\mode=jumbo; mag=magstep(1);' input myfont10
or
    mf '\mode=jumbo; mag=magstep(1); input myfont10'

will do.  This will produce "myfile10.tfm" and the GF font
"myfile10.360gf".

The "360" is "300 * 1.2", indicating the magnification.  A 360 dpi
font can be used either as a magnification 1.2 font on a 300 dpi
printer or as a normal sized font on a 360 dpi printer.


1g.  GFtoPK.

TeX uses only the TFM file, which Metafont will produce if it's not in
proofing mode.  Most DVI drivers read the PK font format, but Metafont
makes a GF (Generic Font) file.  So we need also to apply the "gftopk"
utility:

    gftopk myfile10.300gf

to produce the wanted "myfile.300pk" (or, on DOS, "myfile.pk") PK
font.


1h.  Storing the Fonts.

Now we have the fonts, where do we store them?  TeX and Metafont are
compiled with default locations written in.  These can be overridden
by certain environment variables.  The names of these variables differ
between systems, but on unix they might be "TEXTFMS" and "TEXFONTS",
for example.  You can find out what environment variables you now
have, by typing "set".  (This works in both unix and DOS.)

If you want TeX and Metafont to find files in the current directory,
you must have "." in the paths they use, either compiled into TeX and
Metafont, or in the environment variables that they read.  (This is
true for both unix and DOS.)

On the other hand, you may be content with your new font, and you may
have write access to the place where most of the fonts are stored.  In
that case, copy your font to there.  There will be a place for the TFM
files, and another for the PK files.  It's up to you or your local
system administrator(s) to know where these directories are, because
their names are very locale dependent.


2.  WHAT WENT WRONG?

The complexity of wrong things far exceeds that of things intended.

Small typing errors are so common, and yet undocumented (why are
common mistakes not documented?), that I thought I'd list several that
have tripped me up on innumerable occasions.  After all, why reinvent
the car crash?


2a.  Base Loading.

MetaFont will load the "plain" (or in Web2c Unix TeX, "mf.base"), if
you type:

    mf fred

But if you omit the argument,

    mf

then _no_ base is preloaded, so "mf" is then equivalent to "virmf",
which only understands MetaFont's primitives, which are the commands
preceded by an asterisk in the Index to The METAFONTbook.

Then mf displays a "**" prompt, to which you may have to type
everything in fine detail:

    ** &plain \mode=localfont; mag=magstep(1); input fred

In unix, this has the advantage that those pesky apostrophes are not
needed.  The "&" tells MetaFont that "plain" refers to "plain.base",
not to "plain.mf".


2b.  Big fonts, but unwanted.

Recently, I found myself accidentally producing fonts with extensions
like "3122gf".  How?

MF will take _anything_ as an excuse to revert to PROOFING MODE.  The
"3122" is a magstep 1 proofing mode.  It's

    (1.2)^1 * 2601.72  = 3122.16  dots per inch.

My intention was for MetaFont on a PC to use an HP Laserjet mode in
place of proofing mode.  However, MetaFont's command line resembles
the law:  every stroke of the pen is significant.  What I had
forgotten was that on my setup, "localfont" must be explicitly
requested.

EmTeX's MetaFont, with plain.mf, defaults to proofing mode.  However,
I usually want a local printer's fontmaking mode.  So I need to say:

    mf '\mode=localfont; input pics'


2c.  Consequences of Some Typing Errors on MetaFont's command line.

Consider a source file "pics.mf" that contains "mag=1200/1000;", so it
is automatically scaled by 1.2 (ie, by magstep 1).  If the target
printer has 300 dpi, then a 360 dpi GF font is wanted.

Here is the gist of what happens for various typing errors, when using
emTeX's "mf186" on a 286 PC to process "pics.mf".

1)  mf186  ->  mf behaves as virmf:

    **

We can type the contents of the command line here.  In fact, MetaFont
usually echoes its interpretation of the command line to its own **
prompt, as the .log ("transcript") file shows.

2)  mf186 pics  ->  proofing mode:

    ! Value is too large (5184)

No tfm is produced, and the gf file has resolution 3122 dpi.  (3121.72
dpi, to be precise.)

3)  mf186 mode=localfont; input pics  ->  misinterpretation:

    ! I can't find file `modes=localfont.mf'.

So, "modes" needs that backslash, otherwise mf thinks it's the start
of a source font's filename.

4)  mf186 \mode=localfont input pics  ->  weird effect:

    >> unknown string mode_name1.2
    ! Not a string
    <to be read again>
                      ;
    mode_setup-> ...ode)else:mode_name[mode]fi;
    l.6 mode_setup
                  ;

Wow!  What a difference a semicolon can make!

5)  mf186 \mode=localfont pics  ->  almost nothing happens:

    ** \mode=localfont pics

    *

There's the echo I mentioned.  From the lack of activity, pics
evidently needs to be "input".

6)  mf186 \mode=localfont; pics  ->

    Same as 5.

So, yes, when the mode is specified, we need "input" before "pics".

7)  mf186 &plain \mode=localfont; input pics  ->

    Works.

Just as without the "&plain", it writes a GF file, "pics.360gf", which
is correct.  (DOS truncates the name to "pics.360".)  So, redundancy
seems okay.  Does it waste time, though?


2d.  Finding the Fonts.

Finding the fonts (*.mf, *.tfm, *.gf, *.pk) trips up TeX, MF, GFtoPK
and the output drivers continually.  "pics.tfm" needs to be put where
TeX will look for TFMs, so I needed to ensure that "." was in the
appropriate path environment variable.  Similarly for the MF, GF and
PK font files.

Environment variables can be tricky.  For example, emTeX's fontmaking
automation program "mfjob" cannot make fonts in the current directory
unless both "." and ".." are added to MFINPUT.  This was not
documented.


3.  Conclusion.

MetaFont, like TeX and many another "portable" program of any
complexity, justify the warning:  "Watch out for the first step."

It's my hope that this document like this one may help to prevent
domestic accidents involving MetaFont, and so contribute to making the
task of using and designing meta-fonts an enjoyable one.  My brief
experience with MetaFont suggests that it can be so.


All the Best!
Geoffrey Tobin