% % LATEX $VER: EnglishDoc.ltx 2.4 (26.11.1994) % % DESCRIPTION: This LaTeX file contains the complete description and % documentation of the Amiga implementation of MetaFont 2.71 % for English speaking users. A German translation of this % text also is available. % % DATE: 05.11.1993 (V1.0) % % AUTHOR: Andreas Scherer % Roland-Straße 16 % 52070 Aachen % Germany % % % CHANGES: 06.11.1993: Description of all utilities (V1.1) % 07.11.1993: Corrections (V1.2) % 19.11.1993: Further corrections (V1.3) % 09.12.1993: Still more corrections (V1.4) % 10.12.1993: I want to apolo-, apolo-, apolo... % I am so, so, so so... % To activate the online display, the environment % variable MFWTERM has to be set to "amiterm" in % lowercase (!) letters (V1.5) % 15.12.1993: New versions of PKtoGF and GFtype (V1.6) % 10.01.1994: Change printer offset (V1.7) % 21.01.1994: Extended info about base-creation due to problems % with `modes.mf' versus `pastex-modes.mf'. This % problem was reported by Stefan Sell (V1.8) % 24.01.1994: We don't dance the `than than' anymore (V1.9) % 27.03.1994: Still more types fixed. (V1.10) % 18.06.1994: New copyright text. (V1.11) % 19.09.1994: New version 2.1 of `modes.mf'. (V1.12) % 23.09.1994: LaTeX2e is the new standard, so use it. (V1.13) % 19.11.1994: New edition for the update. (V2.0) % 20.11.1994: Missing `*' in AMSFONTS path. % Additional `old-german/*' entry. (V2.1) % 21.11.1994: Suggestions by Giuseppe Ghibò used. (V2.2) % 22.11.1994: Suggestions by Georg Heßmann used. (V2.3) % 26.11.1994: Test results updated. (V2.4) % % CONSISTENCY: The following string literal was automatically created % by the "CheckSum" program by Robert Solovay and may not % be changed by hand. % % checksum = "23332 1025 7520 54202" % % COPYRIGHT: % The printed form of this documentation is copyright % (c) 1993,1994 by Andreas Scherer. All rights are reserved. % % The electronic form of this documentation is copyright % (c) 1993,1994 by Andreas Scherer. All rights are reserved. % % Permission is granted to make and distribute verbatim copies of the % electronic form of this documentation provided that the electronic % copyright notice and this permission notice are preserved on all copies. % % Permission is granted to copy and distribute modified versions of the % electronic form of this documentation 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. % \documentclass{article} \hoffset=-2.5mm % Suits my printer for two-side output \language=\USenglish % USenglish in my multilingual TeX configuration \newfont{\manual}{manfnt} % METAFONT in text \newfont{\bigmanual}{manfnt scaled \magstep3} % METAFONT in titles \newcommand{\names}[1]{{\small#1}} \newcommand{\MetaFont}{{\manual META}\-{\manual FONT}} \newcommand{\BigMetaFont}{{\bigmanual META}\-{\bigmanual FONT}} \newcommand{\IniMF}{Ini\names{MF}} \newcommand{\VirMF}{Vir\names{MF}} \newcommand{\GFtoDVI}{\names{GF}to\names{DVI}} \newcommand{\GFtoPK}{\names{GF}to\names{PK}} \newcommand{\GFtype}{\names{GF}type} \newcommand{\MFT}{\names{MFT}} \newcommand{\PKtoGF}{\names{PK}to\names{GF}} \newcommand{\PKtype}{\names{PK}type} \newcommand{\VFtoVP}{\names{VF}to\names{VP}} \newcommand{\VPtoVF}{\names{VP}to\names{VF}} \newcommand{\DVIPS}{\texttt{DVIPS}} \newcommand{\PASCAL}{\textsc{Pas\-cal}} \newcommand{\CallMF}{Call\names{MF}} \title{\BigMetaFont\ for the \textsl{AMIGA}\\ \medskip Documentation of version 2.71\bigskip} \author{Andreas Scherer\\ Roland-Stra{\ss}e 16\\ 52070 Aachen\\ Germany\\ \texttt{\small scherer@genesis.informatik.rwth-aachen.de}\bigskip} \begin{document} \maketitle \begin{abstract} This document describes my 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 {\small\noindent\baselineskip=11pt The printed form of this documentation is copyright\hfil\break \copyright\ 1993, 1994 by Andreas Scherer. All rights are reserved. \noindent The electronic form of this documentation is copyright\hfil\break \copyright\ 1993, 1994 by Andreas Scherer. All rights are reserved. \noindent Permission is granted to make and distribute verbatim copies of the electronic form of this documentation provided that the electronic copyright notice and this permission notice are preserved on all copies. \noindent Permission is granted to copy and distribute modified versions of the electronic form of this documentation 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.\par} \newpage \tableofcontents \newpage \section{Copyright} The \MetaFont\ program is \copyright~1984 by Donald E. Knuth. All rights are reserved. The complete \texttt{WEB} source code is published in the book~\cite{knuth.d}. The associated utility programs were written by various authors, who expressly do not claim copyright, and can be used freely. This implementation of \MetaFont~2.71 for the Commodore Amiga is declared to be \names{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. All programs in this ``user's kit'' make use of the ``EVPaths'' package. ``EVPaths'' is \copyright~1994 by Giuseppe Ghib\`o. All rights are reserved. ``EVPaths'' is used with the kind permission of the author. 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 one of the addresses given on the front page of this documentation. A~``developer's kit'' containing the complete source code with all modifications and enhancements is available there. (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\names{DOS}, Amiga Kickstart, and Amiga Workbench are registered trademarks of Commodore-Amiga Incorporated. \noindent \names{SAS} and \names{SAS/C} are registered trademarks of \names{SAS} Institute Incorporated. \noindent PostScript is a registered trademark of Adobe Systems 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~\names{MB} of Chip\names{RAM} and 4~\names{MB} of Fast\names{RAM}, although a total of only 1~\names{MB} were actually used with 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. (Are there really \MetaFont\ users, who work under \names{OS}~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 \texttt{cmr10} for the 300~dpi DeskJet printer driver of Pas\TeX\ can be as quick as 52~seconds on a 50~\names{MH}z 68030 accelerator board with a coprocessor and sufficient 32~bit~Fast\names{RAM} but as slow as 10~minutes and 50~seconds on a standard 7~\names{MH}z Amiga with slow 16~bit~\names{RAM}, although the programs are capable of running on both configurations. In a brute force attempt with all Fast\names{RAM} disabled (only 2~\names{MB} of Chip\names{RAM} were available, where all binaries and input files were stored) the processing time increased to 17~minutes and 40~seconds. \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 \names{TRAP} test as of January 25, 1992 gracefully. Only permissible differences as described in \texttt{trapman.tex} were encountered. \texttt{diff} files documenting the latest run of the \names{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.1 (March, 1991), \MFT\ version~2 (October, 1989), \PKtoGF\ version~1.1 (October, 1990), and \PKtype\ version~2.3 (November, 1989) as well as the two new programs \VFtoVP\ and \VPtoVF, both version~1.2 (September, 1990). \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 \texttt{LHA} archive. It will contain a working installation of all programs and scripts. 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 MetaFontV2.71[.lha] \end{verbatim} (You should have the \texttt{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 \texttt{MetaFont} will be created and will contain the complete archive in convenient subdirectories described below. You should ``\texttt{assign}'' the name ``\texttt{MF:}'' to this root directory. Less than 3~\names{MB} of free disk space are needed to install the complete \MetaFont\ system. \begin{description} \item{\texttt{MetaFont/bases}:} This directory is the home of the `\texttt{base}' files that \MetaFont\ reads at high speed at the beginning of a run. Here you will find the file \texttt{plain.mf} (version~2.71) and some startup files for `plain' and `cm.' New \texttt{base} files should be created or copied herein. The environment variable \texttt{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{\texttt{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 \texttt{PATH} environment variable. A more detailed description about running the programs will be given in the next section~\ref{running}. \item{\texttt{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 \texttt{METAFONT capacity exceeded, sorry...} The configuration setup file \texttt{mfmemory.config} contains lines of the form \begin{verbatim} set memmax 65530 % default 30000 set screenheight 200 % default 1024 set % default \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 \texttt{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.) The file \texttt{modes} contains a list of settings appropriate for the ready-to-work \texttt{base} file provided with this user's kit\footnote{These are \emph{not} compatible with the Pas\TeX\ settings from \texttt{pastex-modes.mf} of the CallMF package; they refer to the standard \texttt{modes.mf} distribution instead.}. Several printers and the standard previewer are supported. You may change things here according to your personal configuration. \item{\texttt{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 \texttt{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{\texttt{MetaFont/inputs}:} This directory is for \MetaFont\ programmers and system administrators only. It contains text files necessary for the creation of new or changed \texttt{base} files. Here you should install the complete Computer Modern font family, the standard for most \TeX\ users. You may add your own font programs here. \item{\texttt{MetaFont/pool}:} \MetaFont\ (just like \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 \texttt{mf.pool} contains all texts and messages \MetaFont\ is willing to print to your screen or the log file. It was automatically generated by \texttt{TANGLE} in the process of compilation and should not be deleted or changed in any way. \item{\texttt{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 \texttt{rexx}, so no more information about installation and usage of `\CallMF' is given at this place. Just a word about possible incompatibilities. In this distribution I use only modes from the standard distribution \texttt{modes.mf}, Pas\TeX\ relies on \texttt{pastex-modes.mf}. Unfortunately the naming convention in these two files is different, so some manual adjustment will be necessary. In connection with \CallMF\ I highly recommend the use of version~5.58 of the \DVIPS\ program by Tomas Rokicki. Giuseppe Ghib\`o's excellent Amiga port also utilizes these ARexx scripts. \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 have to recompile the source code with changed internal settings. However, you need no longer fear the ``{\ttfamily ask a wizard to enlarge me}'' message, you can do some wizardry yourself! The present implementation is done with the help of the \texttt{Web2C} language converter and so it is possible to include a special feature for controlling the internal variables at runtime. The \IniMF\ and \VirMF\ programs will search these directories for a file called \texttt{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 \texttt{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\names{RAM}!\footnote{If you have that much, I don't believe you!} If you create a standard \texttt{base} file with \IniMF, any change to the configuration \texttt{mfmemory.config} will be acceptable for \VirMF\ in connection with this specific \texttt{base}, except changes to \texttt{memtop}. This will result in the \MetaFont\ message ``{\ttfamily(Fatal base file error; I'm stymied)},'' indicating that this \texttt{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 \texttt{memmax} & 30000 & \texttt{maxhalfword} & Size of main storage\\ \texttt{maxinternal} & 100 & ${}\leq259774$ & Number of internals\\ \texttt{bufsize} & 500 & \texttt{maxhalfword} & Input characters\\ \texttt{errorline} & 72 & \texttt{maxhalfword} & Error context width\\ \texttt{halferrorline} & 42 & $<$\texttt{errline$-15$} & First error line\\ \texttt{maxprintline} & 79 & $\geq60$ & Output text line width\\ \texttt{screenwidth} & 768 & 4095 & Width of display screen\\ \texttt{screenheight} & 1024 & 4095 & Height of display screen\\ \texttt{stacksize} & 30 & 300 & Number of input sources\\ \texttt{maxstrings} & 2000 & \texttt{maxhalfword} & Number of strings\\ \texttt{poolsize} & 32000 & \texttt{maxhalfword} & Characters in strings\\ \texttt{movesize} & 5000 & 10000 & Storage for octant moves\\ \texttt{maxwiggle} & 300 & 1000 & Autorounded points per cycle\\ \texttt{gfbufsize} & 100 & 4096 & Size of the output buffer\\ \texttt{pathsize} & 300 & 1000 & Number of knots in a path\\ \texttt{bistacksize} & 785 & 785 & Stack for bisection algorithm\\ \texttt{headersize} & 25 & 100 & Number of \names{TFM} header words\\ \texttt{ligtablesize} & 5000 & 32510 & Ligature/kern steps\\ \texttt{maxkerns} & 500 & 1000 & Distinct kerns\\ \texttt{maxfontdimen} & 50 & 100 & Number of `fontdimen's\\ \texttt{memtop} & 30000 & \texttt{memmax} & Largest memory index\\ \texttt{scalefactor} & 1 & 10 & Display is `\names{SF}' times reduced\\ \texttt{maxinopen} & 6 & 20 & Number of input files\\ \texttt{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 \texttt{memmax}, and this was actually tested up to the horribly high value~750,000 on my Amiga~2000 with 8~\names{MB} of 32~bit Fast\names{RAM}. You can control the size of the online display by changing the values for \texttt{screenwidth}, \texttt{screenheight}, and \texttt{scalefactor}. The meaning of the first two should be clear, just keep in mind, that \texttt{screenheight} denotes the \emph{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 \texttt{innerwidth} and \texttt{innerheight}. The \texttt{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 \texttt{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 the printer \texttt{modes} file. When drawing on screen \MetaFont\ uses the smaller value of \texttt{screenheight} and \texttt{screen\_rows} respectively \texttt{screenwidth} and \texttt{screen\_cols}, so actually the configuration overrides the internal settings. Unlike earlier versions of \VirMF\ it is no longer necessary to explicitly activate the ``online display'' by setting the environment variable \texttt{MFWTERM} to the (lowercase) value \verb+"amiterm"+. Preferably, this variable should not be set at all. But with any deviating value the visual display can be suppressed in the modes \texttt{proof} and \texttt{smoke} as well. \subsection{Setting up the environment} \label{environment} \MetaFont\ acknowledges several environment variables in the course of its file searching algorithm, for the `\texttt{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 \texttt{base} files, the configuration file \texttt{mfmemory.config}, font description programs, and the text pool file \texttt{mf.pool}. Also the associated utility programs ackowledge these and some other environment variables and use them accordingly. In the old version there had been undesired collisions in the use of environment variables, now corrected in this updated version. Conventionally you can use the system command \begin{verbatim} SetEnv \end{verbatim} to introduce your personal system configuration or you can keep the internal defaults. Here is a list of the 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 \texttt{MFBASES} & \verb+"MF:bases"+ & \texttt{*.base} files\\ \texttt{MFINPUTS} & \verb+"MF:inputs/*,"+ & \\ & \verb+"MF:mfinputs/*,"+ & \\ & \verb+"MF:inputs/amsfonts/sources/*,"+ & \\ & \verb+"MF:mfinputs/amsfonts/sources/*,"+ & \\ & \verb+"MF:inputs/old-german/*,"+ & \\ & \verb+"MF:mfinputs/old-german/*"+ & \texttt{*.mf} files\\ \texttt{MFPOOL} & \verb+"MF:,MF:pool"+ & \texttt{mf.pool}\\ \texttt{MFCONFIG} & \verb+"MF:config"+ & \texttt{mfmemory.config}\\ \hline \end{tabular} \end{center} Additionally there are some environment variables for the utility programs. These allow a distinction between the various types of font encodings. \begin{center} \begin{tabular}{|l|l|l|}\hline Environment & Default setting & Files\\ \hline \texttt{GFFONTS} & \verb+"TEX:gf/*,"+ & \\ & \verb+"TEX:fonts/gf/*,"+ & \\ & \verb+"TEX:texfonts/gf/*"+ & \texttt{*.*gf} files\\ \texttt{PKFONTS} & \verb+"TEX:pk/*,"+ & \\ & \verb+"TEX:fonts/pk/*,"+ & \\ & \verb+"TEX:texfonts/pk/*,"+ & \\ & \verb+"TEX:pk/amiga/*,"+ & \\ & \verb+"TEX:fonts/pk/amiga/*,"+ & \\ & \verb+"TEX:texfonts/pk/amiga/*,"+ & \\ & \verb+"TEX:pk/deskjet/*,"+ & \\ & \verb+"TEX:fonts/pk/deskjet/*,"+ & \\ & \verb+"TEX:texfonts/pk/deskjet/*,"+ & \\ & \verb+"TEX:pk/cx/*,"+ & \\ & \verb+"TEX:fonts/pk/cx/*,"+ & \\ & \verb+"TEX:texfonts/pk/cx/*,"+ & \\ & \verb+"TEX:pk/ljfour/*,"+ & \\ & \verb+"TEX:fonts/pk/ljfour/*,"+ & \\ & \verb+"TEX:texfonts/pk/ljfour/*"+ & \texttt{*.*pk} files\\ \texttt{VFFONTS} & \verb+"TEX:vf,"+ & \\ & \verb+"TEX:fonts/vf,"+ & \\ & \verb+"TEX:texfonts/vf"+ & \texttt{*.vf} files\\ \texttt{PLFONTS} & \verb+"TEX:pl,"+ & \\ & \verb+"TEX:fonts/pl,"+ & \\ & \verb+"TEX:texfonts/pl"+ & \texttt{*.[v]pl} files\\ \hline \end{tabular} \end{center} All programs in this new version unconditionally search for input files in the current directory first, before they consider any of these paths. This eliminates the problem with the possible notation for the ``current'' directory. To keep the interface compatible with the older version, the empty string and also the single dot~\verb/"."/ are recognized as replacements for the current directory, but this brings absolutely no benefits; a file is used from the first place of encounter in the complete search path. The awkward notation for recursive subdirectory search no longer is necessary. Any entry can have appended one or two asterisks~\texttt{*}. A single asterisk causes the path given to be search together with its direct subdirectories (see for example the default setting for \texttt{MFINPUTS} above). Even deeper levels of subdirectory searching is possible by appending two asterisks~\texttt{**}, but this may take some extra time on startup, when directories are nested deeply. Another positive effect of the new path search routines is that you don't have to repeat the above defaults in the environment variables. Should it be necessary to use different or additional paths, all you have to do is to set up the respective environment variable with the missing entries only. All internal defaults will automatically be appended to it, i.e., they will be considered at the end of the searching step without expressly being stated in the external variables. Here I want to thank Giuseppe Ghib\`o, who most generously provided me with the source code of his \texttt{EVPATHS} package. Without this constructive cooperation the elegant implementation of recursive path searching for \MetaFont\ would not have been possible. This new version owes its very existence and its extended contents particularly to the pertinent demands from Italy. In case of an error or an interruption, when \MetaFont\ prompts you with a question mark you may answer by typing `\texttt{e}' (or `\texttt{E}'), thus invoking your text editor. This feature is controlled by the \texttt{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 \texttt{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 \texttt{rexx} directory. If you want to use them, simply set the environment variable \texttt{MFEDIT} to the (string) value \begin{verbatim} "rx MF:rexx/MFEdit.rexx %s %d" \end{verbatim} The second script \texttt{NameStruc} should be placed in the \texttt{REXX:} directory, because it is called directly from within \texttt{MFEdit.rexx}. Just like in the earlier versions 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\names{DOS}~2.0 and higher. Explicit activation of this feature by setting the environment variable \texttt{MFWTERM} to the (lowercase) value \verb/"amiterm"/ is not necessary, this caused some misunderstandings. \section{Running the programs} \label{running} \subsection{Creating new bases with IniMF} Although there is a \texttt{plain.base} file in this package, you may want to create additional \texttt{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 \texttt{base}s for high-speed inclusion. If you call \IniMF\ from the \names{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 \texttt{plain.inimf} or \texttt{cm.inimf} and the rest will be done automatically, resulting in a new \texttt{base} file \texttt{plain.base} or \texttt{cm.base}. Or you can type in consecutive \texttt{input} commands to load multiple files for inclusion in the \texttt{base} file. The last command should be \texttt{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. If you use \texttt{plain.inimf} or \texttt{cm.inimf} as proposed here, the standard distribution \texttt{modes.mf} (current version~2.1) by ``Karl Berry and the \MetaFont\ community'' is added to your \texttt{base} file. This file contains mode descriptions for a variety of output devices, such as many matrix, laser or jet printers, photo typesetters, and screen previewers at different resolutions. There is a slight disadvantage when you include the complete \texttt{modes.mf} file, the \texttt{base} will heavily increase in its size. Feel free to extract only the modes you need for your personal configuration and to put them into a file texttt{local.mf}. You should replace the line ``\texttt{input modes}'' by ``\texttt{input local}'' in \texttt{plain.inimf} and recreate the \texttt{base} file with the help of \IniMF\ as described above. Pas\TeX\ users who want to use the \CallMF\ package may encounter some problems, because Georg He{\ss}mann chose to create his own modes which are \emph{not} compatible with \texttt{modes.mf}. These are collected in the file \texttt{pastex-modes.mf} in the \texttt{MF:rexx/callmf/inputs} directory. You can use these modes, but you will have to replace the entries in \texttt{modes} and recreate the \texttt{base} file to work with them. Or you can setup Pas\TeX\ to work with \texttt{modes.mf}. \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 \texttt{base} files, but it can read such command \texttt{base}s. Just like with \IniMF\ you have two possibilities to call \VirMF\null. If you simply 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' \texttt{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, \texttt{r}, \texttt{e}, \texttt{l}, \texttt{a}, \texttt{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 `\texttt{relax}' means ``do nothing.'' The machine will respond by typing a single asterisk: `\texttt{*}'. 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 `\texttt{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 \texttt{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 \texttt{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:=amiga; 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 \texttt{cmr10} for the screen previewer at resolution 100~dpi but magnified twice, so the resulting font will get the name \texttt{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 gf- and 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 `\texttt{tfm}' file (\texttt{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 `\texttt{gf}' file (\texttt{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 `\texttt{pk}' representation of the pixel information. `\texttt{pk}' files contain the same information as their `\texttt{gf}' counterparts, but in a highly compressed format, so that `\texttt{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 `\texttt{-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 \texttt{cmr10.144gf} to \texttt{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} \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 \texttt{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 `\texttt{mf}'-file containing (parts of) a \MetaFont\ program. You may influence the working of \MFT\ by applying other formats than the \texttt{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 gf- and 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 \names{ASCII} `pictures' for fine control of what \MetaFont\ produces. \subsection{Virtual fonts} The latest addition to this distribution are conversion programs for the creation of ``virtual fonts.'' Thanks to Tomas Rokicki's \DVIPS\ and suitable output drivers for PostScript playing around with this form of character manipulation can be of interest. \begin{verbatim} > VFtoVP vfmfile tfmfile vplfile > VPtoVF vplfile vfmfile tfmfile \end{verbatim} Note that ``VF'' are primarily intended for ``Grand Wizards.'' You should pretty much know what you do when fooling around with them. (I don't, so that's all I want to say here.) \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 1977, 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=\german 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 Pas\TeX. \bibitem{knuth.a} Donald E. Knuth, Computers \& Typesetting~A: The \TeX book, Addison-Wesley Publishing Company, 19th printing, June 1990. This is \emph{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 \texttt{WEB} language. \bibitem{knuth.c} Donald E. Knuth, Computers \& Typesetting~C: The \MetaFont book, Addison-Wesley Publishing Company, fourth printing, June 1990. This is \emph{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 \texttt{WEB} language. \bibitem{knuth.e} Donald E. Knuth, Computers \& Typesetting~E: Computer Modern Typefaces, Addison-Wesley Publishing Company, first printing, May 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=\german \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. In 1994 a completely revised and extended edition of Kopka's books was published in three volumes. \bibitem{kopka.erw} Helmut Kopka, {\language=\german \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 \texttt{WEB} and \texttt{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 on self-contained source files and utilities. (See section~\ref{source}.) From the beginning I did all my programming on the Amiga with the \names{SAS/C} development system. The latest version~6.3 of this fine compiler is fully \names{ANSI} compliant, so it detected a list of omissions in style and speech when recompiling the source code. A major cleanup of the extra files for \names{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 language for 68020~Motorola processors. For this work I want to thank my brother. 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 to the optimized version by Stefan Becker. Running the \names{TRAP} test proved the correctness of the implementation, and this 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 \texttt{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 \texttt{amiga.c} was up and running, using some advanced functions for drawing on screen, thus requiring 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 \texttt{ftp.uni-stuttgart.de (129.69.8.13)}, lately replaced by \texttt{ftp.dante.de (129.206.100.192)} of DANTE~e.V.}, which replaced the old system completely. It included a new \texttt{plain.mf} \texttt{base} program and a whole new \names{TRAP} test. The last major change made to this implementation was the introduction of a really \names{BIG} version of \MetaFont\ (and of \TeX~3.1415 by the way) by increasing \texttt{max\_quarterword} to 32,767 (32~Kilo quarterwords) and \texttt{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 \texttt{memmax}, although this value holds for 36~bit words only. This \names{C} implementation works on the basis of ``64~bit words,'' i.e., a halfword is defined as \textbf{long int}, so the very much higher value may be used. \subsection{Extensions} The most important new feature of this \MetaFont\ system is concerned with the path search algorithm. Thanks to the generous support of Giuseppe Ghib\`o I was able to install the recursive subdirectory search for input files in an easy and elegant fashion. The plan to do this failed up to now, due to the size of the current \names{UNIX} distribution. To avoid any misconceptions, the ``current'' directory was left out from the recursion. Files in the current directory are always used first. As usual the paths in the environment variables are separated by commas. Appending a single asterisk~`\texttt*' to any path entry causes this directory and also every immediate subdirectory to be searched. Double asterisks~`\texttt{**}' result in a more deeply search in the directory tree, but this may take some time on startup. There are internal defaults defined for the various file types, automatically recognized by \MetaFont\ and its utility programs. These defaults need not be repeated in external environment variables. The easily manageable source code also resulted in a simplification of the complete development configuration for \TeX, \MetaFont, and \emph{all} associated utility programs. Above all, the creation and usage of ``virtual'' fonts is enabled, i.e., the connection of characters from different definition files under a new name. Here the use of the program \DVIPS\ by Tomas Rokicki is highly recommended for every serious \TeX\ user on the Amiga. The superb Amiga port of \DVIPS~5.58 by Giuseppe Ghib\`o even supports the \CallMF\ scripts. Besides the four new environment variables for the different font format files (see section~\ref{environment}) the usage of the environment variable \texttt{MFWTERM} was changed. After I made an incorrect statement concerning the value in the first draft of this documentation, thus prohibiting many users of ever seeing the ``online display,'' in this new version I decided to do without the external activation of the display. \subsection{Acknowledgements} Since the release of the first version of my \MetaFont\ implementation I received several letters with comments that led to improvements of this documentation. The described difficulties were eliminated in part in the version of May~1994, published in connection with the Pas\TeX\ distribution on the ``Meeting Pearls''~CD, although one message concerning the ``online display'' only reached me afterwards. Fortunately, in no case the problems were caused by real bugs in the programs, but by inaccuracies and omissions in the documentation. For their letters I thank Stefan Sell, Markus Eiblmeier, and Dieter Sach. Special thanks go to Georg He{\ss}mann, who used my \MetaFont\ implementation for ``Pas\TeX\ on CD.'' For this he demanded several extensions that increased the quality of the programs. In particular, it is due to him that \IniMF\ and \VirMF\ are ``resident.'' The greatest influence on this updated distribution of \MetaFont\ came from Giuseppe Ghib\`o, who urged me to install and use his outstanding implementation of recursive path search. Without his \texttt{EVPATHS} package I never would have dared to do this job. Additionally, the programs \VFtoVP\ and \VPtoVF\ owe their existence to \texttt{EVPATHS}, and the separation of the different character file formats was done after one of his requests. \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. 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. In case of interest I also can provide you with version~3.1415 of \TeX. In the age of electronic media and the ``interconnectedness of everything'' there is a great advantage for all those of you who have access to the Internet (also known as the ``cyberspace''). It saves me the expense for the disk version and answering in writing, when you tell me an electronic address where to send the source code by email or preferably~\texttt{ftp}. In this case the ``developer's kit'' is for free. This is in no way ment as an offense against the multitude of ``normal'' users, it only saves me a lot of work. \end{document}