%
% LATEX $VER: EnglishDoc.ltx 1.3 (19.11.1993)
%
% DESCRIPTION: This LaTeX file contains the complete description and
%              documentation of the Amiga implementation of MetaFont 2.71
%              for English speaking users.  German translation available.
%
% DATE: 05.11.1993 (V1.0)
%
% AUTHOR: Andreas Scherer
%         Abt-Wolf-Straße 17
%         96215 Lichtenfels
%         Germany
%
% CHANGES: 06.11.1993: Description of all utilities (V1.1)
%          07.11.1993: Corrections (V1.2)
%          19.11.1993: Further corrections (V1.3)
%
% COPYRIGHT: (c) 1993 Andreas Scherer
%
% Permission is granted to make and distribute verbatim copies of the
% electronic form of this document provided that the copyright notice
% and this permission notice are preserved on all copies.
%
% Permission is granted to copy and distribute modified versions of this
% document under the conditions for verbatim copying, provided that the
% entire resulting derived work is distributed under the terms of a
% permission notice identical to this one.

\documentstyle{article}

\language=0 % USenglish in my multilingual TeX configuration

\newfont{\mc}{cmr9} % Medium caps
\newfont{\smallcaps}{cmcsc10} % Caps-small-caps
\newfont{\manual}{manfnt} % METAFONT in text
\newfont{\bigmanual}{manfnt scaled \magstep3} % METAFONT in titles

\newcommand{\MetaFont}{{\manual META}\-{\manual FONT}}
\newcommand{\BigMetaFont}{{\bigmanual META}\-{\bigmanual FONT}}
\newcommand{\GFtoDVI}{{\mc GF}to{\mc DVI}}
\newcommand{\GFtoPK}{{\mc GF}to{\mc PK}}
\newcommand{\GFtype}{{\mc GF}type}
\newcommand{\MFT}{{\mc MFT}}
\newcommand{\PKtoGF}{{\mc PK}to{\mc GF}}
\newcommand{\PKtype}{{\mc PK}type}
\newcommand{\PASCAL}{{\smallcaps Pas\-cal}}
\newcommand{\IniMF}{Ini{\mc MF}}
\newcommand{\VirMF}{Vir{\mc MF}}
\newcommand{\CallMF}{Call{\mc MF}}

\title{\BigMetaFont\ for the {\sl AMIGA}\\
  \medskip Documentation of version 2.71\bigskip}

\author{Andreas Scherer\\
  Abt-Wolf-Stra{\ss}e 17\\
  96215 Lichtenfels\\
  Germany\bigskip}

\begin{document}

\maketitle

\begin{abstract}
This document describes a new implementation of \MetaFont~2.71 for the
Commodore Amiga.  \MetaFont\ is the name of a computer font generation
system invented by Prof.~Donald E. Knuth of Stanford University.  It reads
text files prepared with `programs' that specify the outline of characters
in fonts of type, graphical symbols, or other elements for printing high
quality documents.  Typesetting systems like \TeX\ make use of the font metric
information produced by \MetaFont\ and printer drivers or screen previewers
make use of the pixel information as to where to put the `ink.'  The usage
of the associated programs is described to some detail, but no introduction
to the \MetaFont\ language itself is given.  Refer to the bibliography
(section~\ref{bibliography} of this text) for detailed information about
\MetaFont\ programming.
\end{abstract}

\vfill\noindent
Copyright \copyright\ 1993 Andreas Scherer

\bigskip\noindent
Permission is granted to make and distribute verbatim copies of the
electronic form of this document provided that the copyright notice
and this permission notice are preserved on all copies.

\smallskip\noindent
Permission is granted to copy and distribute modified versions of this
document under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

\newpage
\tableofcontents

\newpage
\section{Copyright}
The \MetaFont\ program and the associated utilities are copyright
\copyright~1984 by Donald E. Knuth.  All rights are reserved.  The
complete {\tt WEB} source code is published as~\cite{knuth.d}.

This new implementation of \MetaFont~2.71 for the Commodore Amiga is
declared to be {\mc FREEWARE}.  All rights are reserved.  You may use,
copy, and distribute the package in complete archived or installed form
and for a nominal fee for media and shipping only.

Although considerable effort has been expended to make the \MetaFont\
program correct and reliable, no warranty is implied;  the author and the
implementor disclaim any obligation or liability for damages, including but
not limited to special, indirect, or consequential damages arising out of
or in connection with the use or performance of this software.

This work has been a ``labor of love'' and both the author and the
implementor hope that users enjoy it.

Please send comments, suggestions, bug reports, etc., to Andreas Scherer,
Abt-Wolf-Stra{\ss}e 17, 96215 Lichtenfels, Germany.  A~``developer's kit''
containing the complete source code with all modifications and enhancements
is available at this address. (See section~\ref{source} for details.)

\bigskip
\noindent\TeX\ is a trademark of the American Mathematical Society.

\noindent\MetaFont\ is a trademark of Addison-Wesley Publishing Company.

\noindent Commodore is a registered trademark of Commodore Electronics Limited.

\noindent Amiga, Amiga{\mc DOS}, Amiga Kickstart, and Amiga Workbench are
registered trademarks of Commodore-Amiga Incorporated.

\noindent {\mc SAS} and {\mc SAS/C} are registered trademarks of {\mc SAS}
Institute Incorporated.

\section{System requirements}
The minimum configuration tested with this implementation of \MetaFont\
was a Commodore Amiga~2000 running the standard 68000~Motorola processor
and 2~{\mc MB} of Chip{\mc RAM} and 4~{\mc MB} of Fast{\mc RAM}, although
a total of only 1.5~{\mc MB} of {\mc RAM} were actually used by the default
configuration.  Memory requirement may increase depending on the font to be
created and the settings in the \MetaFont\ configuration.
(See section~\ref{memory}.)
The operating system was Kickstart~37.175 and Workbench~38.36.  All
programs included in this package are capable of running under version~1.3
of the operating system.  Only the online display of \MetaFont\ requires
version~2, because of the use of some advanced graphics routines, but
this feature is protected when used with version~1.3.

There are special versions of the \IniMF\ and \VirMF\ programs provided for
advanced hardware configurations like the Amiga~3000 and Amiga~4000 or
Amigas with accelerator boards.  These two programs rely on features of
the 68020~Motorola processor not present in the 68000~processor.  They
will run approximately twenty to thirty percent faster, but they will
crash on non-accelerated Amigas!  All other programs that come with this
package are compiled for use on any standard Amiga configuration.

\MetaFont\ is a large system intended for large tasks, so this is no
greasy kids' stuff!  The creation of {\tt cmr10} for the 300~dpi DeskJet
printer driver of Pas\TeX\ can be as quick as 48~seconds on a 50~{\mc MH}z
68030 accelerator board with a coprocessor and sufficient 32~bit Fast{\mc RAM}
but as slow as 10~minutes and 5~seconds on a standard 7~{\mc MH}z Amiga with
slow 16~bit {\mc RAM}, although the programs are capable of running on
both configurations.

\section{Compatibility}
This is \MetaFont~2.71 for the Commodore Amiga.  It is fully compatible
with the original implementation by Donald E. Knuth and has passed the
{\mc TRAP} test as of January 25, 1992 gracefully.  Only permissible
differences as described in {\tt trapman.tex} were encountered.
{\tt diff} files documenting the latest run of the {\mc TRAP} test will
be made accessible by the implementor on request.
(See section~\ref{source} for details.)

Also included are \GFtoDVI\ version~3.0 (October, 1989), \GFtoPK\ version~2.3
(July, 1990), \GFtype\ version~3.0 (April, 1989), \MFT\ version~2 (October,
1989), \PKtoGF\ version~1.0 (January, 1988), and \PKtype\ version~2.3
(November, 1989).

\section{Installation}
\label{install}
\subsection{Extracting the archive}
This ``\MetaFont\ user's kit'' is a self-contained system; everything you
need for the creation of beautiful fonts for \TeX\ is here.  This subsection
describes the various subdirectories and their contents.  Normally this
package should come in the form of an {\tt LHA} archive.  It will contain
a working installation of all programs and scripts, except that some
environmental settings have to be installed by hand.  Sorry, there is
no `Installer' script, but installation is really very easy.  First you
have to extract the files by the command
\begin{verbatim}
   > LHa x MetaFont[.lha] <path or device for installation>
\end{verbatim}
(You should have the {\tt LHa} program to do this.  If you don't, look for
Fish Library Disk~715 for the current version.\footnote{But don't send any
money to Stefan Boberg, because you won't get what you want!})  A root
directory {\tt MetaFont} will be created and will contain the
complete archive in convenient subdirectories described below.  You will
need less than 3~{\mc MB} of free disk space to install the complete
\MetaFont\ system.
\begin{description}
\item{{\tt MetaFont:bases}:} This directory is the home of the `base'
files that \MetaFont\ reads at high speed at the beginning of a run.  Here
you will find the file {\tt plain.mf} (version~2.71) and some startup files
for `plain' and `cm.'  New base files should be created or copied herein.
The environment variable {\tt MFBASES} should contain an entry pointing to
this directory in order that \MetaFont\ can find them.  (See
section~\ref{environment} for details about the environment variables
recognized by \MetaFont.)

\item{{\tt MetaFont:bin}:} The most important part of this package are the
binary files of the programs for \MetaFont\ and the associated utilities.
You should tell the operating system to look for the programs here by adding
the installation path to the {\tt PATH} environment variable.  A more
detailed description about running the programs will be given in the next
section~\ref{running}.

\item{{\tt MetaFont:config}:} The present implementation of \MetaFont\ is
capable of resetting the memory configuration on startup in case the inner
settings are too meager for a given task and \MetaFont\ aborts its run with
the error message {\tt METAFONT capacity exceeded, sorry...}  The configuration
setup file {\tt mfmemory.config} contains lines of the form
\begin{verbatim}
   set memmax             65530     % default 30000
   set screenheight         200     % default  1024
   set <internal size> <user value> % default <value>
\end{verbatim}
You may change the settings (in decent ranges!) or delete some lines from
the file, thus resetting to internal values (given in the `default'
column).  The environment variable {\tt MFCONFIG} should contain an entry
that points to this directory.  (See section~\ref{environment} for
details about the environment variables recognized by \MetaFont\ and
section~\ref{memory} for details about the memory configuration.)

\item{{\tt MetaFont:doc}:} At least this directory you have already
visited if you are reading this file.  Here you find the documentation
for \MetaFont~2.71 in both German and English.  The \LaTeX\ source files
must be present, the {\tt dvi}-output may have been deleted due to space
limitations, but you can recreate it with a running \TeX\ installation;
no special macros or unusual fonts are necessary for this file.

\item{{\tt MetaFont:inputs}:} This directory is for \MetaFont\ programmers
and system administrators only.  It contains text files necessary for the
creation of new or changed base files and the complete Computer Modern font
family, the standard for most \TeX\ users.  You may add your own font programs
here. \MetaFont\ will find them when the environment variable {\tt MFINPUTS}
has an entry for this directory.  (See section~\ref{environment} for details
about the environment variables recognized by \MetaFont.)

\item{{\tt MetaFont:pool}:} \MetaFont\ (as well as \TeX) is a \PASCAL\ program,
so it has to use a special method of string handling due to restrictions implied
by this programming language.  The `pool' file {\tt mf.pool} contains all
texts and messages \MetaFont\ is willing to print to your screen or the
log file.  It was automatically generated by {\tt TANGLE} in the process
of compilation and should not be deleted or changed in any way.

\item{{\tt MetaFont:rexx}:} This directory contains the public domain
package `\CallMF' (version~1.0), consisting of three ARexx scripts by Georg
He{\ss}mann, Martin Bok\"amper, J\"org H\"ohle, and Ulrich Wisser.  It is
very useful in connection with He{\ss}mann's Pas\TeX\null.  Both the previewer
and the printer driver refer to `\CallMF' in case a font is missing at a
certain size.  The ARexx scripts will create the missing fonts automatically
or in batch mode.  You will find a documentation of `\CallMF'~\cite{hessmann}
in a subdirectory of {\tt rexx}, so no more information about installation
and usage of `\CallMF' is given at this place.
\end{description}

\subsection{Controlling memory sizes}
\label{memory}
Originally \MetaFont\ (and \TeX) is a \PASCAL\ program not capable of
dynamically controlling its memory allocation.  Normally to change
\MetaFont's memory size you need to recompile the source code with changed
internal settings.  However, you need no longer fear the ``{\tt ask a wizard
to enlarge me}'' message, you can do some wizardry yourself!  The present
implementation is done with the help of the {\tt Web2C} language converter
from the {\mc UNIX} distribution and so it is very convenient to include
a special feature for controlling the internal variables at runtime.

\MetaFont\ uses an extra path and environment variable {\tt MFCONFIG}.
(See section~\ref{environment} for further details on the environment.)
The \IniMF\ and \VirMF\ programs will search these directories for a file
called {\tt mfmemory.config}, which is expected to contain instructions,
one per line, of the form
\begin{verbatim}
   set memmax       100000
   set screenheight    400
   set scalefactor       2
\end{verbatim}
The example file given in the {\tt config} directory `sets' what are my
present standard configuration, slightly higher than the internal defaults.
Not all settings need to be given in the file.  Note that you can't just
set everything to the maximum -- that would require more than 8~Giga bytes
of Fast{\mc RAM}!\footnote{If you have that much, I don't believe you!}

If you create a standard base file with \IniMF, any change to the
configuration {\tt mfmemory.config} will be acceptable for \VirMF\ in
connection with this specific base, except changes to {\tt memtop}.  This
will result in the \MetaFont\ message ``{\tt(Fatal base file error; I'm
stymied)},'' indicating that this base was produced with a different \IniMF.

Here is a complete list of all parameters allowed in the configuration
file, their internal defaults and some rules for their minimum and maximum
values:
\begin{center}
\begin{tabular}{|l|r|r|l|}\hline
  Setting & Default & Maximum & Purpose\\\hline
  {\tt memmax} & 30000 & {\tt maxhalfword} & Size of main storage\\
  {\tt maxinternal} & 100 & ${}\leq259774$ & Number of internals\\
  {\tt bufsize} & 500 & {\tt maxhalfword} & Input characters\\
  {\tt errorline} & 72 & {\tt maxhalfword} & Error context width\\
  {\tt halferrorline} & 42 & {\tt<errline$-15$} & First error line\\
  {\tt maxprintline} & 79 & $\geq60$ & Output text line width\\
  {\tt screenwidth} & 768 & 4095 & Width of display screen\\
  {\tt screenheight} & 1024 & 4095 & Height of display screen\\
  {\tt stacksize} & 30 & 300 & Number of input sources\\
  {\tt maxstrings} & 2000 & {\tt maxhalfword} & Number of strings\\
  {\tt poolsize} & 32000 & {\tt maxhalfword} & Characters in strings\\
  {\tt movesize} & 5000 & 10000 & Storage for octant moves\\
  {\tt maxwiggle} & 300 & 1000 & Autorounded points per cycle\\
  {\tt gfbufsize} & 100 & 4096 & Size of the output buffer\\
  {\tt pathsize} & 300 & 1000 & Number of knots in a path\\
  {\tt bistacksize} & 785 & 785 & Stack for bisection algorithm\\
  {\tt headersize} & 25 & 100 & Number of {\mc TFM} header words\\
  {\tt ligtablesize} & 5000 & 32510 & Ligature/kern steps\\
  {\tt maxkerns} & 500 & 1000 & Distinct kerns\\
  {\tt maxfontdimen} & 50 & 100 & Number of `fontdimen's\\
  {\tt memtop} & 30000 & {\tt memmax} & Largest memory index\\
  {\tt scalefactor} & 1 & 10 & Display is `{\mc SF}' times reduced\\
  {\tt maxinopen} & 6 & 20 & Number of input files\\
  {\tt paramsize} & 150 & 1000 & Macro parameters\\\hline
\end{tabular}
\end{center}
Some of these values are internally multiplied by a factor of~4 or~8, so
the actual number of bytes needed for a specific setting is a little bit
hard to describe.  As long as you don't encounter problems, I recommend
that you stick to the defaults or the standard configuration file provided
with this package.  In most cases of insufficient memory size, the only
value to increase is {\tt memmax}, and this was actually tested up to the
horribly high value~750,000 on my Amiga~2000 with 8~{\mc MB} of 32~bit
Fast{\mc RAM}.

You may control the size of the online display by changing the values for
{\tt screenwidth}, {\tt screenheight}, and {\tt scalefactor}.  The meaning
of the first two should be clear, just keep in mind, that {\tt
screenheight} denotes the {\em interlaced\/} setting, although
non-interlaced screenmodes will automatically be detected and
taken care of, i.e., only half as much pixel lines will actually be drawn.
And the two values don't set the size of the window, but the respective
{\tt innerwidth} and {\tt innerheight}.  The {\tt scalefactor} is a
reduction factor, i.e., the online display will be reduced by this factor
in both its width and height.  To make sensible use of this feature, the
{\tt plain.base} provided with this package was compiled with the
internal settings
\begin{verbatim}
   screen_rows:=4095; screen_cols:=4095; % infinity
\end{verbatim}
defined in my printer modes file.  When drawing on screen \MetaFont\ uses
the smaller value of {\tt screenheight} and {\tt screen\_rows} respectively
{\tt screenwidth} and {\tt screen\_cols}, so actually the configuration
overrides the internal settings.

\subsection{Setting up the environment}
\label{environment}
\MetaFont\ acknowledges a couple of environment variables in the course of
its file searching algorithm, for the `{\tt E}' feature to start your
system editor in case of an error, and for setting up the online display.
The \IniMF\ and \VirMF\ programs use multiple search paths when looking for
command base files, the configuration file {\tt mfmemory.config}, font
description programs, and the text pool file {\tt mf.pool}.  Either you
use the system call ``{\tt SetEnv <variable> <setting>}'' to introduce your
personal system configuration or you keep the internal defaults.  Here is
a list of the four path environments, their default settings and what
\MetaFont\ expects to find in the respective directories.

\begin{center}
\begin{tabular}{|l|l|l|}\hline
  Environment    & Default setting    & Files\\\hline
  {\tt MFBASES}  & {\tt ",MF:bases"}  & {\tt *.base} dump files\\
  {\tt MFCONFIG} & {\tt ",MF:config"} & {\tt mfmemory.config}\\
  {\tt MFINPUTS} & {\tt ",MF:inputs"} & {\tt *.mf} program files\\
  {\tt MFPOOL}   & {\tt ",MF:pool"}   & {\tt mf.pool} string file\\\hline
\end{tabular}
\end{center}

The comma in these defaults denotes the current directory as the first
entry, i.e., if you want to search in `{\tt RAM:}' first, you could say
\verb/"RAM:,,MF:inputs"/, thus making the current directory the second
search path.  If the environment variables are not set by the `SetEnv'
function call the internal defaults will become active and the current
directory is always search first, so you may want to keep them.

In case of an error or an interruption, when \MetaFont\ prompts you with
a question mark you may answer by typing `{\tt e}' (or `{\tt E}'), thus
invoking your text editor.  This feature is controlled by the {\tt MFEDIT}
environment variable that holds a calling sequence to bring up your
preferred system editor in the currently processed file (not necessaryly
the file you called \MetaFont\ with) and in the offending line.  Specify
any program call or script that brings up your editor in file `\verb/%s/'
and line `\verb/%d/.'  The default setting is as follows, it invokes the
{\tt MEmacs} editor provided with the operating system:
\begin{verbatim}
   EDITOR "MEmacs goto %d %s"
\end{verbatim}
You will find some ARexx scripts suitable for the Cygnus Ed Professional
editor in the {\tt rexx} directory.  If you want to use them, simply set
the environment variable {\tt MFEDIT} to the (string) value
\begin{verbatim}
   "rx MF:rexx/MFEdit.rexx %s %d"
\end{verbatim}
The second script {\tt NameStruc} should be placed in the {\tt REXX:}
directory, because it is called directly from within {\tt MFEdit.rexx}.

Also there is an online display feature as described in the `\MetaFont
book' by Don Knuth~\cite{knuth.c}.  As it makes use of some advanced
library functions not present in older versions of the Amiga operating
system, it will work only with Amiga{\mc DOS}~2.0 and higher (sorry).  To
activate this feature, set the environment variable {\tt MFWTERM} to the
value {\tt AMITERM} and every proof or smoke mode run will display its
results on your screen.

\section{Running the programs}
\label{running}
\subsection{Creating new bases with IniMF}
Although there is a {\tt plain.base} file in this package, you may want to
create additional base files that include other \MetaFont\ commands than
the default set described in the `\MetaFont book'~\cite{knuth.c}.  For this
purpose there is the \IniMF\ program, capable of creating such binary bases
for high-speed inclusion.  If you call \IniMF\ from the {\mc CLI} (command
line input, the shell) without an argument, it will prompt you with two
asterisks, meaning ``\MetaFont\ is all geared up for action, please type a
file name to continue.''
\begin{verbatim}
   > IniMF
   This is METAFONT, C Version 2.71 (INIMF)
   **
\end{verbatim}
If you follow the concept proposed here, it is very easy to do the next
step.  Answer the \MetaFont\ prompt with the name of an ``initialization
program'' like {\tt plain.inimf} or {\tt cm.inimf} and the rest will be
done automatically, resulting in a new base file {\tt plain.base} or {\tt
cm.base}.  Or you can type in consecutive {\tt input} commands to load
multiple files for inclusion in the base file.  The last command should
be {\tt dump}; this will tell \IniMF\ to create the compressed command
file and to terminate.

Alternatively you may type a one-liner like
\begin{verbatim}
   > IniMF plain.inimf
\end{verbatim}
and the results will be exactly the same as above.

\subsection{Creating new fonts with VirMF}
\label{examples}
The production version of \MetaFont\ is called `\VirMF' and is slightly
different to \IniMF\null.  It is designed for high-speed production runs and
is incapable of creating base files, but it can read such command bases.  Just
like with \IniMF\ you have two possibilities to call \VirMF\null.  If you just
type its name (and if the operating system knows where to find the program),
\MetaFont\ will prompt you for an interactive dialog.
\begin{verbatim}
   > VirMF
   This is METAFONT, C Version 2.71
   **
\end{verbatim}
You may answer this prompt with any valid command, assuming `plain' base
preloaded as described in the `\MetaFont book'~\cite{knuth.c}.

For an easy beginning try the following (quoted from page~31 of the
`\MetaFont book'~\cite{knuth.c}).  Type `\verb/\relax/'---that's
backslash, {\tt r}, {\tt e}, {\tt l}, {\tt a}, {\tt x}---and hit
$\langle$return$\rangle$ (or whatever stands for ``end-of-line'' on
your keyboard).  \MetaFont\ is all geared up for action, ready to make
a big font; but you're saying that it's all right to take things easy,
since this is going to be a real simple run.  The backslash means that
\MetaFont\ should not read a file, it should get instructions from the
keyboard; the `{\tt relax}' means ``do nothing.''

The machine will respond by typing a single asterisk: `{\tt *}'.  This
means it's ready to accept instructions (not the name of a file).  Type the
following, just for fun:
\begin{verbatim}
   drawdot (35,70); showit;
\end{verbatim}
and $\langle$return$\rangle$---don't forget to type the semicolons along
with the other stuff.  A more-or-less circular dot should now appear on
your screen!  And you should also be prompted with another asterisk.  Type
\begin{verbatim}
   drawdot (65,70); showit;
\end{verbatim}
and $\langle$return$\rangle$, to get another dot.  (Henceforth we won't
keep mentioning the necessity of $\langle$return$\rangle$ing after each
line of keyboard input.)  Finally, type
\begin{verbatim}
   draw (20,40)..(50,25)..(80,40); showit;
   shipit; end.
\end{verbatim}
This draws a curve through three given points, displays the results, ships
it to an output file, and stops.  \MetaFont\ should respond with
`\verb/[0]/', meaning that it has shipped out a character whose number is
zero, in the ``font'' just made; and it should also tell you that it has
created an output file called `{\tt mfput.2602gf}'.

Alternatively you may specify one or more arguments on the command line
when calling \VirMF\null.  The first argument may be the name of an alternative
base file by prepending a \verb/&/ sign (as in \verb/&plain/) and there may
be a string of commands that will be executed after the base has been
installed.  For example, if you want to create a font at a specific
resolution, type something like the following:
\begin{verbatim}
   > VirMF &plain "\mode:=previewer; mag:=magstep2; input cmr10"
\end{verbatim}
You have to type the quotation marks because of the semicolons.  They have
a special meaning for the Amiga operating system.  This command will create
the standard text font {\tt cmr10} for the screen previewer at resolution
100~dpi but magnified twice, so the resulting font will get the name {\tt
cmr10.144gf} and \MetaFont\ will write the following text to your screen
(and into the log file).
\begin{verbatim}
   This is METAFONT, C Version 2.71
   (...cmr10.mf (...cmbase.mf) (...roman.mf (...romanu.mf
   [65] [66] [67] [68] [69] [70] [71] [72] [73] [74] [75]
   [76] [77] [78] [79] [80] [81] [82] [83] [84] [85] [86]
   [87] [88] [89] [90]) (...romanl.mf [97] [98] [99] [100]
   [101] [102] [103] [104] [105] [106] [107] [108] [109]
   [110] [111] [112] [113] [114] [115] [116] [117] [118]
   [119] [120] [121] [122]) (...greeku.mf [0] [1] [2] [3]
   [4] [5] [6] [7] [8] [9] [10]) (...romand.mf [48] [49]
   [50] [51] [52] [53] [54] [55] [56] [57]) (...romanp.mf
   [36] [38] [63] [62]) (...romspl.mf [16] [17] [25] [26]
   [27] [28]) (...romspu.mf [29] [30] [31]) (...punct.mf
   [33] [60] [35] [37] [39] [40] [41] [42] [43] [44] [46]
   [47] [58] [59] [61] [64] [91] [93] [96]) (...accent.mf
   [18] [19] [20] [21] [22] [23] [24] [32] [94] [95] [125]
   [126] [127]) (...romlig.mf [11] [12] [13] [14] [15])
   (...comlig.mf [34] [45] [92] [123] [124]) ) )
   Font metrics written on cmr10.tfm.
   Output written on cmr10.144gf (128 characters, 7276 bytes).
   Transcript written on cmr10.log.
\end{verbatim}

If you know a little bit of the \MetaFont\ language, it should be clear what
else  you can do here; if you don't, I~recommend that you buy the `\MetaFont
book'~\cite{knuth.c} or the second volume of Kopka's series~\cite{kopka.erw}.

\subsection{Converting between {\tt gf}- and {\tt pk}-formats}
\MetaFont\ (and \TeX) is a highly portable programming system available for
a wide variety of computing machines from small systems like the Amiga to
``number crunching monsters.''  Also its binary output is intended to be
independent of a special hardware configuration.  As in the example run
listed in section~\ref{examples}, \MetaFont\ normally produces threefold
output files.

Typesetting systems like \TeX\ don't know where to put the
`ink,' they only want information about the respective sizes of the
characters and their positions in a font.  These informations are written
into the `{\tt tfm}' file ({\tt cmr10.tfm} in the example run) and contain
the ``(\TeX) font metric'' information.

Printer drivers or screen previewers that read ``device independent files''
produced by \TeX\ or other programs need the actual information about the
shapes of the characters they want to display.  \MetaFont\ writes the pixel
information about every character in a font of type in the socalled
``generic font format'', i.e., it writes a `{\tt gf}' file ({\tt
cmr10.144gf} in the example run).  The file extension denotes the specific
resolution of the produced font in ``dots per inch,'' so you can
distinguish between previewer fonts and printer fonts.  The ``generic
font'' format is very convenient at this place, and even some device driver
programs can handle them directly.

More often your \TeX\ system will deal with something called the `{\tt pk}'
representation of the pixel information.  `{\tt pk}' files contain the
same information as their `{\tt gf}' counterparts, but in a highly
compressed format, so that `{\tt pk}' files are much smaller.  The
conversion between the two pixel information formats is done by means of
two programs, \GFtoPK\ and \PKtoGF\null.  You call these programs in the
following way
\begin{verbatim}
   > GFtoPK [-v] gffile [pkfile]
   > PKtoGF [-v] pkfile [gffile]
\end{verbatim}
The `{\tt -v}' option tells the programs to be a little more `verbose',
else you won't see any screen output.  The first argument denotes the input
file (don't leave the extension out) in the respective format.  The
optional second argument denotes the output file in the alternative format.
If you don't give this second argument, the extension of the input file
will be transformed in a standard way to the extension of the output file.
The command line
\begin{verbatim}
   > GFtoPK cmr10.144gf
\end{verbatim}
will transform {\tt cmr10.144gf} to {\tt cmr10.144pk}.  You may specify a
full path name for the second argument and the output file will be created
where you want it.

\subsection{Fine control of the fonts with GFtoDVI}
This installation of \MetaFont\ knows two special modes `proof' and
`smoke,' corresponding to virtual devices with a resolution of 2602~dpi.
The program \GFtoDVI\ can produce pretty printed hardcopies of fonts created
for these devices.  Simply type
\begin{verbatim}
   > GFtoDVI
\end{verbatim}
and \GFtoDVI\ will prompt you for a {\tt gf}-filename.  You may change some
internal settings for this run by appending a slash to this filename and
\GFtoDVI\ will prompt you for ``special font substitutions,'' i.e., the
replacement of `gray' or `black' fonts for a special output device.  (See
the `\MetaFont book'~\cite{knuth.c} for details.)  Like most other
programs, \GFtoDVI\ is capable of accepting its arguments directly from the
command line input, so you may type
\begin{verbatim}
   > GFtoDVI cmr10.2602gf/
\end{verbatim}
and you will be prompted for further input.

\subsection{Pretty printed font listings with MFT}
Another special feature of this implementation is the \MFT\ program
that transforms ordinary \MetaFont\ program source files into \TeX\ input
files for formatted output of the source listing.  The only command line
argument necessary is the name of a `{\tt mf}'-file containing (parts of)
a \MetaFont\ program.  You may influence the working of \MFT\ by
applying other formats than the {\tt plain.mft}.  It is fun to play with
other settings and options.
\begin{verbatim}
   > MFT file[.mf] [-cs] [change[.ch]] [style[.mft]]
\end{verbatim}

\subsection{Analyzing {\tt gf}- and {\tt pk}-files}
The last two programs in this distribution are for font testing purposes.
They will provide you with textual information about the contents of the
pixel files in `generic' and `compressed' format.
\begin{verbatim}
   > GFtype [-m] [-i] gffile
   > PKtype pkfile
\end{verbatim}
The two options for \GFtype\ mean ``Mnemonic output'' and ``pIxel output''
respectively.  This will add more information to the output, especially the
outline of the characters in the form of {\mc ASCII} `pictures' for fine
control of what \MetaFont\ produces.

\section{For further reading}
\label{bibliography}
Here is a short list of literature related to \MetaFont\ and its
companions.  You should refer to these books when you seek for detailed
information about programming in the \MetaFont\ language.  Also you may
find very interesting stuff about the history of \TeX\ and \MetaFont\ since
1978, typesetting on computers in general, and the literate programming
discipline used for the development of ``Computers \& Typesetting.''

\begin{thebibliography}{99}
\bibitem{hessmann} Georg He{\ss}mann et.~al., {\language=1
  ARexx Unterst\"utzung f\"ur \MetaFont, Dokumentation zur Version 1.0},
  Description of the `\CallMF' package by Georg He{\ss}mann, Martin
  Bok\"amper, J\"org H\"ohle, and Ulrich Wisser for use with the
  Pas\TeX\ system, included in this Amiga implementation.
\bibitem{knuth.a} Donald E. Knuth, Computers \& Typesetting~A:
  The \TeX book, Addison-Wesley Publishing Company, 19th printing,
  June 1990.  This is {\em the\/} reference manual for all users of the
  \TeX\ system.  It describes the \TeX\ language in all levels
  of detail.
\bibitem{knuth.b} Donald E. Knuth, Computers \& Typesetting~B:
  \TeX: The Program, Addison-Wesley Publishing Company, fourth
  printing, February 1992.  This 600~page book contains the lavishly
  documented and annotated source code for the \TeX\ program, written
  in the {\tt WEB} language.
\bibitem{knuth.c} Donald E. Knuth, Computers \& Typesetting~C:
  The \MetaFont book, Addison-Wesley Publishing Company, fourth
  printing, June 1990.  This is {\em the\/} reference manual for all
  users of the \MetaFont\ system.  It describes the \MetaFont\
  language in all levels of detail.
\bibitem{knuth.d} Donald E. Knuth, Computers \& Typesetting~D:
  \MetaFont: The Program, Addison-Wesley Publishing Company, fourth
  printing, February 1992.  This 566~page book contains the lavishly
  documented and annotated source code for the \MetaFont\ program,
  written in the {\tt WEB} language.
\bibitem{knuth.e} Donald E. Knuth, Computers \& Typesetting~E:
  Computer Modern Typefaces, Addison-Wesley Publishing Company, first
  printing, Mai 1986.  This book contains specimen of all characters
  found in the Computer Modern font family, closely related to the
  appearance of all \TeX nical documents.
\bibitem{knuth.lit} Donald E. Knuth, Literate Programming, Center for the
  Study of Language and Information, first printing, 1992.  This is a
  collection of texts by Knuth related to the ``literate programming
  discipline,'' applied to the highest extend in the \TeX\ and \MetaFont\
  programs.  Also it contains the errorlog for \TeX~82 (until September 20,
  1991).
\bibitem{kopka.ein} Helmut Kopka, {\language=1
  \LaTeX--Eine Einf\"uhrung}, Addison-Wesley Publishing Company, fourth
  printing, 1992.  This is the first volume of the two-part series for
  German \LaTeX\ users.  It seems to be more popular than the reference
  manual by Leslie Lamport.
\bibitem{kopka.erw} Helmut Kopka, {\language=1
  \LaTeX--Erweiterungsm\"oglichkeiten mit einer Einf\"uhrung in \MetaFont},
  Addison-Wesley Publishing Company, third printing, 1992.  This is the
  second volume of the two-part series for German \LaTeX\ users.  It
  contains an introduction to \MetaFont\ and an introduction to literate
  programming in {\tt WEB} and {\tt CWEB}.
\end{thebibliography}

\section{History}
This Amiga port of \MetaFont~2.71 is based in part on the complete
\TeX\ and \MetaFont\ system supplied by Edmund Mergl on Fish Library
Disks 611--616.  Starting with \MetaFont~2.7 from this implementation,
I~introduced a lot of modifications and enhancements.

The major difference between the version by Edmund Mergl and my own is
that now \MetaFont\ is a complete stand-alone package, relying totally
on self-contained source files and utilities. (See section~\ref{source}.)

From the beginning I did all my programming on the Amiga with the {\mc
SAS/C} development system.  The latest version~6.3 of this fine compiler
is fully {\mc ANSI} compatible, so it detected a list of omissions in style
and speech when recompiling the source code.  A major cleanup of the extra
files for {\mc C}, i.e., the introduction of prototypes and the correction
of casting problems, was necessary.

As soon as version~2.7 was running, it was compared with the famous Amiga
port by Stefan Becker from Fish Library Disk~486 and proved to be much
slower, so some improvements seemed to be necessary to compete with this
system as well.  The tightest sections of the ``inner loop'' of \MetaFont\
were recoded in assembly lanugage for 68020~Motorola processors.  This
resulted in an overall speedup of about twenty to thirty percent compared
to the non-optimized version and of about five to eight percent compared
with the optimized version by Stefan Becker.

Running the {\mc TRAP} test proved the correctness of the implementation,
so the major part was done very fast.  The test routine by Donald Knuth was
very convenient to find the last nasty bug in my own part (had something to
do with a variable `\verb/be_careful/').  But visual tests both with my own
\MetaFont\ and with Stefan Becker's port showed problems with the online
display.  Neither the implementation by Stefan Becker nor by Edmund Mergl
worked in accordance with the `\MetaFont book'~\cite{knuth.c}.  Especially
the test routine {\tt 6test.mf} provided for the Computer Modern font
family caused some rethinking.  (An example of this test can be found on
page~192 of~\cite{knuth.c}.)  Finally a revised version of {\tt amiga.c}
was up and running, using some advanced functions for drawing on screen.
The online display requires version~2 of the Amiga operating system.

Adapting some ideas by David Crooke implemented in his Amiga port of
\TeX~3.141, I introduced a revised path search algorithm and the
possibility to use runtime-definable memory sizes with \MetaFont\null.
(See section~\ref{memory} for details about the memory configuration.)

In September~1993 the first step to version~2.71 was done with the errata
sheets provided by Addison-Wesley Publishing Company.  All changes
concerning the new version were implemented in the change file.

Finally in October~1993 I got hold of the official version~2.71\footnote{by
anonymous ftp from the Stuttgart server {\tt ftp.uni-stuttgart.de
(129.69.8.13)}}, which replaced the old system completely.  It included a
new {\tt plain.mf} base program and a whole new {\mc TRAP} test.  The last
change made to this implementation was the introduction of a really {\mc BIG}
version of \MetaFont\ (and of \TeX~3.1415 by the way) by increasing {\tt
max\_quarterword} to 32,767 (32~Kilo quarterwords) and {\tt max\_halfword}
to 1,073,741,823 (1~Giga memwords), so now nobody will ever exceed the maximum
setting for the main memory (you would have to have 8~Giga bytes of free
memory!).  Everybody seems to think that `262,142' is the maximum value
for {\tt memmax}, although this value holds for 36~bit words only.  This
{\mc C} implementation works on the basis of ``64~bit words,'' i.e., a
halfword is defined as {\bf long int}, so the very much higher value
may be used.

\section{Source code}
\label{source}
This package is the ``\MetaFont\ user's kit,'' so no source code for the
actual programs is provided with it (there is a directory of the complete
Computer Modern font library, but this is a different kind of source code).
A~``developer's kit'' is available from the implementor on request.  If you
would like to have the complete source code, send a self-addressed envelope
and 10~Deutsche Mark (or 10~US~Dollars) to the address on the cover of this
documentation, and you will receive the latest version on disk together with
all necessary tools for re-compilation and future bug fixes.

\end{document}
