\documentstyle[texnames,11pt]{article}

\title{\METAFONT{} for Beginners\\{\normalsize  Second Draft}}

\date{}

\author{Geoffrey {\sc Tobin}\thanks{ecsgrt@luxor.latrobe.edu.au} \thanks{With 
three corrections from David {\sc Kastrup}
(dak@kaa.informatik.rwth-aachen.de).}}

\begin{document}

\maketitle

\subsection*{Scope}

This is not a tutorial in \METAFONT{}.  It is an attempted description of
how some of the pitfalls in running the program may, hopefully, be
avoided.


\subsection*{Reference}

``The \METAFONT{}book", by Donald Ervin {\sc Knuth}, published by the
American Mathematical Society and Addison Wesley Publishing Company.
First edition, 1986, covers \METAFONT{} 1.0.
Later editions cover \METAFONT{} 2.0 and above.
This file is based on the 1986 edition.\footnote {
Opinion:  I actually enjoy reading The \METAFONT{}book, whereas
The \TeX{}book confuses me no end.}


\subsection*{Motivation}

It's a common experience to have initial (and medial and final {\tt :-)} )
difficulty with running \METAFONT{}, and not all ``\TeX{}perts" are as
familiar with MF as they are with \TeX{}.  Still, nothing ventured,
nothing gained.  So let's be of good cheer, and get down to work.


\section{Overview}

\subsection{Font files}

\METAFONT{} is a program for making bitmap fonts for use by \TeX{}, its
viewers, printer drivers, and related programs.  It interprets a
drawing language with a syntax slightly like Pascal's.  The input can
be interactive, or from a source file.  \METAFONT{} source files are
usually suffixed ``.mf".  The output is a {\sc gf} (``generic font") file,
suffixed ``.gf", which contains the bitmap.  This may be compressed to
a {\sc pk} (``packed") font by the auxiliary program {\sf GFtoPK}.

A bitmap is all that's needed for large-scale proofs, as produced by
the {\sf GFtoDVI} utility, but for \TeX{} to typeset a font it needs a {\sc tfm}
(``\TeX{} Font Metric") file to describe the dimensions, ligatures and
kerns of the font.  \METAFONT{} can be told to make a {\sc tfm} file, by
turning on fontmaking.  Most output device modes (see part \ref{1b} below)
do this.

More detailed descriptions of {\sc tfm}, {\sc gf} and proof mode are found in
Appendices F, G, and H, respectively of ``The \METAFONT{}book".

The {\sc dvi} Drivers Standard, Level 0, draft 0.05, includes precise
definitions of the file formats of {\sc tfm}, {\sc gf} and {\sc pk} fonts.
That document is obtainable from such \TeX{} archives as
ftp.uni-stuttgart.de, where it is currently found as the several
files in the directory\\
 {\sf soft/\TeX{}/drivers/dvi-standard/level-0}.


\subsection{Base files and Modes} \label{1b}

The \METAFONT{} language contains two or three hundred primitives, which
are the commands preceded by an asterisk in the Index (Appendix I) to
The \METAFONT{}book.  From these we can build more complex operations,
using macros.  In \METAFONT{} macros have some of the desirable
characteristics of functions in other languages.  Collections of
macros can be stored in \METAFONT{} source files.

Base files are ``precompiled binaries" that \METAFONT{} loads faster than
it loads the original source files.

The plain base provides the commands that The \METAFONT{}book describes.
(See Appendix B of ``The \METAFONT{}book", if you have it around - maybe
a library has it - I'm learning from a copy borrowed from the local
university's library.)

When it starts, \METAFONT{} automatically loads\footnote{There 
are releases of \METAFONT{} that contain the plain base, and
so don't have to load it.  However, on most computers, including
personal computers, reading bases is so fast that such a ``preloaded"
base is unnecessary.}
the ``plain" base.
This is usually called ``plain.base".  In Karl Berry's web2c
distribution for unix, it's named ``mf.base".  Em\TeX{} for {\sc dos} calls it
``plain.bas", due to filename truncation.


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

The local modes file lists printers (and monitors), giving each a
font-making ``mode", containing a description of some refinements that
must be made in order to produce good-looking output.  For example,
how dark to make the characters.

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

\begin{verbatim}
    inimf 'plain; input local; dump'
\end{verbatim}

If using the em\TeX{} version of \METAFONT{} for a {\sc pc}, type:

\begin{verbatim}
    mf/i plain; input local; dump
\end{verbatim}

\subsection{Proof Mode}

The first obstacle to beware of is that plain \METAFONT{} uses ``proof"
mode by default.  (The \METAFONT{}book, page 270, defines this mode.)
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 {\bf not} produce a 
{\sc 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 {\sc dos}, ``.260"), and the ``failure" to
produce any {\sc tfm} file.


\subsection{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:
\begin{verbatim}
    mf myfont10
\end{verbatim}

This processes file ``myfont10.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:
\begin{verbatim}
    mf '\mode=localfont; input myfont10'
\end{verbatim} 


On MS-DOS, type it without the apostrophes:
\begin{verbatim}
    mf \mode=localfont; input myfont10
\end{verbatim} 

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


\subsection{Font Naming}

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


\subsection{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 \verb+\mine+ as
a font-selection command for ``myfont10.tfm", say:
\begin{verbatim}
    \font\mine=myfont10
\end{verbatim} 

Then to typeset ``Mary had a little lamb," in the ``myfont10" font, and
then to revert to the previous font, type
\begin{verbatim}
    {\mine Mary had a little lamb,}
\end{verbatim} 


\subsection{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:
\begin{verbatim}
    mf \mode=jumbo; mag=magstep(1); input myfont10
\end{verbatim}

to produce ``myfile10.tfm" (again!) and a {\sc gf} font, ``myfile10.360".

On unix, the csh and sh interpret semicolons, backslashes and
parentheses specially, so these will have to be 'quoted'.  Either
\begin{verbatim}
    mf '\mode=jumbo; mag=magstep(1);' input myfont10
\end{verbatim}
or
\begin{verbatim}
    mf '\mode=jumbo; mag=magstep(1); input myfont10'
\end{verbatim}
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.


\subsection{{\sf GFtoPK}}

\TeX{} uses only the {\sc tfm} file, which \METAFONT{} 
will produce if it's in a
font-making mode.  (The \METAFONT{}book, Appendix F.)  Most {\sc dvi} drivers
read the {\sc pk} font format, but \METAFONT{} makes a {\sc gf}
 (Generic Font) file.
So we need also to apply the ``{\sf GFtoPK}" utility:
\begin{verbatim}
    {\sf GFtoPK} myfile10.300gf
\end{verbatim}  
to produce the wanted ``myfile.300pk" (or, on {\sc dos}, ``myfile.pk") 
{\sc pk} font.


\subsection{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.


\subsection{The ``{\tt **}" prompt}

Instead of typing on the command line, as most \METAFONT{} programs will
permit, you are always allowed to type:
\begin{verbatim}
    mf
\end{verbatim}

Then mf displays a ``{\tt **}" prompt, to which you respond with the command
line arguments:
\begin{verbatim}
    \mode=localfont; mag=magstep(1); input fred
\end{verbatim}

In unix, this has the advantage that those pesky apostrophes are not
needed.  However, for shell scripts (and for batch files in {\sc dos}), the
command line is a boon.


\subsection{Using a different base}

Suppose that you made another base, ``joe.base", to replace plain.
Typing
\begin{verbatim}
    mf &joe
\end{verbatim}
ejects the ``plain" base, and loads the ``joe" base.

On some systems, the ``cm" base, for making the Computer Modern fonts
is loaded in this way:
\begin{verbatim}
    mf &cm
\end{verbatim}

On other systems, a separate program, ``cmmf", exists, which
automatically loads ``cm.base".  In ``web2c", cmmf is a link to the same
program as mf, and the program reads its own command line name to
determine which base to load first; thus, ``cmmf" loads ``cmmf.base",
which is web2c's usual name for the {\sc cm} base.


\section{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?

References for some of these points:

The \METAFONT{}book, chapter 5, ``Running \METAFONT{}", contains instructive
examples, and supposedly ``dangerous", but actually basic and useful,
notes.

In that chapter, and in chapter 7, ``Recovery from Errors", {\sc Knuth}
discusses the diagnosis of \METAFONT{}'s error messages.  I find this
perhaps the hardest part of the book - if not of using \METAFONT{}.


\subsection{Big fonts, but unwanted}\label{2a} 

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

MF will take {\bf anything} as an excuse to revert to {\bf proof mode}.  The
``3122" is a magstep 1 proof mode.  It's
\begin{verbatim}
    (1.2)^1 * 2601.72  = 3122.16  dots per inch.
\end{verbatim}

My intention was for \METAFONT{} on a PC to use an HP Laserjet mode in
place of proof 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.

Em\TeX{}'s \METAFONT{}, with plain.mf, defaults to proof mode.  However,
I usually want a local printer's font-making mode.  So to process
``pics.mf" correctly, I need to say:
\begin{verbatim}
    mf '\mode=localfont; input pics'
\end{verbatim}


\subsection{Consequences of Some Typing Errors on \METAFONT{}'s command line}\label{2b}

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 {\sc gf} font is wanted.

Here is the gist of what happens for various typing errors, when using
em\TeX{}'s ``mf186" on a 286 {\sc pc} to process ``pics.mf".

\begin{enumerate}
\item
\verb+mf186+  $\Longrightarrow$  \METAFONT{} will keep prompting for arguments:
\begin{verbatim}
    **
\end{verbatim}

We can type the contents of the command line here; for example, I can
now type ``pics".  In fact, even if you use the command line, the .log
(``transcript") file shows \METAFONT{} echoing its interpretation of the
command line to a  **  prompt.

\item  \verb+mf186 pics+  $\Longrightarrow$  proof mode:

\begin{verbatim}
    ! Value is too large (5184)
\end{verbatim}

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

\item  \verb+mf186 mode=localfont; input pics+  $\Longrightarrow$  misinterpretation:
\begin{verbatim}
    ! I can't find file `modes=localfont.mf'.
\end{verbatim}

So, ``modes" needs that backslash, otherwise mf thinks it's the start
of a source font's filename.  Backslash (``$\backslash$") and ampersand (``\&") are
escapes from this standard interpretation by \METAFONT{} of the first
argument.

\item  \verb+mf186 \mode=localfont input pics+  $\Longrightarrow$  weird effect:
\begin{verbatim}
    >> unknown string mode_name1.2
    ! Not a string
    <to be read again>
                      ;
    mode_setup-> ...ode)else:mode_name[mode]fi;
    l.6 mode_setup
                  ;
\end{verbatim}

Wow!  What a difference a semicolon can make!

\item \verb+mf186 \mode=localfont pics+  $\Longrightarrow$  almost nothing happens:
\begin{verbatim}
    ** \mode=localfont pics

    *
\end{verbatim}

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

\item  \verb+mf186 \mode=localfont; pics+  $\Longrightarrow$

    Same as 5.

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

\item  \verb+mf186 &plain \mode=localfont; input pics+  $\Longrightarrow$

    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?
\end{enumerate}

\subsection{Finding the Fonts}\label{2c}

Finding the fonts (*.mf, *.tfm, *.gf, *.pk) trips up \TeX{}, \METAFONT{}, {\sf 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 {\sc mf}, {\sc gf} and
{\sc pk} font files.

Environment variables can be tricky.  For example, em\TeX{}'s font-making
automation program ``mfjob" cannot make fonts in the current directory
unless both ``." and ``.." are added to MFINPUT.  This was not
documented.

Also, some popular \TeX{} output drivers, such as the em\TeX{} drivers on
{\sc dos} and OS/2, and Tomas Rokicki's ``dvips", which has been ported to
many systems, make missing fonts automatically - provided that they
can find the necessary mf source files.  Again, making fonts in the
current directory can require some tweaking.

On unix, dvips uses a shell script ``MakeTeXPK" (on {\sc dos}, a batch file
``MakeTeXP"), which creates a temporary directory, which it then
changes to.  This can cause \METAFONT{} not to find mf font sources
in what {\bf used} to be the current directory.  Gert W. {\sc Bultman}
(bultman@dgw.rws.nl) has suggested adding a line to MakeTeXPK:
\begin{verbatim}
    set MFINPUTS=${MFINPUTS}:`pwd`;  export MFINPUTS
\end{verbatim}
to add the current directory to the search path, before the change to
the temporary directory.

\section{Conclusion}

\METAFONT{}, like \TeX{} and many another ``portable" program of any
complexity, merit the warning:  ``Watch out for the first step."

It's my hope that a document like this 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

\end{document}

