%&latex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% This is the file vfinst.tex, part of the VFinst package
%% (version 1.00, August, 1998) for PostScript Type1 font 
%% installation.  (Author: Alan Hoenig, ajhjj@cunyvm.cuny.edu)
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% THIS IS A STANDARD \LaTeX (LaTeX2e) FILE.

\documentclass{article}

\def\TT#1 {{\tt #1} }
\newcommand{\vfinst}{\texttt{VFinst}}\let\VFinst=\vfinst
\newcommand{\CTAN}{\textsc{ctan}}
\newcommand{\TDS}{\textsc{tds}}
\newcommand{\helper}[2]{#2 #1}

\title{The \TT VFinst virtual font installer (version 1.00)}
\author{Alan Hoenig}

\begin{document}

\maketitle

If you've ever wanted to set up outline fonts for use by \TeX\ or
\LaTeX, \VFinst\ may be of use to you.  \VFinst\ sets these fonts up
for use by \TeX\ and \LaTeX, and at the end of the \VFinst\
process, you'll be able to typeset with your new fonts, confident that
accents, ligatures, and the like will appear in your document with the
usual \TeX\ conventions.  Here are the fonts you get at the end of the
process.
\begin{enumerate}
  \item For every upright font: you get the upright font, the small 
    caps font, an oblique font, and an underline font.  
  \item For every italic font, you get the italic font, a small caps
    italic, an unslanted italic, and an underline font.  
  \item Additional fonts: You will also get titling (display)
    fonts, both upright and italic, and a swash italic font, 
    if the appropriate raw fonts were present.  
\end{enumerate}
\VFinst\ takes care to use expert fonts to build the small caps fonts,
if these raw fonts were originally present.  You also get test files
for plain \TeX\ and \textsc{NFSS} (\LaTeX), to 
both test the fonts and to provide
examples of how to declare and use each of the fonts in a \TeX\ 
document.

At the end of the \VFinst\ process, you get all {\tt.vf} and {\tt.tfm}
files for all fonts, which have been renamed for you according to the
{\tt fontname2.1} conventions.  All oblique and italic fonts use the
true italic angle for the font.  The {\it dvips\/} map file {\tt
psfonts.map} will have been updated for you.  All fonts will have been
placed in the proper area on your hard disk.  You may choose original
\TeX\ ({\tt ot1}) or Cork ({\tt t1}) encodings for your fonts, which
can be installed according to the \TDS\ (\TeX\ Directory Structure) or
`traditional' standard.  All raw fonts follow the {\tt 8r
TeXBase1Encoding}.

All this and more is expanded upon in the remainder of this file.
{\bf Please read the file thoroughly.}  The first
section, a general introduction, is followed by four sections that a
new user will need:
\begin{itemize}
  \item`\VFinst\ and what you'll need to run it', 
  \item`Installation and set up', 
  \item `Running \VFinst', and 
  \item `Using your new fonts'.  
\end{itemize}
The remainder can be read later (if at all).

If this software proves useful to you, you may also wish to
investigate two other packages I wrote, both on \CTAN.  {\it
MathInst\/} helps
install commercial math fonts with your newly installed PostScript
fonts so that equations and such come out looking fully compatible
with your text.  {\it MathKit\/}
does the same thing, but it uses Metafont to create symbols from the
Computer Modern fonts that match your text fonts.  These packages can
be found in the 
\begin{verbatim}
fonts/utilities/mathinst
fonts/utilities/mathkit
\end{verbatim}
areas of \textsc{ctan}.

\section{Introduction}
One thing that {\em should\/} be easy to do with \TeX\ is make
commercial outline fonts transparently usable by \TeX\ and \LaTeX.
Even though a tool like \TT fontinst does make it easy to do this, \TT
fontinst still requires inside knowledge not easily
come by.  The set of tools called \vfinst\ is my attempt
to make the task of installing families of PostScript fonts as simple
as possible, but {\bf only\/} for well-formed families of fonts.  That
is, I am concerned here only with {\em text\/} fonts, roman fonts
appearing in medium and other weights, with italic variants, and
optionally with small caps or expert fonts, and possibly a few
additional matching fonts, like swash italic caps, display fonts, and
so on thrown in.  Special dingbat fonts, unusual families like
Poetica, foreign language fonts, math fonts, and the like will not be
reliably installed with this software.  Neither will fonts that are
narrow, extended, or other `width' variants.  (I have prepared two
other tools---\textit{MathInst} and \textit{MathKit}---that help
typeset documents so that the mathematics is compatible with the text
fonts.  Both these tools are available on \textsc{ctan}; see above.)

Here's the basic idea.  You place copies of all the fonts you want to
install in a special work place.  Then, you activate the \vfinst\
scripts, run all the additional scripts that \vfinst\ produces,
and that's it!  \vfinst\ does these things for you:
\begin{itemize}
  \item produces all \TT.vf and \TT.tfm files;
  
  \item renames the fonts according to
  version~2.1 of Karl Berry's \TT fontname convention;
  
  \item automatically updates the \TT psfonts.map file for {\it dvips};
  
  \item generates two test files, for plain \TeX\ and NFSS (\LaTeX),
      showing how to use your new fonts; and 

  \item generates a script or batch file for placing all new fonts and
      other associated files in their proper places  (It also
      generates a script for creating any needed new directories.)
\end{itemize}
and does these for either `traditional' or {\sc tds}-compliant systems.
(TDS stands for `\TeX\ Directory Structure'.)  Once you've executed
all these scripts or batch files, the fonts are ready for use.  

Here are the fonts you get:

\begin{itemize}
  \item for each upright font (roman and bold or semibold, usually):
      \begin{itemize}
        \item the font itself, 
        \item matching small caps (mock or real), 
        \item a slanted (oblique) font, and
        \item an underline font.
      \end{itemize}
  
  \item for each italic font (roman and bold or semibold, usually):
      \begin{itemize}
        \item the font itself, 
        \item matching small caps, 
        \item an unslanted italic, and 
        \item an underline font.
      \end{itemize}
  \item display or titling fonts (both upright and italic), 
  if they are present; and
  \item swash italic fonts, if they are present.
\end{itemize}
If you have included expert or small caps fonts among your
fonts for installation, \vfinst\ automatically takes them into
account when building the virtual fonts.  
If you have included expert raw fonts, you actually get two font
families at the end---both use `expertised' fonts, but one family
contains regular digits, and the other contains old style digits.

It's not well known, but the angle of inclination for an italic font
varies quite a bit from font family to font family.  The oblique and
unslanted italic fonts that \vfinst\ creates use the true italic angle
for that font.  You also get several underline fonts, font in which
each character is underlined so it is easy to typeset lengthy
underlined passages without worrying about line breaks.

{\fontsize{9}{10}\selectfont
(This paragraph is for reference purposes only; it mentions things that
will very likely not be of interest to most people.)  The virtual fonts
created use raw fonts which follow the `8r' \TT TeXBase1Encoding being
promulgated by the international community of \TeX\ developers.  (This
encoding provides easy access to all characters in the font.  Pardon
to all for the cryptic acronyms that abound.)  The
resulting virtual fonts themselves follow either the original \TeX\
encoding (so-called \texttt{OT1} or \texttt{ot1}) or the newer Cork
encoding (\texttt{T1} or \texttt{t1}).\endgraf}

Pierre MacKay's \TT makevf script helped inspire
\vfinst.
The remainder of this document describes the \vfinst\ installation
procedure, its use, and other important details in greater detail.

Although I hope this software is useful, it
comes with no warranty whatsoever.  I cannot accept responsibility for
any harmful effects from this software. 

\subsection{Changes from prior versions}
Separate \textsc{dos} versions of \vfinst\ are no longer supported. 

Several bug fixes are particularly important.  One odd but interesting bug
prevented \vfinst\ from working properly with New Century Schoolbook
fonts.  A second concerned the way \textit{dvips}-map entries were
generated for \textsc{tds} systems.  Both have been fixed.

Speaking of \textsc{tds} systems, this version has been very
thoroughly tested with such systems, a fact which has not been true in
the past.  Several major bugs were uncovered and fixed, and my
apologies to all that they persisted for so long.

\subsubsection{Lousy afm files}
The major problem users may continue to have lies not with {\it
this\/} software, but with the \texttt{afm} files that accompany the
files.  These files provide the metric and other information for a
Type1 font analogously to \TeX's \texttt{tfm} files.  Apparently,
little software takes advantage of these files, and digital foundries
are at best sloppy when preparing them.  \vfinst\ relies on the
\texttt{afm} files to learn things about the fonts it's processing,
and sloppily prepared \texttt{afm}s lead to disaster.  This version of
\vfinst\ attempts to second-guess an \texttt{afm} file as much as
possible.  A variable called \verb+@sloppy_afms+ contains a list of
particularly sloppy \texttt{afm}.  Currently, it refers to Adobe
Garamond and Minion, Monotype Bulmer, Lucida Bright, and BitStream
Chianti.  You can add to it if you feel you've discovered another
malefactor.  (See the beginning of file \texttt{vfinst.lib} for this
variable.)  Another mechanism for correcting \texttt{afm} files lies
in the file \texttt{vfinst.rc}; see below.

\subsection{Scope of testing}
This software was tested on a Linux box and under WindowsNT~4.0 using
both \textsc{tds} and traditional versions of \TeX.  \vfinst\ was
extensively tested on several popular font families, including the
PostScript-resident fonts Times Roman, Palatino, and New Century
Schoolbook, as well as Adobe Garamond, Adobe Caslon, Adobe Minion,
Monotype Bulmer, and Monotype Baskerville, Lucida Bright, plus many
other families of fonts that were lying around on my hard disk.  They
all installed fine for me.

\subsection{Legal jargon and caveats}
This software is distributed according to the terms of the \textsc{GNU}
`copyleft' agreement.  In addition, please note that if you make any
alterations to any of the files in this package, you must change the
names of the altered files.  You are allowed to freely use this
material and to pass it along (in the unaltered state!) provided you
will not be using it to make money; otherwise, you must get in touch
with me to secure permission.

While the author hopes that it will prove useful, it is distributed
with no guarantee or warranty whatsoever.  Users should take
\textsc{great care} to carefully back up their data before using.

\section{\TT VFinst and what you'll need to run it}

\vfinst\ itself consists of Perl scripts and some supporting files.

%% These files are named:
%%  
%% \begin{itemize}
%%   \item \TT 1vfinst and \TT 2vfinst; 
%%   \item \TT vfinst.lib, a library of common routines; 
%%   \item \TT vfinst.par, a set of parameters that everyone who uses
%% this material will have to customize for their installation; 
%%   \item \TT vfinst.rc, a file containing some non-invasive corrections
%% to particular \TT.afm files (\vfinst\ reads this information without requiring
%% you to modify the \TT.afm files themselves); 
%%   \item several map files called \texttt{map.a2d}, \texttt{map.n2a},
%% and \texttt{map.sup} (These have been compiled using information
%% from several of the files provided in Karl Berry's \texttt{fontname}
%% package.); 
%%   \item example output; and 
%%   \item several miscellaneous other files.
%% \end{itemize}

\subsection{Example output}
In the subdirectory {\tt example}, you'll find the {\tt pfb} and {\tt
afm} files for the Roman typeface Utopia, placed in the public domain
by URW.  In addition, you'll find other files that are the result of
the {\tt vfinst} process.  

\subsection{What you'll need}
Here's what you'll need to properly install your fonts using \vfinst:
\begin{enumerate}
\item a version of \TeX\ that understands virtual fonts (version 3 or
better of \TeX);
\item the \texttt{fontinst} package available from any \CTAN\ archive
or mirror in the area 
\begin{verbatim}
fonts/utilities/fontinst/inputs
\end{verbatim}
Installation of this
package is easy---you simply take {\bf all\/} of the files in this directory
and place them in a directory on your system that \TeX\ know how to
read from.  For traditional systems, this is apt to be a place like
`{\tt tex/inputs}' and on a {\sc tds} system, a place like 
\begin{verbatim}
texmf/tex/generic/fontinst
\end{verbatim}
is appropriate.  
(There are apparently several different versions on \CTAN.
You want version~1.5 or greater.  Versions before that may not
work.)
\item the {\it dvips\/} post-processor;
\item a copy of the file \texttt{8r.enc}, part of the
\texttt{fontname} package (this package is available from any \CTAN\
archive from the area \texttt{info/fontname}); and
\item a copy of Perl.
Perl is a powerful language for text processing.  I chose Perl because
versions of Perl are freely available for every computer platform.
You don't need to understand Perl---just get a copy of the executable
file, place it on your computer's path, and (if necessary) make it
executable.  This material has been tested under Perl5 (the current
version).  Perl should be available from any good software archive and
from many \textsc{cdrom} collections of software.
\end{enumerate}

This material should run on any platform on which runs Perl and \TeX.

\section{Installation and set up}

\subsection{Installation}

To install \vfinst, create a new directory, possibly something like
\begin{verbatim} 
 /usr/local/vfinst
\end{verbatim}
under Unix or
\begin{verbatim}
 \tex\vfinst
\end{verbatim}
under \textsc{dos}.  Copy the all the \vfinst\ files (with the
possible exeception of the examples) into that directory.  

Now create a work directory below this new directory, with a full 
pathname like
\begin{verbatim} 
 /usr/local/vfinst/work
\end{verbatim}
for Unix or
\begin{verbatim}
 \tex\vfinst\work
\end{verbatim}
under \textsc{dos}.   
Switch to this lowest level \TT work subdirectory, which we
will call the \vfinst{} {\tt work}ing directory.  If you are on a
Unix system, make sure you have permission to write files in this
working area.

Also, make sure that your implementation of \TeX\ contains 
the {\it parent\/} directory and the {\it current\/} directory on 
its own search path.

There are some things that need setting in the file \TT vfinst.par,
which is one of the files in the \vfinst{} directory.
{\bf Everyone\/} must set these up properly---\vfinst\ won't work
properly otherwise, and there are no default settings for these
parameters.  Take the time to doublecheck the settings for
accuracy.  

Since this is a Perl file, you must follow Perl syntax in
the setup.  This isn't difficult; see below for examples of setups.
In particular, the Perl comment character is {\tt\char`\#}, which
can hide or expose a line to Perl as the `{\tt\char`\%}' does in a
\TeX\ document.

\subsection{Everybody must set these...}
\begin{enumerate}
\item \TT \$vfenc is the encoding you'll want to be using.  Although
    many in the \TeX\
    community are pushing an encoding called \TT t1, I prefer to use the
    original \TeX\ encoding called \TT ot1 because there is room in these
    virtual fonts for many additional characters.  Your only choice for
    this parameter is \TT t1 or \TT ot1.  Users of versions of
   \LaTeX\ predating December 1996 might enter 
    \TT T1 or \TT OT1 instead.

{\fontsize{9}{10}\selectfont
If you use the lowercase {\tt ot1} or {\tt t1} designations, you'll
need to {\em make sure\/} that corresponding files {\tt
ot1\char`\*.etx} and {\tt t1\char`\*.etx} are in a \TeX\ input
directory.  If such named files do not accompany your copy of \TT
fontinst, the simplest thing to do is make a copy of all the {\tt
OT1\char`\*.etx} and {\tt T1\char`\*.etx} files, which are part of the
\TT fontinst package, and give them the appropriate names, eg
{\tt cp OT1.etx ot1.etx} (using Unix syntax).\endgraf}

%% \item \TT \$vfencoding is the place which 
%% contains a copy of the file \TT 8r.enc (which describes the
%% \TT TeXBase1Encoding promulgated by all good users of \TeX).  This
%% place merits its own variable only because I've found it convenient to
%% place this file somewhere with a short path name---otherwise the
%% entries in \TT psfonts.map become uncomfortably long.  You don't need
%% to set this variable; if it's not set, \vfinst\ will assume that \TT
%% 8r.enc appears in the same directory as {\tt\$vfmapdir}. 
\end{enumerate}

In earlier versions of \vfinst, a special variable contained the
location of the file \TT 8r.enc.  With this release, it is assumed
visible to \TT dvips without any path prefix.  For traditional users,
this may mean placing it in your \TT work directory.  For TDS users,
this means nothing special, as \TT dvips will be able to find it via
the search mechanism that accompanies the TDS installation.

\subsection{TDS systems}
\TeX\ knows it's a {\sc tds} installation if the variable \TT
\$vftexmf is defined; it should have as
values the root \TeX/MF directory.  One advantage of
{\sc tds} is that \vfinst\ can then figure out for itself where most
things belong.

In a {\sc tds} system, \vfinst\ will ask you later for certain
additional information pertaining to your fonts.
For each font family, \vfinst\ needs a typeface name (like
`\texttt{agaramon}', `\texttt{times}', etc.) and a supplier
(\texttt{adobe}, \texttt{monotype}, and so on).  \vfinst\ tries to 
figure this out by itself, and may simply request verification from
you.  In stubborn cases, it will ask you for this information.

\subsection{Traditional systems}
On traditional systems, all {\tt.afm}'s go in one place, all
{\tt.tfm}'s in another, and so on.  Such installations need to define
the following variables.  Directories are not well-structured in these
kinds of systems, so \vfinst\ needs lots of information from you, and
this additional information belongs in \texttt{vfinst.par}.

\begin{enumerate}
\item \TT \$vfvf is the place where virtual fonts are kept.  If you have vf's
    on your system already, use this directory name.  Otherwise, you'll
    need to check your {\it dvips} or driver documentation to see where those
    programs expect to find the vf's.  It should be something like
    \begin{verbatim}
      "/usr/lib/tex/fonts/vf"
    \end{verbatim}
    (Unix) or perhaps
    \begin{verbatim}
      "\\emtex\\fonts\\vf"
    \end{verbatim}
    (\textsc{dos}; the backslash must be doubled as shown, or Perl will 
    misunderstand it). 

\item \TT \$vftfm is the place where \TeX\ looks for your \TT.tfm files.

\item \TT \$vfpsfonts records the location of your outline font files, files
    typically with extensions \TT.pfa or \TT .pfb. 

\item \TT \$vfafm is the directory containing all the \TT.afm files for the
    outline font files.  Unlike most software out there, \TeX\ needs these
    files. 

\item \TT \$vfmapdir is the place where you keep the file \TT psfonts.map that 
    {\it dvips} uses.

\item \TT \$vfinputs is the place where the \TT.fd and other input 
    files belong.
\end{enumerate}

\subsection{Sample setups}
The first part of the \vfinst\ setup for a traditional Unix system
might look as follows.  These declarations are part of the file \TT
vfinst.par. 

On a Unix {\sc tds} system, these settings might have the following form.
\begin{verbatim}
$vftexmf    = "/usr/texmf";
$vfencoding = "/usr"; # where is the file 8r.enc?               
$vfenc      = "ot1";
\end{verbatim}

Here is a sample Unix setup for a traditional \TeX\ system. 
\begin{verbatim}
$vfmapdir   = "/usr/lib/tex/ps"; 
$vfinputs   = "/usr/lib/tex/inputs"; 
$vfencoding = "/usr";
$vfenc      = "ot1";
$vfvf       = "/usr/lib/tex/fonts/vf";
$vftfm      = "/usr/lib/tex/fonts/tfm";
$vfpsfonts  = "/psfonts";
$vfafm      = "/psfonts/afm";
\end{verbatim}
On a \textsc{dos} system, these instructions
might take the form
\begin{verbatim}
$vfmapdir   = "\\tex\\ps";
$vfinputs   = "\\tex\\inputs";
$vfencoding = "$vfinputs";
$vfenc      = "t1";
$vfvf       = "\\tex\\fonts\\vf";
$vftfm      = "\\tex\\fonts\\tfm";
$vfpsfonts  = "\\psfonts";
$vfafm      = "\\psfonts\\afm";
\end{verbatim}
(note the doubled backslashes).

\subsection{Other parameters \& considerations}
The other `wizards only' parameters should already have been set for
you. 

If your system understands the `shebang' convention (whereby you type
the name of script, and it knows to invoke Perl and run like a named
program; the first line of the script must begin with `{\tt\#!}'),
then all you'll need to do is adjust the initial line of files
{\tt1vfinst} and {\tt2vfinst} to reflect the location of your Perl
executable.  On Unix systems, you'll also need to make these scripts
executable via the {\tt\ chmod +x\ } command.

If your version of \TeX\ is a
multitasking application, such as Tom Rokicki's excellent \TeX View on
NextStep, you'll need to make the application quit and restart it to
make your new fonts visible to it.

\section{Running \TT VFinst }

To use \vfinst, simply copy all the fonts (outline file plus \TT.afm file)
to the \vfinst\ {\tt work}ing directory.  \vfinst\ won't care what filenames
these have, nor how many font families are represented.  If you have
any expert, small caps, extension, or alternate fonts, include them
too by all means.  \vfinst\ will use them if present to make true small
caps fonts.  {\bf You MUST make sure that the outline font file
and the matching {\tt.afm} have identical filenames.}

Then, simply execute the following sequence of commands:
\begin{itemize}
\item {\tt1vfinst}
\item {\tt2vfinst}
\end{itemize}
Under the `shebang' notation, you need simply enter something like
{\tt../1vfinst}; otherwise, type something like {\tt perl ../1vfinst}.
These two scripts execute rapidly, although they pause to request
information or verification from you.  They will try to figure out the
font supplier, the font family, and some {\sc tds} directory information,
and it is this material that needs to be verified and/or provided. 

Sometimes digital foundries are sloppy about naming their fonts
consistently, and so \vfinst\  may ask you to verify or enter a font family
abbreviation for one family more than once.  For example, Monotype
Baskerville has been assigned to the family named {\tt BaskervilleMT}
while the matching expert font is in the family {\tt BskvillExpMT}.
(These are the names appearing in the {\tt.afm} file.)  A \TeX\ author
clearly needs them in the same font family, so verify family {\tt mbv}
for the first, and verify family {\tt mbv} for the second, so that
\vfinst\ will know they are in the same family.

It often pays to briefly examine the files that \TT1vfinst produces.
There is a small file \TT duplicat.lst which contains a list of fonts
that \vfinst\ thinks are duplicates.  It will help later steps proceed
faster if you eliminate any duplicates---and if you do, don't forget
to remove both \TT.pfb and \TT.afm file.  Entries in this file may
also indicate a problem with the \TT.afm file; see
page~\pageref{afm-error}\ below for more on this.

The other output file is \TT fonts.lst, a list of all fonts with their
proposed new names, old names, and some information that will be of
interest to later steps in the \vfinst\ process.  You should examine
this list and eliminate any special-purpose fonts, such as special
fraction or ornament fonts, from the installation
process.  It will also
be helpful to eliminate all fonts with a width variant (such as
Helvetica Narrow, etc.).

If you remove any fonts from your working directory, make sure to
re-run \TT1vfinst.

There are several additional steps. Execute the following scripts,
which are outputs of the previous two steps:
\begin{itemize}
\item {\tt mkdirs.bat}
\item {\tt newnames.bat}
\end{itemize}
to create any missing directories and to rename the fonts according to
the {\tt fontname2.1} conventions.  These steps take very little time.

Then, execute the command
\begin{verbatim}
tex makefont
\end{verbatim}
to create the virtual fonts; the file \TT makefont.tex is the output
of the original Perl scripts.  This step may take a long
while.  Ignore warnings about missing glyphs.

Next, execute the script
\begin{itemize}
\item {\tt maketfm.bat}
\end{itemize}
to convert your Ascii property list files into the binary {\tt.tfm} and
{\tt.vf} files that \TeX\ expects.  Finally, execute the two scripts

\begin{itemize}
\item {\tt putfonts.bat}
\item {\tt putvftv.bat}
\end{itemize}
These two scripts, which execute rapidly, are responsible for
placing all files into
places from which \TeX\ can use them for typesetting.  {\bf The fonts
cannot be said to be installed until these two steps are carried out.}
I suppose that users on multi-user systems will have to request their system
administrator perform these tasks.

One special step is necessary for \textsc{tds} systems only!  Whenever
new fonts are added to a \textsc{tds} system, it will be necessary to
run a small utility which accompanies \TeX.  This tool may be named
\TT texhash or \TT configure or \TT mktexlsr something else entirely,
and is necessary to place the names of the new fonts in database that
\textsc{tds} uses to locate files and fonts.

Now, your new fonts are ready for
use.  You can test your fonts by running either of the files {\tt
testpln.tex} or {\tt testltx.tex} through \TT plain \TeX\ or through
\LaTeX.  These files also show what commands to use to select your new
fonts.

Once the installation has been completed according to the above
steps, everything left in the work directory may be deleted.

\subsection{Installing `raw' fonts}
\vfinst\ is intended for fonts that require auxiliary constructs
called \textit{virtual fonts} for proper use by \TeX.  This does not
include every font you might purchase.  For example, dingbat fonts,
special alphabets (phonetic fonts, foreign languages, {\sc apl}) and
so on don't require the virtual font mechanism.  Installation to make
these fonts usable by \TeX\ is a much simpler process, but you have to
do the work yourself.  To illustrate the process, let's suppose you
have files {\tt foo.afm} and {\tt foo.pfb} for installation.  Follow
these steps:
\begin{itemize}
\item You'll need program \texttt{afm2tfm}, part of the {\it dvips\/}
suite.  Execute the command
\begin{verbatim}
afm2tfm foo
\end{verbatim}
This creates a file {\tt foo.tfm} for use by \TeX, and displays a line
like
\begin{verbatim}
foo AGaramond-Regular
\end{verbatim}
(or whatever) on your console..  
\item Place this displayed line in the file {\tt psfonts.map}.  If
it's a non-resident font, you'll need to adjust this line as follows:
\begin{verbatim}
foo AGaramond-Regular <foo.pfb
\end{verbatim}
to automatically download the font to the printer at print time.
\item Place the {\tt.afm} and {\tt.pfb} font files where they belong
on your system disk.  Place {\tt foo.tfm} where it belongs.
\item To select this font in a {\tt plain} document, add a line like
\begin{verbatim}
\font\myfont = foo at 13pt
\end{verbatim}
to make \verb+\myfont+ the command that selects this font (at thirteen
points).  In \LaTeX, you can use the undocumented command 
\begin{verbatim}
\newfont{\myfont}{foo at 13pt}
\end{verbatim}
to accomplish the same goal.
\end{itemize}

\section{Using your new fonts}
The files {\tt testpln.tex} or {\tt testltx.tex} can help you test and
preview your new fonts.  These files also can be consulted to see how
these fonts were selected; this will be most useful for users of \TT
plain \TeX.

\LaTeX\ users will, of course, select their fonts by selecting the
proper family, series, and shape.  Note that in the presence of expert
fonts, \vfinst\ creates two families---one that is expertised but with
standard numerals, and another that is expertised and uses old style
figures.  In the absence of expert fonts, \vfinst\ installs a single
family (and creates small caps by means of judicious scaling of the
font majuscules.  Thus, if the font family name \TT foo has no expert
fonts, \vfinst\ installs the raw fonts under the family {\tt foo}.  In
the presence of expert fonts, you will have two families---{\tt foox}
and {\tt foo9}.  Note too the existence of several new font shapes
which may be available for use by {\sc nfss}:
\begin{itemize}
  \item {\tt si} provides italic small caps;
  \item {\tt t}  provides a titling or display font;
  \item {\tt ti} provides a titling or display italic; 
  \item {\tt sw} provides a swash italic variant;
  \item {\tt un} provides an underline upright font; and
  \item {\tt ni} provides an underline italic font.
\end{itemize}
\vfinst\ will only provide these shapes in case the original raw fonts
that were present support these shapes.

\section{Causes for failure and other problems}
\vfinst\ maintains an extensive log file called \TT vfinst.vlg
which contains useful information which may be of use in case of
disaster or other problems.  (Another log file, \texttt{maketfm.vlg},
records information about the making of the binary font files but is
generally of less usefulness.)

You may find that when you install too many fonts at once, \TeX\ won't
have enough font memory to load all of them at once.  You may have to
compile the test documents in parts---comment out a portion, test the
remainder, and so on.

Installing too many fonts may lead to another rare error involving
older versions of \textit{dvips}.  After a while, the
\texttt{psfonts.map} file becomes too lengthy and \textit{dvips}
expires while complaining of being `out of string space'.  The easiest
fix is simply to comment out entries in \texttt{psfonts.map} that you
aren't currently using.  The comment character is \TeX's `{\tt\%}'
symbol.  Even better: simply update to a current version of
\textit{dvips}. 

\vfinst\ warns you on the rare occasion when the {\tt fontname} name
of a font exceeds eight characters; an example is the swash italic
display characters in Adobe Minion.  This is only a problem for
\textsc{dos} users, who should probably remove these fonts from the
\vfinst\ {\tt work} directory and re-run \vfinst.  

\subsection{Fixing {\tt.afm} files}
Virtual fonts that are created but don't typeset as you expect may
indicate a problem with the font {\tt.afm} files rather than with
\vfinst.  Font providers are often careless (at best!) with these
files.  Errors that I have encountered include misspelling the words
`bold' and `italic' (now really!), improper specifying an $x$-height
to be 0, and improperly naming the glyphs of the fonts.  All these
will effect the resulting fonts.

\label{afm-error}Entries in the file \TT duplicat.lst may 
indicate other problems with the \TT.afm file.  While testing, I many
times received warning that \vfinst\ thought that one font was a
duplicate of another when in fact one font was a regular weight and
the second was bold.  Closer inspection of the bold \TT.afm revealed
the problem---the `Weight' entry the \TT.afm file had erroneously been
filled in as `{\tt regular}' even though it was a bold font.
Basically, \TT.afm problems involve correcting metric data in the body
of the file or correcting non-metric data in the initial portion of
the file.  Both \TT fontinst and \vfinst\ provide means for correcting
these errors.  It is a bad, bad idea to make corrections to the
\TT.afm file itself.  

Changes to data in the initial portion of an \TT.afm involve creating
a file called \TT vfinst.rc each line of which records three
items---the font name of the deficient font, the name of the
characteristic to change, and the corrected value of that
characteristic.  Each of these fields should be separated by one or
more spaces.  The font name is the long font name that follows the
keyword `FontName' in the first part of the \TT.afm file (within the
the first dozen lines from the top of the file).

The \TT.rc file that comes with the current distribution looks like this:
{\fontsize{8}{9}\selectfont
\begin{verbatim}
CentaurSwashMT            FullName       Centaur Swash Italic MT
Courier                   Weight         Roman
Courier-Oblique           Weight         Roman
Helvetica                 Weight         Roman
JansonExpertMT-BoldItalic ItalicAngle    -14
NewCenturySchlbk-Italic   Weight         Roman
Palatino-Italic           Weight         Roman
AGaramond-Bold            Weight         Bold
AGaramond-Semibold        Weight         Semibold
AGaramond-BoldItalic      Weight         Bold
AGaramond-SemiboldItalic  Weight         Semibold
AGaramondExp-Bold         Weight         Bold
AGaramondExp-Semibold     Weight         Semibold
AGarExpSemIta             Weight         Semibold
AGarExpSemIta             FullName Adobe Garamond Expert Semibold Italic
AGaramondExp-BoldItalic   Weight         Bold
AGaramond-BoldItalic      ItalicAngle    -18.5
AGaramondExp-BoldItalic   ItalicAngle    -18.5
AGarExpSemIta             ItalicAngle    -18.5
AGaramond-SemiboldItalic  ItalicAngle    -18.5
AGaramond-Italic          ItalicAngle    -18.5
AGaramondExp-Italic       ItalicAngle    -18.5
AGaramondAlt-Italic       ItalicAngle    -18.5
NewsGothic-Oblique        Weight         Medium
Garamond-BookItalic       Weight         Book
NewsGothic-BoldOblique    Weight         bold
\end{verbatim}
}%
This file indicates, for example, 
that \vfinst\ is to regard the weight of the font
\TT Courier as Roman, the italic angle of \TT JansonExpertMT-BoldItalic
as $-14^{\circ}$, and the full name of \TT CentaurSwashMT as that 
given here.  (The original font didn't include the
word `italic' in the font name, so \vfinst\ assumed the swash applied
to upright fonts.)  

I'd be grateful to anyone who could send me additional errors of this
nature they encounter in using fonts, so I can encounter them in
future revisions of this file. 

%% Problems with the body of the \TT.afm file can be fixed with special
%% \TT fontinst instructions.  For example, one serious yet common
%% problem involves improper naming of the glyphs within the \TT.afm
%% file.  Suppose an expert font names its lowercase letters
%% `a', `b', and so on instead of `Asmall', `Bsmall', etc.  Then {\tt
%% fontinst}, the engine on which \vfinst\ runs, will not use these
%% glyphs in a small caps font.  Here's how I used \TT fontinst to fix
%% this. 
%% 
%% When installing a font via the command
%% \begin{verbatim}
%% \installfont{foorc9t}{foor8r,foorc8a,latin}%
%%   {OT1c}{OT1}{foox}{m}{sc}{}
%% \end{verbatim}
%% where the {\tt foo} fonts suffer this disability, I ``turn off'' the
%% miniscule (lowercase) information with commands like
%% \begin{verbatim}
%% \unsetglyph{a}
%% \end{verbatim}
%% placed (together with additional syntactical necessities) in a file
%% \TT minoff.mtx.  In the same way, commands in a file \TT numoff.mtx
%% turn off standard digit glyph information.  Then, I make use of the
%% glyph information in the small caps font (here, {\tt foorc8a}) with
%% commands like
%% \begin{verbatim}
%% \SmallCapFrom{Asmall}{a}
%% \end{verbatim}
%% in a file {\tt smcapon.mtx} which also contains a definition of this
%% command.  In the same way, the file {\tt osfon.mtx} sets old style
%% figures from the glyphs in this font.  These four metric \TT.mtx files are
%% part of the \vfinst\ distribution; please use them as examples for
%% solving similar kinds of problems.  We use them in this instance 
%% by modifying the above install command {\em by hand\/}:
%% \begin{verbatim}
%% \installfont{foorc9t}{foor8r,minoff,numoff,foorc8a,smcapon,%
%%   osfon,latin}{OT1c}{OT1}{foox}{m}{sc}{}
%% \end{verbatim}
%% Now, run the revised file \TT makefont.tex through \TeX, and continue
%% the \vfinst\ process from this point.

\section{Other operating systems}

{\fontsize{9}{10}\selectfont
I designed these scripts to be easy to adapt to other operating
systems.  That, in fact, motivated my choice of Perl.  All of the
testing and development work was done in Unix, however.

Here are some things that need attention in going to another operating
system. Change the three environment variables marked for `wizards only'.  
\begin{enumerate}
\item \TT\$vfsep is the directory separator in paths; for ex, \TT/ in Unix, 
   \verb|\| in \textsc{dos}.
\item \TT\$vfcopy is the copy command (eg, \TT cp and \TT copy in Unix
    and \textsc{dos}.  respectively)
\item \TT\$vfdel is the delete command (for erasing files); it is \TT
    rm in Unix and \TT del in \textsc{dos}.
\item \TT\$mv is the move command---the command that will move one
file onto another even if the destination file already exists.  In
Unix, this command is `\texttt{mv}'.  On {\sc dos}, it is `{\tt call
domove}' where {\tt domove.bat} is a batch file with lines
\begin{verbatim}
copy %1 %2
del %1
\end{verbatim}
(The file {\tt domove.bat} is part of the {\sc dos} distribution.  You must
remember to copy it to the \vfinst\ working directory or to a place on your
system's search path.)
\item \TT\$ren is the command for renaming a file. 
\item \TT\$rem is the string that introduces comments in system {\sc
Ascii} files.  It is `{\tt\#}' and `{\tt rem}' in Unix and {\sc dos}.
\end{enumerate}

Other places in the Perl files where it seemed to me would require
system dependent changes are marked by the phrase `system dependent'
in comments in the code.\par}

\section{Additional info; authorial communications; acknowledgments}
I'm truly grateful for the comments, suggestions, and trapped bugs
reported by folks who took time to wrestle with this software.  I
especially want to acknowledge
\helper{Chang}{Andrew}, 
\helper{Christian}{Burger},
\helper{Courjon}{Daniel}, 
\helper{Marquardt}{Colin},
\helper{Ness}{David} (especially!), 
\helper{Padowitz}{Seth},
\helper{Roggen}{Arend van }, 
\helper{Sullivan}{Wayne},
\helper{Swift}{Matt},
\helper{Walker}{Richard}, and
\helper{Yates}{Michael}.

For some additional information, please consult the book {\it \TeX\
Unbound: \LaTeX\ and \TeX\ Strategies for Fonts, Graphics, and More\/}
by Alan Hoenig (New York and Oxford: Oxford University Press, 1998). 

I'd love to hear from anyone with comments, criticisms, suggestions
for improvements, and (of course) bugs that need fixing.  

\begin{flushright}
  Alan Hoenig\\
  {\tt ajhjj@cunyvm.cuny.edu}\\
  Department of Mathematics\\
  John Jay College\\
  445 West 59th Street\\
  New York, NY 10019 USA\\[1pc]
  24 August 1998
\end{flushright}

\end{document}
