\documentstyle[a4]{article}

\newfont{\mflogo}{logo10}

\newcommand{\DVIview}{{\tt DVIview}}
\newcommand{\TeXFonts}{{\tt \TeX Fonts}}
\newcommand{\BaKoMa}{{BaKoMa}}
\newcommand{\version}{3.01}
\newcommand{\dvi}{{\tt dvi}}
\newcommand{\vf}{{\tt vf}}
\newcommand{\vp}{{\tt vp}}
\newcommand{\tfm}{{\tt tfm}}
\newcommand{\pk}{{\tt pk}}
\newcommand{\mf}{{\tt mf}}
\newcommand{\metafont}{{\mflogo METAFONT}}
\newcommand{\fname}{\tt}
\newcommand{\fnt}{\tt}

% Usage: \diagram{width}{height}{filename [options]}
% Loads diagram from 'Diagrams' directory
\newcommand{\diagram}[3]{\makebox[#1][l]{\rule[-#2]{0mm}{#2}\special{DVIview_diagram @.Diagrams.#3}}}


\title{\TeXFonts}
\author{by\\
\\
Paul Field\\
\\
Documentation for\\
\TeXFonts\ version \version}

\begin{document}
\maketitle


\noindent
\TeXFonts\ is the repository for the various font files needed
by \TeX, \LaTeX\ and related programs such as \DVIview.

This document explains how to find out what fonts you have installed
and explains why there are so many fonts. It also explains, for advanced
users, how to create your own font packages.


\section{What fonts have I got?\label{sec:what_fonts}}
\TeXFonts\ is made up of a number of {\em font packages}. These
make it easy for you to add and remove sets of fonts, and to upgrade fonts.

To see what font packages you have, double-click on the \TeXFonts\ icon.
A directory viewer will open showing the standard \TeXFonts\ packages
and {\fname 3rdParty} and {\fname User} directories.

The {\fname 3rdParty} directory will contain any font packages that are
not part of the standard \TeXFonts\ distribution.

The {\fname User} directory contains your own fonts; section \ref{sec:user}
explains how to add your own fonts in more detail.

Each font package is an application. It should have a !Help file to
explain the fonts it contains and any restrictions on their use.
Double-clicking on the package will (usually) open a directory viewer
showing the fonts in the package.


\section{Why so many fonts?}
If you look in, say, the \BaKoMa\ font package you will see at least 50 fonts
(unless you have the minimal installation).
Many of them have the same name but end in a different number. For example,
{\fnt cmr17}, {\fnt cmr12} and {\fnt cmr6}. \TeX\ and \LaTeX\ have {\em type
styles\/} and fonts are these styles at particular point sizes. For example,
{\fnt cmr} is the type style and {\fnt cmr10} is the {\fnt cmr} style
at 10pt. RISC OS has a single font for each type style, which is
scaled to the appropriate size. Why does \TeX\ use all these different fonts?

Many people believe that fonts should look slightly
different at different font sizes and that scaling isn't enough (although the
RISC OS font system does something cleverer than simple scaling).
For example, here are {\fnt cmr17} and {\fnt cmr6} both shown at 17pt
\footnote{If you only have a partial installation of the \BaKoMa\ fonts
then \DVIview\ may be substituting other fonts for {\fnt cmr17} and {\fnt
cmr6} :-) }:

\newfont{\demobig}{cmr17}
\newfont{\demosmall}{cmr6 at 17pt}

{\setlength{\baselineskip}{17pt}
{\demobig Here is some 17pt text in cmr17}

{\demosmall Here is some 17pt text in cmr6}
}

As you can see, {\fnt cmr17}, which is designed to be used at 17pt, has
thinner characters and appears lighter than {\fnt cmr6}.



\section{Adding your own fonts\label{sec:user}}
If you want to add some fonts for your own personal use then you should
add them to one of the user font packages provided by \TeXFonts.

The user font packages are in \TeXFonts' {\fname User} directory;
there are two packages:

\begin{description}
\item[URiscOS] is intended for fonts that include RISC OS
font files.
\item[UOthers] is intended for fonts that {\em do not\/} include RISC OS
font files.
\end{description}

Double-clicking on the font package icon will open a directory into which
you can place your fonts.



\section{Letting the system know about new fonts and font packages}
In \TeXFonts' packages directory there is a file called {\fname !!Update}.
Double-clicking on this causes \TeXFonts\ to rescan all its packages
and so bring the list of fonts up-to-date.



\section{Creating a font package}
To create a font package you need to make a new application directory
inside the {\fname 3rdParty} directory and create an {\fname !Install}
file inside it. It is strongly recommended
that you also provide a {\fname !Help} file and a {\fname !Run} file, which
should open the directory (or directories) containing the fonts. You may
also provide other application files (such as {\fname !Boot} and
{\fname !Sprites}).

There are also various {\em package files} that you might also include
in your directory. These are discussed below.


\subsection{The {\fname !Install} file\label{sec:install}}

The {\fname !Install} file is run by \TeXFonts\ to install the package's
fonts and set up any other package-specific environmental variables
or resources.

{\fname !Install} should add the package's font directory to the
{\verb=TeXFonts$Path=} variable and the package directory
to the {\verb=TeXFontsPackages$Path=} variable.
If the package contains RISC OS font files, the {\fname !Install} file
will also use the {\tt FontInstall} command to add the font
directory to {\verb=Font$Path=}.

These path variables are limited in length and so your package
should try to keep short what it adds to the paths. To do this,
your {\fname !Install} file should declare a path variable for
the package and then use that to declare the fonts. For
example (taken from {\fname !URiscOS.!Install}):
\begin{verbatim}
Set URiscOS$Path <Obey$Dir>.

TeXFontsUtils:AddToPath TeXFonts$Path         URiscOS:TeX.
TeXFontsUtils:AddToPath TeXFontsPackages$Path URiscOS:
FontInstall URiscOS:
\end{verbatim}
Notice that you should use the utility {\fname TeXFontsUtils:AddToPath}
to add items to paths; it will correctly place commas between
items.

You should also remember that \DVIview\ requires \TeX\ fonts with RISC OS
font files to appear in a directory called {\fname TeX}.

If you want to split your package into sub-directories then look at
the \BaKoMa\ package to see how to install it.


\subsection{Package files}

There are several package files that provide general information about the
fonts in your package. Applications will find these files by searching
the directories in the {\verb=TeXFontsPackages$Path=} variable.

The currently-defined package files are described in the following subsections.


\subsubsection{The {\fname Summary} file\label{sec:summary}}

The package file {\fname Summary} provides a summary of information about all
the fonts in the package. Its main purpose is to provide information about
fonts when the package is {\em partially installed}. In other words, if, for
example, {\fnt cmr12} hasn't been installed, there is enough information in
the summary file for a program like \DVIview to replace it with, say, {\fnt
cmr10}.

\TeXFonts\ provides a facility for automatically producing summary files.
Set the current directory to your package directory and type:
\begin{verbatim}
TeXFontsUtils:Summarise @ Summary
\end{verbatim}


\subsubsection{The {\fname RO\_Render} file}

The package file {\fname RO\_Render} provides a mapping between fonts and
the RISC OS fonts that should be used to render them. Its primary use is for
virtual fonts.

The format of the file is a sequence of lines of the form:
\begin{quote}
{\em $<$\TeX\ font name$>$ $<$RISC OS font name$>$}
\end{quote}


For example:
\begin{verbatim}
rphvr Homerton.Medium
rpcrb Corpus.Bold
rpcrr Corpus.Medium
rpsyr Symbol
rptmr Trinity.Medium
\end{verbatim}


\section{Font messages}
If your package contains RISC OS outline fonts, you may wish to include
a font message file so that the font manager doesn't spend time scanning
your package for fonts. However, if you allow partial installation of your
fonts, you must be careful that the message file reflects the fonts that are
actually installed.

Probably the simplest approach to this problem is to place each part of
the partial installation into separate sub-directories in your package.
Then you can provide a message file for each sub-directory.
Unfortunately, this approach will lead to longer path variables
(see section \ref{sec:install}).



\section{Distributing a font package}
If your font package is large you may wish to break it up into a 
number of different archives so that people do not need to download
and store files they do not need. There are two ways of breaking
up a package.

\subsection{Partial installation}
A package is {\em partially installed} if only some of its fonts
have been installed. For example, the \BaKoMa\ package provides
a core archive with one member of each font family (e.g. {\fnt cmr10}).
Other archives contain other members of the family (e.g. {\fnt cmr6} and
{\fnt cmr12}). As long as the summary file for the entire package
(see section \ref{sec:summary}) is present in the core archive, programs
like \DVIview\ can do a good job of emulating the missing fonts.

Obviously, you can provide archives suitable for partial installation
simply by copying fonts into different archives.


\subsection{Font splitting}
Each font is made of a number of files, such as \mf\ and \tfm. Not
all users need all files, so you can split the package by providing
certain font files in different archives.

For example, the \BaKoMa\ package separates the \mf\ files and the {\fname
Type1} files into separate archives; people without Postscript printers do
not need the {\fname Type1} files and many \DVIview\ users work without needing
\mf\ files.

\TeXFonts\ provides a utility for splitting your package into
parts containing particular files. Assuming your package is in the
current directory, you could separate out the \mf\ files using this command:
\begin{verbatim}
TeXFontsUtils:Extract !Package mfsplit mf
\end{verbatim}
The first parameter is the name of your package directory (or a
sub-directory, if you like). The second parameter is the name of the
directory you would like the extracted files placed into (the directory
is created for you). The final parameter is the name of the files
you want to extract.

The command copies the directory structure from the package directory
you give it and moves any file called {\fname mf} to the copied structure.


\subsection{A naming convention}
You can allow partial installation and apply font splitting together.
To try to minimise confusion when someone is trying to select which
archives to install, it is recommended that you use the following
naming convention:
\begin{quote}
{\em $<$Package id$>$$<$Installation level$>$$<$Split type$>$}
\end{quote}

\begin{description}

\item [\em{$<$Package id$>$}] is a code identifying your package.

\item [\em{$<$Installation level$>$}] is a digit indicating the level of
installation. Level 1 should contain the ``core'' fonts, with higher levels
containing other sizes in the font families or, perhaps, more unusual fonts.

\item [\em{$<$Split type$>$}] identifies the font files in the archive.

\end {description}

Here's an example. The \BaKoMa\ archives are named like this:
\begin{description}
\item [BaK1core] contains the core font files for {\fnt cmr10}.
\item [Bak1mf] contains the \mf\ file for {\fnt cmr10}.
\item [Bak1ps] contains the {\fname Type1} file for {\fnt cmr10}.
\item [Bak1ro] contains the RISC OS font files for {\fnt cmr10}.

\item [Bak2core] contains the core font files for {\fnt cmr6} and {\fnt
cmr17}.
\item [Bak2mf] contains the \mf\ files for {\fnt cmr6} and {\fnt
cmr17}.
\item [Bak2ps] contains the {\fname Type1} files for {\fnt cmr6} and {\fnt
cmr17}.
\item [Bak1ro] contains the RISC OS font files for {\fnt cmr6} and {\fnt
cmr17}.

\end{description}




\section{Versions (from 3.00)}
\begin{description}
\item[3.01]
 \begin{itemize}
   \item Recompiled to be 26/32-bit neutral.
 \end{itemize}
\item[3.00]
 \begin{itemize}
   \item Support for font packages.
   \item User font packages provided.
   \item Detailed documentation provided.
   \item Comes with new \BaKoMa\ font package.
 \end{itemize}

\end{description}



\section{Copying and altering !TeXFonts}
Please refer to individual font packages for conditions of their use
and distribution.


You may freely distribute \TeXFonts\ provided that:
\begin{enumerate}
 \item No charge is made for it.
 \item It is not distributed as a `freebie' with commercial software.
 \item No changes are made to it (i.e. no files are added, deleted or
modified).
\end{enumerate}

You must not distribute programs that modify \TeXFonts\ in any way except
to add font packages to the {\fname 3rdParty} directory. If you need
\TeXFonts\ to be changed for some reason, please ask
\footnote{This clause is only to protect you from changes I make to
\TeXFonts. If you alter it, especially the {\fname !Boot} file, and I don't
know what you've done then I may well make incompatible changes in a
future release. To make life easy, simply tell me what changes you
need made and I'll accommodate you}.

You may not change \TeXFonts\ but you can distribute font packages
as separate items, provided that your installation system (program or
instructions to the user) installs the package in the {\fname 3rdParty}
directory (you may create sub-directories in the {\fname 3rdParty}
directory).



\section{Contacting the author}
My email address is: {\tt dviview@cloudinthesky.co.uk}\\
I can also be contacted at:\\
346 Chadwell Heath Lane\\
Chadwell Heath\\
Romford\\
Essex\\
RM6 4YH\\
UK\\
Telephone (from the UK): 0181 598 9676\\
Telephone (non-UK): +44 181 598 9676

\section{Current maintenance}

Paul Field has generously agreed to allow the distribution of this new
26/32-bit neural version of TeXFonts. Although all credit for TeXFonts goes
to Paul, any errors or bugs may have occured as a result of my recompilation
of the source code.

Therefore, whilst all thanks should be sent to Paul, for bugs and current
maintenance of the program, please contact me. \\
\\
David Llewellyn-Jones: {\tt david@flypig.co.uk} \\
\\
TeXFonts is available from: {\tt http://www.flypig.co.uk/armtex.htm}


%\section{What is a font?}
%In each font directory you'll find a number of files. This section
%briefly explains what the files are and when you need them.

%\begin{description}
%\item[\tfm] tfm stands for \TeX\ font metric. These files contain
%information about the size of characters in the font, kerning information
%and so on. They are needed by \TeX\ and any program that processes
%\dvi\ files (e.g. \DVIview).

%\item[\mf] These are \metafont\ files, containing all the information needed
%to produce the \TeX\ font files (e.g. \tfm\ and \pk\ files).


\end{document}
