diff options
Diffstat (limited to 'Master/texmf-dist/doc/fonts/fontinst/manual/fontinst.tex')
-rw-r--r-- | Master/texmf-dist/doc/fonts/fontinst/manual/fontinst.tex | 4680 |
1 files changed, 4680 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/fonts/fontinst/manual/fontinst.tex b/Master/texmf-dist/doc/fonts/fontinst/manual/fontinst.tex new file mode 100644 index 00000000000..a66b89054c5 --- /dev/null +++ b/Master/texmf-dist/doc/fonts/fontinst/manual/fontinst.tex @@ -0,0 +1,4680 @@ +%%% ==================================================================== +%%% @LaTeX-file{ +%%% author = "Alan Jeffrey and Rowland McDonnell and +%%% Ulrik Vieth and Lars Hellstr{\"o}m", +%%% version = "1.928", +%%% date = "2007-09-06", +%%% time = "11:22:41 +02:00", +%%% filename = "fontinst.tex", +%%% email = "fontinst@tug.org", +%%% checksum = "", +%%% 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 +% Modified by Lars Hellstr\"om July 2004 and later + + + +\documentclass[a4paper]{ltxguide} +\usepackage[OT1]{fontenc} +\usepackage{url,xspace} +\usepackage{graphicx} + +\IfFileExists{palatino.flag}{ + \renewcommand\rmdefault{ppl} +} +%\renewcommand\rmdefault{padx} +%\renewcommand\rmdefault{pmnx} + +% \MakeShortVerb{\|} + + +% 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{% + \def\and{\egroup\qquad\hbox\bgroup} + \leavevmode \hbox{\@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@ +} +\newenvironment{isyntax}{% + \let\\\@centercr + \list{}{% + \itemsep \z@ + \itemindent -1.5em% + \listparindent \itemindent + \advance \leftmargin 1.5em% + }% + \advance \rightskip \z@\@plus0.7\linewidth \relax + \linepenalty=100\relax + \item\relax +}{\endlist} +\makeatother + +\newenvironment{smalldes}{% + \list{}{% + \setlength\labelwidth{0pt}% + \setlength\itemindent{-\leftmargin}% + \setlength\listparindent{1em}% + \setlength\parsep{0pt}% + \setlength\itemsep{0pt plus 1pt}% + \setlength\topsep{\itemsep}% + \let\makelabel\descriptionlabel + }% +}{\endlist} + +\newenvironment{hackernote}{% + \list{}{ + \setlength{\leftmargin}{0pt}% + \setlength\labelwidth{0pt}% + \setlength{\listparindent}{1.4em}% + \setlength{\parsep}{0pt plus 1pt}% + \setlength{\itemsep}{\medskipamount}% + }\item[]% + \small + \textit{Note for hackers.}\hspace{0.5em}% +}{\endlist} + +% % I don't use the <...> feature for verbatim, +% % so I undo that ltxguide feature. +% \makeatletter +% \renewcommand{\verbatim@font}{% +% \normalfont \ttfamily +% % \catcode`\<=\active +% % \catcode`\>=\active +% } +% \makeatother + + +% ltxguide.cls decl environment, but with equal space above and +% below. +\DeleteShortVerb{\|} +\makeatletter +\newenvironment{decl*}[1][]{% + \par + \small + \addvspace{2.3ex}% + \vskip -\parskip + \ifx\relax#1\relax + \def\@decl@date{}% + \else + \def\@decl@date{\NEWfeature{#1}}% + \fi + \noindent\hspace{-\leftmargini}% + \begin{tabular}{|l|}% + \hline\ignorespaces +}{% + \\\hline + \end{tabular}% + \nobreak\@decl@date\par\nobreak + \vspace{2.3ex}\vskip -\parskip +} +\makeatother +\MakeShortVerb{\|} + + +% Set spacing around captions. + +\setlength{\abovecaptionskip}{\medskipamount} +\setlength{\belowcaptionskip}{\medskipamount} + +% Markup for logos, file types, programs, etc. + +\newcommand*{\meta}{\m} +\newcommand*{\marg}{\arg} +\newcommand*{\parg}[1]{\texttt{(}\m{#1}\texttt{)}} + +\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} + +\makeatletter +\newcommand{\La}{% + L\kern-.36em + {% + \setbox0\hbox{T}% + \vbox to\ht0{\hbox{% + $\m@th$\csname S@\f@size\endcsname + \fontsize\sf@size\z@\math@fontsfalse\selectfont + A% + }\vss}% + }% +} +\makeatother +\DeclareRobustCommand\AllTeX{(\La\kern-.075em)\kern-.075em\TeX} + +\newcommand{\PS}{Post\-Script\xspace} +\newcommand{\TT}{True\-Type\xspace} + +\newcommand*{\setfilename}[1]{\texttt{#1}} +\newcommand*{\setdotfilename}[1]{\setfilename{.#1}} +\newcommand*{\setpackagename}[1]{\textsf{#1}} + +\newcommand{\dvips} {\setpackagename{dvips}\xspace} +\newcommand{\Dvips} {\setpackagename{Dvips}\xspace} +\newcommand{\fontinst}{\setpackagename{font\-inst}\xspace} +\newcommand{\Fontinst}{\setpackagename{Font\-inst}\xspace} +\newcommand{\fontdoc}{\setpackagename{font\-doc}\xspace} +\newcommand{\Fontdoc}{\setpackagename{Font\-doc}\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{\cvpl}{(\setfilename{v})\setfilename{pl}\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{\enc}{\setfilename{enc}\xspace} +\newcommand{\Enc}{\setfilename{Enc}\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{\pdf}{\setfilename{pdf}\xspace} +\newcommand{\Pdf}{\setfilename{Pdf}\xspace} +\newcommand{\ttf}{\setfilename{ttf}\xspace} +\newcommand{\Ttf}{\setfilename{Ttf}\xspace} +\newcommand{\map}{\setfilename{map}\xspace} +\newcommand{\Map}{\setfilename{Map}\xspace} + + +\newcommand{\vftovp}{\setpackagename{vftovp}\xspace} +\newcommand{\vptovf}{\setpackagename{vptovf}\xspace} +\newcommand{\pltotf}{\setpackagename{pltotf}\xspace} +\newcommand{\tftopl}{\setpackagename{tftopl}\xspace} + +\newcommand{\BibTeX}{Bib\TeX} + + + + +\title{fontinst} +\subtitle{Font installation software for \TeX} +\author{Alan Jeffrey\and Rowland McDonnell\and Lars Hellstr\"om} +\illustration{roadmap.eps} +\version{1.9} +\date{August 2009} + +\begin{document} + +\maketitle + + +% \begin{itshape} +% This manual is currently being rewritten, and may therefore be a +% bit disorganised. For authoritative information on command syntaxes +% and the like, see the Literate Programming sources for +% \fontinst. The main file there is \textsl{\texttt{fisource.tex}}. +% \end{itshape} +% +% \bigskip + +\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@tug.org}. The mail will be sent to the + \texttt{fontinst} mailing list. If you would like to be on the + \texttt{fontinst} mailing list, see + \url{http://tug.org/mailman/listinfo/fontinst}. +\end{footnotesize} + +\tableofcontents + +% \vfill + +\clearpage + + +\section{Introduction} + +The purpose of \fontinst is to make digital fonts, as they may +be bought from a foundry or other supplier, usable with \AllTeX; +in general, they are not directly so. An obvious problem can be +that the font information is not available in a format that \TeX\ +understands. A more subtle problem is that the fonts are often +organised in a way that is unsuitable for automatic typesetting. +It is furthermore necessary to inform \AllTeX\ and related software +about the existence of the new font, and the pieces of code needed +to do this are somewhat exotic. + +Regarding the first problem, \fontinst can bridge the gap between +non-\TeX\ and \TeX-specific file formats, but may need some help from +other tools (\setfilename{pltotf}, \setfilename{vptovf}, +\setfilename{ttf2afm}, etc.) with conversions between text and binary +file formats. Regarding the last problem, \fontinst can generate the +necessary code, although you may in some cases need to paste it into +the right configuration file yourself. It is however with respect to +the second problem that \fontinst shines, as the many minutiae of +providing fonts for \AllTeX\ are automated to a very high degree, +while still providing you as user with the power to fine-tune every +detail of the output. In addition, \fontinst is available for every +platform that has \TeX. + +The reason \fontinst is so portable is simply that it is written in +\TeX, exploiting those features of the language which does other +things than typesetting. A drawback of this is the inability to work +directly with binary file formats, but an advantage is that users +do not need to learn a separate command language before they can +configure the tool; \fontinst only introduces a set of new \TeX\ +commands, not a new set of syntax rules. Moreover, many encoding and +metric files used with \fontinst can also be typeset as \LaTeX\ +documents, yielding a rendering of their contents which might be more +pleasing to the eye than the raw code. + +The main thing \fontinst does is creating virtual fonts (\vf's). For +this, it takes the approach that the world is full of glyphs, and a +subset of these are to be picked, perhaps tweaked, and finally wrapped +up as a new font for \TeX\ to use. In the basic case where one merely +wants to make a specific foundry-supplied font available to \TeX, what +one does is to present only that font as glyphbase for \fontinst, since +this means all glyphs in the resulting virtual font will come from that +base font, only reorganised to meet the requirements of \AllTeX. It is +however not uncommon to use several base fonts for forming a single +glyphbase, maybe because the foundry has arbitrarily decided to divide +the basic font up into separate ``base'', ``expert'', and ``alternate'' +varieties that don't match the needs of \TeX, or maybe because the +foundry did not provide all the glyphs of standard \TeX\ fonts and glyphs +from some other font family are used to fill in the gaps. Either way, +since it's you that's doing the packaging, it is you that gets to say +what goes into the package. + +In the process of creating some virtual fonts, many minor pieces of +data are encounted that would be needed when informing \AllTeX\ and +related software about these new fonts. +\Fontinst records this information and provides for writing finished +files in the most common formats, notably \LaTeX\ \fd files and +\dvips \map files. One can even ask \fontinst to have certain +transformations performed on the base fonts, to extend or tweak the +repertoire of glyph shapes that are available. + + +\subsection{Overview of the process} + +If you're using \fontinst, the usual steps you need to take to use +an ordinary \PS latin text font with \LaTeX\ are these: +\marginpar{Related commands:} +\begin{enumerate} +\item \label{WhatToDoList:1} + Gather \afm files for the base fonts you want to make use of, and + (optionally) give the \afm files appropriate names. +\item \label{WhatToDoList:2} + Use \fontinst\marginpar{\cs{transformfont}} to produce \texttt{8r} + encoded \pl files from these \afm files. +\item \label{WhatToDoList:3} + Use \fontinst\marginpar{\cs{installfont}} to create T1 and OT1 + encoded \pl and \vpl files from the |8r| encoded \pl files (this + procedure will also create suitable \fd files). +\item \label{WhatToDoList:4} + Use \fontinst (its \setfilename{finstmsc.sty}\marginpar{ + \cs{adddriver}} variety) to generate the mapfile entries needed + for the above. +\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 (typically involves + editing some configuration file or files, possibly also running + some helper command to update cached configuration information). +\item + Test it. (The \LaTeX\ command \cs{usefont} lets you select a font + by encoding, family, series, and shape. The Plain\TeX\ file + \setfilename{testfont.tex} provides an easy way of producing font + tables.) +\item + Perhaps write a package file to make selecting the new font + a little easier. +\end{enumerate} + +The \setfilename{examples\slash basic\slash basicex.tex} file +contains examples of doing \ref{WhatToDoList:2} +and~\ref{WhatToDoList:3}; in many cases, it is possible to use the +|\latinfamily| command to do all of this. +The \setfilename{examples\slash basic\slash basicex2.tex} file +contains examples of doing \ref{WhatToDoList:4}. + + +\section{Defining terms} + +The process of making fonts usable involves some rather technical +issues, so in order to understand a discussion of what is going on, +it is necessary to first get the terminology straight. Feel free to +skip parts of this if you think you already know the material covered +or for the moment want to concentrate on other aspects of what +\fontinst does, but bear in mind that you may then have reason to return +to this section at a later time. + +% 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, we 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 \LaTeX\ 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' and have icons that look like a +laser printer. The information in all these formats is basically +the same: the only difference is in its representation. \pfa +stands for `printer font ASCII', while \pfb stands for `printer +font binary'. \pfa files are pure \PS code (though in parts highly +convoluted) and can typically be pasted into or copied from \PS +documents using a text editor if one feels like hacking. Since \pfa +files contain a large chunk of hex-encoded binary data, they are +however about twice the size of the equivalent \pfb, where text and +binary data reside in separate sections of an overall binary file +format. + +% 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. +(Pdf\TeX\ is different from \TeX\ in this respect; since pdf\TeX\ +integrates most of the functionality of a \dvi driver, it may be unable +to generate working \pdf output if the some Type~1 printer font file +is not available.) + +\Dvi drivers generating \pdf often require Type~1 fonts to be in \pfb +format, as that is very close to how the data is stored in a \pdf +file. + + +\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 \dvi drivers that use the windowing system +for rendering text. +% They are kept in font suitcase files on Macintoshes. +%\marginnote{And where on other computers?} + +Technically, \pk files are also bitmap font files, for use on screen +or with a printer, but \TeX\ systems tend to be set up so that \pk +files are generated automatically when needed. (Of course, this +requires that the font is first available in some other format, +usually \mf or \pfb.) + + +\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 from an \afm file create the +necessary \tfm and \vf files (well, really \pl and \vpl files, but +see below) 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{\TT and OpenType font files} + +The \TT format was created as an Apple--Microsoft collaboration to +avoid being dependent on Adobe's font technologies. Later Adobe and +Microsoft went on to define the OpenType format, which is a +development of \TT. However, the three don't always agree on the +fine details of the format. + +A \TT font file is a collection of rather disparate tables, and can +therefore contain scalable outline fonts (like \PS~type~1), bitmap +screen fonts, and font metrics all in one file; for software with +direct support for \TT this tends to simplify font installation, but +for \TeX\ it rather adds a level of complication. An advantage for +\TeX\ use is that the suppliers provide font metrics in a +cross-platform format (as opposed to rather obscure platform-specific +formats, which could previously be the norm), but they still have to +undergo conversion before we can use them. \TT is furthermore a +``there is more than one way to do it'' format, so it sometimes +happens that information which is present in the font is ignored by +some programs because that information happened to be in an unusal +format\dots + +Classical \TT fonts have outlines defined in terms of quadratic +Bezier curves. The main addition in the OpenType specification was a +second outline format (CFF\slash type~2) which uses cubic Bezier +curves. Both outline formats are directly supported in \pdf and can +(even if the driver doesn't have built-in support for the format) +with a thin wrapper be used in \PS, but there is also a tradition of +rather converting to type~1 before using such fonts with \TeX; the +latter leads to a slight drop in quality. + + + + +\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 \emph{are} +fonts, even though they contain no information about the shape of +letters, and are rarely needed by anything except \TeX. (\Dvi drivers +generally read \tfm files so that they can keep track of exact glyph +widths and fine-tune positioning accordingly, but they would get by +fairly well with only the information in the printer fonts.) + + +\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, which are standard utilities in a \TeX\ system. + + +\subsubsection{Virtual font files (\vf files)} + +These are binary data files in a format designed for use by \TeX\ +\dvi drivers. Their main purpose in life is to replace the raw font +abstraction available in the printer with one more convenient for +\TeX. These files are used by \dvi driver software only. + +\Dvi drivers use \vf files to work out what should \emph{really} be +printed when you ask for a particular character. +Technically they are like subroutine libraries for \dvi drivers, +with one subroutine for each character in the virtual font: when +the \dvi driver sees a \dvi command to set a character from a virtual +font, it will execute a sequence of \dvi commands (the ``mapcommands +property'' of this character) that it reads in the \vf file. You need +not worry about the details of this, as \fontinst deals with them for +you. Creating and using virtual fonts is what this document is about, +so don't worry if this doesn't make sense yet. (After all, how much +do you need to know about the inner workings of \dvi files to typeset +and print \TeX\ documents?) + +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. + + +\subsubsection{Font mapping files (\map files)} + +These are files telling \dvi drivers which printer fonts correspond to +specific \TeX\ fonts (\tfm files) -- how a specific \TeX\ font should +be \emph{mapped} onto a font concept available in the \dvi driver's +output format. Unlike \tfm, \fd, and \vf files, +which tend to be found as soon as they're in a suitable location +(such as the current directory), mapfiles typically need to be fully +installed or selected through a command-line option before any notice +is taken of them. + +The format of mapfiles varies from driver to driver, but a common +format is that of \dvips, where each line is a separate entry (except +lines that contain comments). The first word of an entry is the +\TeX~font name, the second word is the basic printer font name, and +remaining words provide additional information (e.g., the name of the +file in which the font is stored). + +The default in most \TeX\ systems is that fonts are assumed to be \mf +fonts unless there is a specific \map file entry which says otherwise. +Hence if you're trying to use a new Type~1 font, but the \dvi driver +gives you an error message that `\textit{somefile}\texttt{.mf} not +found', then the problem is most likely with the mapfiles. + + + + + + +\subsection{Fonts and characters} + +The term `character' (or just `char') is frequently used in +discussions of fonts, but not always correctly, and when getting into +the details of what \fontinst does it is necessary to keep the +terminology straight. + +\begin{description} +\item[Glyph] + A glyph is an image, often associated with one or several characters. + Some examples of glyphs are: + `A', `\textsf{A}', `$\mathcal{A}$', `B', `F', + `{\usefont{OT1}{cmr}{m}{n}f}', + `{\usefont{OT1}{cmr}{m}{n}fi}', `\~{}'. + Fonts are collections of glyphs. \Fontinst refers to glyphs by name. +\item[Slot] + This is jargon for `a numbered position in a font'. (What is + important is the number, and that this number refers to a position + in a font, but which font is usually specified separately.) + For typesetting, \TeX\ identifies glyphs as ``slot $n$ in font $f$''. +\item[Character] + The modern definition is that a character is the smallest component + of written language that has semantic value. Speaking of a + character, one refers to the abstract meaning, rather + than a specific shape. + + Since fonts have often contained a unique glyph for each character + and each usable glyph has been assigned a particular slot, + it is not uncommon (in particular in older terminology) to see the + three mixed up, usually so that one says `character' where one of + the other two would have been more correct. The \TeX-related font + file formats is no exception, as you may see examples of elsewhere + in this document. +\item[Encoding] + There are really two different encoding concepts that one encounters + when using \fontinst. The differences are not great, and an + encoding of one kind often corresponds to an encoding of the other + kind, but it is not merely a matter of translation. + + A \emph{\LaTeX\ encoding} is a mapping from characters (or more + formally \LaTeX\ Internal Character Representations) to slots. + In the \texttt{OT1} encoding, `\o' (or more technically `|\o|') maps + to slot~28, whereas in the \texttt{T1} encoding it maps to slot~248. + This kind of encoding affects what \TeX\ is doing; \dvi drivers are + not involved. + + A \emph{font encoding} (or \emph{encoding vector}) is a mapping from + slots to glyph names. This is the kind of encoding that \fontinst + primarily deals with, and also the kind of encoding that \dvi + drivers make use of. \texttt{ot1.etx} associates slot~28 with + `\texttt{oslash}', whereas \texttt{t1.etx} and \texttt{EC.enc} (one + of several to \texttt{T1} corresponding encoding vectors that come + with \dvips) associates slot~28 with `\texttt{fi}'. + + \LaTeX\ encodings occur in \fontinst only as names and only in + relation to \fd files. It is unlikely that you will need to create + one of your own. The mappings defined by font encodings are on the + other hand of great importance and \etx files are used to direct + the generation of virtual fonts. Advanced \fontinst users may well + find that they need to create new font encodings to achieve their + goals. +\end{description} + +\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 + +% 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\ \texttt{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 +an `\"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 one thing \fontinst helps with. + +% 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 are verbatim, typewriter, and monowidth fonts?} + +The verbatim, typewriter, and monowidth concepts are common sources +of confusion for those who use \fontinst to install fonts +with \LaTeX; in particular +there are many misconceptions about the relation between them. The +official view (of which not much has actually been brought forward) +is that these concepts are really about three quite different things. + +A font is a \emph{monowidth} (monospaced, fixed-pitch) font if all +glyphs in it have exactly the same width. Some font formats make +special provisions for such fonts; the most notable example is the +\afm format, where a single \texttt{CharWidth} keyword specifies the +width for all glyphs in the font. \Fontinst responds to this +by including the command +\begin{quote} + |\setint{monowidth}{1}| +\end{quote} +in the \mtx file generated from an \afm, but that is everything that is +hard-wired into the program. That a font is monowidth is however +something that one should take note of when installing it for \TeX, +as it means many of the glyphs in it have such a strange appearance +that they are (pretty much) useless. The \texttt{endash} is for +example usually only half as long as the \texttt{hyphen} and the +letters in ligature glyphs are only half as wide as normal letters. +Many of the \etx and \mtx files that come with \fontinst +contain special commands to avoid making use of such degenerate +glyphs. + +That a font is a \emph{typewriter} font really only means that it has +a typewriterish look about it. The two most familiar typewriter fonts +are probably Computer Modern Typewriter (\texttt{cmtt}) and Courier. +Both of these fonts are monowidth, but there is no absolute rule about +this. One of the standard \TeX\ fonts is for example Computer Modern +Variable-width Typewriter (\texttt{cmvtt}), which is not a monowidth +font, as Figure~\ref{Fig:TTvsVTT} shows. +\begin{figure} + \begin{tabular}{ll} + \texttt{cmtt}:& \fontfamily{cmtt}\selectfont + The quick brown fox jumps over the lazy dog.\\ + \texttt{cmvtt}:& \fontfamily{cmvtt}\selectfont + The quick brown fox jumps over the lazy dog. + \end{tabular} + \caption{Two typewriter fonts} + \label{Fig:TTvsVTT} +\end{figure} + +The verbatim concept has very little to do with fonts at all; in +\LaTeX\ it is considered to be a property of the environment +(\texttt{verbatim}, \texttt{macrocode}, etc.) rather than a property +of the font. The connection there is with fonts is that the encoding +of the font must contain visible ASCII (as defined in Appendix~C +of \emph{The \TeX book}%~\cite{TeXbook} +) as a subset for the text to +be rendered correctly. The \texttt{cmtt} family is the only one amongst +the original Computer Modern fonts which meets this criterion and +that is the primary grounds for the idea that these three concepts +should be connected. Today that reason is at best a very weak one, as +all \texttt{T1}-encoded fonts also meet the criterion of containing +visible ASCII as a subset. + +A circumstance which has probably added to the confusion is that +\texttt{OT1} is usually claimed to be one encoding. In reality the +Computer Modern fonts that are declared in \LaTeX\ as being +\texttt{OT1} display as many as five different encodings, as shown in +Table~\ref{Tab:OT1-fonts}. +\begin{table}[!tb] + \DeleteShortVerb{\|} + \begin{tabular}{l|c|c|c|} + & \texttt{TEX TEXT}& + \begin{tabular}[b]{c} + \texttt{TEX TEXT}\\ + \texttt{WITHOUT}\\ + \texttt{F-LIGATURES} + \end{tabular}& + \begin{tabular}[b]{c}\texttt{TEX}\\ + \texttt{TYPEWRITER}\\ + \texttt{TEXT} + \end{tabular}\\ + \hline + non-italic& + \begin{tabular}{l} + \texttt{cmb10}\\ + \texttt{cmbx5}--\texttt{12}\\ + \texttt{cmbxsl10}\\ + \texttt{cmdunh10}\\ + \texttt{cmff10}\\ + \texttt{cmfib8}\\ + \texttt{cmr6}--\texttt{17}\\ + \end{tabular} + \begin{tabular}{l} + \texttt{cmsl8}--\texttt{12}\\ + \texttt{cmss8}--\texttt{17}\\ + \texttt{cmssbx10}\\ + \texttt{cmssdc10}\\ + \texttt{cmssi8}--\texttt{17}\\ + \texttt{cmssq8}\\ + \texttt{cmssqi8}\\ + \texttt{cmvtt10} + \end{tabular}& + \begin{tabular}{l} + \texttt{cmcsc8}--\texttt{10}\\ + \texttt{cmr5} + \end{tabular}& + \begin{tabular}{l} + \texttt{cmsltt10}\\ + \texttt{cmtcsc10}\\ + \texttt{cmtt8}--\texttt{12} + \end{tabular}\\ + \hline + italic& + \begin{tabular}{l} + \texttt{cmbxti10}\\ + \texttt{cmfi10}\\ + \texttt{cmti7}--\texttt{12}\\ + \texttt{cmu10} + \end{tabular}&& + \begin{tabular}{l} + \texttt{cmitt10} + \end{tabular}\\ + \hline + \end{tabular} + \MakeShortVerb{\|} + \caption{``\texttt{OT1}-encoded'' Computer Modern fonts, collected + according to the actual font encoding} + \label{Tab:OT1-fonts} +\end{table} +Since most monowidth fonts are only used for setting verbatim text, +there is some code in \texttt{ot1.etx} which automatically chooses a +\texttt{TEX TYPEWRITER TEXT} encoding for the font when the +\texttt{monowidth} integer is set. The only reason for this is the +guess that this is what the user wanted. + + + +\section{Fontmaking commands} + +There are three main types of files that you may write to control what +\fontinst does: \emph{command files} (usually with suffix +\setdotfilename{tex}), \emph{encoding definition files} (suffix +\setdotfilename{etx}), and \emph{metric files} (suffix +\setdotfilename{mtx}). Command files directly tell \fontinst to do +things, whereas the purpose of an encoding or metric file is more to +store data, but all three file types are technically sequences of +\TeX\ commands that \fontinst execute when reading the file. Normal +\TeX\ syntax rules apply in all three file types, although a few +commands may behave in unfamiliar ways. + +Within the command file category, it is possible to discern certain +subcategories. Most command files are written for one particular +task, but some are common pieces that have been factored out from +larger command files and are merely meant to be |\input| where +appropriate. (\setfilename{csc2x.tex} in the \fontinst distribution is +an example of this latter kind.) One may also distinguish between +command files that are made for use with \setfilename{fontinst.sty} +command definitions and command files that are made for use with +\setfilename{finstmsc.sty} command definitions. This section documents +the commands that are particular to the former category, whereas the +next section documents commands that are particular to the latter. + + +\subsection{Install commands} + +The core fontmaking takes place within a block of ``install +commands''. (This name is a bit unfortunate since nothing is actually +installed; rather some files that need to be installed are generated.) +Such blocks have the structure +\begin{quote} + |\installfonts|\\ + \m{install commands}\\ + |\endinstallfonts| +\end{quote} +The \m{install commands} describe the fonts, glyphs and encodings used +to build fonts, whereas the purpose of the delimiting |\installfonts| +and |\end|\-|install|\-|fonts| are rather to organise the writing +of \fd files. + +\begin{decl*} + |\installfonts|\\ + |\endinstallfonts| +\end{decl*} +At |\installfonts|, \fontinst's internal list of \fd files to generate +are cleared. At |\endinstallfonts|, \fd files are written for those +combinations of encoding and font family that appeared in the +\meta{install commands}. + +\begin{hackernote} + |\installfonts|, |\endinstallfonts|, and the individual + install commands between them also cooperate in a rather complicated + grouping scheme to cache glyphbases. This may interfere with + non-\fontinst commands in the \meta{install commands}. If for + example an assignment to some |\tracing|\dots\ parameter here does + not seem to have any effect, try making the assignment |\global|. +\end{hackernote} + +The most important \meta{install command} is +\begin{decl*} + |\installfont|\arg{font-name}\arg{metrics-list}\arg{etx-list}\\ + \hspace*{1.5em}\arg{encoding}\arg{family}\arg{series}% + \arg{shape}\arg{size} +\end{decl*} +This produces a \TeX\ virtual font called \m{font-name}. The +\meta{metrics-list} and the \meta{etx-list} determine this font, +whereas the other arguments specify how the \fd file will declare it +for \LaTeX. The \m{encoding}, \m{family}, \m{series}, and \m{shape} +are precisely the NFSS parameters. The \m{size} is either a shorthand +declared by \verb|\declaresize| (see below), or is an \fd size +specification. + +Like most \fontinst lists, the elements in the \meta{metrics-list} and +\meta{etx-list} are separated by commas (so-called comma-separated +lists). In their simplest form, the elements of these lists are file +names (minus suffixes): \mtx files in the \meta{metrics-list} and +\etx files in the \meta{etx-list}. First the \mtx files are processed +to build up a glyphbase, i.e., store definitions of glyphs and their +metric properties in memory, and then the \etx files are processed +(several times) to select a set of glyphs and write the corresponding +information to a \vpl file. + +For example, to install the \texttt{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 \texttt{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} + +As the second example indicates, there is more to the list items than +just file names. In the case of an metrics list item, the syntax +permits the two forms +\begin{decl*} + \meta{filename}\meta{optional modifiers}\\ + |\metrics| \meta{metric commands} +\end{decl*} +\NEWfeature{v1.923} +where an \meta{optional modifier} is one of +\begin{decl*} + \verb*| scaled |\meta{rawscale factor}\\ + \verb*| suffix |\meta{glyph name suffix}\\ + \verb*| encoding |\meta{etx}\\ + \verb*| option |\meta{string} +\end{decl*} +A list item may contain several such modifiers, but most commonly it +does not contain any. The +\meta{metric commands} are explicit metric commands, as described in +Section~\ref{Sec:Metric}; this latter feature is meant for minor +adjustments that you don't want to bother creating a separate \mtx +file for. + +The \meta{filename} above primarily refers to a file +\meta{filename}\texttt{.mtx}, but that need not always exist before +executing the above command. If there exists a \pl, \afm, or \vpl file +with the right name then that is first converted to a corresponding +\mtx file. However, a special case occurs if there is an |encoding| +modifier: this forces conversion of a \pl or \vpl file even if an +\mtx file exists, and also forces using the specified \etx file when +assigning glyph names to the slots of that file. Normally the choice +of \etx file for such conversions to \mtx is based on +|\declareencoding| declarations. + +The |scaled| modifier sets the \texttt{rawscale} variable for the +processing of that file. This has the effect of scaling all raw +glyphs from that file to \meta{rawscale factor} per milles of their +previous size. The |suffix| modified causes the \meta{glyph name +suffix} to be implicitly appended to all glyphs defined by this file. +The |option| modifier adds the \meta{string} to the list of ``options'' +for this file. The |\ifoption| command can be used in the file to test +whether a particular string has been supplied as an option. + +\begin{hackernote} + In general, \fontinst commands process comma-separated list arguments + by first splitting at commas and then fully expanding each item, but + this \meta{metrics-list} argument is an exception. This is first + fully expanded (|\edef|) and then split into items. The difference + is that a macro used in this \meta{metrics-list} argument can expand + to several list items, whereas a macro used in an ordinary + comma-separated list argument can only expand to (part of) a single + list item. + + The |\metrics| list items do however constitute an exception within + this exception. These list items are in their entirety protected + from the initial full expansion, so you don't have to worry about + peculiar fragility errors there. +\end{hackernote} + +The elements in the \meta{etx-list} have fewer variants, but there is +still a general syntax +\begin{decl*} + \meta{filename}\meta{optional modifiers} +\end{decl*} +The \meta{optional modifier}s permitted are: +\begin{decl*} + \verb*| mtxasetx|\\ + \verb*| option |\meta{string} +\end{decl*} +The \texttt{option} one is as for metric files. \texttt{mtxasetx} is +probably only relevant for use with |\installrawfont| (see below). + + +\begin{decl}[v1.912] + |\installfontas|\arg{font-name}\\% + \hspace*{1.5em}\arg{encoding}\arg{family}\arg{series}% + \arg{shape}\arg{size} +\end{decl} +This install command adds an \fd entry for the \meta{font-name}, but +it doesn't actually generate that font. Usually that font was +generated by a previous |\installfont|, and this is used to create +additional entries for the font. + + +\begin{decl} + |\installrawfont|\arg{font-name}\arg{metrics-list}\arg{etx-list}\\ + \hspace*{1.5em}\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. Often a \pl +file with the specified name will already exist when this command is +called, and that will then be overwritten. These two \pl files will +typically be somewhat different. +The normal reason for using this command is that one wishes to +``refine'' the metrics of a font that was generated by transformation +commands. + +For example, to install an \texttt{8r}-encoded Times Roman raw font +(using \texttt{8r.etx} and \texttt{8r.mtx}), you say: +\begin{verbatim} + \installrawfont{ptmr8r}{ptmr8r,8r}{8r} + {8r}{ptm}{m}{n}{} +\end{verbatim} +(The files referred to are, in order, \texttt{ptmr8r.pl}, +\texttt{ptmr8r.mtx}, \texttt{8r.mtx}, and \texttt{8r.etx}.) + +The effect of a +\begin{decl*}[v1.923] + \meta{filename}\verb*| mtxasetx| +\end{decl*} +in the \meta{etx-list} is not that \meta{filename}\texttt{.etx} is +read, but that \meta{filename}\texttt{.mtx} is read. The +interpretation of the commands in this file is however not the +customary, and almost the only thing paid attention to is the +correspondence between glyph names and slot numbers that is provided +by the |\setrawglyph| and |\setscaledrawglyph| commands; this +correspondence is treated as if it was given by |\setslot| \dots\ +|\endsetslot| commands in an \etx file. This is however only +guaranteed to work with transformable metric files. + +The purpose of this feature is to simplify installation of fonts with +very special encodings, such as ``Dingbat'' or ``Pi'' fonts. Instead +of creating an \etx file, which would probably only be useful with +that particular font, one can make use of the fact that the +interesting information is anyway available in the \mtx file. To +install Zapf Dingbats in their default encoding, one can thus say +\begin{verbatim} + \installrawfont{pzdr}{pzdr}{pzdr mtxasetx} + {U}{pzd}{m}{n}{} +\end{verbatim} + +Unlike the case with |\installfont|, which actually creates a real +(although virtual) font, |\installrawfont| can only create the +metrics for a font. The \dvi driver will require some other kind of +implementation of this font, usually an entry in some map file (e.g. +\texttt{psfonts.map}, in the case of \dvips) that links the \TeX\ font +name to e.g.\ a \PS\ font name and file. (Many \dvi drivers are +configured in such a way that they, without such a map file entry, +will call Metafont with the font name and thereby raise a sequence of +error messages about a \setdotfilename{mf} that doesn't exist. These +results are often rather confusing.) + + + +\begin{decl} + |\installfamily|\arg{encoding}\arg{family}\arg{fd-commands} +\end{decl} +This tells \fontinst to write an \fd file for the given combination +of encoding and family, and clears the internal list of entries to +put in that file. |\installfamily| commands usually come first in each +block of \meta{install commands}. + +For example, if you intend to produce a \texttt{T1}-encoded Times +family of fonts, 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} +In more recent versions of \fontinst, the |\installfamily| command is +only necessary if you want the \m{fd-commands} argument to be +nonempty, but it doesn't hurt to make it explicit. + +\begin{hackernote} + The \m{fd-commands} argument is tokenized with the current catcodes + and written to file without expansion. In particular this means + that spaces will be inserted after all control sequences whose + names consists of letters, which can be unexpected if you intend to + make use of control sequences whose names contain |@| characters. + + One way around this is to use |\fontinstcc| and |\normalcc| to + temporarily switch catcodes around the |\installfamily| command. +\end{hackernote} + + + +\subsection{Transformation commands} + + +\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}. + +The following commands are valid \m{transformed font}s: +\begin{decl*} + |\fromafm|\arg{afm}\\ + |\fromany|\arg{whatever}\\ + |\frompl|\arg{pl}\\ + |\fromplgivenetx|\marg{pl}\marg{etx}\\ + |\frommtx|\arg{mtx} +\end{decl*} +These read the metrics of the font which is about to be transformed from +an external file. |\fromafm|, |\frompl|, and |\fromplgivenetx| write out +an \mtx file corresponding to the \afm or \pl file. In addition, +|\fromafm| also writes out a raw \pl file, containing just the glyph +metrics but no kerning information. |\fromplgivenetx| permits +specifying which encoding file to use when associating glyph names to +slots, whereas |\frompl| tries to guess this from the +\texttt{CODINGSCHEME} property of the \pl file. |\fromany| looks for +a file in any of the formats (in the order \mtx, \pl, \afm) and +behaves as the first |\from|\dots\ for which it found a file. + +A \m{transformed font} may also be one of the following: +\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 +units 1000 to the design size. Typical examples are 167 for slanted +fonts (a slant of $\frac{1}{6}$) or 850 for condensed fonts (shrunk +to 85\% of their natural width). + +The final case of a \m{transformed font} is: +\begin{decl*} + |\reencodefont|\arg{etx}\arg{transformed font} +\end{decl*} +This rearranges the encoding vector of \m{transformed font} to match +the encoding given by the \etx file. + + +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 equivalent +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} +See Section~\ref{Sec:Mapmaking} and +Subsection~\ref{Ssec:MapFragments} for details on how to generate +such lines automatically. + + +\subsection{The \cs{latinfamily} command} + + +\begin{decl} + |\latinfamily|\marg{family}\marg{commands} +\end{decl} +This command is by itself an entire |\installfonts| \dots\ +|\endinstallfonts| block, automatically doing |\transformfont|s, +|\installfont|s, and |\install|\-|raw|\-|font|s depending on which +base font metrics it finds. It generates virtual fonts in the +\texttt{T1}, \texttt{OT1}, and \texttt{TS1} encodings. + +There is really much to much about this command for it to be described +in full here. Please see other available documentation. + +\begin{decl} + |\fakenarrow|\marg{width factor} +\end{decl} +This command makes |\latinfamily| fake `narrow' fonts in the family it +is working on, by $x$-scaling the normal fonts. The \meta{width factor} +is the scale factor to use. + + +\subsection{Reglyphing commands} + +``Reglyphing'' is an \mtx file transformation that changes glyph +names but leaves the slot numbers and metrics as they were; +optionally it may drop some of the metric commands. See +Subsection~\ref{Ssec:Des:Reglyph} for an introduction to this. + +Like installation commands, reglyphing commands are preferably placed +in a block between two delimiter commands: +\begin{decl*} + |\reglyphfonts|\\ + \meta{reglyphing commands}\\ + |\endreglyphfonts| +\end{decl*} +The purpose of these delimiter commands is to delimit the scope in +which the various declarations made take effect. After +|\endreglyphfont|, you're back to the ``clean'' state that existed +before the |\reglyphfont|. + +\begin{decl} + |\reglyphfont|\marg{destination font}\marg{source font} +\end{decl} +This is the only command that actually does something; all the other +commands simply set parameters for the processing carried out here. +What the command does is that it reads the \meta{source font} (which +may be in \mtx, \pl, \afm, or \vpl format, but will be converted to +\mtx before it is read for reglyphing) and writes each command back to +the \meta{destination font} (in \mtx format \emph{only}), but often +with some subtle modifications. + +It should be observed that the ``destination font'' generated by this +command is not a real font, but just an \mtx file. If that \mtx file +contains raw glyph defintions (|\setscaledrawglyph| commands) then +these will refer to the \meta{source font}, so that is all a \dvi +driver needs to be informed about. + +\begin{decl} + |\renameglyph|\marg{to}\marg{from}\\ + |\renameglyphweighted|\marg{to}\marg{from}\marg{weight}\\ + |\killglyph|\marg{glyph}\\ + |\killglyphweighted|\marg{glyph}\marg{weight} +\end{decl} +The |\renameglyph| and |\renameglyphweighted| commands cause each +reference to the glyph \meta{from} in the source font to be replaced +by a reference to the glyph \meta{to} in the destination font. Thus if +the source font contains a command that sets a glyph with the name +\meta{from}, then this will in the destination font be changed to a +command that sets a glyph with the name \meta{to}, but with the same +metrics, slot, and base font name as in the source font. Kerns are +similarly adjusted to be for the \meta{to} glyph. + +There is also a ``weight'' associated with each command being copied +from source font to destination font, and if that weight is too small +then the command will be omitted from the destination font. The weight +of a command is the sum of the weights of all glyphs mentioned in that +command. A glyph for which no settings have been made has weight $0$. +A glyph name which is the \meta{from} of a |\renameglyphweighted| or +the \meta{glyph} of a |\killglyphweighted| has the \meta{weight} +specified there. A \meta{from} glyph of a |\renameglyph| gets the +weight stored in the \texttt{renameweight} integer variable +(by default $1$) and the \meta{glyph} of a |\killglyph| gets the +weight stored in the \texttt{killweight} integer variable (by default +$-10$). It is this large negative weight that makes |\killglyph| +``kill'' glyphs. + +The weight condition for keeping a command is given by the +|\iftokeep| command, which is regarded as a \fontinst command +variable (see Section~\ref{Sec:Variables}). The default definition is +to keep things with non-negative weight (typically everything that +doesn't involve a glyph that has been killed), but for example +\setfilename{csckrn2x.tex} redefines it to only keep things with +positive weight (typically everything involving at least one glyph +that has been renamed and not any that has been killed). + + +\begin{decl} + |\offmtxcommand|\marg{command}\\ + |\onmtxcommand|\marg{command} +\end{decl} +Turning a command `off' using |\offmtxcommand| means no such commands +are to be copied to a destination font by |\reglyphfont|. Turning it +back `on' using |\onmtxcommand| restores it to normal, i.e., whether +it is copied depends on the weight of the command. + +\begin{hackernote} + |\offmtxcommand| and |\onmtxcommand| are wrappers around the + general-purpose |\offcommand| and |\oncommand| commands (see + Subsection~\ref{Ssec:Variables}). The wrapping makes the general + commands to act on a family of internal macros, namely those which + are used by |\reglyphfont| as definitions of the transformable + metric commands. +\end{hackernote} + + +\subsection{Miscellaneous settings} + +\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}. Font substitutions happen at |\endinstallfonts| time, and +cause font declarations using |sub| or |ssub| to be added to the \fd +files being written. + +\verb|\substitutenoisy| means that a warning will be given when +the substitution is made by \LaTeX. +\verb|\substitutesilent| means that \LaTeX\ should not warn when +the font substitution is made. + +For example, to say that the series |bx| can be replaced by the +series |b| (a request for series |bx| selects a font with actual series +|b|), you say: +\begin{verbatim} + \substitutesilent{bx}{b} +\end{verbatim} +To say that the shape |ui| can be replaced by the shape |it| (a +request for shape |ui| selects a font with actual shape |it|), 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} +In order to disable a default substitution, use the \meta{from} for +both arguments. + +The |\installfontas| command should be considered as an +alternative to using font substitution, as it gives much finer +control over what \fd entries will be made. + + +\begin{decl} + |\declaresize|\arg{size}\arg{fd-size-range} +\end{decl} +This declares a new size shorthand, and gives the \fd size +specifications 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} +The first of these is what gives an empty \meta{size} argument for +the font installation commands the meaning ``all sizes''. + +\begin{decl} + |\declareencoding|\arg{string}\arg{etx} +\end{decl} +This declares which \etx file corresponds to which +\texttt{CODINGSCHEME} string, and is used when reading metrics in \pl +format. 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{Low-level conversion commands} + +The following commands are the low-level commands which carry out +various conversions. There's usually no need to bother about them +unless you are hacking \fontinst, but you may see them in the header +comments of files \fontinst generates, so here's a description of what +they do and when they are used. + +\begin{decl} + |\afmtomtx|\marg{afmfile}\marg{mtxfile}\\ + |\generalpltomtx|\marg{plfile}\marg{mtxfile}% + \marg{plsuffix}\marg{opt-enc} +\end{decl} +These handle importing font metric data to the \fontinst native \mtx +format. + +|\afmtomtx| converts metrics in \afm format. It uses the +\texttt{minimumkern} integer variable and the |\slanteditalcorr| and +|\uprightitalcorr| command variables. + +|\generalpltomtx| converts metrics in \pl or \vpl format. If the +\meta{opt-enc} string expression is nonempty then that is taken as the +name of an \etx file that assigns glyph names to the slots in the font. + +\begin{decl} + |\mtxtomtx|\marg{source MTX}\marg{destination MTX} +\end{decl} +This is the heart of the |\transformfont| command. It makes use of the +\texttt{x-scale}, \texttt{y-scale}, and \texttt{slant-scale} integer +variables, and the \texttt{etx-name} string variable. + +\begin{decl} + |\mtxtopl|\marg{mtxfile}\marg{plfile} +\end{decl} +This converts \mtx metrics to \pl format; more precisely it generates +\texttt{CHARACTER} property lists for |\setrawglyph| and +|\setscaledrawglyph| commands. Kerning information is ignored. + +The command is used immediately after an |\afmtomtx| or |\mtxtomtx|. +The invariant is that if there can be some |\setrawglyph| or +|\setscaledrawglyph| command which refers to a glyph in some font, +then there must also be a \pl file with metrics for that font. + +\begin{decl} + |\etxtovpl|\marg{encoding list}\marg{vplfile}\\ + |\etxtopl|\marg{encoding list}\marg{plfile} +\end{decl} +These are the cores of |\installfont| and |\installrawfont| +respectively. They don't really convert files---it's more like +generating a \vpl or \pl under the control of the \etx. + + + + + + +\subsection{Other} + +The following commands also belong in this section, but don't belong +to any of the major groups. + +\begin{decl} + |\recordtransforms|\marg{filename}\\ + |\endrecordtransforms| +\end{decl} +See Subsection~\ref{Ssec:MapFragments} for an explanation of how these +are used. + +\begin{decl} + |\NOFILES| +\end{decl} +This command switches off file generation, and causes \fontinst to +only generate empty files. It only affects the user level commands, +so it is primarily of use when debugging commands that build on +these, such as for example the |\latin|\-|family| command. + + + + + +\section{Mapmaking commands} +\label{Sec:Mapmaking} + +The commands described in this section are for use with command files +that input \texttt{finstmsc.sty}. + + +\subsection{Mapfile command reference} + +For an introduction to making map file entries, see +Subsection~\ref{Ssec:MapFragments}. + +\begin{decl} + |\adddriver|\marg{driver name}\marg{fragment file name} +\end{decl} +This opens the file \meta{fragment file name} for writing mapfile +entries to. The \meta{driver name} selects the format of these +entries. \emph{Note} that if the \meta{fragment file name} does not +include a suffix, it will get the suffix \setfilename{tex}, which is +probably not what you want. + +\begin{decl} + |\makemapentry|\marg{\TeX\ font name} +\end{decl} +This causes a mapfile entry for the specified font to be written to +all files currently open for receiving mapfile entries. These +commands are usually automatically generated by \fontinst. + +\begin{decl} + |\donedrivers| +\end{decl} +This closes all files open for receiving mapfile entries. + + +\subsection{Drivers} + +The \meta{driver name}s that may be used with |\adddriver| are: + +\begin{decl} + |dvips| +\end{decl} +The \dvips driver. The mapfiles generated are useful also with +pdf\TeX, but one does not always use the exact same file for both; +sometimes they require different settings. + +\begin{decl} + |dvipdfm| +\end{decl} +The \setpackagename{dvipdfm} \dvi-to-\pdf driver. Not much tested, +but appears to work. + +\begin{decl}[v1.915] + |pltotf| +\end{decl} +Not really a \dvi driver. The file that is generated is a shell +script of \texttt{pltotf} commands for converting precisely those \pl +files which are needed to \tfm files (\fontinst generally generates +also a bunch of \pl files that in the end turn out to be +unnecessary). The \texttt{TFMfileprefix} variable can be used to +specify a path to the directory where these files should be placed. + +\begin{decl} + |debug| +\end{decl} +Not a \dvi driver either, but for each base font a report on the +information that was available. Useful if you need to write the +driver file yourself. + +\begin{hackernote} + Creating a new driver \meta{foo} is mostly a matter of suitably + defining the |\make_|\meta{foo} command. +\end{hackernote} + + +\subsection{Configuration commands} +\label{Ssec:MapConfig} + +The following commands configure the generation of mapfile entries, +mostly with respect to how various pieces of information are deduced +from other pieces. + +\begin{decl} + |\AssumeAMSBSYY|\\ + |\AssumeBaKoMa|\\ + |\AssumeMetafont| +\end{decl} +These commands change what the map file writer does when it needs to +know the \PS name for a font but only knows the \TeX\ name. This +usually happen when the metrics came from a \pl file. + +|\AssumeAMSBSYY| tells it to uppercase the \TeX\ name and use that as +\PS name; this is correct for the AMS\slash Blue~Sky\slash Y\&Y +conversions of the Computer Modern fonts. + +|\AssumeBaKoMa| tells it to lowercase the \TeX\ name and use that as +\PS name; this is correct for the BaKoMa conversions of the Computer +Modern fonts. + +|\AssumeMetafont| tells it to ignore base fonts for which no \PS name +is known, on the assumption that they are \mf fonts. + + +\begin{decl} + |\AssumeLWFN| +\end{decl} +This commands changes what the map file writer does when it needs to +know the name of the file in which a \PS font is stored. The file name +is constructed from the \PS font name using the $5+3+3+\cdots$ +convention used in (Classic) Mac~OS. + +By default \fontinst uses as \PS font file name the \TeX\ name of the +font (i.e., the name of the source \afm or whatever file) and appends +to that the contents of the \texttt{PSfontsuffix} string. + +For fonts which fit neither of these schemes, one can give individual +specifications using the command +\begin{decl*} + |\specifypsfont|\marg{PS font name}\marg{actions} +\end{decl*} +Note that the font is here identified using its \PS font name, not the +\TeX\ font name. + +An \meta{action} is one of\footnote{Additional actions can be added +in the future, if there is a need for them. It is not a problem if not +all driver can support an action, since all actions typically default +to \cs{download}.} +\begin{decl*}[v1.928] + |\download|\marg{file}\\ + |\fulldownload|\marg{file} +\end{decl*} +where \meta{file} is a file to download (`download' typically means +``include in the generated \PS output or equivalent''). The difference +between |\download| and |\fulldownload| have to do with how partial +downloading (subsetting) of fonts should be handled. |\download| means +use the driver's defaults (often settable via command line options) +for this. |\fulldownload| means don't subset: always include the full +font, if \fontinst knows how to express this in a map file entry for +this particular driver. + +If FooBar-Regular is a non-subsettable font, then you may specify this +to \fontinst through a command like +\begin{verbatim} + \specifypsfont{FooBar-Regular}{\fulldownload{foobar.pfb}} +\end{verbatim} +To specify that the PDF ``base 14'' fonts do not require downloading, +one would say +\begin{verbatim} + \specifypsfont{Courier}{} + \specifypsfont{Courier-Bold}{} + \specifypsfont{Courier-BoldOblique}{} + \specifypsfont{Courier-Oblique}{} + \specifypsfont{Helvetica}{} + \specifypsfont{Helvetica-Bold}{} + \specifypsfont{Helvetica-BoldOblique}{} + \specifypsfont{Helvetica-Oblique}{} + \specifypsfont{Times-Roman}{} + \specifypsfont{Times-Bold}{} + \specifypsfont{Times-Italic}{} + \specifypsfont{Times-BoldItalic}{} + \specifypsfont{Symbol}{} + \specifypsfont{ZapfDingbats}{} +\end{verbatim} +When more than one action appears in the \meta{actions} argument, +then it is usually the last that actually creates the font, whereas +the others contain resources needed by the last. + + +\begin{decl} + |\declarepsencoding|\marg{etx}\marg{postscript name}\marg{action} +\end{decl} +This command specifies how reencoding using a particular \etx file +should be performed by the driver. The \meta{postscript name} is the +\PS name of the encoding vector used, whereas the \meta{action} is the +action (as above) that the driver needs to perform to make the +encoding known to whatever it is that it is serving (often a \PS +interpreter). + +Usually the right thing to do is to |\download| an \enc file, but +there is also an action +\begin{decl*}[v1.931] + |\encodingdownload|\marg{file} +\end{decl*} +which tries to express the fact that the \meta{file} contains an +encoding vector. In the case of \dvips this is only necessary if +(i)~the font is being subsetted and (ii)~the \meta{file} name is +nonstandard (does not end with \enc). + +\begin{decl}[v1.931] + |\providepsencoding|\marg{etx}\marg{postscript name}\marg{action} +\end{decl} +This command is the same as |\declarepsencoding|, except that it +doesn't do anything if an encoding has already been declared for this +\meta{etx}. It is used for autogenerated encoding declarations, so +that these will not override one issued by the user. + + + +\begin{decl} + |\storemapdata|\marg{\TeX\ font name}\marg{source}\marg{transforms} +\end{decl} +This records information about how the font named \meta{\TeX\ font +name} was generated. Such commands are usually found in the file of +recorded transforms. If a font is encountered for which no +information has been stored, then the corresponding \mtx file will be +sourced, looking for a |\storemapdata| command there. + +A \meta{source} is one of +\begin{decl*} + |\fromafm|\marg{\afm name}\marg{PS name}\\ + |\frompl|\marg{\pl name}\\ + |\frommtx|\marg{\mtx name}\\ + |\fromvpl| +\end{decl*} +Note that several of them have a different syntax and meaning than +they do in fontmaking command files. + +A \meta{transform} is one of +\begin{decl*} + |\reencodefont|\marg{etx}\\ + |\reglyphfont|\\ + |\transformfont|\marg{x-scale}\marg{slant-scale} +\end{decl*} +Note that all of these have a different meaning than they do in +fontmaking command files. + +\begin{decl} + |\debugvalue|\arg{name} +\end{decl} +This adds a value to the list of those that are reported by the +\texttt{debug} driver. Example: +\begin{verbatim} + \debugvalue{PS_font_file} +\end{verbatim} + + + +\subsection{Basic conversion commands} + +Some of the basic ``convert an $X$ file to a $Y$ file'' commands in +\fontinst are not useful as part of a fontmaking run, and are +available only in \texttt{finstmsc.sty} to conserve some memory. + +\begin{decl} + |\enctoetx|\marg{encfile}\marg{etxfile} +\end{decl} +This reads the file \meta{encfile}\texttt{.enc} which should be +simple \PS code defining a \PS encoding vector and generates a +corresponding rudimentary \fontinst encoding file +\meta{etxfile}\texttt{.etx}. It's a basic ``import encoding to +\fontinst'' command. + +\begin{decl}[v1.911] + |\etxtoenc|\marg{etxfiles}\marg{encfile} +\end{decl} +This does the opposite of |\enctoetx|; the information in the \etx +files that is converted is the correspondence between slots and glyph +names. +\NEWfeature{v1.927} +The \meta{etxfiles} argument is a comma-separated list of encoding +files which are superimposed to generate the \PS encoding. The first +|\setslot| for a particular slot is the one which decides which glyph +will be placed there. + +\begin{decl}[v1.928] + |\etxtocmap|\marg{etxfile}\marg{cmapfile} +\end{decl} +This reads an \etx file and generates a corresponding ToUnicode CMap +file; the information that is converted is the map from slot numbers +to |\Unicode| code points. + + + + +\section{General commands} + + + +This section describes commands and mechanisms that are the same in +all file types. Commands that are particular for one type of file are +described in subsequent sections. + + +\subsection{Variables} +\label{Ssec:Variables} + +Many (but not all) of the activities \fontinst perform can be +understood as either ``setting variables'' or ``formatting and writing +to file data stored in some variable''. The accessing of variables is +an important aspect of how \fontinst works. + +Variables come in different types and variables of different types +live in different namespaces; |\int{foo}|, |\str{foo}|, and +|\dim{foo}| refer to three different variables which are all named +|foo|. Variables are either set or not set. Unless the contrary is +stated explicitly, each variable defaults to not being set. It is an +error to access the value of a variable that has not been set. +\Fontinst variable assignments are as a rule local, i.e., will be +undone when the enclosing \TeX\ group is ended. Most command file +commands that cause files to be read will begin a group before +reading the file(s) and end the group at some point after having +read them. + +Taking string variables as an example, there are three commands for +changing a string variable: +\begin{decl*} + |\setstr|\arg{name}\arg{string expression}\\ + |\resetstr|\arg{name}\arg{string expression}\\ + |\unsetstr|\arg{name} +\end{decl*} +The |\resetstr| command unconditionally sets the string variable +\meta{name} to the full expansion of the \meta{string expression}. +The |\unsetstr| command unconditionally renders the string variable +\meta{name} unset. If the the string variable \meta{name} is +currently unset then the |\setstr| command will set it to the full +expansion of the \meta{string expression}, but if it already is set +then |\setstr| does nothing. + +This pattern with three commands, one |\set|\dots\ which only sets +unset variables, one |\reset|\dots\ which sets variables regardless of +whether they have been set or not, and one |\unset|\dots\ which unsets +variables is recurring in \fontinst. Variables are most commonly set +using some |\set|\dots\ command; this has the effect that the first +command to try to set a variable is the one which actually sets it. + +If |\set|\dots\ is the command for setting the value of a variable, +the command for getting that value has the same name without the +|set| part, e.g., |\setint|--|\int|, |\setglyph|--|\glyph|, etc. +(Notable exceptions are |\setkern|, where the ``get'' command is +called |\kerning|, and |\setcommand|, where no separate ``get'' +command is needed.) There +are typically also conditionals for testing whether variables are +set, and these take the form |\ifis|\dots\arg{name}|\then|. + +\medskip +% The following commands for changing the value of a variable can be +% used anywhere: + +\begin{decl} + |\setdim|\arg{dim}\arg{dimension}\\ + |\setint|\arg{int}\arg{integer expression}\\ + |\setstr|\arg{str}\arg{string expression} +\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 expression}. + +\begin{decl} + |\setcommand|\arg{command}\meta{parameter text}\arg{replacement text} +\end{decl} +If the command \m{command} is currently undefined, it is defined to +grab parameters as specified by the \meta{parameter text} and then +expand to the \m{replacement text}. This uses the same syntax for +parameters as the \TeX\ \verb|\def| command. +\begin{center} + \begin{tabular}{r l} + Number of parameters& \meta{parameter text}\\ + 0& (empty)\\ + 1& |#1|\\ + 2& |#1#2|\\ + 3& |#1#2#3|\\ + \multicolumn{2}{c}{and so on.} + \end{tabular} +\end{center} +Some examples: +\begin{verbatim} + \setcommand\lc#1#2{#2} + \setcommand\lc#1#2{#1small} +\end{verbatim} +With the first definition, |\lc{A}{a}| expands to |a|, but with the +second it expands to |Asmall|. + +\begin{decl} + |\resetdim|\arg{dim}\arg{dimension}\\ + |\resetint|\arg{int}\arg{integer expression}\\ + |\resetstr|\arg{str}\arg{string expression} +\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 +the \m{string expression}. (|\resetstr| mostly boils down to a \TeX\ +|\edef| command.) + +\begin{decl} + |\resetcommand|\arg{command}\meta{parameter text}\arg{replacement text} +\end{decl} +The command \m{command} is defined to grab parameters as specified by +the \meta{parameter text} and then expand to the \m{replacement text}. +This is a synonym for the \TeX\ \verb|\def| command. + +\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. + +\begin{decl}[v1.900] + |\offcommand|\marg{command}\\ + |\oncommand|\marg{command} +\end{decl} +|\offcommand| turns off a command, i.e., it redefines it to do +nothing (while still taking the same number of arguments). +|\oncommand| turns a command back on, i.e., it restores the +definition the command had before a previous |\offcommand|. Using +|\offcommand| on a command that is already off or |\oncommand| on a +command that is not off has no effect. + + +\subsection{Argument types and expansion} + +Most arguments of \fontinst commands belong to one of the following +six categories: +\begin{itemize} + \item integer expressions, + \item string expressions, + \item comma-separated lists of string expressions, + \item dimensions, + \item commands (i.e., a single \TeX\ control sequence), and + \item code (zero or more commands in sequence, each of which may + have arguments of its own). +\end{itemize} +Integer expressions are explained in Subsection~\ref{Sec:integer} +below. + +The most common form of a string expression is simply a sequence of +character tokens, but any balanced text which expands to such a +sequence of tokens is legal. Several of the standard \etx files use +macros in string expressions to make glyph names to some extent +configurable. Besides such custom macros, the following \fontinst +commands may be used to access variable values inside a string +expression +\begin{decl*} + |\strint|\arg{int}\\ + |\str|\arg{str}\\ + |\dim|\arg{dim} +\end{decl*} +Incidentally, these \m{int}, \m{str}, and \m{dim} are themselves +string expressions (for the names of integer, string, and dimen +respectively variables). + +Dimensions are simply \TeX\ \meta{dimen}s; their use is rather +limited. \Fontinst does not provide for any sort of ``dimen +expressions''. Most actual lengths are expressed as integer +expressions, in AFM units ($1/1000$ of the font size). + +Common to integer expressions, string expressions, and +dimensions is that these argument types get expanded during +evaluation (in the case of string expressions, this expansion +\emph{is} the evaluation), which means one can use macros in +arguments of these types. Command arguments do not get +expanded---they are mainly used with commands that modify the +definitions of other commands. + +Comma-separated lists of string expressions are first split at commas +(without prior expansion) and each element is then treated as a +string expression (i.e., \emph{gets expanded}). (As remarked elsewhere, +the \meta{metrics-list} argument of |\installfont| is not properly a +comma-separated list of string expressions, even though it may look +like one.) + +Code arguments are generally expanded, but one should not make any +presumptions about \emph{when} this will happen, and similarly not +assume that code placed in such an argument will only be executed +once. It is typically safe to use a macro in a code argument if the +definition of that macro stays the same throughout, but one should +otherwise not use any other commands in code arguments than those +explicitly documented as legal there. + +Finally, there are command arguments which do not fall into any of +these categories. For these, one cannot give any rules: they +might get expanded, but it could also happen that they won't. + + + +\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 in +\emph{The \TeX book}). Typical examples of this kind of integer +expression are |0|, |1000|, |538|, |-20|, |"9C|, |'177|, etc. + +\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} glyphs. Unlike +other types of variable accesses, where it is an error to access +something that has not been explicitly set, this command returns |0| +if no kern has been set between the two glyphs. + +\begin{decl} + |\neg|\arg{integer expression}\\ + |\add|\arg{integer expression}\arg{integer expression}\\ + |\sub|\arg{integer expression}\arg{integer expression}\\ + |\max|\arg{integer expression}\arg{integer expression}\\ + |\min|\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}\\ + |\half|\arg{integer expression}\\ + |\otherhalf|\arg{integer expression} +\end{decl} +These commands evaluate their argument(s) and perform some arithmetic +operations on the result(s). + +|\neg| returns the negation of the \m{integer expression}. + +|\add| returns the sum of the two \m{integer expression}s. + +|\sub| returns the first \m{integer expression} minus the second. + +|\max| returns the maximum of the two \m{integer expression}s. + +|\min| returns the minimum of the two \m{integer expression}s. + +|\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. |\scale| does better rounding than the corresponding +combination of |\mul| and |\div|. + +|\half| returns half the \m{integer expression}. It does better +rounding than |\scale|\arg{integer expression}|{500}| or +|\div|\arg{integer expression}|{2}|. + +|\otherhalf| returns the ``other half'' of the \m{integer +expression}, i.e., the sum of |\half| something and |\otherhalf| the +same thing is that thing back. + + +\subsection{Conditionals and loops} + +\Fontinst has a rather extensive family of conditionals (|\if|s), and +as of late also some convenient loop commands. The most common forms +of a \fontinst conditional are +\begin{decl*} + |\if|\dots \meta{argument(s)}|\then| \meta{then branch} |\Fi|\\ + |\if|\dots \meta{argument(s)}|\then| \meta{then branch} |\Else| + \meta{else branch} |\Fi| +\end{decl*} +i.e., \fontinst uses Plain\TeX\ style conditionals (with else and fi +control sequences) rather than \LaTeX\ style conditionals (with +separate arguments for the two branches). Every |\if|\dots\ command +can be thought of as testing some condition. +If the condition is true then the \meta{then branch} will be executed, +but not the \meta{else branch} (if there is one). +If the condition is false then the \meta{then branch} will not be +executed, but if there is an \meta{else branch} then that will be +executed. Conditionals may be nested (i.e., occur in the then or else +branch). + +\begin{hackernote} + The |\then| is not just syntactic sugar, but a functional part of + those conditionals which take arguments. Its purpose is to look + like an |\if| to \TeX\ when the conditional occurs in a skipped + branch of another conditional. +\end{hackernote} + +The most common conditionals are those which test if a variable is set. +\begin{decl*} + |\ifisint|\arg{int}|\then|\\ + |\ifisdim|\arg{dim}|\then|\\ + |\ifisstr|\arg{str}|\then|\\ + |\ifiscommand|\arg{command}|\then| +\end{decl*} +These cause the following \meta{then branch} to be executed if the +specified variable is set, and the \meta{else branch} to be executed +if the variable is not set. The \meta{int}, \meta{dim}, and +\meta{str} are string expressions for the names of an integer, +dimension, and string respectively variable. The \meta{command} is +the actual control sequence (command variable) that should be tested. + +\begin{decl} + |\ifisglyph|\arg{glyph}|\then| +\end{decl} +This similarly tests if a glyph (also a variable of a kind) is set in +the current glyph base. The glyph name \meta{glyph} is a string +expression. + +\begin{decl}[v1.917] + |\ifareglyphs|\marg{glyph list}|\then| +\end{decl} +This command tests whether all the glyphs in the \meta{glyph list} +(a comma-separated list of string expressions) are set in the current +glyph base. If one of the glyphs is not set then the condition is +false. + +\begin{decl}[v1.900] + |\ifnumber|\marg{integer expression}\meta{rel}% + \marg{integer expression}|\then| +\end{decl} +The \meta{rel} is one of \texttt{<}, \texttt{=}, and \texttt{>}. +This command evaluates the two \meta{integer expression}s and +then tests whether the specified relation holds between their values. + +\begin{decl}[v1.900] + |\ifiskern|\marg{glyph1}\marg{glyph2}|\then| +\end{decl} +This tests whether a kern has been set with \meta{glyph1} on the left +and \meta{glyph2} on the right (both arguments are string +expressions). This is almost the negation of +\begin{verbatim} + \ifnumber{\kerning{<glyph1>}{<glyph2>}}={0}\then +\end{verbatim} +but |\ifiskern| can distinguish the case that an zero kern has been +set (true) from the case that no such kern has been set (false), +which |\kerning| can not. It is however unlikely that this +distinction would ever be of use in a practical situation. + +\begin{decl}[v1.924] + |\ifoption|\marg{string}|\then| +\end{decl} +Test whether \meta{string} (a string expression) is among the current +list of options. This list is by default empty, elements are added +using |option| modifiers (cf.~the description of |\installfont|), and +the list is cleared for each new file for which one can specify +options. + +\begin{decl}[v1.909] + |\Else| + |\Fi| +\end{decl} +For \fontinst, these two control sequences are precisely the same as +the \TeX\ primitives |\else| and |\fi|, but things are a bit more +complicated in \fontdoc. The mechanism in \fontdoc\ that allows it to +present both branches of the conditional in the typeset output +requires that |\Else| and |\Fi| generate typeset output. See also the +|\showbranches| \fontdoc command. + +\begin{hackernote} + Before |\Else| and |\Fi| were introduced, the \TeX\ primitives + |\else| and |\fi| were used instead for \fontinst conditionals. + Back then, \fontdoc defined all conditionals to expand to |\iftrue|. + + It used to be the case that all conditionals would be fully + expandable (which in particular would have made it possible to use + them in string expressions), but that is no longer the case. +\end{hackernote} + +The \fontdoc formatter for visible branches treats an |\Else| +immediately followed by an `if' as an `else if', i.e., it assumes the +entire else branch consists of the conditional begun at that `if' and +leaves out one level of indentation. When that is not the case, you +will upon typesetting get a \LaTeX\ error about |\begin{IfBranchDummy}| +and |\end{IfBranch}|. In that case you need to help the formatter by +placing something between the |\Else| and the `if'; as it turns out +leaving an empty line there is sufficient (although just a single +newline is not). + + +\begin{decl}[v1.901] + |\for|\parg{name}\marg{start}\marg{stop}\marg{step} + \meta{body} |\endfor|\parg{name} +\end{decl} +will cause the \meta{body} code to be repeated some number of times. +How many depends on the values of \meta{start}, \meta{stop}, and +\meta{step}, which are integer expressions. + +As a precaution, the \meta{body} is not allowed to contain any +empty lines (|\par| tokens). If you want to have the visual +separation (for sakes of legibility or otherwise), put a |%| +somewhere on the line---that makes it nonempty. + +\meta{name} should consist of character tokens only. It is used as +the name of an integer variable, which will serve as loop variable. +This variable gets reset to the value of \meta{start} before the first +repetition of \meta{body code}. After each repetition but the last, +it is incremented by \meta{step}. \meta{body} gets repeated if +the value of \meta{name} has not gotten past that of \meta{stop}. To +get past means to be bigger if \meta{step} is positive and to be +smaller if \meta{step} is negative. In the case that \meta{step} is +zero, the entire construction above will be equivalent to +\begin{quote} + |\resetint|\marg{name}\marg{start}\\ + \meta{body} +\end{quote} + +|\for| \textellipsis\ |\endfor| constructions can be nested. +\meta{name} is used by |\for| to identify its matching |\endfor|, so +they need to be identical in |\for| and |\endfor|. \textbf{Note} that +the delimiters around the \meta{name} are parentheses, not braces. + + +\begin{decl}[v1.901] + |\foreach|\parg{name}\marg{csep-list} + \meta{body} |\endfor|\parg{name} +\end{decl} +will cause the \meta{body} code to be repeated one time for each item +in the \meta{csep-list}. \meta{csep-list} is a comma-separated list +of string expressions. + +As a precaution, the \meta{body} is not allowed to contain any +empty lines (|\par| tokens). If you want to have the visual +separation (for sakes of legibility or otherwise), put a |%| +somewhere on the line---that makes it nonempty. + +\meta{name} should consist of character tokens only. It is used as +the name of a string variable, which will serve as loop variable. +Before each repetition of the \meta{body code}, the loop variable will +get reset to the next item in the \meta{csep-list}. + +|\foreach|\textellipsis\ |\endfor| constructions can be nested. +\meta{name} is used by |\foreach| to identify its matching |\endfor|, +so they need to be identical in |\foreach| and |\endfor|. +\textbf{Note} that the delimiters around the \meta{name} are +parentheses, not braces. + + + +\subsection{Other general commands} + +\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}[v1.914] + |\needsTeXextension|\marg{extension tests}\marg{who} +\end{decl} +The |\needsTeXextension| command issues a warning if \fontinst is not +being run on one of the listed extensions of \TeX. This can be used to +protect files that make use of features not present in base \TeX. As +\meta{who} is preferably used the file name in which the command +occurs; it should be the answer to ``who is issuing this warning?'' + +An extension test is one of: +\begin{decl*} + |\eTeX|\marg{version number}\\ + |\pdfTeX|\marg{version number}\marg{revision} +\end{decl*} +Multiple tests in sequence are \textsc{or}'ed together. If you rather +need to \textsc{and} them, then use separate |\needsTeXextension| +commands. + +\begin{hackernote} + At present there is no test for Omega. This is really a shame, + because the extended character codes (outside the 0--255 range) + provided by Omega is the existing extension that would be most + useful for \fontinst, but Omega documentation does not give any + indication of how such a test should be implemented. Code + contributions are welcome. +\end{hackernote} + + +\begin{decl}[v1.915] + |\fontinstcc|\\ + |\normalcc| +\end{decl} +|\fontinstcc| switches to the catcodes used in e.g.\@ +\texttt{fontinst.sty}: |_| and |@| are letters, space and newline are +ignored, and |~| is a space. |\normalcc| switches back to normal +catcodes. + +\begin{decl}[v1.900] + |\begincomment| \meta{text} |\endcomment| +\end{decl} +This hides the \meta{text} from \fontinst processing, but allows it +to show up when the file is typeset with \fontdoc. + +\begin{decl}[v1.906] + |\fontinsterror|\marg{subsystem}\marg{error}\marg{help}\\ + |\fontinstwarning|\marg{subsystem}\marg{warning}\\ + |\fontinstwarningnoline|\marg{subsystem}\marg{warning}\\ + |\fontinstinfo|\marg{subsystem}\marg{info} +\end{decl} +General commands to convey information to the user, based on \LaTeX's +|\PackageError|, |\PackageWarning|, etc. + +\begin{decl}[v1.906] + |\messagebreak| +\end{decl} +Used to start a new line in an \meta{error}, \meta{help}, +\meta{warning}, or \meta{info} message. + + +Finally, there are two Plain\TeX\ commands which should be mentioned: +\begin{decl*} + |\input| \meta{file name}\\ + |\bye| +\end{decl*} +|\input| followed by a \meta{file name} (\emph{without} braces around) +is the recommended way of inputting a \fontinst command file, or the +\fontinst package itself (\texttt{fontinst.sty}, +\texttt{finstmsc.sty}, etc.). This is the only way to make things work +regardless of whether the underlying format is \LaTeX, Plain\TeX, or +even a raw Ini\TeX. + +|\bye| is the command to use to terminate a \fontinst command file. + + + + + +\section{Encoding files} + +An \emph{encoding file} (or \texttt{.etx} file) is a \TeX\ document +with the structure: +\begin{quote} + |\relax|\\ + \meta{ignored material}\\ + |\encoding|\\ + \meta{encoding commands}\\ + |\endencoding|\\ + \meta{ignored material} +\end{quote} +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. The structure is then +\begin{quote} + |\relax|\\ + |\documentclass{article} %| Or some other class\\ + |\usepackage{fontdoc}|\\ + \meta{\LaTeX\ preamble}\\ + |\begin{document}|\\ + \meta{\LaTeX\ text}\\ + |\encoding|\\ + \m{encoding commands}\\ + |\endencoding|\\ + \meta{\LaTeX\ text}\\ + |\end{document}| +\end{quote} + + +See also the descriptions in \emph{Writing ETX format font encoding +specifications} (\texttt{encspecs.tex}). + + +\subsection{Encoding commands} + +The \m{encoding commands} are: + +\begin{decl} + |\nextslot|\arg{integer expression} +\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. Immediately +after |\encoding|, the next slot number is $0$. + +\begin{decl}[v1.8] + |\skipslots|\arg{integer expressions} +\end{decl} +Advances the number of the next slot. + +\begin{decl} + |\setslot|\arg{glyph} \m{slot commands} |\endsetslot| +\end{decl} +Assigns \m{glyph} to the current slot. The \m{slot commands} can be +used to specify additional behaviour for the slot, and typically also +contains comments about the glyph. + +\begin{decl}[v1.9] + |\setleftboundary|\marg{glyph} \m{slot commands} + |\endsetleftboundary| +\end{decl} +Makes the beginning of a word (left boundary) behave like the right +side of \m{glyph} with respect to kerning. |\ligature| commands in +the \meta{slot commands} create beginning of word ligatures. + +\begin{decl}[v1.9] + |\setrightboundary|\marg{glyph} +\end{decl} +Makes the end of a word (right boundary) behave like the left +side of \m{glyph} with respect to kerning and ligatures. The current +slot position is left empty. + +\begin{decl} + |\inputetx|\arg{file} +\end{decl} +Inputs the \m{encoding commands} of \m{file}\texttt{.etx}. + +\begin{decl}[v1.917] + |\setfontdimen|\marg{fontdimen no.}\marg{integer variable} +\end{decl} +Sets up a correspondence between a font dimension and an integer +variable. When generating a font, the font dimension value is taken +from the integer variable. When converting a font from \pl or \vpl +format, the fontdimen value will be recorded as a |\setint| command +for the variable. + +\begin{decl}[v1.924] + |\ifdirect| +\end{decl} +Encoding files set up a correspondence between slot numbers and glyph +names, which can be used in two different ways. In the \emph{direct} +mode, encoding files map slot numbers to glyph names. In the +\emph{inverse} mode, glyph names are mapped to slot numbers. The +inverse mapping can in general be one-to-many, and when precisely one +target slot is needed \fontinst chooses that arbitrarily. The |\ifdirect| +conditional can be used to disambiguate the inverse mapping, by +conditionalising all undesired |\setslot|s on that the file is being +interpreted in the direct mode. For example: +\begin{verbatim} + \ifdirect + \setslot{hyphen} + \comment{Soft hyphen slot} + \endsetslot + \Else + \skipslots{1} + \Fi +\end{verbatim} + +Currently the only case in which encoding files are being read in +the inverse mode is when reencoding fonts. + +\begin{decl}[v1.8] + |\setslotcomment|\marg{text}\\ + |\resetslotcomment|\marg{text}\\ + |\unsetslotcomment| +\end{decl} +These commands can be used to specify an automatic |\comment| text +for all slots. They are ignored by \fontinst, but interpreted by +\fontdoc. + +\begin{decl}[v1.8] + |\useexamplefont|\marg{font} +\end{decl} +This command is ignored by \fontinst. In \fontdoc it sets the font +that is used by the |\slotexample| command. The \meta{font} argument +has the same syntax for a font as the \TeX\ primitive |\font|. + + + + +\subsection{Slot commands} + +The \m{slot commands} are: + +\begin{decl} + |\comment|\arg{text} +\end{decl} +A comment, which is ignored by \fontinst, but typeset as a separate +paragraph by \fontdoc. + +\begin{decl}[v1.917] + |\label|\arg{text} +\end{decl} +A reference label (like in \LaTeX), which records the slot number and +glyph name. Ignored by \fontinst. + +\begin{decl} + |\ligature|\arg{ligtype}\arg{glyph1}\arg{glyph2} +\end{decl} +|\ligature| declares a ligature of type \m{ligtype}, which will take +effect if the current glyph is immediately followed by \meta{glyph1} +when \TeX\ is constructing a list of horizontal material. This +ligature will then replace the two glyphs by the third glyph +\meta{glyph2}. For example: +\begin{verbatim} + \setslot{ff} + \comment{The `ff' ligature.} + \ligature{LIG}{i}{ffi} + \ligature{LIG}{l}{ffl} + \endsetslot +\end{verbatim} +declares one ligature \(\texttt{ff}*\texttt{i} \longrightarrow +\texttt{ffi}\) and one ligature \(\texttt{ff}*\texttt{l} +\longrightarrow \texttt{ffl}\). + +The eight \m{ligtype}s are the names of the underlying \pl +properties, i.e.,: +\begin{quote} + \texttt{LIG}\hfil + \texttt{/LIG}\hfil + \texttt{/LIG>}\hfil + \texttt{LIG/}\hfil + \texttt{LIG/>}\hfil + \texttt{/LIG/}\hfil + \texttt{/LIG/>}\hfil + \texttt{/LIG/>>} +\end{quote} +The basic \texttt{LIG} may be immediately preceded or followed by a +slash, and then immediately followed by \texttt{>} characters not +exceeding the number of slashes. The slashes specify retention of the +left or right original glyph; the \texttt{>} signs specify passing +over that many glyphs of the result without further ligature or kern +processing. + +\begin{decl}[v1.918] + |\Ligature|\arg{ligtype}\arg{glyph}\arg{glyph}\\ + |\oddligature|\marg{note}\arg{ligtype}\arg{glyph}\arg{glyph} +\end{decl} +The |\Ligature| command is by default a synonym of |\ligature| (but +\fontdoc may typeset them differently). The |\oddligature| command is +by default ignored by \fontinst. See \setfilename{encspecs.tex} for +an explanation of the semantic differences. + +\begin{decl} + |\makerightboundary|\arg{glyph} +\end{decl} +This makes the current slot the end of word (right boundary) marker +with respect to ligatures and kerning, i.e., \TeX\ will kern and +ligature as if there was an invisible occurrence of this character +after the last character of every word. All kerns and ligatures with +\meta{glyph} as the right part will apply for this slot. + +It is preferable to use |\setrightboundary| to control end of word +behaviour if you have an empty slot to spare. + +\begin{decl} + |\Unicode|\marg{code point}\marg{name}\\ + |\charseq|\marg{\cs{Unicode} commands} +\end{decl} +These commands declare a Unicode character or character sequence as +possible interpretations of what is in this slot. They are ignored +when making fonts, but \fontdoc give them a prominent role in +encoding specifications and to |\etxtocmap| they are the primary +properties of the slot. + +\begin{decl}[Obsolete?!] + |\usedas|\arg{type}\arg{control sequence} +\end{decl} +This command declares a \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} +There is currently no code in \fontinst which makes any use of this +command. It might in principle be possible to autogenerate \LaTeX\ +output encoding definition (\meta{enc}\texttt{enc.def}) files and +math symbol declarations from this information. + +\begin{decl} + |\nextlarger|\arg{glyph} +\end{decl} +Math font property: makes \meta{glyph} the \textsc{nextlarger} entry +of the current slot. + +\begin{decl} + |\varchar| + \m{varchar commands} + |\endvarchar| +\end{decl} +Math font property: sets the \textsc{varchar} entry for the current +slot, using the \m{varchar commands}. The possible \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}. + + +\subsection{Other} + +\begin{decl}[v1.9] + |\ifisinslot|\marg{glyph}\marg{slot}|\then| +\end{decl} +During \vpl\slash\pl generation, this conditional tests whether glyph +\meta{glyph} (a string expression) is put in the slot \meta{slot} (an +integer expression). Since encoding files are normally read several +times in that context, the exact behaviour of this command is a bit +uncertain. It was intended to support collecting additional +information about the fonts being generated, but at the time of +writing this is probably only of academic interest. + + +\begin{decl}[v1.931] + |\declarepsencoding|\marg{etx-name}\marg{PS-encoding-name}% + \marg{action} +\end{decl} +This command is placed in \etx files generated by |\enctoetx|, and has +the same syntax as in a mapmaking command file (see +Subsection~\ref{Ssec:MapConfig}). It records information about the +source encoding file to assist the map file writer, but is mostly +ignored by main \fontinst. + + + + +\section{Metric files} +\label{Sec:Metric} + + +A \emph{metric file} (or \mtx file) is a \TeX\ document with the +structure: +\begin{quote} + |\relax|\\ + \emph{ignored material}\\ + |\metrics|\\ + \m{metric commands}\\ + |\endmetrics|\\ + \emph{ignored material} +\end{quote} +This describes the glyphs in a font, using the \m{metric commands}. +Like encoding files, metric files can simultaneously be \LaTeX\ +documents. + +Metric files are usually either \emph{hand-crafted} or +\emph{transformable}. The transformable metric files typically encode +the metrics of one particular font and are automatically generated. +Hand-crafted metric files (such as \setfilename{latin.mtx}) typically +do not contain much explicit metric data, instead the code there makes +use of metrics previously specified by other files to construct new +glyphs or adjust metrics to meet special conditions. Whereas +transformable metric files tend to be mere lists of metric data, the +hand-crafted metric files are more like programs. + + +\subsection{Metric commands} + +The \m{metric commands} are as follows. All glyph name arguments are +string expressions. + +\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}, for example: +\begin{verbatim} + \setglyph{IJ} + \glyph{I}{1000} + \glyph{J}{1000} + \endsetglyph + + \setglyph{Asmall} + \glyph{A}{850} + \endsetglyph +\end{verbatim} +The \meta{glyph commands} are not executed if the glyph has already +been set. + +\begin{decl} + |\resetglyph|\arg{name} + \m{glyph commands} + |\endresetglyph| +\end{decl} +This builds a glyph using the \m{glyph commands}, and defines +(at~|\endresetglyph|) \meta{name} to be that glyph, regardless of +whether that glyph was already defined. + +\begin{decl} + |\unsetglyph|\arg{name} +\end{decl} +Makes the glyph called \m{name} undefined. + +\begin{decl} + |\setrawglyph|\arg{name}\arg{font}\arg{dimen}\arg{slot}\\ + \hspace*{1.5em}\arg{width}\arg{height}\arg{depth}\arg{italic + correction}\\ + |\setscaledrawglyph|% + \arg{name}\arg{font}\arg{dimen}\arg{scale}\arg{slot}\\ + \hspace*{1.5em}\arg{width}\arg{height}\arg{depth}\arg{italic + correction} +\end{decl} +These commands will usually be +generated automatically from an \afm or \pl file. +If the glyph \meta{name} is undefined, then this sets it to be that +which is found in slot \meta{slot} of font \meta{font}. The +\meta{width}, \meta{height}, \meta{depth}, and \meta{italic} are +saved away as the width, height, depth and italic correction +respectively of the glyph. + +The \meta{scale} is a scaling factor which has been applied to the +font to give it the specified metrics. +If the integer variable \texttt{rawscale} is set, another scaling by +that amount will be applied to the glyph (this is how the |scaled| +keyword in |\installfont| metrics-lists take effect). + +The \meta{dimen} is the nominal \emph{design size} of the \meta{font}, +usually |10pt|; this information isn't really needed for anything, but +the \vf format requires it to be specified and match what is in +\meta{font}\setfilename{.tfm}, so a \dvi driver is allowed to error +out on us if we don't get this value right. + + +\begin{decl} + |\setnotglyph|\arg{name}\arg{font}\arg{dimen}\arg{slot}\\ + \hspace*{1.5em}\arg{width}\arg{height}\arg{depth}\arg{italic + correction}\\ + |\setscalednotglyph|% + \arg{name}\arg{font}\arg{dimen}\arg{scale}\arg{slot}\\ + \hspace*{1.5em}\arg{width}\arg{height}\arg{depth}\arg{italic + correction} +\end{decl} +These set a glyph called \m{name}\texttt{-not} (if that wasn't set +already) to have the specified width, height, depth, and italic +correction but be invisible in print. + +Such commands are usually generated automatically from an \afm file, +when a glyph is present in the \m{font} but is not in the default +encoding. They take the same arguments as |\setrawglyph| and +|\setscaledrawglyph| respectively (although the \meta{slot} will +normally be |-1|), because +reencoding a font can turn |\setrawglyph| commands into +|\setnotglyph| commands and vice versa. + + +\begin{decl} + |\inputmtx|\arg{file} +\end{decl} +Inputs the \m{metric commands} of \m{file}\texttt{.mtx}. + +\begin{decl}[v1.9] + |\usemtxpackage|\marg{package~list}\\ + |\ProvidesMtxPackage|\marg{package~name} +\end{decl} +|\usemtxpackage| behaves like |\inputmtx|, but it will only input a +file if no |\ProvidesMtxPackage| for that file has been issued. By +putting a |\ProvidesMtxPackage| in an \mtx file one can |use| it in +several places without having to worry about it being sourced more +than once. + +\begin{hackernote} + |\ProvidesMtxPackage| declarations make local assignments, so the + package is forgotten when the current group ends. In particular, the + settings made with |\ProvidesMtxPackage| are forgotten when the + current glyph base is flushed. +\end{hackernote} + + + +\subsection{Glyph commands} + +The \m{glyph commands} add material to the glyph currently being +constructed in a |\setglyph| \dots\ |\endsetglyph| or +|\resetglyph| \dots\ |\endresetglyph|. They 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{string expression} +\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{string expression} +\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}, but at the |\pop| the current +position and glyph width are restored to what they were at the |\push|, +for example: +\begin{verbatim} + \setglyph{aacute} + \push + \movert{\half{\sub{\width{a}}{\width{acute}}}} + \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} + \small + |\push|\\ + |\movert|\arg{first integer expression}\\ + |\moveup|\arg{second integer expression}\\ + |\glyph|\arg{glyph}|{1000}|\\ + |\pop| +\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}. + +\bigskip + +Inside a |\setglyph| definition of \m{glyph}, you can use expressions +such as |\width|\arg{glyph} to 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} + + +\subsection{Kerning commands} + +The kerning commands may be used anywhere in a metrics file. + +\begin{decl} + |\setkern|\arg{glyph}\arg{glyph}\arg{integer expression} +\end{decl} +This sets a kern between the two glyphs, scaled by the current +value of \texttt{rawscale}, unless such a kern already has been set. + +\begin{decl}[v1.9] + |\resetkern|\arg{glyph}\arg{glyph}\arg{integer expression} +\end{decl} +|\resetkern| unconditionally sets a kern between the two glyphs, +scaled by the current value of \texttt{rawscale}. + +\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} +The commands work by copying kerning pairs containing the first glyph. +As the names indicates, these commands do not override kerning pairs +previously set. + +\begin{decl}[v1.8] + |\setleftrightkerning|\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 both sides, for example: +\begin{verbatim} + \setleftrightkerning{Asmall}{A}{850} +\end{verbatim} +This command is equivalent to doing first a |\setleftkerning| and +then a |\setrightkerning|. + +\begin{decl}[v1.906] + |\noleftkerning|\arg{glyph}\\ + |\norightkerning|\arg{glyph}\\ + |\noleftrightkerning|\arg{glyph} +\end{decl} +Removes all kerning on the specified side(s) of the \meta{glyph}. + +\begin{decl}[v1.9] + |\unsetkerns|\marg{left~glyph~list}\marg{right~glyph~list} +\end{decl} +Removes all kerns with one glyph in the \meta{left glyph list} on the +left and one glyph in the \meta{right glyph list} on the right. + + + +\subsection{Other} + +\begin{decl}[v1.915] + |\aliased|\marg{font's name}\marg{alias name} +\end{decl} +This command, which syntactically counts as a \meta{string +expression}, is meant to be used in glyph name arguments of commands +one may find in metric files. It was added to support combining +mapfile entry generation with a custom form of reglyphing that has +been developed for the \texttt{T2} bundle (Cyrillic font support). +This does however not necessarily mean that the \texttt{T2} bundle +has been updated to take advantage of this feature. + +The basic problem is that cyrillic fonts display a much greater +variation in how the glyphs are named than latin fonts do.% +\footnote{The Adobe guidelines have not been as prevailing here as +in the latin range, but this isn't entirely surprising when they +give opaque suggestions such as using the name \texttt{afii10018} +for \texttt{U+0411} (\textsc{cyrillic capital letter be}). The +suggestion made some sense though; AFII (Association for Font +Information Interchange) maintained a glyph registry.} +This complicates writing files similar to \setfilename{latin.mtx}, so +the author of the \texttt{T2} bundle took the route to regularize the +glyph names at the \afm to \mtx conversion step. Since \TeX\ does not +know anything about glyph names, this makes no difference for the +virtual fonts that are built. +The glyph names do however make a difference for base fonts that are +reencoded, since \PS encoding vectors list explicit glyph names that +have to be the same as in the font. \Fontinst's choice of encoding +vector for a mapfile entry is based on which \etx file was used in the +reencoding, and hence the glyph names used when reencoding must match +those actually used in the font, or problems will follow. + +The |\aliased| command can be used to preserve the information +necessary for such reencodings. If a glyph name is specified as for +example +\begin{verbatim} + \aliased{afii10018}{CYRB} +\end{verbatim} +then \fontinst will behave as if the glyph name is \texttt{CYRB} +(i.e., the \meta{alias name}) for all purposes \emph{except} +reencoding, where instead \fontinst behaves as if the glyph name is +the \meta{font's name} \texttt{afii10018}. This makes it possible to +use \etx files when reencoding which can be correctly translated to +the right encoding vectors. + + +\begin{decl}[v1.931] + |\providepsencoding|\marg{etx}\marg{postscript name}\marg{action} +\end{decl} +If this command occurs in an \mtx file then it was placed there by a +|\declare|\-|ps|\-|encoding| in an \etx file that was used to +reencode this \mtx. It is meant for consumption by the mapfile writer, +and is ignored by main \fontinst. + + + +\section{\textsf{fontdoc} commands} + +The following commands are defined by \fontdoc but are unknown to +\fontinst. + + +\subsection{Comment commands} + +\begin{decl} + |\plaindiv|\\ + |\plainint|\\ + |\plainmax|\\ + |\plainmin|\\ + |\plainneg| +\end{decl} +These are the \LaTeX\ definitions of |\div|, |\int|, |\max|, |\min|, +and |\neg| respectively. They are provided under these names because +\fontinst uses the normal names for integer expression constructions. + +\begin{decl}[v1.8] + |\slotexample| +\end{decl} +This typesets the character in the current slot from the example font +(cf.~|\use|\-|example|\-|font|). + +\begin{decl}[v1.916] + |\macroparameter|\marg{digit} +\end{decl} +This can be used in integer and string expressions. It typesets as +\textit{\#n}, where `\textit{n}' is the \meta{digit}. + +\begin{decl}[v1.918] + |\textunicode|\marg{code point}\marg{name} +\end{decl} +This generates a reference to a particular Unicode character, for use +within a |\comment| or similar. + + +\subsection{Style control commands} + +\begin{decl}[v1.909] + |\showbranches| +\end{decl} +The is the main switch that turns on displaying both branches of +\fontinst conditionals. If you use this command in an encoding or +metrics file, you \textbf{must} use |\Else| and |\Fi| to delimit the +conditionals in that file. If you do not use this command in an +encoding or metrics file, then the conditionals will not generate any +typeset material and neither will their \meta{else branch}es. + + + + +\section{\fontinst variables} +\label{Sec:Variables} + +The following is a list of the \fontinst variables that are +accessible for the user through the |\set|\textellipsis, +|\reset|\textellipsis, |\unset|\textellipsis, etc.\ commands. You may +of course set or use other variables in the \mtx and \etx files you +write yourself, as does for example the standard \mtx file +\texttt{latin.mtx}, but all variables that \fontinst commands +implicitly use or set are listed below. + +% \begin{list}{}{% +% \setlength\labelwidth{0pt}% +% \setlength\itemindent{-\leftmargin}% +% \setlength\parsep{0pt} +% \def\makelabel#1{\hspace\labelsep \normalfont\ttfamily #1}% +% } +\begin{itemize} + \item[acccapheight] (integer denoting length) + \begin{smalldes} + \item[Description] The height of accented full capitals. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[address] (string) + \begin{smalldes} + \item[Description] Snailmail address put in \BibTeX-style file + header of automatically generated \enc files. No + \texttt{address} field is written unless the \texttt{address} + string is set. Quotes are not automatically inserted around + the \texttt{address} string. + \item[Set by] \etx files. + \item[Used by] The \etx-to-\enc converter. + \end{smalldes} + \item[afm-name] (string) + \begin{smalldes} + \item[Description] Name of source font. Internal variable. + \item[Set by] |\from|\dots\ commands. + \item[Used by] The |\transform|\-|font|, |\install|\-|font|, + |\install|\-|raw|\-|font|, and |\reglyph|\-|font| commands. + \end{smalldes} + \item[ascender] (integer denoting length) + \begin{smalldes} + \item[Description] The ascender height of the font. + \item[Set by] \mtx files. The \afm-to-\mtx converter usually writes + |\setint| commands for this integer. + \item[Used by] Some \mtx and \etx files. + \end{smalldes} + \item[author] (string) + \begin{smalldes} + \item[Description] Author name(s) put in \BibTeX-style file + header of automatically generated \enc files. See the macro + |\ref_to_sourcefile| for more details. + \item[Set by] \etx files. + \item[Used by] The \etx-to-\enc converter. When not set, the + value \texttt{"See file }\meta{etx name}\texttt{"} is used + instead. + \end{smalldes} + \item[\cs{autoinstallfamily}] (command) + \begin{smalldes} + \item[Description] Command called by the font installation + commands, as + \begin{quote} + |\autoinstallfamily|\marg{encoding}\marg{family} + \end{quote} + when they are asked to install a font with a combination of + \meta{encoding} and \meta{family} that has not been seen + before (there was no explicit |\installfamily|). + \item[Set by] Explicit commands. Defaults to calling + |\installfamily|. + \item[Used by] Font installation commands. + \end{smalldes} + \item[axisheight] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{22}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[baselineskip] (integer denoting length) + \begin{smalldes} + \item[Description] + The font designer's recommendation for natural length of the + \TeX\ parameter |\baselineskip|. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[bigopspacing1] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\xi\sb{9}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[bigopspacing2] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\xi\sb{10}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[bigopspacing3] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\xi\sb{11}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[bigopspacing4] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\xi\sb{12}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[bigopspacing5] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\xi\sb{13}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[capheight] (integer denoting length) + \begin{smalldes} + \item[Description] The height of the font's full capitals. + \item[Set by] \mtx files. The \afm-to-\mtx converter usually writes + |\setint| commands for this variable. + \item[Used by] Some \mtx and \etx files. + \end{smalldes} + \item[cmapname] (string) + \begin{smalldes} + \item[Description] The name given to the CMap generated from + an \etx file. + \item[Set by] \etx files. + \item[Used by] The \etx-to-CMap converter. When not set, the + value |fontinst-|\nolinebreak[1]\meta{cmap file name} is + used instead. + \end{smalldes} + \item[codingscheme] (string) + \begin{smalldes} + \item[Description] The codingscheme name. + \item[Set by] \etx files. + \item[Used by] The \cvpl writer. When not set, the + value \texttt{UNKNOWN} is used instead. + \end{smalldes} + \item[defaultrulethickness] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\xi\sb{8}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[delim1] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{20}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[delim2] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{21}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[denom1] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{11}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[denom2] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{12}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[descender] (integer denoting length) + \begin{smalldes} + \item[Description] The depth of lower case letters with descenders. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[descender\_neg] (integer denoting length) + \begin{smalldes} + \item[Description] The vertical position of the descender line + of the font, i.e., the negative of the font's descender depth. + \item[Set by] \mtx files. The \afm-to-\mtx converter usually writes + |\setint| commands for this variable. + \item[Used by] Some \mtx and \etx files. + \end{smalldes} + \item[designsize] (dimension) + \begin{smalldes} + \item[Description] The design size of the font. + \item[Set by] \mtx files. The \cvpl-to-\mtx converter usually writes + |\setdim| commands for this variable. + \item[Used by] The \cvpl writer. The design size defaults to + $10\,\mathrm{pt}$ if this variable is not set. + \item[Note] The value of this variable has no effect on how + the font is declared to \LaTeX. + \end{smalldes} + \item[designunits] (dimension denoting a real number) + \begin{smalldes} + \item[Description] The design size of a font expressed in the + design unit used in a \cvpl file. + \item[Set by] \mtx files. The \cvpl-to-\mtx converter usually writes + |\setdim| commands for this variable. + \item[Used by] Nothing. If this variable is set, but to any + value other than $1\,\mathrm{pt}$, then some metrics are most + likely wrong. + \end{smalldes} + \item[digitwidth] (integer denoting length) + \begin{smalldes} + \item[Description] The median width of the digits in the font. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[email] (string) + \begin{smalldes} + \item[Description] Email address put in \BibTeX-style file + header of automatically generated \enc files. See the macro + |\ref_to_sourcefile| for more details. + \item[Set by] \etx files. + \item[Used by] The \etx-to-\enc converter. When not set, the + value \texttt{"See file }\meta{etx name}\texttt{"} is used + instead. + \end{smalldes} + \item[encodingname] (string) + \begin{smalldes} + \item[Description] The name by which the encoding in question is + made known to a Postscript interpreter. + \item[Set by] \etx files. + \item[Used by] The \etx-to-\enc converter. When not set, the + value |fontinst-|\nolinebreak[1]|autoenc-|\nolinebreak[1]% + \meta{etx name} is used instead. + \end{smalldes} + \item[etx-name] (string) + \begin{smalldes} + \item[Description] Name of \etx file. Internal variable in + |\transform|\-|font|. + \item[Set by] The |\reencodefont| command. + \item[Used by] The |\mtxtomtx| command. + \end{smalldes} + \item[extraspace] (integer denoting length) + \begin{smalldes} + \item[Description] + The natural width of extra interword glue at the end of a + sentence. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[fontdimen($n$)] (integer) + \begin{smalldes} + \item[Description] Family of semi-internal variables that store + the values to use for font dimension $n$. It is preferred + that the newer |\set|\-|font|\-|dimen| interface is used for + setting these values. + \item[Set by] \etx files. + \item[Used by] The \cvpl writer. + \end{smalldes} + \item[\cs{iftokeep}] (macro) + \begin{smalldes} + \item[Description] |\iftokeep|\,\#1\,|\then|, where \#1 will + be a \meta{number}, behaves like a switch and decides whether + a glyph is kept or not while reglyphing. + \item[Set by] Explicit commands. Defaults to + $$ + \mbox{\cs{iftokeep}\,\#1\,\cs{then}} \mapsto + \mbox{\cs{ifnum}\,\texttt{-1<}\#1} + $$ + \item[Used by] The |\reglyphfont| command. + \end{smalldes} + \item[interword] (integer denoting length) + \begin{smalldes} + \item[Description] The natural width of interword glue (spaces). + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[italicslant] (integer denoting factor) + \begin{smalldes} + \item[Description] The italic slant of a font. + \item[Set by] \mtx files generated from \afm or \cvpl files. \mtx + files generated by |\transformfont|. Locally in the \afm-to-\mtx + converter for possible use in |\uprightitalcorr| or + |\slanteditalcorr|. + \item[Used by] \mtx files (\texttt{latin.mtx} and the like). \etx + files (for determining \texttt{fontdimen(1)}). + \end{smalldes} + \item[killweight] (integer) + \begin{smalldes} + \item[Description] Weight for glyphs that are killed. + \item[Set by] Explicit commands. Defaults to $-10$ if not set. + \item[Used by] The |\kill|\-|glyph| command; indirectly + the |\reglyphfont| command. + \end{smalldes} + \item[letterspacing] (integer denoting length) + \begin{smalldes} + \item[Description] Extra width added to all glyphs of a font. + \item[Set by] \mtx (preferred) or \etx files. + \item[Used by] The \cvpl writer. Defaults to $0$ if not set. + \end{smalldes} + \item[maxdepth] (integer denoting length) + \begin{smalldes} + \item[Description] The maximal depth over all slots in the font. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[maxdepth\_neg] (integer denoting length) + \begin{smalldes} + \item[Description] The negative of the maximal depth of a glyph in + the font. + \item[Set by] \mtx files. The \afm-to-\mtx converter usually writes + |\setint| commands for this variable. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[maxheight] (integer denoting length) + \begin{smalldes} + \item[Description] The maximal height of a glyph in the font. + \item[Set by] \mtx files. The \afm-to-\mtx converter usually writes + |\setint| commands for this variable. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[minimumkern] (integer denoting length) + \begin{smalldes} + \item[Description] Kerns whose size in absolute value is less + than or equal to this variable are ignored. + \item[Set by] Command files or \mtx files. + \item[Used by] The \afm-to-\mtx converter and the \cvpl file + generator. When not set, the value $0$ is used instead. + \end{smalldes} + \item[monowidth] (flag integer) + \begin{smalldes} + \item[Description] Set if this font is monowidth, unset otherwise. + \item[Set by] \mtx files. The \afm-to-\mtx converter writes a + |\setint| command for this variable if the \afm specifies + \texttt{IsFixedPitch true}. + \item[Used by] Some \mtx files (\texttt{latin.mtx} and the like), + \etx files. + \end{smalldes} + \item[num1] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{8}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[num2] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{9}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[num3] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{10}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[quad] (integer denoting length) + \begin{smalldes} + \item[Description] + The quad width of the font, normally approximately equal to + the font size and\slash or the width of an `M'. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \item[Note] + It is the quad width in the symbol math font (family~|2|) + that \TeX\ uses as reference when translating |mu|s to + ordinary lengths. Hence that quad can be considered a math + font designer's scaling factor for |mu|. + \end{smalldes} + \item[PSfontsuffix] (string) + \begin{smalldes} + \item[Description] Suffix added to font names to form name of + file to download to include font. + \item[Set by] Explicit commands in mapmaking command + files. Defaults to `\texttt{.pfa}'. + \item[Used by] The map file fragments writer. + \end{smalldes} + \item[rawscale] (integer denoting factor) + \begin{smalldes} + \item[Description] Scaling factor applied to raw glyphs. + \item[Set by] The |\installfont| command (\texttt{scaled} + clauses in argument \#2). Unset for metric files listed + without a \texttt{scaled} clause. + \item[Used by] The |\set|\-|raw|\-|glyph|, + |\set|\-|not|\-|glyph|, |\set|\-|scaled|\-|raw|\-|glyph|, + |\set|\-|scaled|\-|not|\-|glyph|, |\set|\-|kern|, and + |\reset|\-|kern| commands. + \end{smalldes} + \item[renameweight] (integer) + \begin{smalldes} + \item[Description] Weight for glyphs that are renamed. + \item[Set by] Explicit commands. Defaults to $1$ if not set. + \item[Used by] The |\rename|\-|glyph| command; indirectly + the |\reglyphfont| command. + \end{smalldes} + \item[requireglyphs] (flag integer) + \begin{smalldes} + \item[Description] Set if warnings are to be generated for + glyphs listed in \etx files but not present in the glyph + base. + \item[Set by] Explicit commands. By default not set. + \item[Used by] The \cvpl file generator. + \end{smalldes} + \item[rightboundary] (string) + \begin{smalldes} + \item[Description] The name of a glyph with the property that + kerns on the left may be intended as right word boundary kerns. + \item[Set by] \mtx files. The \cvpl-to-\mtx converter can write + |\setstr| commands for this variable. + \item[Used by] Some \mtx files. + \end{smalldes} + \item[shrinkword] (integer denoting length) + \begin{smalldes} + \item[Description] + The (finite) shrink component of interword glue. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[slant-scale] (integer denoting factor) + \begin{smalldes} + \item[Description] Factor to slant by. + Internal variable in |\transform|\-|font|. + \item[Set by] The |\slant|\-|font|, |\xscale|\-|font|, and + |\scale|\-|font| commands. + \item[Used by] The |\mtxtomtx| command. + \end{smalldes} + \item[\cs{SlantAmount}] (macro expanding to an integer expression) + \begin{smalldes} + \item[Description] Slant factor used for faking oblique shape. + \item[Set by] Explicit commands. Defaults to \texttt{167}. + \item[Used by] The |\latinfamily| command. + \end{smalldes} + \item[\cs{slanteditalcorr}] + (macro expanding to an integer expression) + \begin{smalldes} + \item[Description] The integer expression used to calculate a + guess for the italic correction of glyphs in a font with + positive slant. It has the syntax + \begin{quote} + \cs{slanteditalcorr}\marg{width}\marg{left}\marg{right}% + \marg{bottom}\marg{top} + \end{quote} + where \meta{width} is the glyph's advance width, and the + remaining arguments are coordinates of sides of the glyph's + bounding box. The \texttt{italicslant} integer provides the + italic slant of the font. + \item[Set by] Explicit commands in \textsf{fontinst} command + files. Defaults to + $$ + \max\{0, \mathit{right}-\mathit{width}\}. + $$ + \item[Used by] The \afm-to-\mtx converter. + \end{smalldes} + \item[stretchword] (integer denoting length) + \begin{smalldes} + \item[Description] + The (finite) stretch component of interword glue. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[sub1] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{16}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[sub2] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{17}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[subdrop] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{19}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[sup1] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{13}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[sup2] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{14}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[sup3] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{15}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[supdrop] (integer denoting length) + \begin{smalldes} + \item[Description] Math formula parameter $\sigma\sb{18}$. + \item[Set by] \mtx files. + \item[Used by] Some \etx and \mtx files. + \end{smalldes} + \item[TFMfileprefix] (string) + \begin{smalldes} + \item[Description] Prefix (typically a path) added to names of + TFM files. + \item[Set by] Explicit commands in mapmaking command + files. By default not set, which is equivalent to being empty. + \item[Used by] The \texttt{pltotf} ``map file fragments writer''. + \end{smalldes} + \item[underlinethickness] (integer denoting length) + \begin{smalldes} + \item[Description] The recommended thickness of an underlining + rule. + \item[Set by] \mtx files. The \afm-to-\mtx converter usually writes + |\setint| commands for this variable. + \item[Used by] Some \mtx files (\texttt{latin.mtx} and the like). + \end{smalldes} + \item[\cs{uprightitalcorr}] + (macro expanding to an integer expression) + \begin{smalldes} + \item[Description] The integer expression used to calculate a + guess for the italic correction of glyphs in a font with + non-positive slant. It has the syntax + \begin{quote} + \cs{uprightitalcorr}\marg{width}\marg{left}\marg{right}% + \marg{bottom}\marg{top} + \end{quote} + where \meta{width} is the glyph's advance width, and the + remaining arguments are coordinates of sides of the glyph's + bounding box. The \texttt{italicslant} integer provides the + italic slant of the font. + \item[Set by] Explicit commands in \textsf{fontinst} command + files. Defaults to $0$. + \item[Used by] The \afm-to-\mtx converter. + \end{smalldes} + \item[version] (string) + \begin{smalldes} + \item[Description] Version number put in \BibTeX-style file + header of automatically generated \enc files. See the macro + |\ref_to_sourcefile| for more details. + \item[Set by] \etx files. + \item[Used by] The \etx-to-\enc converter. When not set, the + value \texttt{"See file }\meta{etx name}\texttt{"} is used + instead. + \end{smalldes} + \item[verticalstem] (integer denoting length) + \begin{smalldes} + \item[Description] The dominant width of vertical stems + (usually the width of stems of lower case letters). + \item[Set by] \mtx files. The \afm-to-\mtx converter writes + |\setint| commands for this variable if the \afm file specifies + \texttt{StdVW}. + \item[Used by] Currently nothing. + \end{smalldes} + \item[\texttt{warningspecials}] (switch) + \begin{smalldes} + \item[Description] Controls whether |\glyphwarning| commands + will generate \vpl \texttt{SPECIAL}s. Defaults to `true'. + \item[Set by] Explicit commands (|\warningspecialstrue| and + |\warningspecialsfalse|). + \item[Used by] The \cvpl file generator. + \end{smalldes} + \item[x-scale] (integer denoting factor) + \begin{smalldes} + \item[Description] Horizontal scaling factor. + Internal variable in |\transform|\-|font|. + \item[Set by] The |\xscale|\-|font| and |\scale|\-|font| commands. + \item[Used by] The |\mtxtomtx| command. + \end{smalldes} + \item[xheight] (integer denoting length) + \begin{smalldes} + \item[Description] The x-height of the font. + \item[Set by] \mtx files. The \afm-to-\mtx and \cvpl-to-\mtx + converters usually write |\setint| commands for this variable. + \item[Used by] \mtx files, and \etx files (for determining + \texttt{fontdimen(5)}). + \end{smalldes} + \item[y-scale] (integer denoting factor) + \begin{smalldes} + \item[Description] Vertical scaling factor. + Internal variable in |\transform|\-|font|. + \item[Set by] The |\yscale|\-|font| and |\scale|\-|font| commands. + \item[Used by] The |\mtxtomtx| command. + \end{smalldes} + \item[\meta{\rmfamily glyph}-spacing] (integer denoting length) + \begin{smalldes} + \item[Description] Glyph-specific override for + \texttt{letterspacing}; extra width added to the glyph + \meta{glyph} as part of the process of writing a \vpl + file. + \item[Set by] \etx or \mtx files. + \item[Used by] The \cvpl writer. Defaults to $0$ if not set. + \end{smalldes} +\end{itemize} +% \end{list} +Besides these, the |\latinfamily| command provides a whole range of +helper macros (|\latin_weights|, |\latin_widths|, |\latin_shapes|, +etc.) that are often used somewhat like variables. That subject +does however deserve to be treated separately. + + + +\section{Customisation} + +The \fontinst package reads a file \texttt{fontinst.rc} if it +exists. This can contain your own customisations. The catcodes that +are in force when this file is read are the same as those selected by +|\fontinstcc|. + +Similarly \texttt{finstmsc.sty} reads \texttt{finstmsc.rc} and the +\fontdoc package reads \texttt{fontdoc.cfg}. + +You can create a \texttt{fontinst} format by running ini\TeX{} on +\texttt{fontinst.sty} then saying \verb|\dump|. + + +\section{Notes on features new with v\,1.9} + +The following notes are copied from \texttt{fisource.tex}; they were +written to explain new \fontinst features to old \fontinst users. + + +\subsection{Metric packages} + +\Fontinst has traditionally come with a collection of \mtx +files that complement the \mtx files generated from base font metrics, +in that they build glyphs that may be missing from the base fonts or +in some other way needs to be improved. The most well-known of these +is the \texttt{latin.mtx} file; other examples include +\texttt{textcomp.mtx}, \texttt{mathit.mtx}, and \texttt{latinsc.mtx}. +A problem with these is however that they cannot produce optimal +results for all fonts simply because there are irregular differences +in how fonts are set up by the foundries. Most glyphs come out all right, +but there are usually a few for which the parameters used are more or +less wrong. Therefore most high quality font installations are made +with modified versions of these files, where the parameters have been +tuned to the specific font design. + +Modifying in particular \texttt{latin.mtx} is however not an entirely +easy task, because this is a rather large file (with plenty of +archaic pieces of code in curious places). Doing it once is no big +problem, but if one has to do it several times (maybe because some +errors are discovered in the original \texttt{latin.mtx}) then it is +probably no fun anymore. Furthermore, if one has two or three +modified copies of this file because one has made high quality +installations of that many different fonts then even a trivial bugfix +might start to feel like entirely too much work. + +If one has to make modifications then it is usually easier to deal +with several small files (many of which can be used unchanged) than +one big file. Thus it would be better if these big files were split up +into several smaller ones. +The main problem with splitting up something like \texttt{latin.mtx} +is that there are some commands which are defined at the top and +which are then used in almost all sections of the file. One must make +certain that these commands are always loaded, which makes the metric +files somewhat harder to use (especially if the one who tries to use +them is not the one who wrote them). + +One strategy is to include all definitions needed for a metric file in +it. This has the slight disadvantage that the commands will have to be +defined several times. What is worse however, is that the command +definitions will appear in several files, so if one finds a bug in one +of them, one cannot simply correct this bug in one place. As the number +of files can soon become quite large, correcting such bugs can become +a boring procedure indeed. + +Another strategy is to put all the command definitions in one file +and then explicitly include it in the \meta{file-list} argument of +|\installfont|. This eliminates the repeated bug fixing problem, but +requires the user to do something that the computer can actually do +just as well. + +A third strategy is to put the command definitions in one or several +files and then in each metric file the user explicitly mentions load +the command definitions needed for that particular file. Metric +packages uses an improved version of this strategy, since they also +make it possible for \fontinst to remember which packages (i.e., sets +of command definitions) that have already been loaded, so that they +are not unnecessarily loaded again. The \texttt{newlatin.mtx} file is +an alternative to \texttt{latin.mtx} that implements this strategy. +Most of the actual code is located in the following metric packages: +\begin{center} +\begin{tabular}{l p{0.7\linewidth}} + \texttt{ltcmds.mtx}& Defines some common commands used by the other + files.\\ + \texttt{llbuild.mtx}& Builds the latin lower case alphabet + (unaccented letters are `unfakable', the rest are constructed if + not present in the base fonts).\\ + \texttt{lubuild.mtx}& Builds the latin upper case alphabet.\\ + \texttt{lsbuild.mtx}& Builds accented letters in the latin + smallcaps alphabet, but only if there are unaccented letters to + build them from in the base fonts.\\ + \texttt{lsfake.mtx}& Fakes a latin smallcaps alphabet by shrinking + the upper case alphabet, but only if the glyph had not already + been manufactured.\\ + \texttt{lsmisc.mtx}& Make some miscellaneous smallcaps glyphs + (mostly ``smallcaps f-ligatures'').\\ + \texttt{ltpunct.mtx}& Makes digits, punctuation marks, and other + symbols (mostly by marking as ``unfakable''). +\end{tabular} +\end{center} +\noindent All of these are easy to use as components of equivalents +of a modified \texttt{latin.mtx} files, and all dependencies of one +package upon another are handled via explicit |\usemtxpackage| +commands. + +% For information on the syntax etcetera of commands related to metric +% packages, see Section~\ref{Sec:Metric files}. + + +\subsection{Word boundary ligatures and kerns} + +One of the new features added in \TeX~3 was that of ligatures and +kerns with word boundaries. \Fontinst has had an interface +for making such ligatures and kerns, but it has been completely +redesigned in v\,1.9 and the old interface (setting the integer +|boundarychar|) is no longer recognized by \fontinst. Files +which use the old interface can still be processed with +\texttt{cfntinst.sty}, though. + +Before considering the new commands, it is suitable to make a +distinction between proper glyphs and pseudoglyphs. A proper glyph has +been set using one of the commands |\setrawglyph|, |\setglyph|, and +|\resetglyph|. A pseudoglyph is any name used in the context of a +glyph name which does not denote a proper glyph. If a pseudoglyph +|g-not| was set using the |\setnotglyph| command, then +|\ifisglyph{g-not}\then| will evaluate to true, but something can be +a pseudoglyph even if an |\ifisglyph| test evaluates to false. The +interesting point about pseudoglyphs when considering word boundaries +however, is that a pseudoglyph can have ligatures and kerns. + +Kerns and ligatures at the left word boundary (beginning of word) are +specified using the commands |\setleftboundary| and +|\endsetleftboundary|, which are syntactically identical to +|\setslot| and |\endsetslot| respectively. One important difference is +however that the argument to |\setslot| must be a proper glyph, while +the argument to |\setleftboundary| may be any glyph, hence any +pseudoglyph will do just fine. + +|\ligature| commands between |\setleftboundary| and +|\endsetleftboundary| will generate beginning of word ligatures. Kerns +on the right of the glyph specified in |\setleftboundary| will become +beginning of word kerns. + +Kerns and ligatures at the right word boundary (end of word) are +trickier, due to the asymmetrical nature of the ligkern table in a \pl +file. What a font can do is to specify that the right word boundary, +for purposes of kerning and ligatures, should be interpreted as +character $n$. By including a kern or ligature with character $n$ on +the right, that kern or ligature will be used at the end of a word, +but it will also be used each time the next character is character +$n$. Because of this, one usually wants the slot $n$, which the right +word boundary is interpreted as being, to be empty whenever the +encoding allows this. + +The command +\begin{quote} + |\setrightboundary|\marg{glyph} +\end{quote} +will mark the current slot as used to denote the right word boundary, +and leave the slot empty, increasing the current slot number by one +just like a |\setslot| \textellipsis\ |\endsetslot| block does. Kerns on +the left of \meta{glyph} will be end of word kerns and |\ligature| +commands with \meta{glyph} as the second argument will be for the end +of a word. + +The command +\begin{quote} + |\makerightboundary|\marg{glyph} +\end{quote} +is similar to |\setrightboundary|, but it is a slot command which may +only be used between a |\setslot| and the matching |\endsetslot|. Like +|\setrightboundary|, it marks the current slot as used to denote the +right word boundary, but the glyph specified in the enclosing |\setslot| +will be written to that slot. Ligatures for the glyph specified by the +|\setslot| and ligatures for the glyph specified by the +|\makerightboundary| will both be for this single slot. Kerns on the +right of the |\setslot| glyph and the |\makerightboundary| glyph will +similarly both be for this single slot. The idea is that the |\setslot| +glyph should be used when making a kern or ligature for that glyph, +while the |\makerightboundary| glyph should be used when making a kern +or ligature for the end of a word. \Fontinst will warn you if +these two uses of the slot directly contradict each other. + + +\subsection{Changing the names of glyphs} +\label{Ssec:Des:Reglyph} + +Sometimes, primarily when making a virtual font from more than one raw +font and two of the raw fonts contain different glyphs with the same +name, it becomes necessary to change the names of some glyphs to make +some sense out of it. The main source of this kind of trouble is the +``caps and small caps'' (SC) and ``oldstyle figures'' (OsF) fonts +within many commercial font families. The typical problem is that what +is typographically different glyphs---such as the lowercase `a' +(\texttt{a}, for \fontinst) and the smallcaps `\textsc{a}' +(\texttt{Asmall}, for \fontinst)---are given the same name by +the foundry. + +One way to get round this is to say for example +\begin{quote} + |\setglyph{Asmall} \glyph{a}{1000} \endsetglyph|\\ + |\setleftrightkerning{Asmall}{a}{1000}|\\ + |\unsetglyph{a}|\\ + |\noleftrightkerning{a}| +\end{quote} +and continuing like that for all the duplicate glyph names. This is +however a rather prolix method and if the number of glyphs is large +then it is usually simpler to use the |\reglyphfont| command. + +To reglyph one or several fonts, one writes +\begin{quote} + |\reglyphfonts|\\ + \vadjust{}\quad \meta{reglyphing commands}\\ + |\endreglyphfonts| +\end{quote} +There are two types of reglyphing commands: the |\reglyphfont| +command, and the commands that modify what |\reglyphfont| will do to +the fonts it operates on. The syntax of |\reglyphfont| is +\begin{quote} + |\reglyphfont|\marg{destination font}\marg{source font} +\end{quote} +The \meta{source font} font here is the name (suffix not included, of +course) of the font metric file one wants to change the glyph names in. +This font metric file can be in any of the formats \mtx, \pl, \afm, and +\vpl, and it will be converted to \mtx format if it isn't already in +that format (this happens just as for files listed in the second +argument of |\installfont|). \meta{destination font} (which must be +different from \meta{source font}) will be taken as the name for a +new \texttt{.mtx} file that will be generated. The destination font +can differ from the source font only in two ways: the names of some +glyphs in the source font might be changed, and some of the commands +from the source font might not have been copied to the destination +font. To what extent the fonts are different is determined by what +modifying commands have been executed; when no modifying commands +have been executed, the source and destination font are equal. + +The modifying reglyphing commands are +\begin{quote} + |\renameglyph|\marg{to}\marg{from}\\ + |\renameglyphweighted|\marg{to}\marg{from}\marg{weight}\\ + |\killglyph|\marg{glyph}\\ + |\killglyphweighted|\marg{glyph}\marg{weight}\\ + |\offmtxcommand|\marg{command}\\ + |\onmtxcommand|\marg{command} +\end{quote} +|\renameglyph| simply declares that occurrences of the glyph name +\meta{from} should be replaced by the glyph name \meta{to}. To each +glyph name is also assigned a \emph{weight}, which is used by a +mechanism which conditions copying of commands from the source font to +the destination font by the set of glyphs that command mentions. The +details of this mechanism are however somewhat tricky, so those +interested in the full generality should read the comments in the +source of \fontinst. Here it needs only be noted that if one applies +|\killglyph| to a glyph name, then (under most circumstances) commands +that refer to that glyph name will not be copied to the destination +font. + +|\offmtxcommand| and |\onmtxcommand| also control whether commands are +copied to the destination font, but they look at the actual command +rather than the glyphs it refers to. For example, after the command +\begin{quote} + |\offmtxcommand{\setkern}| +\end{quote} +no |\setkern| commands will be copied. By using |\offmtxcommand|, it +is possible to achieve effects similar to those of the files +\texttt{kernoff.mtx} and \texttt{glyphoff.mtx}---the difference is +that with |\offmtxcommand|, it happens at an earlier stage of the font +generation. As expected, |\onmtxcommand| undoes the effect of +|\offmtxcommand|. + +A special rule pertains to the |\set|\-|raw|\-|glyph|, +|\set|\-|not|\-|glyph|, |\set|\-|scaled|\-|raw|\-|glyph|, and +|\set|\-|scaled|\-|not|\-|glyph| commands, since |\transformfont| +doesn't care what something was in the source font when it generates +the transformed font. To turn these commands off while reglyphing, +you use |\offmtx|\-|command| on |\set|\-|scaled|\-|raw|\-|glyph|. + +The effects of modifying reglyphing commands are delimited by +|\reglyphfonts| and |\endreglyphfonts|, which starts and ends a group +respectively. + +As we expect the most common reglyphing operation will be to go from SC +glyph names to expert glyph names, there is a file \texttt{csc2x.tex} +in the \fontinst distribution which contains the modifying +reglyphing commands needed for setting up that conversion. Thus you +can write for example +\begin{quote} + |\reglyphfonts|\\ + | \input csc2x|\\ + | \reglyphfont{padrcx8r}{padrc8r}|\\ + | \reglyphfont{padscx8r}{padsc8r}|\\ + |\endreglyphfonts| +\end{quote} +to alter the glyph names in the SC fonts in the Adobe Garamond +(\texttt{pad}) family. +Note that the names of the destination fonts here really are rather +arbitrary, since they will only exist as \texttt{.mtx} files, and +thus only need to work within your local file system. In particular, +all the |\setrawglyph| commands in the destination font files still +refer to the source font, so it is that font which the drivers need +to know about. + + +\subsection{Making map file fragments} +\label{Ssec:MapFragments} + +A \emph{map file fragment} is the lines\footnote{Not in general an +entire map file, hence the word \emph{fragment}.} of a map file that +the corresponding driver would need for handling some set of fonts. +When told to, \fontinst can (in a fairly automatic way) create +the map file fragment which is needed for the set of raw fonts +\fontinst has (i) installed directly (using |\installrawfont|) +or (ii) used as a base font for some installed virtual font (generated +by |\installfont|). \Fontinst does not support the map file +syntaxes of every existing driver, but the system is designed to be +extendable and contributions that extend its capabilities are welcome. +Nor can \fontinst examine your \TeX\ system and +determine every piece of information needed to make the correct map +file fragments, but you can tell it roughly how your installation +looks, it can make guesses which work most of the time, and you can +specify most things explicitly if the guesses turn out to be wrong. +Should the available options for configuring the process turn out to +be inadequate for your needs, then please write to the +\fontinst mailing list about this---there is probably a way +to improve the system so that your needs can be met. + +Now what does one have to do to use this map file fragment writer, +then? First you need to tell \fontinst to record the +information the map file fragment writer needs. You do this by giving +the command +\begin{quote} + |\recordtransforms{whatever.tex}| +\end{quote} +at the beginning of the run. Here \texttt{whatever.tex} is the name of +a file that will be created, so you can use some other name if you +like. After that you do all the calls to |\transform|\-|font|, +|\install|\-|font|, |\install|\-|raw|\-|font|, |\latin|\-|family|, +etc.\ you need to make the fonts you want. When you're done, you give +the command +\begin{quote} + |\endrecordtransforms| +\end{quote} +and end the run (say |\bye|). The file \texttt{whatever.tex} will now +contain the information about which fonts were used and what needs to +be done with them. + +The second step is to actually run the map file fragment writer. +Observe that it is located in the file \texttt{finstmsc.sty}, not +\texttt{fontinst.sty}! The commands you need to give it can be so few +that you can type them in at \TeX's \texttt{*} prompt, but if you are +writing a command file then it should typically have the following +structure (comments not necessary, of course): +\begin{center} + \begin{tabular}{ll} + |\input finstmsc.sty|& |%| Input command definitions\\ + \meta{general settings} & |%| See below\\ + |\adddriver|\marg{driver name}\marg{output file}& + |%| Open output file\\ + |\input whatever.tex|& |%| Writes to output file(s)\\ + |\donedrivers|& |%| Close output file(s), tidy up\\ + |\bye|& |%| Quit + \end{tabular} +\end{center} +The |\adddriver| command gives the order ``write map file entries for +the \meta{driver name} \dvi driver to the file \meta{output file}.'' The +plan is that it should be possible to use the name of just about any +major driver (\texttt{dvips}, \texttt{xdvi},\footnote{Or +does that use the same map file as \texttt{dvips}? I heard somewhere +that it did. /LH} \texttt{pdftex},\footnote{pdf\TeX\ can read +the map files generated for \texttt{dvips}, but a separate driver is +desirable because the formats are not completely identical.} +\texttt{OzTeX}, etc.) here and get suitable map file entries for that +driver as output, but for the moment only the \texttt{dvips} and +\texttt{dvipdfm}\footnote{Whose support I made very much to illustrate +that you \emph{don't} have to be a big and ancient driver like +\texttt{dvips} to have supporting code put into \fontinst. +(The fact that I just happened to have printed out the documentation and +that is was easy to read also helped, of course.) Note, however, that +there won't be any support for a driver unless someone sits down and +writes the code for it! Don't assume I will. /LH} drivers are supported. + +You may also use \texttt{debug} or \texttt{pltotf} for \meta{driver name}. +The \texttt{debug} ``\dvi driver'' file simply contains all the available +information about each font (hence it should come handy for debugging +code writing entries for real drivers) in a format that should be easy +to interpret for a human. It could be the right choice if you're going +to write the map file manually, as the combined effects of several +font transformations are not always easy to compute manually. The +file generated for the \texttt{pltotf} ``driver'' is actually a shell +script consisting of a sequence of \pltotf commands. These commands +perform the \pl to \tfm conversion for precisely those fonts that are +actually needed (\fontinst usually generates \pl files also for a +number of fonts at intermediate stages of transformation, and many of +these need not be converted to \tfm files). The \texttt{TFMfileprefix} +string can be used to add a directory path to the \tfm file names, +perhaps saving the step of moving them to their proper location later. + +The file \texttt{whatever.tex} in the above example contains the +commands (|\make|\-|map|\-|entry| commands) that actually cause entries +to be written to the output file. It also contains a number of +|\store|\-|map|\-|data| commands---these describe how some given font +was made. If some metric file you have used contains +|\set|\-|raw|\-|glyph| commands that were not automatically generated +by \fontinst, then there might not be a |\store|\-|map|\-|data| for +the font they refer to in \texttt{whatever.tex}, so you will have to +include such a command yourself somewhere. This can for example be done +in the \meta{general settings} part of the above example file. + +Another class of things that will typically appear in the +\meta{general settings} part above is commands that will inform the +routines actually writing output about your \TeX\ system, about the set +of fonts you are using on this run, or about something else that might +be useful. Some such commands are of a general nature and affect what +assumptions \fontinst will make in certain conditions when no +specific information is available. For the moment there commands are: +\begin{description} + \item[\cs{AssumeMetafont}] Assume all fonts with \pl metrics are + bitmaps generated by Metafont, and therefore make no entries for + them. + \item[\cs{AssumeAMSBSYY}] Assume all fonts with \pl metrics have their + \TeX\ names in all upper case as postscript names---just like the + Computer Modern fonts in the AMS\slash Blue~Sky\slash Y\&Y + distribution. + \item[\cs{AssumeBaKoMa}] Assume all fonts with \pl metrics have their + \TeX\ names in all lower case as postscript names---just like the + Computer Modern fonts in the BaKoMa distribution. +\end{description} +Otherwise the default action of the routine for finding out the +postscript name of a font simply is to observe that it hasn't got a clue +about what the right value is when the metrics were taken from a \pl +file, and therefore it writes `\texttt{??????}' for the postscript name. +\begin{description} + \item[\cs{AssumeLWFN}] Assume postscript fonts for which nothing + else has been specified are stored in files which are named + according to the \mbox{MacOS} scheme for + \texttt{LWFN}s.%\footnote{LaserWriter FoNt} +\end{description} +Otherwise the default action is to use the name of the \afm or \pl from +which the metrics were originally taken, and add the file suffix stored +in the string \texttt{PSfontsuffix}. The default value of this string +is \texttt{.pfa}, but it can be changed using |\resetstr|. + +If neither the default nor the LWFN scheme produce correct results +then you may use the more specific |\specifypsfont| command, which +describes exactly which file (or files, if any) a given font is stored +in. The syntax of this command is +\begin{quote} + |\specifypsfont|\marg{PS font name}\marg{actions} +\end{quote} +where the \meta{actions} is a sequence of ``action commands''. +Currently the only such command is +\begin{quote} + |\download|\marg{file} +\end{quote} +which instructs the map file writer to include in any entry using +that PS font and ``instruction'' that the specified file should be +downloaded. Some examples are +\begin{verbatim} + \specifypsfont{Times-Roman}{} + \specifypsfont{Shareware-Cyrillic-Regular}{\download{fcyr.gsf}} + \specifypsfont{zmnl8ac6}{% + \download{MinionMM.pfb}\download{zmnl8ac6.pro}% + } +\end{verbatim} +Many \dvi drivers (for example \dvips) have more than one style of +font downloading (e.g., partial and full downloading). This interface +could be extended to control also such finer details (for example by +adding a |\fulldownload| command to force full download of a font), +but requests for this has so far been scarce. + +Finally, there is the |\declarepsencoding| command which is used to +link \etx files to postscript encodings. If no postscript encoding has +been linked to a given \etx file then \fontinst will +automatically create a postscript encoding (\texttt{.enc}) file for +that encoding, and use this file for all reencoding commands. +The \texttt{8r} encoding is predeclared, and it doesn't +matter if an encoding is undeclared if you never use it to reencode +fonts, but there is potentially a problem with not having declared +encodings you have installed and use for reencoding, as you may then +find yourself having two files with identical names that define +encodings that do not have the same name (as far as postscript is +concerned). + + + +\subsection{Tuning accent positions---an application of loops} + +The accent placements made by \texttt{latin.mtx} certainly aren't +perfect for all fonts, and the only way to find out where they should +be put is through trying in text the accented letters you get for a +couple of values for the position parameter and deciding which one +works best. Since to try one parameter value you need to (i) edit it +into an \mtx file, (ii) run \fontinst, (iii) run +\vptovf, (iv) run \TeX\ on some test text, and (v) print that +text, trying one parameter value can take annoyingly much time. +Repeating the same procedure ten times to test ten values is not +something one does without being bored (unless one scripts it, of +course), but it is possible to try ten parameter values in a single +virtual font, and without doing very much typing. + +Say you're not too happy with how \texttt{latin.mtx} positions the +accent in the \texttt{ohungarumlaut} glyph: +\begin{quote} + |\setglyph{ohungarumlaut}|\\ + | \topaccent{o}{hungarumlaut}{500}|\\ + |\endsetglyph| +\end{quote} +The |500| is the horizontal position (in thousandths of the width of +the \texttt{o}) that the centre of \texttt{hungarumlaut} in the glyph +constructed will have, so that is the position parameter value that +you want to change. Create an \mtx file containing the code +\begin{quote} + |\for(pos){250}{750}{50}|\\ + | \setglyph{ohungarumlaut\strint{pos}}|\\ + | \topaccent{o}{hungarumlaut}{\int{pos}}|\\ + | \endsetglyph|\\ + | \setleftrightkerning{ohungarumlaut\strint{pos}}|\\ + | {ohungarumlaut}{1000}|\\ + |\endfor(pos)| +\end{quote} +This will set eleven glyphs \texttt{ohungarumlaut250}, +\texttt{ohungarumlaut300}, \texttt{ohungarumlaut350}, \textellipsis\,, +\texttt{ohungarumlaut750}, each being an Hungarianly umlauted `o' +(i.e., an `\H{o}') but all having that umlaut in slightly different +positions. In order to put them in a font, you also need to make an +encoding that contains them. Therefore create an \etx file which +contains the code +\begin{quote} + |\relax\encoding|\\ + |\nextslot{"C0}|\\ + |\for(pos){250}{750}{50}|\\ + | \setslot{ohungarumlaut\strint{pos}}|\\ + | \endsetslot|\\ + |\endfor(pos)|\\ + |\endencoding| +\end{quote} +The command for installing this experiment font would be something like +\begin{quote} + |\installfont|\marg{some name}|{|\meta{the normal list of metrics}% + |,|\penalty0\meta{the new \mtx}|}|\penalty0 + |{ot1,|\meta{the new \etx}|}|\penalty0|{OT1}|\textellipsis +\end{quote} +The reason for including \texttt{ot1} in the third argument above is +that you'll need letters other than `\H{o}' against which you can +compare the experimental glyphs. It would not have been possible to +use \texttt{t1} instead of \texttt{ot1} (even though that has more +Hungarian letters) since that would set all slots in the font and +leave none for these experimental \texttt{ohungarumlaut}s. + +It is even possible to use a loop for making the test text. The +\LaTeX\ macros +\begin{verbatim} +\newcount\slotcount +\newcommand\testtext[3]{% + \slotcount=#1\relax + \begin{description}% + \loop\item[\the\slotcount]#3% + \ifnum #2>>\slotcount \advance \slotcount 1 \repeat + \end{description}% +} +\DeclareTextCompositeCommand{\H}{OT1}{o}{\char\slotcount} +\end{verbatim} +will let you write +\begin{quote} + |\testtext|\marg{first}\marg{last}\marg{text} +\end{quote} +to get the text \meta{text} typeset once for each slot from +\meta{first} to \meta{last} inclusive, with |\H{o}| ranging through the +glyphs in this interval. Thus in this case +|\testtext|\penalty\hyphenpenalty|{"C0}|\penalty\hyphenpenalty|{"CA}|% +\penalty\hyphenpenalty|{Erd\H{o}s}| would be a trivial test. + + +\subsection{Font installation commands} +\label{Ssec:FontInstCmds} + +The |\installfont|, |\installrawfont|, and |\installfontas| commands +have the respective syntaxes +\begin{isyntax} + |\installfont|\marg{font-name}\marg{metrics}\marg{etx-list}\penalty0 + \marg{encoding}\marg{family}\marg{series}\marg{shape}\marg{size}\\ + |\installrawfont|\marg{font-name}\marg{metrics}\marg{etx-list}% + \penalty0 + \marg{encoding}\marg{family}\marg{series}\marg{shape}\marg{size}\\ + |\installfontas|\marg{font-name}\penalty0\marg{encoding}% + \marg{family}\marg{series}\marg{shape}\marg{size} +\end{isyntax} +The \meta{font-name} argument and the last five arguments are common +to all these commands. The first argument is the name of a \TeX\ font +to install. The last five arguments are the NFSS attributes under which +that font will be declared to \LaTeX---encoding, family, series, shape, +and size. It is worth observing that encoding names are usually in +upper case, whereas the family, series, and shape are usually in lower +case. The size argument is either a shorthand (declared using +|\declaresize|) for a particular font +size (or range of font sizes), or an explicit list of font sizes or +ranges of sizes, which is copied directly to the font declaration. +The most common case is to let the size argument be empty, as that is +declared as a shorthand for ``any size''. + +The |\installfontas| command does not itself create the font, it just +makes a note that the specified font declaration should be written to +the proper FD file at |\end|\-|install|\-|fonts|. The +|\install|\-|font| and |\install|\-|raw|\-|font| commands do however +produce the font, in the sense that they write a \vpl and \pl +respectively file for the font. It depends solely on the \meta{metrics} +and \meta{etx-list} arguments what this font will contain. Many +features of these arguments are new with \fontinst v\,1.9; +therefore the complete syntaxes are described below. + +Both arguments are comma-separated lists of basically file names (not +including an extension). The files listed in the \meta{metrics} are +font metric files which together build up a \emph{glyph base} +(definitions of glyphs and metrics related to one or several glyphs), +whereas the files listed in the \meta{etx-list} are encoding definition +files that select a subset of the glyph base for turning into a +\TeX\ font. The font metrics can be in either of the four formats +\mtx, \pl, \afm, and \vpl, which are considered in that order. If the +metrics are not originally in \mtx format then they will be converted +to this format (a new file will be created) before they are used. +The encoding definitions must be in \etx format. The files actually +read will have a suffix \texttt{.mtx}, \texttt{.pl}, \texttt{.afm}, +\texttt{.vpl}, or \texttt{.etx} appended to the name given, depending +on which format is expected. + +Within each element of the comma-separated list, the actual file name +is followed by zero or more \emph{modifier clause}s. A \meta{modifier +clause} consists of a \emph{keyword} followed by some number (usually +one) of \emph{arguments}, separated by spaces. The whole thing looks +a lot like the \meta{rule specifications} of e.g.\ the |\vrule| +command, but here the spaces are mandatory. The currently defined +\meta{modifier clause}s are +\begin{description} + \item[\mdseries\textvisiblespace\texttt{option}\textvisiblespace + \meta{string}] + Available for metric and encoding files. This adds \meta{string} + to the list of options for this file, which may affect what code + the file executes. The file can then test, using the |\ifoption| + command, whether a specific string is one of the options it was + given. + \item[\mdseries\textvisiblespace\texttt{scaled}\textvisiblespace + \meta{factor}] + Available for metric files. Causes the \texttt{rawscale} integer + variable to be set to the \meta{factor} (an integer expression) + while the file is being read. This scales glyphs and kerns that + are added to the glyph base by the \meta{factor}. + \item[\mdseries\textvisiblespace\texttt{suffix}\textvisiblespace + \meta{suffix}] + Available for metric files. Causes \meta{suffix} to be appended + to every glyph name appearing in a glyph or kern that file adds + to the glyph base. Thus ``\texttt{suffix /2}'' effectively + changes a + \begin{quote} + |\setrawglyph{a}|\dots + \end{quote} + to a + \begin{quote} + |\setrawglyph{a/2}|\dots + \end{quote} + \item[\mdseries\textvisiblespace\texttt{encoding}\textvisiblespace + \meta{etx-name}] + Available for metric files, and forces \fontinst to + only consider the \pl and \vpl formats for this font. + As these file formats do not contain glyph names, an \etx file + is used to assign glyph names to the slots in the font. + This \etx file is usually selected according to the + \texttt{CODINGSCHEME} property of the \pl or \vpl (using the + correspondences set up via the |\declare|\-|encoding| command), + but that information is not always as one would want it (there + are even fonts for which it is quite wrong). An \texttt{encoding} + clause bypasses this automatic mechanism, so that the file + \meta{etx-name}\texttt{.etx} is used instead. + +% % The following is no longer true as of v1.926: +% \textbf{Note:} The first time that a file in PL or VPL format is +% used in a \meta{metrics} argument, a corresponding \mtx file is +% generated. This means that if the same file reference is used +% another time then the reference will be to the \mtx file, not to +% the original PL or VPL, and thus \texttt{encoding} clauses on +% subsequent uses will have no effect. Each font only has one +% encoding, so it usually makes no sense to switch the \etx file +% used to interpret a font, but since \mtx files are not +% automatically deleted between runs there is a risk that this +% takes away the intended effect of an \texttt{encoding} clause. + + \item[\mdseries\textvisiblespace\texttt{mtxasetx}] + This is available for files in the \meta{etx-list}. The actual + function of a + \begin{quote} + \meta{file-name} \texttt{mtxasetx} + \end{quote} + item in the \meta{etx-list} is that the file + \meta{file-name}\texttt{.mtx} is inputted (\emph{not} + \meta{file-name}\texttt{.etx}) and that the correspondence + between glyph names and slot numbers set up in + |\set|\-|raw|\-|glyph| or |\set|\-|scaled|\-|raw|\-|glyph| + commands in this file is treated as if it had been set up by + |\setslot| commands in an \etx file. Provided the \mtx file is + transformable, the glyph base will be unaffected. + + The purpose of this feature is to simplify quick and dirty + installations of odd fonts for which no suitable \etx file is + available. This can be useful in early stages of the design of + a new font, but is inferior to installation using proper \etx + files since one for example cannot specify any ligatures in + \mtx files. +\end{description} +Furthermore there is a special exception for the \meta{metrics}: if +the first token in one of the list items is the control sequence +|\metrics|, then the rest of that item is interpreted as explicit +metric commands to execute. + +If the \meta{metrics} of two subsequent |\install|\-|font| +or |\install|\-|raw|\-|font| commands are identical then the glyph +bases will be identical as well. This creates an opportunity for +optimization, which \fontinst makes use of by caching glyph +bases from one installation command to the next so that the glyph +base does not have to be rebuilt in these cases. A side-effect of +this caching is that local assignments made between two font +installation commands are cleared out with the glyph base, but +|\setint| and similar \fontinst commands make global +assignments when used in such positions. + +Some examples might be in order. The first is an adaptation of an +installation command from \texttt{mfnt-0.59} %~\cite{mfnt} +by Matthias Clasen and Ulrik Vieth: the installation command for the +8-bit math font \texttt{xma1000} (which can be thought of as being +to \texttt{cmmi10} sort of as \texttt{ecrm1000} is to \texttt{cmr10}). +The first three \texttt{encoding} clauses are more fine-tuning---without +them, a few glyphs would get incorrect names---but the last two are +quite essential, as the \texttt{msam10} and \texttt{msbm10} fonts +incorrectly claim to have the coding scheme \texttt{TEX MATH +SYMBOLS}. +\begin{verbatim} + \installfont{xma1000}{% + yma1000 encoding mcin,% + cmr10 encoding ot1upright,% + cmmi10,% + cmsy10 encoding omscal,% + msam10 encoding msam,% + msbm10 encoding msbm,% + mccmhax,mccmkern,mcmissing,% + cmsy10-base,cmsy10-extra% + }{mc}{MC}{cm}{m}{n}{<<10->>} +\end{verbatim} +Also note the explicit \LaTeX\ size specification for the range +``10\,pt and up''. + +The second example makes use of a \texttt{suffix} clause to combine +the letters from one font with the digits from another. +\begin{verbatim} + \installfont{msbrj8t}{msbr8r,msbrc8r suffix /2,latin}{digit2,t1} + {T1}{msbj}{m}{n}{} +\end{verbatim} +In this case, the glyph base contains the glyphs of Monotype Sabon +(SabonMT)---under names such as \texttt{A} for `A', \texttt{a} for +`a', and \texttt{one} for a lining digit one---as well as the +glyphs of Monotype Sabon Small Caps and Oldstyle Figures +(SabonMT-SCOSF)---under names such as \texttt{A/2} for `A', +\texttt{a/2} for `\textsc{a}', and \texttt{one/2} for a hanging +digit one. The \texttt{digit2.etx} file simply makes the definition +\begin{verbatim} + \setcommand\digit#1{#1/2} +\end{verbatim} +which causes \texttt{t1.etx} to put \texttt{zero/2} in slot 48 (digit +zero), \texttt{one/2} in slot 49 etc., instead of as it normally +would \texttt{zero} in slot 48, \texttt{one} in slot 49 and so on. +The net effect is that the digits in the generated \texttt{msbrj8t} +is from \texttt{msbrc8r} (SabonMT-SCOSF) but everything else is from +\texttt{msbr8r} (SabonMT). + +The third example makes use of an \texttt{mtxasetx} clause to install +(with its default encoding) a font for which creating an appropriate +\etx file seems not worth the trouble. +\begin{verbatim} + \installrawfont{psyr}{psyr,\metrics + \setint{xheight}{\height{alpha}} + }{txtfdmns,psyr mtxasetx}{U}{psy}{m}{n}{} +\end{verbatim} +The effect of the second \texttt{psyr} is that \texttt{psyr.mtx} is +read (in case there was no \texttt{psyr.mtx} then it is created from +(hopefully) \texttt{psyr.afm}) and the information in it will form +the glyph base. Because of the |\metrics| control sequence, the rest +of that item will be interpreted as explicit metric commands +modifying the glyph base, and thus the |\setint| command can provide +a value for the \texttt{xheight} variable (there doesn't seem to be +such a value in the \afm). Once the glyph base is completed, the +|\install|\-|raw|\-|font| starts writing the file \texttt{psyr.pl} +(that's for the first \texttt{psyr}). The encoding of that font will, +because of the \texttt{psyr mtxasetx}, be the same as that used in +\texttt{psyr.mtx}. Finally, the \texttt{txtfdmns} is for +\texttt{txtfdmns.etx}, an \etx file which sets fontdimens 1--16 as for +a \texttt{T1} encoded font but does not set any slots. Since +\texttt{psyr.mtx} reinterpreted as an \etx file sets slots but no +fontdimens, these complement each other nicely. + + + +\subsection{Bounding boxes} + +Han The Thanh has created an implementation of bounding box support +for \fontinst, and it is a modified form of that support +is distributed with \fontinst as the file \texttt{bbox.sty}. To load +this, begin your command file with +\begin{verbatim} + \input fontinst.sty + \input bbox.sty +\end{verbatim} +The reason for not making it default is that keeping track of bounding +boxes increases some of \fontinst's memory requirements quite a lot. + +One important +characteristic of this implementation is that the dimensions of the +bounding box are not bundled into the same data structure (the +|\g-|\meta{glyph} macros) as the glyph's width, height, depth, and +italic correction are, but stored in a separate data structure (the +|\gb-|\meta{glyph} macros). A glyph doesn't need to have its bounding +box set, it is simply a piece of information that \fontinst +will store if you tell it to and which you can later retrieve. + +The bounding box will be stored as coordinates of the sides in the +normal AFM coordinate system. The commands for retrieving these +coordinates are +\begin{center} + \begin{tabular}{ll} + \textbf{Command}& \textbf{Side}\\ + |\bbtop|\marg{glyph}& top ($y$-coordinate)\\ + |\bbbottom|\marg{glyph}& bottom ($y$-coordinate)\\ + |\bbleft|\marg{glyph}& left ($x$-coordinate)\\ + |\bbright|\marg{glyph}& right ($x$-coordinate) + \end{tabular} +\end{center} +In Thanh's implementation the command names were |\ury|, |\lly|, +|\llx|, and |\urx| respectively instead, but I think the former are +easier to remember. If no bounding box has been set for a glyph then +the above commands will instead report the corresponding coordinate of +the glyph's \TeX\ box (i.e.\ |\height|\marg{glyph}, +|\neg{\depth|\marg{glyph}|}|, |0|, and |\width|\marg{glyph} +respectively). + +The command for setting the bounding box of a glyph is +\begin{quote} + |\setglyphbb|\marg{glyph}\marg{left}\marg{bottom}\marg{right}% + \marg{top} +\end{quote} + + + + + +\section*{Acknowledgements} + +We'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 trigonometry. + + +% \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} |