%%% ====================================================================
%%%  @LaTeX-file{
%%%     author          = "Alan Jeffrey and Rowland McDonnell and
%%%                        Ulrik Vieth",
%%%     version         = "1.801",
%%%     date            = "30 June 1998",
%%%     time            = "01:20:27 CEST",
%%%     filename        = "fontinst.tex",
%%%     email           = "fontinst@cogs.susx.ac.uk",
%%%     checksum        = "53274 2572 11762 94079",
%%%     codetable       = "ISO/ASCII",
%%%     keywords        = "fontinst, TeX, PostScript, documentation",
%%%     supported       = "yes",
%%%     abstract        = "This is the documentation for the fontinst
%%%                        font installation package.",
%%%     package         = "fontinst",
%%%     dependencies    = "ltxguide.cls, url.sty, xspace.sty"
%%%  }
%%% ====================================================================

% Copyright 1993, 1994, 1995, 1996 Alan Jeffrey

% Modified by Rowland McDonnell June 1998
% Modified and revised by Ulrik Vieth June 1998

\documentclass[a4paper]{ltxguide}
\usepackage[OT1]{fontenc}
\usepackage{url,xspace}
\usepackage{graphicx}

%\renewcommand\rmdefault{ppl}
%\renewcommand\rmdefault{pbb}
%\renewcommand\rmdefault{pacj}
%\renewcommand\rmdefault{padj}
%\renewcommand\rmdefault{pmnj}


% Title page and running heads.

\makeatletter
\newcommand{\subtitle}[1]{\renewcommand{\@subtitle}{#1}}
\newcommand{\version}[1]{\renewcommand{\@version}{#1}}
\newcommand{\illustration}[1]{\renewcommand{\@illustration}{#1}}

\newcommand{\@subtitle}{}
\newcommand{\@version}{???}
\newcommand{\@illustration}{cover.eps}

\pagestyle{myheadings}
\AtBeginDocument{\markright{\small\itshape
  \@author\hfill\@title: \@subtitle\quad}}


\renewcommand{\maketitle}{{%
   \thispagestyle{empty}%
   \normalfont\centering
   \null
   {\fontsize{100}{100}\textit{\@title}}%
   \par\bigskip
   {\Large\textbf{\@subtitle}}%
   \vfill
   \includegraphics[width=\textwidth]{\@illustration}%
   \vfill
   {\Large\textbf{%
      \@author\\[\smallskipamount] \@title~v\@version
      \quad\textperiodcentered\quad \@date}}%
   \clearpage
}}
\makeatother


% Set lists tighter (assuming non-zero \parskip).

\makeatletter
\renewcommand{\@listI}{%
   \leftmargin\leftmargini
   \parsep\medskipamount
   \itemsep\z@ % + parsep
   \topsep\z@ % + parskip
   \partopsep\z@
}
\makeatother

% Set spacing around captions.

\setlength{\abovecaptionskip}{\medskipamount}
\setlength{\belowcaptionskip}{\medskipamount}

% Markup for logos, file types, programs, etc.

\newcommand*{\cs}[1]{\texttt{\char`\\ #1}\xspace}

\newcommand*{\OzTeX}{O\kern-.03em z\kern-.15em\TeX}
\newcommand*{\OzMF}{O\kern-.03em zMF}
\newcommand*{\OzTools}{O\kern-.03em z\kern-.15em Tools}

\newcommand{\PS}{Post\-Script\xspace}
\newcommand{\TT}{True\-Type\xspace}

\newcommand*{\setfilename}[1]{\texttt{#1}}
\newcommand*{\setdotfilename}[1]{\setfilename{.#1}}
\newcommand*{\setpackagename}[1]{\textsc{#1}}

\newcommand{\dvips}   {\setpackagename{dvips}\xspace}
\newcommand{\Dvips}   {\setpackagename{Dvips}\xspace}
\newcommand{\fontinst}{\setpackagename{font\-inst}\xspace}
\newcommand{\Fontinst}{\setpackagename{Font\-inst}\xspace}

% \show\fontname
\newcommand{\fontnamekb}{fontname\xspace}
\newcommand{\Fontnamekb}{Fontname\xspace}

\newcommand{\mf} {\setfilename{mf}\xspace}
\newcommand{\Mf} {\setfilename{Mf}\xspace}
\newcommand{\vf} {\setfilename{vf}\xspace}
\newcommand{\Vf} {\setfilename{Vf}\xspace}
\newcommand{\pl} {\setfilename{pl}\xspace}
\newcommand{\Pl} {\setfilename{Pl}\xspace}
\newcommand{\fd} {\setfilename{fd}\xspace}
\newcommand{\Fd} {\setfilename{Fd}\xspace}
\newcommand{\pk} {\setfilename{pk}\xspace}
\newcommand{\Pk} {\setfilename{Pk}\xspace}
\newcommand{\afm}{\setfilename{afm}\xspace}
\newcommand{\Afm}{\setfilename{Afm}\xspace}
\newcommand{\vpl}{\setfilename{vpl}\xspace}
\newcommand{\Vpl}{\setfilename{Vpl}\xspace}
\newcommand{\tfm}{\setfilename{tfm}\xspace}
\newcommand{\Tfm}{\setfilename{Tfm}\xspace}
\newcommand{\mtx}{\setfilename{mtx}\xspace}
\newcommand{\Mtx}{\setfilename{Mtx}\xspace}
\newcommand{\etx}{\setfilename{etx}\xspace}
\newcommand{\Etx}{\setfilename{Etx}\xspace}
\newcommand{\pfa}{\setfilename{pfa}\xspace}
\newcommand{\Pfa}{\setfilename{Pfa}\xspace}
\newcommand{\pfb}{\setfilename{pfb}\xspace}
\newcommand{\Pfb}{\setfilename{Pfb}\xspace}
\newcommand{\dvi}{\setfilename{dvi}\xspace}
\newcommand{\Dvi}{\setfilename{Dvi}\xspace}
\newcommand{\ttf}{\setfilename{ttf}\xspace}
\newcommand{\Ttf}{\setfilename{Ttf}\xspace}

\newcommand{\vftovp}{\setpackagename{vftovp}\xspace}
\newcommand{\vptovf}{\setpackagename{vptovf}\xspace}
\newcommand{\pltotf}{\setpackagename{pltotf}\xspace}
\newcommand{\tftopl}{\setpackagename{tftopl}\xspace}


% Stolen from Dr Knuth
\makeatletter % borrow the private macros of PLAIN (with care)
\def\oct#1{\hbox{\rm\'{}\kern-.2em\it#1\/\kern.05em}} % octal constant
\def\hex#1{\hbox{\rm\H{}\tt#1}} % hexadecimal constant
% macros for font tables
\def\oddline#1{\cr
  \noalign{\nointerlineskip}
  \multispan{19}\hrulefill&
  \setbox0=\hbox{\lower 2.3pt\hbox{\hex{#1x}}}\smash{\box0}\cr
  \noalign{\nointerlineskip}}
\def\evenline{\cr\noalign{\hrule}}
\def\chartstrut{\lower4.5pt\vbox to14pt{}}
\def\beginchart#1{$$\global\count@=0 #1
  \halign to\hsize\bgroup
    \chartstrut##\tabskip0pt plus10pt&
    &\hfil##\hfil&\vrule##\cr
    \lower6.5pt\null
    &&&\oct0&&\oct1&&\oct2&&\oct3&&\oct4&&\oct5&&\oct6&&\oct7&\evenline}
\def\endchart{\raise11.5pt\null&&&\hex 8&&\hex 9&&\hex A&&\hex B&
  &\hex C&&\hex D&&\hex E&&\hex F&\cr\egroup$$}
\def\*{\global\advance\count@ by1 }
\def\:{\setbox0=\hbox{\char\count@}%
  \ifdim\ht0>7.5pt\reposition
  \else\ifdim\dp0>2.5pt\reposition\fi\fi
  \box0\global\advance\count@ by1 }
\def\reposition{\setbox0=\hbox{$\vcenter{\kern2pt\box0\kern2pt}$}}
\def\smallchart{%
%\global\advance\count@ by16
  &\oct{00x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline0
  &\oct{01x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{02x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline1
  &\oct{03x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{04x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline2
  &\oct{05x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{06x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline3
  &\oct{07x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{10x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline4
  &\oct{11x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{12x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline5
  &\oct{13x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{14x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline6
  &\oct{15x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{16x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline7
  &\oct{17x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline}

\def\bigchart{%
%\global\advance\count@ by16
  &\oct{00x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline0
  &\oct{01x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{02x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline1
  &\oct{03x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{04x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline2
  &\oct{05x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{06x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline3
  &\oct{07x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{10x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline4
  &\oct{11x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{12x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline5
  &\oct{13x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{14x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline6
  &\oct{15x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{16x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline7
  &\oct{17x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{20x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline8
  &\oct{21x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{22x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline9
  &\oct{23x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{24x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline{A}
  &\oct{25x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{26x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline{B}
  &\oct{27x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{30x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline{C}
  &\oct{31x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{32x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline{D}
  &\oct{33x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{34x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline{E}
  &\oct{35x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{36x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline{F}
  &\oct{37x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline}

% \font\xrm = cmr10 at 10pt % change this line to test font
% \beginchart\xrm \normalchart \endchart

\newcommand{\smallfontchart}[1]{%
  \font\xrm = #1 \beginchart\xrm \smallchart \endchart}
\newcommand{\bigfontchart}[1]{%
  \font\xrm = #1 \beginchart\xrm \bigchart \endchart}

% \smallfontchart{cmr10 at 10pt}
% \bigfontchart{ecrm1000 at 10pt}
\makeatother
% End stolen from Dr Knuth



\title{fontinst}
\subtitle{Font installation software for \TeX}
\author{Alan Jeffrey and Rowland McDonnell}
\illustration{roadmap.eps}
\version{1.8}
\date{30 June 1998}

\begin{document}

\maketitle

\tableofcontents

\vfill

\begin{footnotesize}
  This manual describes the \texttt{fontinst} software for converting
  fonts from Adobe Font Metric format to forms readable by \TeX.  This
  manual should be distributed with the \texttt{fontinst} software,
  which is available by anonymous FTP from
  \url{ftp://ftp.tex.ac.uk/tex-archive/fonts/utilities/fontinst}, and
  on the various CD-ROMs containing material from the CTAN archives.
  Please do not contact the author directly for copies.

  If you would like to report a bug with \texttt{fontinst}, please
  mail \url{fontinst@cogs.susx.ac.uk}.  The mail will be sent to the
  \texttt{fontinst} mailing list.  If you would like to be on the
  \texttt{fontinst} mailing list, please mail
  \url{fontinst-request@cogs.susx.ac.uk}.

  The \texttt{fontinst} package is copyright \copyright~1993--1996
  Alan Jeffrey.  The \texttt{trig} macro package is copyright
  \copyright~1993--1998 David Carlisle.  Unless indicated otherwise,
  the contents of the \texttt{contrib} directory are copyrighted by
  the individual authors.  All rights reserved.  The moral right of
  the authors has been asserted.
\end{footnotesize}


\clearpage

\section{Introduction}

The \fontinst package is a set of \TeX\ macros written to create
virtual fonts for use with \TeX. Its main use is creating the
files needed so you can use PostScript Type 1 fonts with \LaTeX.

\Fontinst needs information about the fonts it works with.  This
information needs to be supplied in an Adobe Font Metric (\afm) or
\TeX\ Property List (\pl) file.  \pl files can be created from
\tfm files using \tftopl, a program normally included with a \TeX\
system.

The job that \fontinst does is complicated, but it can be used for
many tasks by people who are not \TeX\ font wizards.  Having said
that, you do need to understand at least the basics of \LaTeXe's
font selection mechanism, which is documented in
\texttt{fntguide.tex}, part of the standard \LaTeX\ distribution.
\url{ftp://ftp.tex.ac.uk/tex-archive/macros/latex/base/fntguide.tex}
will fetch a copy if you don't have one to hand.

To get the most benefit out of \fontinst, it's important to
understand and use Karl Berry's `\Fontnamekb' naming scheme.  The
definitive version of this is available from your nearest CTAN
server.  The following URL will fetch all the files needed
compressed into a single ZIP archive:
\url{ftp://ftp.tex.ac.uk/tex-archive/info/fontname.zip}.  I
suggest that you print out the \Fontnamekb documentation and have
it handy when you're learning about \fontinst.

The \fontinst package:
\begin{itemize}
\item Is written in \TeX, for maximum portability (at the cost of
  speed).
\item Supports the OT1 (Computer Modern) and T1 (Cork) encodings.
\item Allows fonts to be generated with arbitrary `fake'
  characters; for example the `ij' character can be faked if
  necessary by putting an `i' next to a `j'.
\item Allows caps and small caps fonts with letter spacing and
  kerning.
\item Allows kerning to be shared between characters, for example
  `ij' can be kerned on the left as if it were an `i' and on the
  right as if it were a `j'.  This is useful, since many
  PostScript fonts only include kerning information for characters
  without diacriticals.
\item Allows the generation of math fonts with \verb|nextlarger|,
  \verb|varchar|, and arbitrary font dimensions.
\item Allows more than one PostScript font to contribute to a
  \TeX\ font, for example the `ffi' ligatures for a font can be
  taken from the Expert encoding, if you have it.
\item Can automatically generate a \fd file for use with \LaTeXe.
\item Can be customized by the user to deal with arbitrary font
  encodings.
\end{itemize}
Fontinst has been a stable piece of software since mid-1994.  All
further updates will be upwardly compatible with the interface
described in this document.

\subsection{What does \fontinst do?}

\Fontinst is a tool written in \TeX\ that can create the various
extra files needed so you can use \PS fonts with \LaTeX\ and \TeX.
It can read in \afm files, and produces the necessary \vpl, \pl,
and \fd files to use the fonts (the human-readable \vpl and \pl
files produced by \fontinst are turned into the machine-readable
\vf and \tfm forms by \vptovf and \pltotf).  It does not help you
configure your DVI driver.

There also exists a \texttt{perl} front-end to \fontinst, intended
specifically for use with a Unix \TeX\ system, which takes care of
routine tasks such as running \vptovf and \pltotf on the generated
files after \fontinst has finished it's job.  It also generates a
font map file for use with \dvips.

\Fontinst's main job is creating \vf files (virtual fonts).  Not
all \TeX\ systems can use them.  As far as I know, all current
(1998) free and shareware \TeX\ systems can; virtual fonts have
been in widespread use with \TeX\ since 1990.  If you have a TeX
system that can't use virtual fonts, \fontinst is most likely
useless to you.

There are some nice things about having a tool written in \TeX\ to
do this: it's completely portable and you can modify its behaviour
using \TeX\ commands.  The only real problem is that it's
relatively slow: you can expect a typical \fontinst run to take
something like 10--20 minutes on, say, a 40~MHz 80486SX PC or a
25~MHz 68LC040 Macintosh.

\Fontinst can do its work on any font for which you have a
corresponding \afm or \tfm metric file, so it's not limited to
working with \PS fonts; I have used it to produce the files I
needed to use \TT fonts with \LaTeX. Whether or not you can do
this depends on whether or not you have suitable metric files and
whether or not your \TeX\ system can use \TT fonts.  In
particular, the pdf\TeX\ program supports \TT fonts and includes a
utility \texttt{ttf2afm} to generate \afm files from \ttf fonts.

Some people have used \fontinst to produce `special effects' with
normal \TeX\ fonts.  One example is the \setpackagename{eco} set
of fonts (available from CTAN:
\url{ftp://ftp.tex.ac.uk/tex-archive/fonts/eco/}).  These fonts
are the same as the standard EC (European Modern) fonts, but with
normal numerals replaced with old style numerals --
\oldstylenums{12345} rather than 12345 -- everywhere except in
maths mode.

\subsection{Installation}

To install \fontinst, put the contents of the \url{inputs/tex},
\url{inputs/etx}, \url{inputs/mtx} and \url{examples} directories
into a directory read by \TeX, for example
\url{TEXMF/tex/generic/fontinst}.

When you use \fontinst, you need to make sure that the \afm and
\pl files it will work on are in a directory searched by \TeX.

If you are using \texttt{web2c} \TeX\ on a Unix system with the
\TeX\ directory structure (TDS), you might put all the \afm files
in subdirectories of \url{TEXMF/fonts/afm/*}.  And then say:
\begin{verbatim}
   setenv TEXINPUTS $TEXMF/fonts/afm//::
\end{verbatim}%$
Note that \pl files are not normally kept in \TeX\ installations, so
if you want to use MF fonts with \fontinst you have to generate the
corresponding \pl files from \tfm files and put them in your working
directory before running \fontinst.

You could adopt a similar strategy with other \TeX\ systems:
create directories for the required files and then change the
relevant parameter (\url{input_folders} in the default
configuration file with \OzTeX, for example).

The approach I use is this: I write a file containing commands for
\fontinst to process, and put the \afm and \pl files needed in the
same directory as that file.  When \fontinst has finished working,
I delete the \afm and \pl files because they are not needed and
waste space on my hard disc drive.  Some application programs on
some computers need \afm files, so it's not always a good idea to
remove them completely.

\subsection{Why do we need \fontinst?}

\TeX\ refers to characters by number when it's typesetting.  When
you use a command like \verb|\i|, \TeX\ puts a number (16 if
you're using OT1, 25 if you're using T1) into the \dvi file.  If
you're using a font designed for use with \TeX, this number will
correspond to the character `\i'.  Assuming OT1 encoding for the
moment, when you come to print out your \dvi file, the DVI driver
will see the number 16 in the \dvi file, and select the character
that sits in position 16 of the corresponding printer font file (a
\pk file in the case of normal \TeX\ fonts).  Unless something has
gone wrong, that will result in the character `\i' being placed on
the page.

It's useful to think of these numbers and the actual characters
corresponding to each number as sets called `encodings'.  A
particular set of characters are assigned particular numbers.  An
example of an encoding is shown in table~\ref{OT1table}.

\TeX\ began life using 7-bit fonts.  This means the original \TeX\
fonts used the numbers 0--127 to represent characters:
128~characters per font.  \TeX\ can now use 8-bit fonts:
256~numbers from 0--255, but even so, most typesetting with \TeX\
still uses the original 7-bit encoding, now called `OT1' (Old
\TeX~1 encoding).  This has a correspondance between numbers and
characters shown in table~\ref{OT1table}.  The numbers used in
that table are hexadecimal and octal because it makes for a neat
table and anyway I stole the code to generate it from Donald Knuth
and that's how he did it.

\begin{table}[!t]
\smallfontchart{cmr10 at 10pt}
\caption{The OT1 font encoding}\label{OT1table}
\end{table}

Returning to the example above, if you've a number 16 in your \dvi
file (expecting `\i', a dotless~i), but rather than printing
with an OT1 encoded font, you print using a non re-encoded \PS
font in Adobe standard encoding, you'll get a blank, because the
Adobe standard encoding has nothing in that character position.

There are several ways round this problem; I'll consider two cases
here.  If you are using \LaTeX\ you can tell it about a new
encoding and re-define the commands that produce characters like
`\i' that live in different positions in different encodings, or
you can use a tool to re-encode the font so that it has the
expected characters in the appropriate positions.

Re-encoding is the approach \fontinst uses: it can produce files
to map the characters in the new font to one of \TeX's existing
encodings; this works with formats other than \LaTeX.

The first approach is used to define the standard encodings that
\LaTeX\ uses.  See, for example, the file \texttt{ot1enc.def} that
comes with the current \LaTeX\ distribution, which defines the a
few commands that refer to characters which aren't in the
positions \TeX\ would otherwise assume.  This works only with
modern versions of \LaTeX.

The second approach is used to allow you to use fonts in other
encodings with any dialect of \TeX. It has the some advantages
over the first method: it works with any \TeX\ format; and it
improves portability, because you can typeset a document using a
standard \TeX\ encoding, sure that the same document will print
correctly on a different kind of computer using a font with a
different encoding.  For example, you might say:
\begin{verbatim}
  \usepackage{times}
\end{verbatim}
in the preamble of your document.  On my computer, that means my
DVI driver will use a Macintosh encoded \TT version of Times.  On
your computer, it might mean the dvi driver will use a Unicode
encoded \PS version of Times-Roman.  The results will be identical
in either case, without needing to modify the document.

\subsection{How do you use \fontinst?}

\Fontinst works on \afm files named (more-or-less) according to
Karl Berry's font naming scheme (see
\url{ftp://ftp.tex.ac.uk/tex-archive/info/fontname} at CTAN).
Let's say you want to use the Adobe Times fonts.  You can get the
metric files for this font from CTAN:
\begin{center}
\begin{small}
\begin{tabular}{ll}
  \emph{Location of file at CTAN} & \emph{Rename to} \\
  \url{fonts/psfonts/adobeafm/base35/tib_____.afm} &
  \texttt{ptmb8a.afm} \\
  \url{fonts/psfonts/adobeafm/base35/tibi____.afm} &
  \texttt{ptmbi8a.afm} \\
  \url{fonts/psfonts/adobeafm/base35/tii_____.afm} &
  \texttt{ptmri8a.afm} \\
  \url{fonts/psfonts/adobeafm/base35/tir_____.afm} &
  \texttt{ptmr8a.afm}
\end{tabular}
\end{small}
\end{center}
The new name is the name you should give the \tfm files so that
\fontinst understands what each file contains.  The initial `|p|'
means `Adobe'; `|tm|' means `Times'; `|b|' bold, `|r|' roman,
`|i|' italic; and `|8a|' means `Adobe standard encoding'.

The simplest use of \fontinst is to put the four \afm files in the
same directory as \texttt{fontinst.sty} and run \TeX\ on
\texttt{fontinst.sty}.  At the \verb|*| prompt type:
\begin{verbatim}
  *\latinfamily{ptm}{} \bye
\end{verbatim}

Some time later (about 17 minutes on my rather old computer),
\fontinst will have finished, having created:
\begin{itemize}
\item Two \pl files for each \afm file
\item One \vpl file for each \TeX\ font
\item One \fd file for each family
\end{itemize}
The \pl files come in pairs: for example, \texttt{ptmb8a.pl} and
\texttt{ptmb8r.pl}.  The |8a| version has the same encoding as the
original font; the |8r| version is re-encoded to |TeXBase1| (|8r|)
encoding, and is the font that is the base on which the T1 and OT1
encoded versions are based on.  The raw |8a| (Adobe standard)
encoded font is not normally used.

These can be converted to \TeX\ fonts using \pltotf or \vptovf.
If you have \OzTeX, launch \OzMF, select \pltotf (or \vptovf) from
the Tools menu, and say `Do all files'.

If you use the \texttt{bash} shell on a Unix system,  you can
process all files using these one-liners at the \verb|$| prompt:
\begin{verbatim}
   $ for f in in *.pl;  do pltotf $f; done
   $ for f in in *.vpl; do vptovf $f; done
\end{verbatim}%$
(This assumes that \pltotf and \vptovf can deduce the file names
of the corresponding \tfm and \vf files automatically.)

You should then:
\begin{itemize}
\item Move the \tfm files to your \TeX\ fonts directory\\
   (e.g.~\url{TEXMFLOCAL/fonts/tfm/*}).
\item Move the \vf files to your virtual fonts directory\\
   (e.g.~\url{TEXMFLOCAL/fonts/vf/*}).
\item Move the \fd files to your \TeX\ inputs directory\\
   (e.g.~\url{TEXMFLOCAL/tex/latex/psfonts/*}).
\end{itemize}
If your \TeX\ installation is organized using the \TeX\ directory
structure (TDS), it is customary to subdivide the \tfm and \vf
files into subdirectories by supplier and typeface name.

The \pl, \vpl, and \mtx files are debris that can now be deleted.
\mtx files are font metric files \fontinst creates for its own use
from \afm and \pl files.  They're just more convenient for \TeX\
to read than other forms -- think of them as \fontinst readable
\afm and \pl files.

By now, you have all the files in place to produce a \dvi file
using the new fonts.  You can make Adobe Times the default roman
font in your document by putting this in your preamble:
\begin{verbatim}
   \renewcommand{\rmdefault}{ptm}
\end{verbatim}

\TeX\ will now happily produce a perfectly good \dvi file
including the new font, which your DVI driver will choke on
because you've not yet told it about the new fonts.  Exactly how
you do this depends on the dvi driver, but they all need the same
information: the name of a \TeX\ font; the printer font name it
corresponds to; some information to handle an re-encoding needed;
and (in the case of a \PS driver) perhaps an instruction to
download the font to the printer.  You don't need to download the
Times font to a \PS printer, because Times is built in to every
\PS printer.

If you use \dvips, these lines added to your \texttt{psfonts.map}
file will do the job:
\begin{verbatim}
  ptmr8r   Times-Roman       "TeXBase1Encoding ReEncodeFont"  <<8r.enc
  ptmri8r  Times-Italic      "TeXBase1Encoding ReEncodeFont"  <<8r.enc
  ptmb8r   Times-Bold        "TeXBase1Encoding ReEncodeFont"  <<8r.enc
  ptmbi8r  Times-BoldItalic  "TeXBase1Encoding ReEncodeFont"  <<8r.enc
  ptmro8r  Times-Roman       "0.167 SlantFont TeXBase1Encoding ReEncodeFont"  <<8r.enc
  ptmbo8r  Times-Bold        "0.167 SlantFont TeXBase1Encoding ReEncodeFont"  <<8r.enc
\end{verbatim}
And now you can print a \dvi file containing the new fonts.  If
you really do want to use the `raw' |8a| encoded fonts for some
reason, you need to add these lines to your \texttt{psfonts.map}
file:
\begin{verbatim}
  ptmr8a   Times-Roman
  ptmri8a  Times-Italic
  ptmb8a   Times-Bold
  ptmbi8a  Times-BoldItalic
  ptmro8a  Times-Roman       "0.167 SlantFont"
  ptmbo8a  Times-Bold        "0.167 SlantFont"
\end{verbatim}

Assuming that you're using the \fd file that \fontinst has
produced, and that you've asked for the Adobe Times family (|ptm|)
in medium series (|m|) and upright shape (|n| for normal) using
the NFSS font selection commands:
\begin{verbatim}
  \renewcommand{\rmdefault}{ptm}
  \rmfamily \mdseries \upshape
\end{verbatim}
Assuming further that you are using the \fd file \texttt{t1ptm.fd}
produced by \fontinst, the \TeX\ font (\tfm file) \texttt{ptmr8t.tfm}
will be selected by the above commands, as you can see from the
relevant line in \texttt{t1ptm.fd}:
\begin{verbatim}
  \DeclareFontShape{T1}{ptm}{m}{n}{<<->> ptmr8t}{}
\end{verbatim}

This is what happens:
\begin{itemize}
\item \TeX\ typesets your document using the font metric file
  \texttt{ptmr8t.tfm}; this is the font that is put in the \dvi
  file.
\item \Dvips looks at the \dvi file, and sees a reference to the
  font \texttt{ptmr8t}.
\item \Dvips searches for a \vf file corresponding to
  \texttt{ptmr8t}; when it finds \texttt{ptmr8t.vf}, it knows it
  has a virtual font on its hands.
  %\footnote{This is a slight lie--why?}
\item \Dvips follows the instructions in the \vf file, which map
  characters in \texttt{ptmr8t.tfm} to characters in the font
  \texttt{ptmr8r.tfm}.  That is, when it sees a number~25 in the
  \dvi file (dotless~i -- `\i' -- in T1 encoding), it replaces it
  with a number~17, which is a dotless~i in |8r| encoding.
\item Then \dvips looks up the name of each number according to
  the scheme given in the file \texttt{8r.enc}, and replaces each
  number with the name of the character, in this case, number~17
  is listed as `dotlessi'.
\item And finally, \dvips tells the printer to print the named
  character.
\end{itemize}

Not all DVI drivers can manage re-encoding as well as \dvips can.
For example, \OzTeX's built-in non-\PS \dvi driver can only work
with numbers, so if I'm using a \PS font, I can't print characters
(such as Eth) that don't have a number in Macintosh text encoding
unless I use \dvips and print on a \PS printer.  \Dvips works with
character names, so it's not subject to this restriction.  In the
example above, \OzTeX\ would replace the number~17 for `dotlessi'
in |8r| encoding with a number~245 for `dotlessi' in Macintosh
text encoding.

The details of the \LaTeXe{} font selection scheme are described
in \emph{\LaTeXe{} font selection} (distributed with \LaTeXe\ as
the file \texttt{fntguide.tex}) and \emph{The \LaTeX\ Companion}
(Goossens, Mittelbach and Samarin, Addison-Wesley).
%You might also find useful the file \url{info/simple-nfss.tex}
%available at your nearest comprehensive \TeX\ archive network
%(CTAN) FTP server.

The files you need to use Times, Helvetica, Courier, and the rest
of the `standard' \PS fonts are distributed as part of the
\setpackagename{PSNFSS} bundle available from CTAN, so there's no
need to create new files to use these fonts.

A more involved example of \fontinst use can be seen in the file
\texttt{fontptcm.tex} which creates the files you need to use a
combination of Times, Symbol, Zapf Chancery and Computer Modern as
\TeX\ math fonts.


\section{Installing your own font family}

The \fontinst package has a command \verb|\latinfamily| meant to
do most of the work to install a `normal' set (family) of roman
text fonts from Adobe.  Assuming you have a set of \afm files to
match the fonts you wish to use, the first step is to rename the
\afm files according to the \Fontnamekb naming scheme.

A `normal' set of text fonts usually includes the basic upright
roman version, bold, italic, and bold italic.  Sometimes there
will also be small caps versions, perhaps some `expert' fonts, and
maybe some other weights such as light, medium, semi bold, black
or ultra bold.

The most important point to note is this: no matter what sort of
computer you're using and no matter what font encoding it uses
normally, \afm files for text fonts are almost always in |8a|
encoding (Adobe standard encoding), so the \afm files when renamed
normally end in |8a|.

A typical set of four \afm files re-named for use with \fontinst
is this:
\begin{verbatim}
  ptmr8r.afm    Times-Roman
  ptmri8r.afm   Times-Italic
  ptmb8r.afm    Times-Bold
  ptmbi8r.afm   Times-BoldItalic
\end{verbatim}
Not all \afm files use |8a| encoding.  If you open an \afm file
using a text editor, you'll see a line looking like this somewhere
near the top:
\begin{verbatim}
  EncodingScheme AdobeStandardEncoding
\end{verbatim}
and if you see exactly that, the \afm file should end with |8a|.
If you see something like this:
\begin{verbatim}
  EncodingScheme FontSpecific
\end{verbatim}
have a look at the name of the font in the \afm file.  If you see
something like this:
\begin{verbatim}
  FontName AGaramondExp-Regular
  FullName Adobe Garamond Regular Expert
\end{verbatim}
you have an `expert' encoded font on your hands, and the \afm file
should end with |8x| to indicate this to \fontinst.  An |8x|
encoded font contains extra glyphs like old style numerals, small
capital letters, more ligatures, and so on.

%% UV: taken out -- repeated below
%%
%If you have an expert font, you can tell \fontinst to use it when
%it's processing a \verb|\latinfamily| command by putting an `|x|'
%on the end of the family name:
%\begin{verbatim}
%  \latinfamily{padx}{}
%\end{verbatim}
%If you want to tell \fontinst to use expert fonts to install fonts
%with old style numerals, you can do so by putting an `|j|' on the
%end of the family name:
%\begin{verbatim}
%  \latinfamily{padj}{}
%\end{verbatim}

The |\latinfamily| command is used like this:
\begin{decl}
  |\latinfamily|\arg{family}\arg{commands}
\end{decl}
This installs a Latin family of fonts.

For example, to install Adobe Times, you say:
\begin{verbatim}
  \latinfamily{ptm}{}
\end{verbatim}
The \textit{commands} issued by \LaTeX\ each time a font from that
family is loaded.  This is most often used with typewriter fonts,
to switch off hyphenation.  For example, Adobe Courier can be
installed with:
\begin{verbatim}
  \latinfamily{pcr}{\hyphenchar\font=-1}
\end{verbatim}
Once the installation is over (which may take some time) the fonts
can be used in \LaTeX\ by selecting an appropriate
\verb|\fontfamily|, for example Adobe Times can be selected with:
\begin{verbatim}
  \fontfamily{ptm}\selectfont
\end{verbatim}
If the fourth letter of the family name is `|x|' then \fontinst
will use expert fonts in creating the fonts.  If the fourth letter
is `|j|' (or for backward compatibility `|9|') then \fontinst will
use expert fonts to create fonts with old style digits.

For example, to install Adobe Garamond using expert fonts, you say:
\begin{verbatim}
  \latinfamily{padx}{}
\end{verbatim}
To install Adobe Garamond using expert fonts with oldstyle digits,
you say:
\begin{verbatim}
  \latinfamily{padj}{}
\end{verbatim}

When you have expert fonts, and you've told \fontinst to use
them, it will carry on as normal, but the resulting font family
will have the name `|padx|' or `|padj|', and it will use expert
glyphs whenever possible, so you'll have a real (rather than
faked) small caps font, real (rather than faked) `ffl' ligatures,
and so on.

Before using these commands, you will need to make sure that you
have the Adobe Font Metric (\afm) files for the fonts, and that
they have appropriate names.  The \fontinst package uses the
\LaTeX\ convention for naming fonts, and uses a \emph{font family}
name which consists of:
\begin{itemize}
\item a \emph{supplier} (or foundry), such as `|p|' for Adobe.
\item a \emph{typeface}, such as `|ad|' for Adobe Garamond.
\item up to two \emph{variants}, such as `|j|' or `|x|' for `old
  style digits' or `expert'.
\end{itemize}
So the family name `|padj|' indicates Adobe Garamond with old
style digits.  Note that the variants `|j|' or `|x|' are
interpreted by \fontinst itself and do not appear in external font
names, whereas other variants are passed through as part of the
font names.  (This is needed for families which have a sans serif
or typewriter variant.)

The \emph{supplier} must be one letter, and the \emph{typeface}
must be two (this is an attempt to fit all filenames into MS-DOS
format).  Each variant is one letter.  The full list of foundries,
typefaces, shapes and variants is given in Karl Berry's
`\emph{Filenames for fonts}' (available by anonymous FTP from
\url{ftp://ftp.tex.ac.uk/tex-archive/info/fontname}), but the more
common ones are given in
Tables~\ref{Tab:foundry}--\ref{Tab:typeface}.

\begin{table}[!t]
\begin{minipage}{0.5\textwidth}
  \small
  \begin{tabular}{ll}
    |b| & Bitstream             \\
    |f| & `free' (public domain) \\
    |h| & Bigelow \& Holmes     \\
    |i| & ITC                   \\
    |l| & Linotype              \\
    |m| & Monotype              \\
    |p| & Adobe (|p| for \PS)   \\
    |r| & `raw' (obsolete)      \\
    |u| & URW                   \\
    |z| & bizarre
  \end{tabular}
  \caption{A partial list of foundries}
  \label{Tab:foundry}
  \begin{tabular}{ll}
    |a| & alternate             \\
    |d| & display, titling      \\
    |f| & fraktur, handtooled   \\
    |j| & oldstyle digits       \\
    |n| & informal, casual      \\
    |p| & ornaments             \\
    |s| & sans serif            \\
    |t| & typewriter            \\
    |w| & script, handwriting, swash \\
    |x| & expert                \\
  \end{tabular}
  \caption{A partial list of variants}
  \label{Tab:variant}
  \begin{tabular}{ll}
    |c| & small caps            \\
    |i| & italic                \\
    |o| & oblique (i.e.,~slanted) \\
    |u| & unslanted italic      \\
  \end{tabular}
  \caption{A partial list of shapes}
  \label{Tab:shape}
\end{minipage}
\begin{minipage}{0.5\textwidth}
  \small
  \begin{tabular}{ll}
    |ac| & Adobe Caslon \\
    |ad| & Adobe Garamond \\
    |ag| & Avantgarde \\
    |bb| & Bembo \\
    |bd| & Bodoni \\
    |bk| & Bookman \\
    |bv| & Baskerville \\
    |ca| & Caslon \\
    |ch| & Charter \\
    |cr| & Courier \\
    |fr| & Frutiger \\
    |fu| & Futura \\
    |gl| & Galliard \\
    |gm| & Garamond \\
    |gs| & Gill Sans \\
    |hv| & Helvetica \\
    |mn| & Minion \\
    |lc| & Lucida \\
    |lh| & Lucida Bright \\
    |ls| & Lucida Sans \\
    |nb| & New Baskerville \\
    |nc| & New Century Schoolbook \\
    |op| & Optima \\
    |pl| & Palatino \\
    |sy| & Symbol \\
    |tm| & Times \\
    |ut| & Utopia \\
    |zc| & Zapf Chancery \\
    |zd| & Zapf Dingbats \\
  \end{tabular}
  \caption{A partial list of faces}
  \label{Tab:typeface}
\end{minipage}
\end{table}

The \fontinst package uses Karl Berry's naming scheme for \afm
files.  The full naming scheme is rather more flexible than the
subset used by \fontinst, which uses filenames consisting of:
\begin{itemize}
\item a \emph{supplier}, such as `|p|' for Adobe.
\item a \emph{typeface}, such as `|hv|' for Helvetica.
\item a \emph{weight}, such as `|r|' for regular.
\item up to two \emph{shapes} or \emph{variants}, such as `|o|'
  for oblique.
\item an \emph{encoding}, such as `|7t|' for Knuth's 7-bit \TeX{}
  encoding.
\item an optional \emph{width}, such as `|n|' for narrow.
\item a \emph{file extension}, such as `\texttt{.tfm}'
  for \TeX{} Font Metric.
\end{itemize}
So the filename name `\texttt{phvro7tn.tfm}' indicates Adobe
Helvetica regular oblique narrow, in the 7-bit \TeX{} encoding.

The full list of shapes, encodings and weights is given in Karl
Berry's `\emph{Filenames for fonts}', but the more common ones are
given in Tables~\ref{Tab:shape}--\ref{Tab:weight}.

\begin{table}
\begin{minipage}{0.5\textwidth}
  \small
  \begin{tabular}{ll}
    |b| & bold \\
    |c| & black \\
    |d| & demibold \\
    |h| & heavy \\
    |k| & book \\
    |l| & light \\
    |m| & medium \\
    |r| & regular \\
    |s| & semibold \\
    |u| & ultra bold \\
    |x| & extra bold \\
  \end{tabular}
  \caption{A partial list of weights}
  \label{Tab:weight}
  \begin{tabular}{ll}
    |c| & condensed \\
    |n| & narrow \\
    |w| & wide \\
    |x| & extended \\
  \end{tabular}
  \caption{A partial list of widths}
  \label{Tab:width}
\end{minipage}
\begin{minipage}{0.5\textwidth}
  \small
  \begin{tabular}{ll}
   |8a| & Adobe Standard        \\
   |8x| & Adobe Expert          \\
   |8r| & \TeX{} 8-bit `raw' (\texttt{TeXBase1})        \\
   |8y| & \TeX{} 8-bit `raw' (\texttt{TeXnANSI})        \\
   |7t| & \TeX{} 7-bit text             (\texttt{OT1})  \\
   |7m| & \TeX{} 7-bit math italic      (\texttt{OML})  \\
   |7y| & \TeX{} 7-bit math symbol      (\texttt{OMS})  \\
   |7v| & \TeX{} 7-bit math extension   (\texttt{OMX})  \\
   |8t| & \TeX{} 8-bit text             (\texttt{T1})   \\
   |8c| & \TeX{} 8-bit text symbols     (\texttt{TS1})  \\
   |9t| & \TeX{} 7-bit text with expert glyphs  \\
   |9o| & \TeX{} 7-bit text with expert glyphs  \\
        & and old-style digits  \\
   |9e| & \TeX{} 8-bit text with expert glyphs  \\
   |9d| & \TeX{} 8-bit text with expert glyphs  \\
        & and old-style digits  \\
   |9c| & \TeX{} 8-bit symbols with expert glyphs \\
        & and old-style digits  \\
   \end{tabular}
   \caption{A partial list of encodings}
\end{minipage}
\end{table}

For example, to install Adobe Garamond including the expert fonts, you
would need to rename the \afm files:
\begin{center}
\begin{small}
\begin{tabular}{lll}
  \emph{Adobe name} & \emph{ATM name} & \emph{Fontinst name} \\
  |AGaramond-Bold.afm|              & |gdb_____.afm|    & |padb8a.afm|   \\
  |AGaramond-BoldItalic.afm|        & |gdbi____.afm|    & |padbi8a.afm|  \\
  |AGaramond-Italic.afm|            & |gdi_____.afm|    & |padri8a.afm|  \\
  |AGaramond-Regular.afm|           & |gdrg____.afm|    & |padr8a.afm|   \\
  |AGaramond-Semibold.afm|          & |gdsb____.afm|    & |pads8a.afm|   \\
  |AGaramond-SemiboldItalic.afm|    & |gdsbi___.afm|    & |padsi8a.afm|  \\
  |AGaramondExp-Bold.afm|           & |geb_____.afm|    & |padb8x.afm|   \\
  |AGaramondExp-BoldItalic.afm|     & |gebi____.afm|    & |padbi8x.afm|  \\
  |AGaramondExp-Italic.afm|         & |gei_____.afm|    & |padri8x.afm|  \\
  |AGaramondExp-Regular.afm|        & |gerg____.afm|    & |padr8x.afm|   \\
  |AGaramondExp-Semibold.afm|       & |gesb____.afm|    & |pads8x.afm|   \\
  |AGaramondExp-SemiboldItalic.afm| & |gesbi___.afm|    & |padsi8x.afm|  \\
  |AGaramond-RegularSC.afm|         & |gdsc____.afm|    & |padrc8a.afm|  \\
  |AGaramond-SemiboldSC.afm|        & |gdsbs___.afm|    & |padsc8a.afm|  \\
\end{tabular}
\end{small}
\end{center}
You can then run \TeX{} on the following document to install the
Adobe Garamond family:
\begin{verbatim}
  \input fontinst.sty
  \latinfamily{padx}{}
  \latinfamily{padj}{}
  \bye
\end{verbatim}
Not all font families can be installed using the \verb|\latinfamily|
command, so the rest of this document describes the full \fontinst
syntax, and is intended for `power users'.


\section{Defining terms}

This is rather a large and perhaps tedious section.  You might be
tempted to skip it so you can get to some more direct information on
how to use \fontinst.  That's fine if you understand everything about
how \TeX\ handles fonts.  If not, I suggest you at least skim though
this section.

\subsection{What's a font?}

Once upon a time, this question was easily answered: a font is a
set of type in one size, style, etc.  There used to be no
ambiguity, because a font was a collection of chunks of type metal
kept in a drawer, one drawer for each font.

These days, with digital typesetting, things are more complicated.
What a font `is' isn't easy to pin down.  A typical use of a \PS
font with \TeX\ might use these elements:
\begin{itemize}
\item Type 1 printer font file
\item Bitmap screen font file
\item Adobe font metric file (\afm file)
\item \TeX\ font metric file (\tfm file)
\item Virtual font file (\vf file)
\item font definition file (\fd file)
\end{itemize}
Looked at from a particular point of view, each of these files
`is' the font.  So what's going on?

\subsubsection{Type 1 printer font files}

These files contain the information needed by your printer to draw
the shapes of all the characters in a font.  They're typically
files with a \pfa or \pfb extension; on Macs they're usually in
files of type `LWFN' which usually have icons that look like a
laser printer.  The information in all these files is basically
the same: the only difference is in its representation.  \pfa
stands for `printer font ASCII', while \pfb stands for `printer
font binary'.  That is, \pfa files contain plain text information,
while \pfb files contain the same information encoded as
machine-readable binary data.

If you have Adobe Type Manager (ATM) installed on your computer,
ATM will use these files to draw an accurate representation of the
letters on the screen of your computer when you are previewing a
\TeX\ document.

Printer font files are not used directly by \TeX\ at all -- \TeX\
just prepares a \dvi file that refers to the fonts by name and the
characters by number: \TeX\ knows nothing about the shapes
involved.  The DVI driver uses the printer font files when you ask
it to print the \dvi file.  This means that you can produce a \dvi
file which uses, say, Palatino, even if you do not have the
Type~1 printer font file for this font on your computer.  You will
need to find a computer that does have Palatino before you can
print it or preview it, though.

(This isn't exactly true for the recently developped pdf\TeX\
program, which integrates some of the functionality of a DVI
driver.)

\subsubsection{Bitmap screen font files}

These files contain a low-resolution bitmap for drawing a
representation of the font on the screen of your computer if ATM
is not installed.  In the \TeX\ world, these files are only used
for screen previews by the DVI driver.  They are kept in font
suitcase files on Macintoshes.
%\marginnote{And where on other computers?}

\subsubsection{Adobe font metric files (\afm files)}

These files are text files which contain information about the
size of each character in a font, kerning and ligature
information, and so on.  They can't be used by \TeX\ directly, but
the information they contain is essential if you want to use a
font with \TeX. \Fontinst can create from an \afm file the
necessary \tfm and \vf files so you can use a font with \TeX.
Once you have created all the files you need to use a font with
\TeX, you can remove the corresponding \afm files from your
computer unless you have other software that needs them.

The job of turning an \afm file into a set of \tfm and \vf files
is one of the main uses for \fontinst.  Most of this document is
concerned with this process, so don't worry if it seems a bit
vague at the moment.

\subsubsection{\TeX\ font metric files (\tfm files)}

These are binary data files in a format designed for use by \TeX\
which contain (more-or-less) the same information as \afm files:
the size of each character in a font (font metric data), kerning,
and ligature information.

When you select a font in \TeX, you are telling \TeX\ to typeset
using a particular \tfm file; from \TeX's point of view, a \tfm
file (and nothing else) \emph{is} a font.  \TeX\ itself doesn't
see printer font files, screen bitmaps, \pk files, \vf files, or
anything else to do with fonts: only \tfm files.

\TeX\ uses these \tfm files to decide where to put characters when
typesetting.  From \TeX's point of view, \tfm files are fonts,
even though they contain no information about the shape of
letters, and are not used by anything except \TeX\ -- once you
have produced a \dvi file, you don't need the \tfm files to print
it out.  (This is a slight lie: \dvips can read \tfm files
corresponding to \PS and \TT fonts so it can modify the metrics
slightly to improve the letterspacing at your chosen output
resolution.  This is an optional minor tweak and not an essential
part of the output process.)

\subsubsection{Property list files (\pl files)}

\pl files are human-readable text files which contain all the font
metric, kerning, ligature, and other information needed to create
a \tfm file.  You can convert between the two file formats using
\tftopl and \pltotf.

\subsubsection{Virtual font files (\vf files)}

These are binary data files in a format designed for use by \TeX\
\dvi drivers.  They're main purpose in life is to let you use
fonts in different encodings to the standard \TeX\ encodings.
These files are used by dvi driver software only.

They are used only by \dvi drivers to work out what it should
\emph{really} print when you ask for a particular character.  They
are arcane creatures, but \fontinst deals with the details for
you, and creating and using them is what this document is about,
so don't worry if this doesn't make sense yet.  (I don't
understand the details about the innards of \vf files, but you'll
find out that that doesn't matter if you just want to use
\fontinst).

Each \vf file has a \tfm file with the same name.  To use a
virtual font, you select the \tfm file as the font to use in your
document.  When the \dvi driver comes across this \tfm file in the
\dvi file, it looks up the \vf file and uses that to decide what
to do.

\subsubsection{Virtual property list files (\vpl files)}

\vpl files are human-readable text files which contain all the
font metric, kerning, mapping, and other information needed to
create a \vf and \tfm pair.

\vptovf will create a \vf/\tfm pair from a \vpl file.  \vftovp
will create a \vpl from a \vf/\tfm pair.  \vftovp also needs to be
able to read all the \tfm files that are referred to by a \vf to
recreate the \vpl -- it looks at the checksums to verify that
everything's okay.

\subsubsection{Font definition files (\fd files)}

These are files containing commands to tell \LaTeX\ which \tfm
files to associate with a request for a font using \LaTeX's font
selection commands.

For example, here is a small and edited part of the \fd file
supplied with \setpackagename{PSNFSS} to allow you to use the
Adobe Times font in T1 encoding:

\begin{verbatim}
  \ProvidesFile{t1ptm.fd}
      [1997/02/11 Fontinst v1.6 font definitions for T1/ptm.]

  \DeclareFontFamily{T1}{ptm}{}

  \DeclareFontShape{T1}{ptm}{m}{n} {<<->> ptmr8t}{}
  \DeclareFontShape{T1}{ptm}{m}{it}{<<->> ptmri8t}{}
  ...
  \DeclareFontShape{T1}{ptm}{b}{n} {<<->> ptmb8t}{}
  \DeclareFontShape{T1}{ptm}{b}{it}{<<->> ptmbi8t}{}
  ...
\end{verbatim}
What this means is: when you use \LaTeX\ to select the font family
|ptm| in T1 encoding in the medium series (|m|) and normal shape
(|n|), \TeX\ uses the font \texttt{ptmr8t.tfm}.  Similarly, if you
select bold italic, \TeX\ uses \texttt{ptmbi8t.tfm}.

\LaTeX\ works out which \fd file to load based on the current
encoding and font family selected.  If you've selected T1 encoded
|ptm| like this:
\begin{verbatim}
  \fontencoding{T1}\fontfamily{ptm}\selectfont
\end{verbatim}
\LaTeX\ loads the file \url{t1ptm.fd} (if it doesn't exist, you're
in trouble).  As you can see above, this file contains information
so that \LaTeX\ knows which \tfm file to use.  So if you ask for,
say, |T1/ptm/b/it| (T1 encoded Times-Roman, bold series, italic
shape), you get the font \texttt{ptmbi8t}.

You can find more about \fd files and \LaTeX's font selection commands
at CTAN:
\url{ftp://ftp.tex.ac.uk/tex-archive/macros/latex/base/fntguide.tex}
and \url{ftp://ftp.tex.ac.uk/tex-archive/info/simple-nfss.tex} are
both useful.

\subsection{What does \fontinst do?}

\fontinst creates \vpl and \pl files from \afm or \pl files to map
any glyph or combination of glyphs in the original font files to
any slot in the output font file.  There, isn't that better?  Off
you go now\ldots

If you're still confused, I'll explain a few things.
\begin{description}
\item[Glyph] This is a jargon word referring to what most people
  think of as a character.  But is an acute accent really a
  character?  And what about an acute accent over an `e'?  You can
  refer to the letter `e' as a glyph; the acute accent `\'{}' as a
  glyph; and the accented letter `{\'e}' as yet another glyph.

\item[Encoding] A particular arrangement of glyphs in a font
  used by a computer.  You're probably familiar with ASCII
  encoding, which has the letter `A' in slot~65, `B' in slot~66,
  and so on.  That's it, really.  \TeX\ uses several different
  encodings.  The most common ones are OT1 (the original \TeX\
  7~bit encoding) and T1 (the newer \TeX\ 8~bit encoding).
  % -- much more on this later.

  The thing is that the average \PS font comes in Adobe standard
  encoding, which, for example, has the glyph dotless~i `\i' in
  slot~245.  But \TeX\ T1 encoding expects the glyph o~dieresis
  `{\"o}' in that slot, and wants dotless~i in slot~25.  So if you
  tried to use a raw \PS font with \TeX, any time you tried to get
  a `{\"o}', you'd get a `\i'; and every time you tried to get a `\i',
  you'd get a blank, because Adobe standard encoding says that
  slot~25 is empty.  The process of dealing with this problem is
  called `re-encoding', and is what \fontinst helps with.

\item[Slot] As mentioned above, this is a numbered position in an
  encoding.  For example, slot~33 in ASCII encoding contains the
  glyph~`!'.
\end{description}

This might not make much sense yet; the best thing to do is relax.
There's a lot of things that need to be dealt with when you're
setting up \LaTeX\ to use a new font, so you can expect to be a
bit confused until you've done it a few times.

\subsection{What do you do with \fontinst?}

If you're using \fontinst, the usual steps you need to take to use
an ordinary \PS text font with \LaTeX\ are these:

\begin{enumerate}
\item Give the \afm files an approriate name.
\item Use \fontinst to produce an |8r| encoded \pl files from
  these \afm files.
\item Use \fontinst to create T1 and OT1 encoded \pl and \vpl
  files from the |8r| encoded \pl filea (this procedure will also
  create suitable \fd files).
\item Use \pltotf to turn each \pl file into a \tfm file.
\item Use \vptovf to turn each \vpl file into a pair of \vf and
  \tfm files.
\item Move the \tfm, \vf, and \fd files into the appropriate
  directories so \LaTeX\ can see them.
\item Tell your DVI driver about the new font (edit \dvips's
  \texttt{psfonts.map} file, or \OzTeX's \texttt{Default}
  configuration file.
\item Perhaps write a package file to make selecting the new font
  a little easier.
\item Test it.
\end{enumerate}


\section{Customization}

The \fontinst package reads a file \texttt{fontinst.rc} if it
exists.  This can contain your own customizations.

You can create a \texttt{fontinst} format by running ini\TeX{} on
\texttt{fontinst.sty} then saying \verb|\dump|.

There are three types of files used by the \fontinst package:
\begin{itemize}
\item \emph{fontinst files} contain commands to process fonts
  metrics so you can use a font with \TeX. For example,
  \texttt{fontptcm.tex} is a \emph{fontinst file}.

\item \emph{encoding files} contain information about an encoding,
  including the code table, ligatures, and font dimensions.  For
  example, \texttt{8r.etx} is an \emph{encoding file}.

\item \emph{metric files} contain information about glyphs,
  including glyph dimensions, composite characters, and kerning.
  For example, \texttt{latin.mtx} is a \emph{metric file}.
\end{itemize}

Any of these files can include the \emph{general commands}, and
can use the \emph{integer expressions}, defined in
Section~\ref{Sec:integer}.

\subsection{General commands}

The following \emph{general commands} can be used anywhere:

\begin{decl}
  |\needsfontinstversion|\arg{version}
\end{decl}
This issues a warning if the current version of the \fontinst
package is less than \m{version}.

\begin{decl}
  |\setdim|\arg{dim}\arg{dimension}\\
  |\setint|\arg{int}\arg{integer expression}\\
  |\setstr|\arg{str}\arg{string}
\end{decl}
If the dimension variable \m{dim} is currently undefined, it is
defined to be the current value of \m{dimension}.

If the integer variable \m{int} is currently undefined, it is
defined to be the current value of \m{integer expression}.

If the string variable \m{str} is currently undefined, it is
defined to be the current value of \m{string}.

\begin{decl}
  |\setcommand|\arg{command}\arg{definition}
\end{decl}
If the command \m{command} is currently undefined, it is defined
to be the \m{definition}.  This uses the same syntax for
parameters as the \TeX\ \verb|\def| command.

\begin{decl}
  |\resetdim|\arg{dim}\arg{dimension}\\
  |\resetint|\arg{int}\arg{integer expression}\\
  |\resetstr|\arg{str}\arg{string}
\end{decl}
The dimension variable \m{dim} is defined to be the current value
of \m{dimension}.

The integer variable \m{int} is defined to be the current value of
\m{integer expression}.

The string variable \m{str} is defined to be the current value of
\m{string}.

\begin{decl}
  |\resetcommand|\arg{command}\arg{definition}
\end{decl}
The command \m{command} is defined to be the \m{definition},
regardless of whether it was already defined or not.  This is a
synonym for the \TeX\ \verb|\def| command.

\begin{decl}
  |\ifisint|\arg{int}|\then|\\
  |\ifisdim|\arg{dim}|\then|\\
  |\ifisstr|\arg{str}|\then|\\
  |\ifisglyph|\arg{glyph}|\then|\\
  |\ifiscommand|\arg{command}|\then|
\end{decl}
Expands out to \verb|\iftrue| if the integer variable
\m{int} is defined, and \verb|\iffalse| otherwise.

Expands out to \verb|\iftrue| if the dimension variable
\m{dim} is defined, and \verb|\iffalse| otherwise.

Expands out to \verb|\iftrue| if the string variable
\m{str} is defined, and \verb|\iffalse| otherwise.

Expands out to \verb|\iftrue| if the glyph variable
\m{glyph} is defined, and \verb|\iffalse| otherwise.

Expands out to \verb|\iftrue| if the command
\m{command} is defined, and \verb|\iffalse| otherwise.

\begin{decl}
  |\unsetdim|\arg{dim}\\
  |\unsetint|\arg{int}\\
  |\unsetstr|\arg{str}\\
  |\unsetcommand|\arg{command}
\end{decl}
Makes \m{dim}, \m{int}, \m{str}, or \m{command} an undefined
dimension, integer, string or command.

\subsection{Integer expressions}
\label{Sec:integer}

The \emph{integer expressions} provide a user-friendly syntax for
\TeX\ arithmetic.  They are used to manipulate any integers,
including glyph dimensions, which are given in \afm units, that is
1000 to the design size.  \TeX\ \pl fonts have their dimensions
converted to \afm units automatically.

The \emph{integer expressions} are:

\begin{decl}
  \m{number}
\end{decl}
Returns the value of a \TeX\ \m{number} (as explained ib \emph{The \TeX book}).

\begin{decl}
  |\int|\arg{int}
\end{decl}
Returns the value of the integer variable \m{int}.

\begin{decl}
  |\width|\arg{glyph}\\
  |\height|\arg{glyph}\\
  |\depth|\arg{glyph}\\
  |\italic|\arg{glyph}
\end{decl}
Returns the width, height, depth, or italic correction of the glyph
variable \m{glyph}.

\begin{decl}
  |\kerning|\arg{left}\arg{right}
\end{decl}
Returns the kerning between the \m{left} and \m{right} glyph
variables.

\begin{decl}
  |\neg|\arg{integer expression}\\
  |\add|\arg{integer expression}\arg{integer expression}\\
  |\sub|\arg{integer expression}\arg{integer expression}\\
  |\mul|\arg{integer expression}\arg{integer expression}\\
  |\div|\arg{integer expression}\arg{integer expression}\\
  |\scale|\arg{integer expression}\arg{integer expression}
\end{decl}
|\neg| returns the negation of the \m{integer expression}.

|\ad| returns the sum of the two \m{integer expression}s.

|\sub| returns the first \m{integer expression} minus the second.

|\mul| returns the product of the two \m{integer expression}s.

|\div| returns the first \m{integer expression} divided by the second.

|\scale| returns the first \m{integer expression} times the second,
divided by 1000.

\section{Fontinst files}

A \emph{fontinst file} is any \TeX\ document which inputs the
\fontinst macros.  The commands available are:

\begin{decl}
  |\installfonts|\\
  \m{install commands}\\
  |\endinstallfonts|
\end{decl}
This makes a font family, using the \m{install commands}.  There
can be any number of \verb|\installfonts| commands in a fontinst file.

\begin{decl}
  |\substitutesilent|\arg{to}\arg{from}
  |\substitutenoisy|\arg{to}\arg{from}
\end{decl}
This declares a \LaTeX\ font substitution, that the series or shape
\m{to} should be substituted if necessary by the series or shape
\m{from}.  \verb|\substitutesilent| means that when the font
substitution is made, no warning will given.

\verb|\substitutenoisy| is the same as \verb|\substitutesilent|, but
gives a warning when the substitution is made by \LaTeX.

For example, to say that the series |bx| can be replaced by the
series |b|, you say:
\begin{verbatim}
  \substitutesilent{bx}{b}
\end{verbatim}
To say that the shaoe |ui| can be replaced by the shape |i|, you say:
\begin{verbatim}
  \substitutenoisy{ui}{it}
\end{verbatim}

The following weight substitutions are standard:
\begin{verbatim}
  \substitutesilent{bx}{b}
  \substitutesilent{b}{bx}
  \substitutesilent{b}{sb}
  \substitutesilent{b}{db}
  \substitutesilent{m}{mb}
  \substitutesilent{m}{l}
\end{verbatim}
The following shape substitutions are standard:
\begin{verbatim}
  \substitutenoisy{ui}{it}
  \substitutesilent{it}{sl}
  \substitutesilent{sl}{it}
\end{verbatim}

\begin{decl}
  |\transformfont|\arg{font-name}\arg{transformed font}
\end{decl}
This makes a raw transformed font, for example expanded, slanted,
condensed or re-encoded.  \emph{It is the responsibility of the device
  driver to implement this transform.}  Each \verb|\transformfont|
command writes out an \mtx file and a raw \pl file for \m{font-name}.

A \m{transformed font} is given by the following commands:
\begin{decl}
  |\fromafm|\arg{afm}\\
  |\frompl|\arg{pl}\\
  |\frommtx|\arg{mtx}
\end{decl}
This reads the metrics of a font which is about to be transformed from
an external file.  Both |\fromafm| and |\frompl| write out an \mtx
file corresponding to the \afm or \pl file.  In addition, |\formafm|
also writes out a raw \pl file, containing just the glyph metrics
but no kerning information.

\begin{decl}
  |\scalefont|\arg{integer expression}\arg{transformed font}\\
  |\xscalefont|\arg{integer expression}\arg{transformed font}\\
  |\yscalefont|\arg{integer expression}\arg{transformed font}\\
  |\slantfont|\arg{integer expression}\arg{transformed font}
\end{decl}
This applies a geometric transformation to the font metrics of
\m{transformed font}.  The scale factor or slant factor are given in
1000 units to the design size.  Typical examples are 167 for slanted
fonts or 850 for condensed fonts.

\begin{decl}
  |\reencodefont|\arg{etx}\arg{transformed font}
\end{decl}
This rearranges the encoding vector of \m{transformed font}.


For example, to create an oblique, |8r|-encoded version of Adobe Times
called \texttt{ptmro8r} you say:
\begin{verbatim}
  \transformfont{ptmro8r}{\reencodefont{8r}{\slantfont{167}{\fromafm{ptmr8a}}}}
\end{verbatim}
This will create \texttt{ptmr8a.mtx}, \texttt{ptmr8a.pl},
\texttt{ptmro8r.mtx} and \texttt{ptmro8r.pl}, which can then be used
as raw fonts in \verb|\installfont| commands.  The same transformation
can also be achieved in two steps:
\begin{verbatim}
  \transformfont{ptmr8r}{\reencodefont{8r}{\fromafm{ptmr8a}}}
  \transformfont{ptmro8r}{\slantfont{167}{\frommtx{ptmr8r}}}
\end{verbatim}
This will create \texttt{ptmr8a.mtx}, \texttt{ptmr8a.pl},
\texttt{ptmr8r.mtx}, \texttt{ptmr8r.pl}, \texttt{ptmro8r.mtx} and
\texttt{ptmro8r.pl}.

You will have to inform your device driver about the transformed font,
using the syntax appropriate for that driver.  For example, in \dvips
you add a line to \texttt{psfonts.map}:
\begin{verbatim}
  ptmro8r Times-Roman ".167 SlantFont TeXBase1Encoding ReEncodeFont" <<8r.enc
\end{verbatim}


\iffalse
%%  ------------------------------------------------------------

THE NEXT BIT HASN'T BEEN IMPLEMENTED YET!
AND I'M NOT SURE IT EVER WILL BE...

\begin{decl}
  |\declareafmdirectories|\arg{string}
\end{decl}
This specifies the directories which \afm files may be found in,
separated by commas.  For example:
\begin{verbatim}
\declareafmdirectories{/usr/local/fonts/afm/adobe/,
   /usr/local/fonts/afm/monotype/}
\end{verbatim}

\begin{decl}
  |\declarepldirectories|\arg{string}
\end{decl}
This specifies the directories which \pl files may be found in,
separated by commas.  For example:
\begin{verbatim}
\declarepldirectories{/usr/local/fonts/pl/cm/,
   /usr/local/fonts/pl/dc/}
\end{verbatim}

\begin{decl}
  |\declareetxdirectories|\arg{string}
\end{decl}
This specifies the directories which \etx files may be found in,
separated by commas.  For example:
\begin{verbatim}
\declareetxdirectories{/usr/local/tex/inputs/fontinst/,
   /tmp/fontinst/}
\end{verbatim}

\begin{decl}
  |\declaremtxdirectories|\arg{string}
\end{decl}
This specifies the directories which \mtx files may be found in,
separated by commas.  For example:
\begin{verbatim}
\declaremtxdirectories{/usr/local/tex/inputs/fontinst/,
   /tmp/fontinst/}
\end{verbatim}

\begin{decl}
  |\declaretempdirectory|\arg{string}
\end{decl}
This specifies a prefix which should be added to any temporary
files before writing them.  For example, you can have any
temporary files placed in the directory \url{/tmp/fontinst} by
saying:
\begin{verbatim}
\declaretempdirectory{/tmp/fontinst/}
\end{verbatim}
This directory should be included in the \etx and \mtx
directories.

%%  ------------------------------------------------------------
\fi

\begin{decl}
  |\declaresize|\arg{size}\arg{fd-size-range}
\end{decl}
This declares a new size, and gives the \fd commands for it.  For
example, \url{fontinst.sty} declares the following sizes:
\begin{verbatim}
  \declaresize{}{<<->>}
  \declaresize{5}{<<5>>}
  \declaresize{6}{<<6>>}
  \declaresize{7}{<<7>>}
  \declaresize{8}{<<8>>}
  \declaresize{9}{<<9>>}
  \declaresize{10}{<<10>>}
  \declaresize{11}{<<10.95>>}
  \declaresize{12}{<<12>>}
  \declaresize{14}{<<14.4>>}
  \declaresize{17}{<<17.28>>}
  \declaresize{20}{<<20.74>>}
  \declaresize{25}{<<24.88>>}
\end{verbatim}

\begin{decl}
  |\declareencoding|\arg{string}\arg{etx}
\end{decl}
This declares which \etx file corresponds to which encoding
string.  For example, \url{fontinst.sty} declares the following
encoding strings:
\begin{verbatim}
  \declareencoding{TEX TEXT}{OT1}
  \declareencoding{TEX TEXT WITHOUT F-LIGATURES}{OT1}
  \declareencoding{TEX TYPEWRITER TEXT}{OT1TT}
  \declareencoding{TEX MATH ITALIC}{OML}
  \declareencoding{TEX MATH SYMBOLS}{OMS}
  \declareencoding{TEX MATH EXTENSION}{OMX}
  \declareencoding{EXTENDED TEX FONT ENCODING - LATIN}{T1}
  \declareencoding{TEX TEXT COMPANION SYMBOLS 1---TS1}{TS1}
  \declareencoding{TEXBASE1ENCODING}{8r}
  \declareencoding{TEX TYPEWRITER AND WINDOWS ANSI}{8y}
\end{verbatim}

\subsection{Install commands}

The \m{install commands} describe the fonts, glyphs and encodings used
to build fonts.  The \m{install commands} are:

\begin{decl}
  |\installfamily|\arg{encoding}\arg{family}\arg{fd-commands}
\end{decl}
This produces a \LaTeX\ family with the given encoding and family,
for example to create the Cork-encoded Times family, you say:
\begin{verbatim}
  \installfamily{T1}{ptm}{}
\end{verbatim}
The \m{fd-commands} are executed every time a font in that family is
loaded, for example to stop the Courier font from being hyphenated you
say:
\begin{verbatim}
  \installfamily{T1}{pcr}{\hyphenchar\font=-1}
\end{verbatim}

\begin{decl}
  |\installfont|\arg{font-name}\arg{file-list}\arg{etx}\\
  \arg{encoding}\arg{family}\arg{series}\arg{shape}\arg{size}
\end{decl}
This produces a \TeX\ virtual font called \m{font-name} from a
comma-separated \m{file-list} which should be \texttt{.mtx},
\texttt{.afm} or \texttt{.pl} filenames, with an optional
`\texttt{scaled} \m{scale}' suffix.  Any \texttt{.afm} files are also
converted into \texttt{.pl} files, for use as `raw' fonts.  The
resulting \TeX\ font is encoded using \m{etx}\texttt{.etx}, and can be
accessed in \LaTeXe{} with the given \m{encoding}, \m{family},
\m{series} and \m{shape}.  The \m{size} is either declared by
\verb|\declaresize|, or is an \fd size specification.

For example, to install the T1-encoded Times Roman font
(using \texttt{T1.etx} and \texttt{latin.mtx}), you say:
\begin{verbatim}
  \installfont{ptmr8t}{ptmr8r,latin}{T1}
    {T1}{ptm}{m}{n}{}
\end{verbatim}
To install a OT1-encoded Times Roman font with a scaled version of
Symbol for the Greek letters, you say:
\begin{verbatim}
  \installfont{zptmrsy}{ptmr8r,psyr scaled 1100,latin}{OT1}
    {OT1}{ptm}{m}{n}{}
\end{verbatim}
This instruction sets the \texttt{rawscale} variable used by
\verb|\setrawglyph|, \verb|\setnotglyph| and \verb|\setkern|.

\begin{decl}
  |\installrawfont|\arg{font-name}\arg{file-list}\arg{etx}\\
  \arg{encoding}\arg{family}\arg{series}\arg{shape}\arg{size}
\end{decl}
This is similar to |\installfont| except that it produces
a \TeX\ raw font as \pl file rather than a virtual font.

For example, to install an 8r-encoded Times Roman raw font
(using \texttt{8r.etx} and \texttt{8r.mtx}), you say:
\begin{verbatim}
  \installfont{ptmr8t}{ptmr8r,8r}{8r}
    {8r}{ptm}{m}{n}{}
\end{verbatim}

\subsection{The \cs{latinfamily} command}

The \verb|\latinfamily| command is essentially a short-cut to save you
preparing a huge file with many different \fontinst commands in it.

It takes \afm or \mtx files as the source of font metric data to work
with.  Usually, you have a set of \afm files.  They must be named
according to a subset of the \Fontnamekb naming scheme.  To illustrate
the process, here is an edited part of the console log from a use of
\verb|\latinfamily|:
\begin{verbatim}
  \latinfamily{pad}{}
\end{verbatim}
This log does not show \fontinst `in action'; it's just to illustrate
which fonts are looked for when you use the \verb|\latinfamily|
command.
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,m,n,>> seek padr8r.mtx
  INFO>> to make LaTeX font shape <<pad,m,sc,>> seek padrc8r.mtx
  INFO>> to make LaTeX font shape <<pad,m,sl,>> seek padro8r.mtx
  INFO>> to make LaTeX font shape <<pad,m,it,>> seek padri8r.mtx
  INFO>> to make LaTeX font shape <<pad,m,n,c>> seek padr8rn.mtx
  INFO>> to make LaTeX font shape <<pad,m,sc,c>> seek padrc8rn.mtx
  INFO>> to make LaTeX font shape <<pad,m,sl,c>> seek padro8rn.mtx
  INFO>> to make LaTeX font shape <<pad,m,it,c>> seek padri8rn.mtx
\end{verbatim}

The important point to notice is that \fontinst needs an |8r| encoded
\mtx file for each font when you are using the \verb|latinfamily|
command.  If it can't find an |8r| encoded \mtx file, it'll look for
for an |8a| encoded \afm file.  It will automatically turn the file it
finds into an |8r| encoded \mtx file.  So when \fontinst says
`\verb|seek padr8r.mtx|', it is in fact looking for
\texttt{padr8r.mtx} and \texttt{padr8a.afm}.  Whatever it finds, it
will end up with \verb|padr8r.mtx| to work on.

The first line of the log shows that \fontinst is trying to create a
\vpl file for |pad/m/n|.  That is, font family |pad| (Adobe Garamond),
font series |m| (normal `book' or `regular' weight), and font shape
|n| (normal upright).

If it finds what it's looking for, it will create the files:
\begin{verbatim}
  padr7t.vpl
  padr8t.vpl
  padr8c.vpl
\end{verbatim}
And add these lines to the given \fd files:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{m}{n}{<<->> padr7t}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{m}{n}{<<->> padr8t}{}
  TS1pad.fd:    \DeclareFontShape{TS1}{pad}{m}{n}{<<->> padr8c}{}
\end{verbatim}
This means you will have three new fonts to use in \LaTeX: the OT1, T1
and TS1 encoded versions of |pad/m/n|.  You'll be able to select (say)
|T1/pad/m/n| by saying:
\begin{verbatim}
  \fontencoding{T1}\fontfamily{pad}\fontseries{m}\fontshape{n}\selectfont
\end{verbatim}
This is the clumsiest way of selecting that particular font, but I've
done it to illustrate exactly what's happening.

The next line:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,m,sc,>> seek padrc8r.mtx
\end{verbatim}
shows that \fontinst is trying to install a small caps font.  If you
have a real small caps metric file named \texttt{padrc8r.mtx} (don't
forget it'll look for an |8a| encoded \afm file), \fontinst will go
ahead and create the \vpl file and \fd file entry as expected.

But you don't normally have a real small caps font, so \fontinst will
quite happily produce a fake small caps font.  To do this, it looks
for a suitable metric file by dropping the `|c|':
\begin{quote}
  `Hmm\ldots\ I can't find \texttt{padrc8r}, so I'll look for
  \texttt{padr8r}.'
\end{quote}
And you will eventually have:
\begin{verbatim}
  padrc7t.vpl
  padrc8t.vpl
\end{verbatim}
And add these lines to the given \fd files:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{m}{sc}{<<->> padrc7t}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{m}{sc}{<<->> padrc8t}{}
\end{verbatim}
(Note that it won't install a TS1-encoded small caps font because
TS1 is a text symbol font, which would look the same in the upright
and small caps shape.)

The next log line shows \fontinst trying to create a \vpl for the
oblique version of Adobe Garamond:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,m,sl,>> seek padro8r.mtx
\end{verbatim}
It's quite usual for an oblique version to be unavailable, but
\fontinst has a way round this: it can fake an oblique font from the
corresponding `straight' version:
\begin{quote}
  `Oh dear: I can't find \texttt{padro8r}, so I'll look for
  \texttt{padr8r} and use clever maths to fake a slanted version.'
\end{quote}
This is not as straightforward as the small caps case.  \Fontinst
only works out what the metrics ought to be if the entire font is
slanted to the right.  It's up to the DVI driver to actually print a
slanted font.  \Dvips can do this.

You will eventually have:
\begin{verbatim}
  padro7t.vpl
  padro8t.vpl
  padro8c.vpl
\end{verbatim}
And these lines added to the given \fd files:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{m}{sl}{<<->> padro7t}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{m}{sl}{<<->> padro8t}{}
  TS1pad.fd:    \DeclareFontShape{TS1}{pad}{m}{sl}{<<->> padro8c}{}
\end{verbatim}

The next line is straightforward:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,m,it,>> seek padri8r.mtx
\end{verbatim}
If \fontinst can't find a suitable metrics file (\texttt{padri8r.mtx}
or \texttt{padri8a.afm}), it carries on without doing anything.  If it
does find a suitable metrics file, it churns away until you will
eventually have:
\begin{verbatim}
  padri7t.vpl
  padri8t.vpl
  padri8c.vpl
\end{verbatim}
And these lines added to the given \fd files:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{m}{it}{<<->> padri7t}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{m}{it}{<<->> padri8t}{}
  TS1pad.fd:    \DeclareFontShape{TS1}{pad}{m}{it}{<<->> padri8c}{}
\end{verbatim}

The next line is a bit different.  \Fontinst is now trying to create a
\vpl file for a \emph{condensed} font:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,m,n,c>> seek padr8rn.mtx
\end{verbatim}
If it finds a suitable metric file (Adobe Garamond, medium weight,
normal upright shape, condensed), it will eventually produce:
\begin{verbatim}
  padr7tn.vpl
  padr8tn.vpl
  padr8cn.vpl
\end{verbatim}
And these lines added to the given \fd files:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{mc}{n}{<<->> padr7tn}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{mc}{n}{<<->> padr8tn}{}
  TS1pad.fd:    \DeclareFontShape{TS1}{pad}{mc}{n}{<<->> padr8cn}{}
\end{verbatim}
There is no standard \LaTeX\ command like \verb|\bfseries| to select
the medium condensed (|mc|) series created here.  If you want to use
this font, you must do something like:
\begin{verbatim}
  \fontfamily{pad}\fontseries{mc}\selectfont
\end{verbatim}
If it doesn't find a suitable metric file for a narrow series,
\fontinst will just skip over and continue, unless you specifically
tell it to fake a narrow series.

And so the process continues: \fontinst attempts to create \vpl files
for condensed versions of all the font shapes met so far, and then
goes on to:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,b,n,>> seek padb8r.mtx
\end{verbatim}
And again, if it finds a suitable metric file (\texttt{padb8r.mtx} or
\texttt{padb8a.afm}), it'll potter off and create the files:
\begin{verbatim}
  padb7t.vpl
  padb8t.vpl
  padb8c.vpl
\end{verbatim}
And these lines added to the given \fd files:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{b}{n}{<<->> padb7t}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{b}{n}{<<->> padb8t}{}
  TS1pad.fd:    \DeclareFontShape{TS1}{pad}{b}{n}{<<->> padb8c}{}
\end{verbatim}
With this step done, fontinst will try to create \vpl files for the
small caps, slanted, and italic versions of |pad/b|; and then it'll
try to create condensed versions of all those:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,b,n,>> seek padb8r.mtx
  INFO>> to make LaTeX font shape <<pad,b,sc,>> seek padbc8r.mtx
  INFO>> to make LaTeX font shape <<pad,b,sl,>> seek padbo8r.mtx
  INFO>> to make LaTeX font shape <<pad,b,it,>> seek padbi8r.mtx
  INFO>> to make LaTeX font shape <<pad,b,n,c>> seek padb8rn.mtx
  INFO>> to make LaTeX font shape <<pad,b,sc,c>> seek padbc8rn.mtx
  INFO>> to make LaTeX font shape <<pad,b,sl,c>> seek padbo8rn.mtx
  INFO>> to make LaTeX font shape <<pad,b,it,c>> seek padbi8rn.mtx
\end{verbatim}
If it manages to find the files it needs to create the \vpl files to
use all those fonts with \LaTeX, you'll end up with the following
lines in the T1 \fd file (I've ignored the OT1 \fd file to save some
space):
\begin{verbatim}
  \DeclareFontShape{T1} {pad}{b} {n} {<<->> padb8t}{}
  \DeclareFontShape{T1} {pad}{b} {sc}{<<->> padbc8t}{}
  \DeclareFontShape{T1} {pad}{b} {sl}{<<->> padbo8t}{}
  \DeclareFontShape{T1} {pad}{b} {it}{<<->> padbi8t}{}
  \DeclareFontShape{T1} {pad}{bc}{n} {<<->> padb8tn}{}
  \DeclareFontShape{T1} {pad}{bc}{sc}{<<->> padbc8tn}{}
  \DeclareFontShape{T1} {pad}{bc}{sl}{<<->> padbo8tn}{}
  \DeclareFontShape{T1} {pad}{bc}{it}{<<->> pckbi8tn}{}
\end{verbatim}
To translate into English: Adobe Garamond bold in `normal', small
caps, slanted, and italic versions, as well as condensed versions of
all four.

Again, because there's no convenient way of selecting the condensed
versions with existing \LaTeX\ commands, you need to say something
like:
\begin{verbatim}
  \fontfamily{pad}\fontseries{bc}\selectfont
\end{verbatim}
to use the bold condensed (|bc|) versions of this font; you can of
course use \verb|\itshape|, \verb|\scshape|, \verb|\slshape|, and
\verb|upshape| to switch between the italic, small caps, slanted, and
`normal' versions of Adobe Garamond bold condensed once you've got
|pad/bc| selected.

So far, you've seen \verb|\latinfamily| look at two different weights
and two different widths.  For each weight, \verb|\latinfamily| will
try and install eight different fonts as you can see above.  It will
try and install the same eight different fonts for each of the
following different weights:
\begin{center}
\begin{tabular}{lll}
  \emph{\LaTeX} & \emph{Fontname} & \emph{description} \\
  |ul|     & |a|           & ultra light  \\
  |el|     & |i|           & extra light  \\
  |l|      & |l|           & light        \\
  |m|      & |k|, |r|      & book, regular \\
  |mb|     & |m|           & medium       \\
  |db|     & |d|           & demi bold    \\
  |sb|     & |s|           & semi bold    \\
  |b|      & |b|           & bold         \\
  |eb|     & |c|, |h|, |x| & black, heavy, extra bold \\
  |ub|     & |u|           & ultra bold
\end{tabular}
\end{center}
The \LaTeX\ column contains the label that will be used in the
\verb|\DeclareFontShape| command to specify the font series.  The
\Fontnamekb column contains the width specifier used to name the font
metric file that \fontinst will look for in that case.

In other words, at some stage \fontinst will look for:
\begin{verbatim}
  INFO>> to make LaTeX font shape <<pad,sb,n,>> seek pads8r.mtx
\end{verbatim}
and if it finds a suitable metric file (\texttt{pads8r.mtx} or
\texttt{pads8a.afm}), it will create:
\begin{verbatim}
  pads7t.vpl
  pads8t.vpl
  pads8c.vpl
\end{verbatim}
and \fd file entries like this:
\begin{verbatim}
  OT1pad.fd:    \DeclareFontShape{OT1}{pad}{sb}{n}{<<->> pads7t}{}
   T1pad.fd:    \DeclareFontShape{T1} {pad}{sb}{n}{<<->> pads8t}{}
  TS1pad.fd:    \DeclareFontShape{TS1}{pad}{sb}{n}{<<->> pads8c}{}
\end{verbatim}
and since |sb| is not a normal \LaTeX\ font series, you'll need to use
something like:
\begin{verbatim}
  \fontfamily{pad}\fontseries{sb}\selectfont
\end{verbatim}
to use this font.

% For example, \verb|\latinfamily{ptm}{}| is
% syntactic sugar for:
% \begin{verbatim}
%    \transformfont{ptmr8r}{\reencodefont{8r}{\fromafm{ptmr8a}}}
%    \transformfont{ptmri8r}{\reencodefont{8r}{\fromafm{ptmri8a}}}
%    \transformfont{ptmb8r}{\reencodefont{8r}{\fromafm{ptmb8a}}}
%    \transformfont{ptmbi8r}{\reencodefont{8r}{\fromafm{ptmbi8a}}}
%    \transformfont{ptmro8r}{\slantfont{167}{\frommtx{ptmr8r}}}
%    \transformfont{ptmbo8r}{\slantfont{167}{\frommtx{ptmb8r}}}
%    \installfonts
%       \installfamily{T1}{ptm}{}
%       \installfamily{OT1}{ptm}{}
%       \installfont{ptmr8t}{ptmr8r,latin}{T1}{T1}{ptm}{m}{n}{}
%       \installfont{ptmr7t}{ptmr8r,latin}{OT1}{OT1}{ptm}{m}{n}{}
%       \installfont{ptmrc8t}{ptmr8r,latin}{T1c}{T1}{ptm}{m}{sc}{}
%       \installfont{ptmrc7t}{ptmr8r,latin}{OT1c}{OT1}{ptm}{m}{sc}{}
%       \installfont{ptmri8t}{ptmri8r,latin}{T1}{T1}{ptm}{m}{it}{}
%       \installfont{ptmri7t}{ptmri8r,latin}{OT1i}{OT1}{ptm}{m}{it}{}
%       \installfont{ptmro8t}{ptmro8r,latin}{T1}{T1}{ptm}{m}{sl}{}
%       \installfont{ptmro7t}{ptmro8r,latin}{OT1}{OT1}{ptm}{m}{sl}{}
%       \installfont{ptmb8t}{ptmb8r,latin}{T1}{T1}{ptm}{b}{n}{}
%       \installfont{ptmb7t}{ptmb8r,latin}{OT1}{OT1}{ptm}{b}{n}{}
%       \installfont{ptmbc8t}{ptmb8r,latin}{T1c}{T1}{ptm}{b}{sc}{}
%       \installfont{ptmbc7t}{ptmb8r,latin}{OT1c}{OT1}{ptm}{b}{sc}{}
%       \installfont{ptmbi8t}{ptmbi8r,latin}{T1}{T1}{ptm}{b}{it}{}
%       \installfont{ptmbi7t}{ptmbi8r,latin}{OT1i}{OT1}{ptm}{b}{it}{}
%       \installfont{ptmbo8t}{ptmbo8r,latin}{T1}{T1}{ptm}{b}{sl}{}
%       \installfont{ptmbo7t}{ptmbo8r,latin}{OT1}{OT1}{ptm}{b}{sl}{}
%    \endinstallfonts
% \end{verbatim}


\section{Encoding files}

An \emph{encoding file} (or \texttt{.etx} file) is a \TeX\ document
consisting of:

\begin{decl}
  |\relax|\\
  \emph{ignored material}\\
  |\encoding|\\
  \m{encoding commands}\\
  |\endencoding|\\
  \emph{ignored material}
\end{decl}
This describes the encoding of a font, using the \m{encoding
  commands}.

Since the encoding file ignores any material between \verb|\relax| and
\verb|\encoding|, an \emph{encoding file} can also be a \LaTeX\
document.


\subsection{Encoding commands}

The \m{encoding commands} are:

\begin{decl}
  |\nextslot|\arg{number}
\end{decl}
Sets the number of the next slot.  If there is no \verb|\nextslot|
command, the number is the successor of the previous slot.

\begin{decl}
  |\skipslots|\arg{number}
\end{decl}
\NEWfeature{v1.8}
Advances the number of the next slot.

\begin{decl}
  |\setslot|\arg{glyph}\\
  \m{slot commands}\\
  |\endsetslot|
\end{decl}
Sets the slot of the \m{glyph}.  The \m{slot commands} describe
the glyph, and give its usage in \TeX.

\begin{decl}
  |\inputetx|\arg{file}
\end{decl}
Inputs the \m{encoding commands} of \m{file}\texttt{.etx}.


\subsection{Encoding variables}

The \emph{encoding files} may set the following integer variables.

\begin{decl}
  |boundarychar|
\end{decl}
The slot of the boundary character.

\begin{decl}
  |fontdimen(|$n$|)|
\end{decl}
The value of the $n$-th font dimension.

\begin{decl}
  |letterspacing|
\end{decl}
The extra space to be added between every glyph.

\begin{decl}
  |\int|\arg{glyph}
\end{decl}
The slot number for \m{glyph}.


The \emph{encoding files} may set the following string variables:

\begin{decl}
  |codingscheme|
\end{decl}
The font coding scheme.


\subsection{Slot commands}

The \m{slot commands} are:

\begin{decl}
  |\comment|\arg{text}
\end{decl}
A comment, which is ignored by \fontinst.

\begin{decl}
  |\ligature|\arg{ligtype}\arg{glyph}\arg{glyph}
\end{decl}
Specifies a ligature of type \m{ligtype} from the current glyph
followed by the first glyph to the second glyph.  The \m{ligtype}s are
as in \vpl files (see the \texttt{vptovf} Web source for more
details).  For example:
\begin{verbatim}
  \setslot{ff}
    \ligature{LIG}{i}{ffi}
    \ligature{LIG}{l}{ffl}
    \comment{The `ff' ligature.}
  \endsetslot
\end{verbatim}

\begin{decl}
  |\usedas|\arg{type}\arg{control sequence}
\end{decl}
\NEWfeature{Obsolete?!}
Sets the \TeX\ control sequence for this slot, with the \emph{type}
taken from:
\begin{verbatim}
  char       accent     mathord
  mathbin    mathrel    mathopen
  mathclose  mathpunct  mathvariable
  mathaccent mathdelim
\end{verbatim}

\begin{decl}
  |\nextlarger|\arg{glyph}
\end{decl}
Sets a \textsc{nextlarger} entry from the current slot to the
\m{glyph}.

\begin{decl}
  |\varchar|\\
  \m{varchar commands}\\
  |\endvarchar|
\end{decl}
Sets a \textsc{varchar} entry for the current slot, using the
\m{varchar commands}.  The \m{varchar commands} are:
\begin{decl}
  |\vartop|\arg{glyph}\\
  |\varmid|\arg{glyph}\\
  |\varbot|\arg{glyph}\\
  |\varrep|\arg{glyph}
\end{decl}
Sets the top, middle, bottom, or repeated \m{glyph} of the
\textsc{varchar}.



\section{Metric files}

A \emph{metric file} (or \texttt{.mtx} file) is a \TeX\ document
consisting of:

\begin{decl}
  |\relax|\\
  \emph{ignored material}\\
  |\metrics|\\
  \m{metric commands}\\
  |\endmetrics|\\
  \emph{ignored material}
\end{decl}
This describes the glyphs in a font, using the \m{metric commands}.


\subsection{Metric commands}

The \m{metric commands} are:

\begin{decl}
  |\setglyph|\arg{name}\\
  \m{glyph commands} \\
  |\endsetglyph|
\end{decl}
If the glyph called \m{name} is undefined, it is built using the
\m{glyph commands} given below, for example:
\begin{verbatim}
  \setglyph{IJ}
     \glyph{I}{1000}
     \glyph{J}{1000}
  \endsetglyph
  \setglyph{Asmall}
     \glyph{A}{850}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\resetglyph|\arg{name}\\
  \m{glyph commands}\\
  |\endsetglyph|
\end{decl}
Gives the definition of the glyph called \m{name} using the
\m{glyph commands}.

\begin{decl}
  |\unsetglyph|\arg{name}
\end{decl}
Makes the glyph called \m{name} undefined.

\begin{decl}
  |\setrawglyph|\arg{name}\arg{font}\arg{dimen}\arg{integer}\\
    \arg{integer}\arg{integer}\arg{integer}\arg{integer}
\end{decl}
This sets a glyph called \m{name} from the \m{font}, which has the
given design size, slot, width, height, depth and italic correction.
If the integer variable \texttt{rawscale} is set, the glyph will be
scaled by that amount.  This command will usually be generated
automatically from an \afm or \pl file.

\begin{decl}
  |\setnotglyph|\arg{name}\arg{font}\arg{dimen}\\
    \arg{integer}\arg{integer}\arg{integer}\arg{integer}
\end{decl}
This sets a glyph called \m{name}\texttt{-not}, which is present in
the \m{font}, but is not in the default encoding.  It takes the same
arguments as \verb|\setrawglyph|, although the slot will normally be
$-1$.  This command will usually be generated automatically from an
\afm file.

\begin{decl}
  |\setkern|\arg{glyph}\arg{glyph}\arg{integer expression}
\end{decl}
Sets a kern between the two glyphs, scaled by the current value of
\texttt{rawscale}, if it has been set.

\emph{Note} that there is a bug with the current implementation: if
more than one kern value is given for the same pair of glyphs, then
both are written to the (V)PL file.  Really it should only be the
first pair (to fit with all the other \verb|\set...| commands).
This bug is not likely to be fixed soon.

\begin{decl}
  |\setleftkerning|\arg{glyph}\arg{glyph}\arg{integer expression}\\
  |\setrightkerning|\arg{glyph}\arg{glyph}\arg{integer expression}
\end{decl}
Sets the amount by which the first glyph should mimic how the second
glyph kerns on the left or right, for example:
\begin{verbatim}
  \setleftkerning{Asmall}{A}{850}
  \setrightkerning{Asmall}{A}{850}
  \setleftkerning{IJ}{I}{1000}
  \setrightkerning{IJ}{J}{1000}
\end{verbatim}
Sets the amount by which the first glyph should mimic how the second
glyph kerns on the right, for example:

\begin{decl}
  |\setleftrightkerning|\arg{glyph}\arg{glyph}\arg{integer expression}
\end{decl}
\NEWfeature{v1.8}
Sets the amount by which the first glyph should mimic how the second
glyph kerns on both sides, for example:
\begin{verbatim}
  \setleftrightkerning{Asmall}{A}{850}
\end{verbatim}

\begin{decl}
  |\inputmtx|\arg{file}
\end{decl}
Inputs the \m{metric commands} of \m{file}\texttt{.mtx}.


\subsection{Metric variables}

The \emph{metrics files} may set the following integer variables:

\begin{decl}
  |ascender|\\
  |capheight|\\
  |descender|\\
  |xheight|
\end{decl}
The height of the tallest lower-case letter.

The height of the tallest capital letter.

The depth of the lowest lower-case letter.

The x-height of lower-case letters without ascenders.

\begin{decl}
  |italicslant|
\end{decl}
The ratio of the italic slant, given in units of rightward movement
for each 1000 units of upward movement.

\begin{decl}
  |minimumkern|
\end{decl}
Any kern smaller than this amount is ignored.

\begin{decl}
  |monowidth|
\end{decl}
This variable is set if the font is monowidth.

\begin{decl}
  |underlinethickness|
\end{decl}
The width of the underline rule.

\begin{decl}
  \m{glyph}|-spacing|
\end{decl}
The letter spacing for the glyph \m{glyph}.


The \emph{metrics files} may set the following dimension variables:

\begin{decl}
  |designsize|
\end{decl}
The design size of the font.


\subsection{Glyph commands}

The \m{glyph commands} are:

\begin{decl}
  |\glyph|\arg{glyph}\arg{integer expression}
\end{decl}
Sets the named glyph \m{glyph} at the given scale, with 1000 as the
natural size.  This:
\begin{itemize}
\item Advances the current glyph width.
\item Sets the current glyph height to be at least the height of the
  named glyph, adjusted for the current vertical offset.
\item Sets the current glyph depth to be at least the depth of the
  named glyph, adjusted for the current vertical offset.
\item Sets the current glyph italic correction to be the same as the
  set glyph.
\end{itemize}
The named glyph must have already been defined, otherwise an error
will occur.  For example:
\begin{verbatim}
  \setglyph{fi}
    \glyph{f}{1000}
    \glyph{i}{1000}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\glyphrule|\arg{integer expression}\arg{integer expression}
\end{decl}
Sets a rule of the given width and height, for example:
\begin{verbatim}
  \setglyph{underline}
    \glyphrule{333}{40}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\glyphspecial|\arg{text}
\end{decl}
Sets a driver-dependent \verb|\special|, for example:
\begin{verbatim}
  \setglyph{crest}
    \glyphspecial{Filename: crest.eps}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\glyphwarning|\arg{text}
\end{decl}
Sets a warning \verb|\special|, and produces a warning message each
time the glyph is used, for example:
\begin{verbatim}
  \setglyph{missingglyph}
    \glyphrule{500}{500}
    \glyphwarning{Missing glyph `missingglyph'}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\movert|\arg{integer expression}
\end{decl}
Moves right by the given amount, and advances the current glyph width,
for example:
\begin{verbatim}
  \setglyph{Asmall}
    \movert{50}
    \glyph{A}{700}
    \movert{50}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\moveup|\arg{integer expression}
\end{decl}
Moves up by the given amount, and advances the current vertical
offset.  Each glyph should always end at vertical offset zero, for
example:
\begin{verbatim}
  \setglyph{onehalf}
    \moveup{500}
    \glyph{one}{700}
    \moveup{-500}
    \glyph{slash}{1000}
    \moveup{-200}
    \glyph{two}{700}
    \moveup{200}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\push|\\
  \m{glyph commands}\\
  |\pop|
\end{decl}
Performs the \m{glyph commands} without adjusting the current position
or glyph width, for example:
\begin{verbatim}
  \setglyph{aacute}
    \push
      \movert{\div{\sub{\width{a}}{\width{acute}}}{2}}
      \glyph{acute}{1000}
    \pop
    \glyph{a}{1000}
  \endsetglyph
\end{verbatim}

\begin{decl}
  |\glyphpcc|\arg{glyph}\arg{integer expression}\arg{integer expression}
\end{decl}
This is generated from \texttt{PCC} instructions in an \afm file, and
is syntactic sugar for:
\begin{quote}
\begin{small}
|\push|\\
|\movert|\arg{first integer expression}\\
|\moveup|\arg{second integer expression}\\
|\glyph|\arg{glyph}|{1000}|\\
|\pop|
\end{small}
\end{quote}

\begin{decl}
  |\resetwidth|\arg{integer expression}\\
  |\resetheight|\arg{integer expression}\\
  |\resetdepth|\arg{integer expression}\\
  |\resetitalic|\arg{integer expression}
\end{decl}
Sets the width, height, depth, or italic correction of the current
glyph.

\begin{decl}
  |\samesize|\arg{glyph}
\end{decl}
Sets the dimensions of the current glyph to be the same as \m{glyph}.

Inside the definition of \m{glyph}, you can use expressions such as
|\width|\arg{glyph}, which will refer to the glyph defined so far.
For example, a display summation sign can be defined to be a text
summation $\sum$ scaled 120\% with 0.5\,pt extra height and depth
using:
\begin{verbatim}
  \setglyph{summationdisplay}
    \glyph{summationtext}{1200}
    \resetheight{\add{\height{summationdisplay}}{50}}
    \resetdepth{\add{\depth{summationdisplay}}{50}}
  \endsetglyph
\end{verbatim}
Within a |\resetglyph|, these expressions will refer to the previous
definition of the glyph.  For example, you can add sidebearings to the
letter `A' with:
\begin{verbatim}
  \resetglyph{A}
    \movert{25}
    \glyph{A}{1000}
    \movert{25}
  \endresetglyph
\end{verbatim}


\section{Future work}

The \fontinst software is now fairly stable, but there are
some things I would like to do sometime\dots
\begin{itemize}
\item See if it's possible to automatically generate `first cut' math
  fonts.

\item Add a way to use alternate sets and SC fonts.

\item Find out if there's a way to generate smaller VPLs for T1 small
  caps fonts.

\item Allow reals rather than just integers in AFM files.

\item Fix the bug with multiple \verb|\setkern| entries.
\end{itemize}
A more detailed list is distributed as the file \texttt{TODO}.


\section*{Acknowledgements}

I'd like to thank all of the \fontinst $\alpha$-testers, especially
Karl Berry, Damian Cugley, Steve Grahthwohl, Yannis Haralambous, Alan
Hoenig, Rob Hutchings, Constantin Kahn, Peter Busk Laursen, Ciar{\'a}n {\'O}
Duibh{\'\i}n, Hilmar Schlegel, Paul Thompson, Norman Walsh and John Wells,
who made excellent bug-catchers!

Thanks to Barry Smith, Frank Mittelbach, and especially Sebastian
Rahtz for many useful email discussions on how virtual fonts should
interact with \LaTeXe.

Thanks to Karl Berry and Damain Cugley for detailed comments on this
documentation.

Thanks to David Carlisle for the use of his \texttt{trig} macros for
calculating trignometry.


\section*{Warranty and distribution}

There is no warranty for the \fontinst package, to the extent
permitted by applicable law. Except when otherwise stated in writing,
the author provides the program `as is' without warranty of any kind,
either expressed or implied, including, but not limited to, the
implied warranties of merchantability and fitness for a particular
purpose. The entire risk as to the quality and performance of the
program is with you.  Should the package prove defective, you assume
the cost of all necessary servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing
will the author be liable to you for damages, including any general,
special, incidental or consequential damages arising out of the use or
inability to use the program (including but not limited to loss of
data or data being rendered inaccurate or losses sustained by you or
third parties or a failure of the program to operate with any other
programs), even if such holder or other party has been advised of the
possibility of such damages.

Redistribution of unchanged files is allowed provided that all files
listed in the \texttt{MANIFEST} file are distributed.

If you receive only some of these files from someone, or if you
receieve altered files, then complain!

\end{document}
