%%% ====================================================================
%%%  @LaTeX-file{
%%%     author          = "Alan Jeffrey",
%%%     version         = "1.332",
%%%     date            = "27 June 1994",
%%%     time            = "14:42:27 BST",
%%%     filename        = "fontinst.tex",
%%%     address         = "School of Cognitive and Computing Sciences
%%%                        University of Sussex
%%%                        Brighton BN1 9QH
%%%                        UK",
%%%     FAX             = "+44 273 678188",
%%%     email           = "alanje@cogs.sussex.ac.uk",
%%%     codetable       = "ISO/ASCII",
%%%     keywords        = "font installation PostScript documentation",
%%%     supported       = "yes",
%%%     abstract        = "This is the documentation for the fontinst
%%%                        font installation package.",
%%%     package         = "fontinst",
%%%     dependencies    = "none"
%%%  }
%%% ====================================================================

\def\fontinstversion{1.332}

% Copyright 1993, 1994 Alan Jeffrey

\documentclass{article}

\title{The {\tt fontinst} package, v\fontinstversion}
\author{Alan Jeffrey \\ alanje@cogs.susx.ac.uk}
\date{June 1994}

%\address{School of Cognitive and Computing Sciences \\
%   University of Sussex \\
%   Falmer \\
%   Brighton BN1 9QH \\
%   UK}
%\netaddress{alanje@cogs.susx.ac.uk}

\def\vb#1{{\tt\string#1}}
\def\arg#1{{\tt\char`\{}{\em #1\/}{\tt\char`\}\penalty10}}
\def\psname#1{${\rm\langle#1\rangle}$}

\def\identity#1{#1}

\def\syntax{\description}
\def\endsyntax{\enddescription}
\def\syn#1{\item[\mdseries{\begin{tabular}{@{}l}#1\end{tabular}}]\mbox{}
   \par\noindent\ignorespaces}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

The {\tt fontinst} package is a set of \TeX\ macros which allows users
to install virtual fonts.  It can convert fonts from Adobe Font Metric
({\tt afm}) or \TeX\ Property List ({\tt pl}) format into Virtual
Property List ({\tt vpl}) format.  These Virtual Fonts ({\tt vf}s) can
then be used by your favourite device driver, such as {\tt dvips}.

The package:
\begin{itemize}
\item Is written in \TeX, for maximum portabilty (at the cost of speed).
\item Supports the OT1 (Computer Modern) and T1 (Cork) encodings.
\item Allows fonts to be generated in an arbitrary encoding, 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 Automatically generates a \verb|fd| file for use with \LaTeXe.
\item Can be customized by the user to deal with arbitrary font encodings.
\end{itemize}
Fontinst is now a stable piece of software.  All further updates will
be upwardly compatible with the interface described in this document.

\section{Installation}

To install {\tt fontinst}, put the contents of the {\tt inputs} and {\tt 
examples} directories
into a directory read by \TeX, for example \verb|/usr/local/tex/inputs|.
You should also make sure the {\tt afm} files you plan to use can be
read by \TeX, for  
example in Unix csh:
\begin{verbatim}
   setenv TEXINPUTS /usr/local/fonts/afm:$TEXINPUTS
\end{verbatim}
That's it!

\section{Usage}

The simplest way to use the {\tt fontinst} package is to start by running 
\TeX\ on {\tt fontinst.sty}, and then responding to the \verb|*|
prompt by saying:
\begin{verbatim}
   \latinfamily{ptm}{}\bye
\end{verbatim}
This will install the Adobe Times fonts.  It may 
take some time, and will produce:
\begin{itemize}
\item One {\tt pl} file for each {\tt afm} file.
\item One {\tt vpl} file for each \TeX\ font.
\item One {\tt fd} file for each family.
\end{itemize}
These can be converted to \TeX\ fonts using {\tt pltotf} or {\tt
vptovf}, for example in Unix csh:
\begin{verbatim}
   tutorial% foreach X(*.pl)
   ? pltotf $X $X:r.tfm
   ? end
   tutorial% foreach X(*.vpl)
   ? vptovf $X $X:r.vf $X:r.tfm
   ? end
\end{verbatim}
You should then:
\begin{itemize}
\item Move the {\tt tfm} files to your \TeX\ fonts directory
   (e.g.~\verb|/local/fonts/tfm|). 
\item Move the {\tt vf} files to your
   virtual fonts directory (e.g.~\verb|/local/fonts/vf|).
\item Move the {\tt fd} files to your \TeX\ inputs directory 
   (e.g.~\verb|/local/tex/inputs|).
\end{itemize}
Finally, you should tell your {\tt dvi}-to-PostScript driver about the
fonts.  This will depend on your driver, for example with {\tt dvips}
you should add the following lines to your {\tt psfonts.map} file:
\begin{verbatim}
   ptmr0      Times-Roman
   ptmri0     Times-Italic
   ptmb0      Times-Bold
   ptmbi0     Times-BoldItalic
\end{verbatim}
You can then use the fonts!  For example, to make Adobe Times the default 
roman font in \LaTeXe, you say:
\begin{verbatim}
   \renewcommand{\rmdefault}{ptm}
\end{verbatim}
Once you have installed and used the Times fonts, you can install the 
other standard Adobe fonts (Times, Helvetica and Courier) in a similar
way.  You can also install Adobe Times and 
Symbol as \TeX\ math fonts by running \TeX\ on \verb|fontptcm.tex|.

\section{Installing your own Latin fonts}

The {\tt fontinst} package has a simple interface for installing most 
Latin fonts.  Most users will never need to use any commands other than 
these.  The commands are:
\begin{syntax}
\syn{\vb\latinfamily\arg{family}\arg{commands}}
   This installs a Latin family of fonts.  For example, to install Adobe 
   Times, you say:
\begin{verbatim}
   \latinfamily{ptm}{}
\end{verbatim}
   The {\em commands\/} are 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 `{\tt x}' then {\tt
   fontinst} will use 
   any Expert fonts in creating the fonts.  If the fourth letter is
   `{\tt 9}' then {\tt fontinst} will use Expert fonts to create
   fonts with old style digits.
 
\end{syntax}
Before using these commands, you will need to make sure that you have the 
Adobe Font Metric ({\tt afm}) files for the fonts, and that they have 
appropriate names.  The {\tt fontinst} package uses the \LaTeX{}
convention for naming fonts, and uses a {\em font family} name which
consists of:
\begin{itemize}
\item a {\em foundry}, such as `{\tt h}' for Bigelow \& Holmes.
\item a {\em face}, such as `{\tt lc}' for Lucida.
\item up to two {\em variants}, such as `{\tt b}' for Bright.
\end{itemize}
So the family name `{\tt hlcb}` indicates Bigelow \& Holmes Lucida Bright.

The foundry must be one letter, and the face 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, faces and variants is
given in Karl Berry's `Filenames for fonts', but the more
common ones are given in Tables~\ref{Tab:foundry}--\ref{Tab:variant}.

\begin{table}
\begin{center}
   \begin{tabular}{clclcl}
   a &     Autologic &
   b &     Bitstream &
   h &     Bigelow \& Holmes \\
   l &     Linotype &
   m &     Monotype &
   p &     Adobe \\
   z &     bizarre
   \end{tabular}
   \caption{A partial list of foundries}
   \label{Tab:foundry}
\end{center}
\begin{center}
   \begin{tabular}{clclcl}
   bb &     Bembo &
   bd &     Bodoni &
   bk &     Bookman \\
   bv &     Baskerville &
   ca &     Caslon &
   ch &     Charter \\
   cr &     Courier &
   cs &     Century Schoolbook &
   fr &     Frutiger \\
   fu &     Futura &
   gj &     Granjon &
   gl &     Galliard \\
   gm &     Garamond &
   gs &     Gill Sans &
   hv &     Helvetica \\
   lc &     Lucida &
   nc &     New Century Schoolbook &
   pl &     Palatino \\
   pn &     Plantin &
   pp &     Perpetua &
   rw &     Rockwell \\
   st &     Stone &
   sy &     Symbol &
   tm &     Times \\
   un &     Univers &
   ut &     Utopia &
   zc &     Zapf Chancery
   \end{tabular}
   \caption{A partial list of faces}
\end{center}
\begin{center}
   \begin{tabular}{clclcl}
   4 &     fax &
   9 &     oldstyle digits &
   b &     bright \\
   m &     math italic &
   n &     informal &
   s &     sans serif \\
   t &     typewriter &
   v &     math extension &
   w &     script, handwritten, swash \\
   x &     expert &
   y &     symbol
   \end{tabular}
   \caption{A partial list of variants}
   \label{Tab:variant}
\end{center}
\end{table}

The {\tt fontinst} package uses Karl Berry's naming scheme for {\tt
afm} files.  The full naming scheme is rather more flexible than the
subset used by {\tt fontinst}, which uses filenames consisting of:
\begin{itemize}
\item a {\em foundry}, such as `{\tt h}' for Bigelow \& Holmes.
\item a {\em face}, such as `{\tt lc}' for Lucida.
\item a {\em weight}, such as `{\tt r}' for regular.
\item up to two {\em shapes}, such as `{\tt i}' for italic.
\item up to two {\em variants}, such as `{\tt b}' for Bright.
\item an {\em encoding}, such as `{\tt 0}' for Adobe Standard.
\item an optional {\em width}, such as `{\tt c}' for Compressed
\item a {\em file extension}, such as `{\tt .afm}' for Adobe Font
   Metric. 
\end{itemize}
So the filename name `{\tt hlcrib0c.afm}' indicates Bigelow \& Holmes
Lucida Bright Italic Compressed in the Adobe Standard encoding.

The full list of shapes, encodings and weights is 
given in Karl Berry's `Filenames for fonts', but the more
common ones are given in Tables~\ref{Tab:shape}--\ref{Tab:weight}.
Note that some variants and encodings overlap, such as `{\tt x}' for
Expert.  In this case, you do not have to give the variant, for
example, Adobe Times Expert is `{\tt ptmrx}', not `{\tt ptmrxx}'.

\begin{table}
\begin{center}
   \begin{tabular}{clclcl}
   c &     small caps &
   i &     italic &
   o &     oblique (i.e.,~slanted) 
   \end{tabular}
   \caption{A parital list of shapes}
   \label{Tab:shape}
\end{center}
\begin{center}
   \begin{tabular}{clclcl}
   0 &     Adobe Standard &
  7t &     \TeX{} text {\tt OT1} &
   a &     Adobe Alternate \\
   m &     \TeX{} math italic {\tt OML} &
   q &     \TeX{} text extended {\tt T1} &
   v &     \TeX{} math extension {\tt OMX} \\
   x &     Adobe Expert &
   y &     \TeX{} math symbols {\tt OMS} 
   \end{tabular}
   \caption{A parital list of encodings}
\end{center}
\begin{center}
   \begin{tabular}{clclcl}
   b &     bold &
   d &     demibold &
   i &     extra light \\
   l &     light &
   s &     semibold &
   x &     extra bold
   \end{tabular}
   \caption{A parital list of weights}
   \label{Tab:weight}
\end{center}
\end{table}

For example, to install Adobe Garamond including the Expert fonts, you
would need to rename the {\tt afm} files:
\begin{center}\begin{tabular}{rl}
   {\em Adobe's name\/} & {\em fontinst name} \\
   AGaramond-Bold.afm               & {\tt pgmb0.afm} \\ 
   AGaramond-BoldItalic.afm         & {\tt pgmbi0.afm}  \\
   AGaramond-Italic.afm             & {\tt pgmri0.afm}  \\
   AGaramond-Regular.afm            & {\tt pgmr0.afm}  \\
   AGaramond-Semibold.afm           & {\tt pgms0.afm}  \\
   AGaramond-SemiboldItalic.afm     & {\tt pgmsi0.afm}  \\
   AGaramondExp-Bold.afm            & {\tt pgmbx.afm}  \\
   AGaramondExp-BoldItalic.afm      & {\tt pgmbix.afm}  \\
   AGaramondExp-Italic.afm          & {\tt pgmrix.afm}  \\
   AGaramondExp-Regular.afm         & {\tt pgmrx.afm}  \\
   AGaramondExp-Semibold.afm        & {\tt pgmsx.afm}  \\
   AGaramondExp-SemiboldItalic.afm  & {\tt pgmsix.afm}
\end{tabular}\end{center}
You can then run \TeX{} on the following document to install the
Garamond family:
\begin{verbatim}
   \input fontinst.sty
   \latinfamily{pgmx}{}
   \latinfamily{pgm9}{}
   \bye
\end{verbatim}
Not all font families can be installed using the Latin family
commands, so the rest of this document describes the full {\tt
fontinst} syntax, and is intended for `power users'.

\section{Syntax}

There are three types of files used by the {\tt fontinst} package:
\begin{itemize}

\item {\em fontinst files\/} contain commands to install fonts.  For
   example {\tt fonttime.tex} is a {\em fontinst file}.

\item {\em encoding files\/} contain information about an encoding,
   including the code table, ligatures, and font dimensions.  For
   example {\tt T1.etx} is an {\em encoding file}.

\item {\em metric files\/} contain information about glyphs, including
   glyph dimensions, composite characters, and kerning.  For example,
   {\tt latin.mtx} is a {\em metric file}.

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

\subsection{General commands}

The following commands can be used anywhere:
\begin{syntax}

\syn{\vb\needsfontinstversion\arg{version}}
   This issues a warning if the current version of the {\tt fontinst} 
   package is less than {\em version}.
   
\syn{\vb\setdim\arg{dim}\arg{dimension}}
   If the dimension variable
   {\em dim\/} is currently undefined, it is defined to be 
   the current value of {\em dimension}.

\syn{\vb\setint\arg{int}\arg{integer expression}}
   If the integer variable
   {\em int\/} is currently undefined, it is defined to be 
   the current value of {\em integer expression}.

\syn{\vb\setstr\arg{str}\arg{string}}
   If the string variable
   {\em str\/} is currently undefined, it is defined to 
   be the current value of {\em string}.

\syn{\vb\setcommand\arg{command}\arg{definition}}
   If the command {\em command\/} is currently undefined, it is defined 
   to be the {\em definition}.  This uses the same syntax as the \TeX{} 
   \verb|\def| command.
   
\syn{\vb\resetdim\arg{dim}\arg{dimension}}
   The dimension variable {\em dim\/} is defined to be 
   the current value of {\em dimension}.

\syn{\vb\resetint\arg{int}\arg{integer expression}}
   The integer variable {\em int\/} is defined to be 
   the current value of {\em integer expression}.

\syn{\vb\resetstr\arg{str}\arg{string}}
   The string variable {\em str\/} is defined to 
   be the current value of {\em string}.

\syn{\vb\resetcommand\arg{command}\arg{definition}}
   This is a synonym for \verb|\def|.
   
\syn{\vb\ifisint\arg{int}\vb\then}
   Expands out to \vb\iftrue\ if the integer
   variable {\em int\/} is defined, and 
   \vb\iffalse\ otherwise.

\syn{\vb\ifisdim\arg{dim}\vb\then}
   Expands out to \vb\iftrue\ if the dimension
   variable {\em dim\/} is defined, and 
   \vb\iffalse\ otherwise.

\syn{\vb\ifisstr\arg{str}\vb\then}
   Expands out to \vb\iftrue\ if the string 
   variable {\em str\/} is defined, and 
   \vb\iffalse\ otherwise.

\syn{\vb\ifisglyph\arg{glyph}\vb\then}
   Expands out to \vb\iftrue\ if the glyph 
   variable {\em glyph\/} is defined, and 
   \vb\iffalse\ otherwise.

\syn{\vb\ifiscommand\arg{command}\vb\then}
   Expands out to \vb\iftrue\ if the command {\em command\/} is defined,
   and \vb\iffalse\ otherwise.

\syn{\vb\unsetdim\arg{dim}}
   Makes {\em dim\/} an undefined dimension.

\syn{\vb\unsetint\arg{int}}
   Makes {\em int\/} an undefined integer.
   
\syn{\vb\unsetstr\arg{str}}
   Makes {\em str\/} an undefined string.

\syn{\vb\unsetcommand\arg{command}}
   Makes {\em command\/} an undefined command.
   
\end{syntax}

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

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

The {\em integer expressions\/} are:
\begin{syntax}

\syn{\psname{number}}
   A \TeX\ \psname{number}.

\syn{\vb\int\arg{int}}
   The value of the integer variable {\em int}.

\syn{\vb\width\arg{glyph}}
   The width of the glyph variable {\em glyph}.

\syn{\vb\height\arg{glyph}}
   The height of the glyph variable {\em glyph}.

\syn{\vb\depth\arg{glyph}}
   The depth of the glyph variable {\em glyph}.

\syn{\vb\italic\arg{glyph}}
   The italic correction of the glyph variable {\em glyph}.

\syn{\vb\kerning\arg{left}\arg{right}}
   The kerning between the {\em left\/} and {\em right\/} glyph variables.
   
\syn{\vb\neg\arg{integer expression}}
   The negation of the {\em integer expression}.

\syn{\vb\add\arg{integer expression}\arg{integer expression}}
   The sum of the two {\em integer expression\/}s.

\syn{\vb\sub\arg{integer expression}\arg{integer expression}}
   The first {\em integer expression\/} minus the second.
   
\syn{\vb\mul\arg{integer expression}\arg{integer expression}}
   The multiplication of the two {\em integer expression\/}s.

\syn{\vb\div\arg{integer expression}\arg{integer expression}}
   The first {\em integer expression\/} divided by the second.
   
\syn{\vb\scale\arg{integer expression}\arg{integer expression}}
   The first {\em integer expression\/} times the second, divided by 1000.

\end{syntax}

\section{Fontinst files}

A {\em fontinst file\/} is any \TeX\ document which inputs the {\tt 
fontinst} macros.  The commands available are:
\begin{syntax}

\syn{\vb\installfonts\\{\em install commands}\\\vb\endinstallfonts}
   This makes a font family, using the {\em install commands}.  There
   can be any number of \verb|\installfonts| commands in a {\em fontinst
   file}. 

\syn{\vb\substitutesilent\arg{from}\arg{to}}
   This declares a \LaTeX{} font subsubstitution, that the series or
   shape {\em from\/} should be substituted if necessary by the series
   or shape {\em to}.  
   When the font substitution is made, no warning will be made.
   For example, to say that the series {\em bx\/}
   can be replaced by the series {\em b}, you say:
\begin{verbatim}
   \substitutesilent{bx}{b}
\end{verbatim}
   The following declarations are standard:
\begin{verbatim}
   \substitutesilent{bx}{b}
   \substitutesilent{b}{bx}
   \substitutesilent{b}{sb}
   \substitutesilent{b}{db}
   \substitutesilent{sc}{nc}
\end{verbatim}

\syn{\vb\substitutenoisy\arg{from}\arg{to}}
   This is the same as \vb\substitutesilent, but gives a warning when
   the substitution is made by \LaTeX.  For example:
\begin{verbatim}
   \substitutenoisy{ui}{it}
\end{verbatim}
   The following declarations are standard:
\begin{verbatim}
   \substitutenoisy{ui}{it}
\end{verbatim}

\syn{\vb\transformfont\arg{font-name}\arg{transformed font}}
   This makes a raw transformed font, for example expanded, slanted, 
   or re-encoded.  {\em It is the responsibility of the device driver to 
   implement this transform.}  A {\em transformed font\/} is given by:
   \begin{center}
      \begin{tabular}{rcl}
         \em transformed font
            & $::=$
            & \vb\fromafm\arg{afm} \\
            & $|$ 
            & \vb\frommtx\arg{mtx} \\
            & $|$ 
            & \vb\scalefont\arg{integer expression}\arg{transformed font}
            \\
            & $|$ 
            & \vb\xscalefont\arg{integer expression}\arg{transformed font}
            \\
            & $|$ 
            & \vb\yscalefont\arg{integer expression}\arg{transformed font}
            \\
            & $|$ 
            & \vb\slantfont\arg{integer expression}\arg{transformed font}
            \\
            & $|$ 
            & \vb\reencodefont\arg{etx}\arg{transformed font}
      \end{tabular}
   \end{center}
   For example, if you have a file {\tt latin1.etx}, then
   to create an oblique, ISO Latin-1 encoded version of Adobe 
   Times called {\tt ptmrol} you say:
\begin{verbatim}
   \transformfont{ptmrol}{
      \slantfont{167}{
         \reencodefont{latin1}{
            \fromafm{ptmr0}
         }
      }
   }
\end{verbatim}
   This will create {\tt ptmr0.pl}, {\tt ptmrol.pl}, {\tt ptmr0.mtx} and 
   {\tt ptmrol.mtx}, which can then be used as raw fonts in 
   \vb\installfonts.  You will have to inform your device driver about 
   the transformed font, using the syntax appropriate for that driver.  
   For example, in {\tt dvips} you add a line to {\tt psfonts.map}:
\begin{verbatim}
   ptmrol Times-Roman .167 SlantFont ISOLatin1Encoding ReEncodeFont
\end{verbatim}
            
\iffalse 

THE NEXT BIT HASN'T BEEN IMPLEMENTED YET!

\syn{\vb\declareafmdirectories\arg{string}}
   This specifies the directories which {\tt 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}

\syn{\vb\declarepldirectories\arg{string}}
   This specifies the directories which {\tt 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}

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

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

\syn{\vb\declaretempdirectory\arg{string}}
   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 \verb|/tmp/fontinst| by saying:
\begin{verbatim}
\declaretempdirectory{/tmp/fontinst/}
\end{verbatim}
   This directory should be included in the \verb|etx| and \verb|mtx| 
   directories. 
   
\fi

\syn{\vb\declaresize\arg{size}\arg{fd-size-range}}
   This declares a new size, and gives the {\tt fd} commands for it.  For 
   example, {\tt 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}

\syn{\vb\declareencoding\arg{string}\arg{etx}}
   This declares which {\tt etx} file corresponds to which encoding 
   string.  For example, {\tt fontinst.sty} declares the following 
   encoding strings:
\begin{verbatim}
   \declareencoding{EXTENDED TEX FONT ENCODING - LATIN}{T1}
   \declareencoding{TEX TEXT}{OT1}
   \declareencoding{TEX TYPEWRITER TEXT}{OT1tt}
   \declareencoding{TEX MATH ITALIC}{OML}
   \declareencoding{TEX MATH SYMBOLS}{OMS}
   \declareencoding{TEX MATH EXTENSION}{OMX}
\end{verbatim}
   
\end{syntax}

\subsection{Install commands}

The {\em install commands\/} describe the fonts, glyphs and
encodings used to build fonts.  The {\em install commands\/} are:
\begin{syntax}

\syn{\vb\installfamily\arg{encoding}\arg{family}\arg{fd-commands}}
   This produces a \LaTeX\ family with the given encoding and family, for 
   example to install the Cork-encoded Times family, you say:
\begin{verbatim}
   \installfamily{T1}{ptm}{}
\end{verbatim}
   The {\em 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}

\syn{\vb\installfont\arg{font-name}\arg{file-list}\arg{etx}
   \arg{encoding}\arg{family}\arg
   {series}\arg{shape}\arg{size}} 
   This produces a \TeX\ virtual font called {\em font-name\/} from a 
   comma-separated list of {\em files\/} which should be
   {\tt.mtx}, {\tt.afm} or {\tt.pl} filenames, with an optional 
   `{\tt scaled} {\em scale}' suffix.
   Any {\tt.afm} files are also converted into {\tt.pl} files, for use
   as `raw' fonts.
   The resulting \TeX\ font is encoded using 
   {\em etx}{\tt.etx}, and can be accessed in \LaTeXe{} with the given
   {\em encoding}, {\em family}, {\em series} and {\em shape}.  The
   {\em size\/} is either declared by \vb\declaresize, or is an {\tt
   fd} size specification. For example, to install the Cork-encoded Times  
   Roman font, you say:
\begin{verbatim}
   \installfont{ptmrq}{ptmr0,latin}{T1}
      {T1}{ptm}{m}{n}{}
\end{verbatim}
   To install a \TeX~text-encoded Times Roman font with a scaled version 
   of Symbol for the Greek letters, you say:
\begin{verbatim}
   \installfont{ptmr}{ptmr0,psyr scaled 1100,latin}{OT1}
      {OT1}{ptm}{m}{n}{}
\end{verbatim}
   To install a version of {\tt cmr10} with old style digits, you say:
\begin{verbatim}
   \installfont{cmro10}{cmr10,cmmi10}{OT1o}
      {OT1}{cmr9}{m}{n}{<10> <10.95>}
\end{verbatim}
   This instruction sets the {\tt rawscale} variable used by 
   \verb|\setrawglyph|, \verb|\setnotglyph| and \verb|\setkern|.
   
\end{syntax}

\subsection{The Latin commands}

The Latin font commands are just syntactic sugar for the {\em fontinst
file\/} commands.  For example, \verb|\latinfamily{ptm}{}| is
syntactic sugar for:
\begin{verbatim}
   \transformfont{ptmro0}{\slantfont{167}{\fromafm{ptmr0}}}
   \transformfont{ptmbo0}{\slantfont{167}{\fromafm{ptmb0}}}
   \installfonts
      \installfamily{T1}{ptm}{}
      \installfamily{OT1}{ptm}{}
      \installfont{ptmrq}{ptmr0,latin}{T1}{T1}{ptm}{m}{n}{}
      \installfont{ptmr7t}{ptmr0,latin}{OT1}{OT1}{ptm}{m}{n}{}
      \installfont{ptmrcq}{ptmr0,latin}{T1c}{T1}{ptm}{m}{sc}{}
      \installfont{ptmrc7t}{ptmr0,latin}{OT1c}{OT1}{ptm}{m}{sc}{}
      \installfont{ptmriq}{ptmri0,latin}{T1}{T1}{ptm}{m}{it}{}
      \installfont{ptmri7t}{ptmri0,latin}{OT1i}{OT1}{ptm}{m}{it}{}
      \installfont{ptmroq}{ptmro0,latin}{T1}{T1}{ptm}{m}{sl}{}
      \installfont{ptmro7t}{ptmro0,latin}{OT1}{OT1}{ptm}{m}{sl}{}
      \installfont{ptmbq}{ptmb0,latin}{T1}{T1}{ptm}{b}{n}{}
      \installfont{ptmb7t}{ptmb0,latin}{OT1}{OT1}{ptm}{b}{n}{}
      \installfont{ptmbcq}{ptmb0,latin}{T1c}{T1}{ptm}{b}{sc}{}
      \installfont{ptmbc7t}{ptmb0,latin}{OT1c}{OT1}{ptm}{b}{sc}{}
      \installfont{ptmbiq}{ptmbi0,latin}{T1}{T1}{ptm}{b}{it}{}
      \installfont{ptmbi7t}{ptmbi0,latin}{OT1i}{OT1}{ptm}{b}{it}{}
      \installfont{ptmboq}{ptmbo0,latin}{T1}{T1}{ptm}{b}{sl}{}
      \installfont{ptmbo7t}{ptmbo0,latin}{OT1}{OT1}{ptm}{b}{sl}{}
   \endinstallfonts
\end{verbatim}

\section{Encoding files}

An {\em encoding file\/} (or {\tt.etx} file) is a \TeX\ document consisting of:
\begin{syntax}

\syn{\vb\relax\\{\em ignored material}\\\vb\encoding\\
   {\em encoding commands}\\\vb\endencoding\\{\em ignored material}}
   This describes the encoding of a font, using the {\em encoding
   commands}.

\end{syntax}
Since the encoding file ignores any material between \vb\relax\ and
\vb\encoding, an {\em encoding file\/} can also be a \LaTeX\ document,
for example:
\begin{verbatim}
\documentstyle[fontdoc]{article}
\begin{document}
This is an encoding.
\encoding ... \endencoding
That's all.
\end{document}
\end{verbatim}

\subsection{Encoding commands}

The {\em encoding commands\/} are:
\begin{syntax}

\syn{\vb\nextslot\arg{number}}
   Sets the number of the next slot.  If there is no \vb\nextslot\ 
   command, the number is the successor of the previous slot.  
   
\syn{\vb\setslot\arg{glyph}\\{\em slot commands}\\\vb\endsetslot}
   Sets the slot of the {\em glyph}.  The {\em slot commands\/} describe 
   the glyph, and give its usage in \TeX.

\syn{\vb\inputetx\arg{file}}
   Inputs the {\em encoding commands\/} of {\em file}{\tt .etx}.
   
\end{syntax}

\subsection{Encoding variables}

The {\em encoding files\/} may set the following integer variables:
\begin{syntax}

\syn{\tt boundarychar}
   The slot of the boundary character.
   
\syn{\tt fontdimen({\em n})}
   The value of the $n$th font dimension.
   
\syn{\tt letterspacing} The extra space to be added between every glyph.

\end{syntax}
In addition, they will set an integer variable for each slot in the 
encoding.  The slot number for {\em glyph\/} is \vb\int\arg{glyph}.

The {\em encoding files\/} may set the following string variables:
\begin{syntax}

\syn{\tt codingscheme}
   The font coding scheme.

\end{syntax}

\subsection{Slot commands}

The {\em slot commands\/} are:
\begin{syntax}

\syn{\vb\usedas\arg{type}\arg{control sequence}}
   Sets the \TeX\ control sequence for this slot, with the {\em type\/} 
   taken from:
\begin{verbatim}
   char       accent     mathord  
   mathbin    mathrel    mathopen 
   mathclose  mathpunct  mathvariable
   mathaccent mathdelim
\end{verbatim}

\syn{\vb\nextlarger\arg{glyph}}
   Sets a {\sc nextlarger} entry from the current slot to the {\em 
   glyph}. 
   
\syn{\vb\varchar\\{\em varchar commands}\\\vb\endvarchar}
   Sets a {\sc varchar} entry for the current slot, using the {\em 
   varchar commands}.

\end{syntax}

\subsection{Varchar commands}

The {\em varchar commands\/} are:
\begin{syntax}

\syn{\vb\vartop\arg{glyph}}
   Sets the top {\em glyph\/} of the {\sc varchar}.

\syn{\vb\varmid\arg{glyph}}
   Sets the middle {\em glyph\/} of the {\sc varchar}.

\syn{\vb\varbot\arg{glyph}}
   Sets the bottom {\em glyph\/} of the {\sc varchar}.

\syn{\vb\varrep\arg{glyph}}
   Sets the repeated {\em glyph\/} of the {\sc varchar}.

\end{syntax}

\section{Metric files}

A {\em metric file\/} (or {\tt.mtx} file) is a \TeX\ document consisting of:
\begin{syntax}

\syn{\vb\relax\\{\em ignored material}\\\vb\metrics\\
   {\em metric commands}\\\vb\endmetrics\\{\em ignored material}}
   This describes the glyphs in a font, using the {\em metric 
   commands}.

\end{syntax}

\subsection{Metric commands}

The {\em metric commands\/} are:
\begin{syntax}

\syn{\vb\setglyph\arg{name} \\
{\em glyph commands\/} \\
\vb\endsetglyph}
   If the glyph called {\em name\/} is undefined, it is built using the 
   {\em glyph commands\/} given below, for example:
\begin{verbatim}
\setglyph{IJ}
   \glyph{I}{1000}
   \glyph{J}{1000}
\endsetglyph
\setglyph{Asmall}
   \glyph{A}{700}
\endsetglyph
\end{verbatim}

\syn{\vb\resetglyph\arg{name} \\
{\em glyph commands\/} \\
\vb\endsetglyph}
   Gives the definition of the glyph called {\em name\/} using the
   {\em glyph commands}.

\syn{\vb\unsetglyph\arg{name}}
   Makes the glyph called {\em name\/} undefined.

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

\syn{\vb\setnotglyph\arg{name}\arg{font}\arg{dimen}\\
   \arg{integer}\arg{integer}\arg{integer}\arg{integer}}
   This sets a glyph called {\em name\/}{\tt-not}, which is present in 
   the font, but is not in the default encoding.  It takes the same 
   arguments as \vb\setrawglyph{}, although the slot will normally be $-1$.
   This command will usually be generated automatically from an {\tt afm} 
   file.

\syn{\vb\setkern\arg{glyph}\arg{glyph}\arg{integer expression}}
   Sets a kern between the two glyphs, scaled by the current value of 
   {\tt rawscale}, if it has been set.

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

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

\syn{\vb\inputmtx\arg{file}}
   Inputs the {\em metric commands\/} of {\em file}{\tt .mtx}.
   
\end{syntax}    

\subsection{Metric variables}

The {\em metrics files\/} may set the following integer variables:
\begin{syntax}

\syn{\tt ascender}  The height of the tallest lower-case letter.

\syn{\tt capheight}  The height of the tallest capital letter.

\syn{\tt descender}  The depth of the lowest lower-case letter.

\syn{\tt italicslant} The ratio of the italic slant, given in units of 
   rightward movement for each 1000 units of upward movement.

\syn{\tt minimumkern}  Any kern smaller than this amount is ignored.  

\syn{\tt monowidth} This variable is set if the font is monowidth.

\syn{\tt underlinethickness} The width of the underline rule.

\syn{\tt xheight} The x-height.

\syn{{\em glyph\/}{\tt -spacing}} The letter spacing for the {\em glyph}.

\end{syntax}
The {\em metrics files\/} may set the following dimension variables:
\begin{syntax}

\syn{\tt designsize}  The design size of the font.

\end{syntax}

\subsection{Glyph commands}

The {\em glyph commands\/} are:
\begin{syntax}

\syn{\vb\glyph\arg{glyph}\arg{integer expression}}
   Sets the named 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}

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

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

\syn{\vb\glyphwarning\arg{text}}
   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}
\endsetglyph
\end{verbatim}

\syn{\vb\movert\arg{integer expression}}
   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}
\setendglyph
\end{verbatim}

\syn{\vb\moveup\arg{integer expression}}
   Moves up by the given amount, and advances the current vertical
   offset.  Each glyph should always end with 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}

\syn{\vb\push\\
{\em glyph commands\/}\\
\vb\pop}
   Performs the {\em 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}

\syn{\vb\glyphpcc\arg{glyph}\arg{integer expression}\arg{integer 
   expression}}
   This is syntactic sugar for:
\begin{quote}
   \vb\push \\
   \vb\movert\arg{first integer expression} \\
   \vb\moveup\arg{second integer expression} \\
   \vb\glyph\arg{glyph}\verb|{1000}| \\
   \vb\pop
\end{quote}
   
\syn{\vb\resetwidth\arg{integer expression}}
   Sets the width of the current glyph.
   
\syn{\vb\resetheight\arg{integer expression}}
   Sets the height of the current glyph.
   
\syn{\vb\resetdepth\arg{integer expression}}
   Sets the depth of the current glyph.
   
\syn{\vb\resetitalic\arg{integer expression}}
   Sets the italic correction of the current glyph.
   
\syn{\vb\samesize\arg{glyph}}
   Sets the dimensions of the current glyph to be the same as {\em glyph}. 
   
\end{syntax}
Inside the definition of {\em glyph}, you can use expressions 
such as \vb\width\arg{glyph}, which will refer to the glyph defined so 
far.  For example, a display summation can be defined to be a text 
summation $\sum$ scaled 120\% with 0.5pt extra height and depth using:
\begin{verbatim}
\setglyph{sumdisplay}
   \glyph{textsum}{1200}
   \resetheight{\add{\height{sumdisplay}}{50}}
   \resetdepth{\add{\depth{sumdisplay}}{50}}
\endsetglyph
\end{verbatim}
Within a \vb\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}

There is still a bit of work to do on {\tt fontinst}:
\begin{itemize}

\item Use the package to install more fonts!  This is the most important 
   work to do.
   
\item Add other filters, so that fonts with metrics in formats other than 
   {\tt pl} and {\tt afm} can be read.
   
\item Add the ability to generate \LaTeXe{} packages from {\tt etx} files.

\item Add a way to use Alternate sets.

\end{itemize}
If you have any comments on {\tt fontinst}, or if you have some fonts you 
would like to contribute to the {\tt contrib} directory, please drop me 
a line.

\section*{Acknowledgements}

I'd like to thank all of the {\tt fontinst} $\alpha$-testers,
especially Karl Berry, Damian Cugley, Yannis Haralambous, Alan Hoenig,
Rob Hutchings, Paul Thompson and Norman Walsh, 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 David Carlisle for the use of his {\tt trig} macros for 
calculating trignometry.

\section*{Legal rubbish}

The {\tt fontinst} package is copyright \copyright~1993--1994 Alan 
Jeffrey.  The {\tt trig} macro package is coyright \copyright~1993 David 
Carlisle.  Unless indicated otherwise, the contents of the {\tt contrib} 
directory are \copyright~1994 the individual authors.  All rights 
reserved.  The moral right of the authors has been asserted.

There is no warranty for the {\tt 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. 

You are {\em not allowed\/} to take money for the distribution or use of
these files except for a nominal charge for copying, etc.

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

If you receive only some of these files from someone, complain!

\end{document}