%&latex %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% This is the file vfinst.tex, part of the VFinst package %% (version 1.00, August, 1998) for PostScript Type1 font %% installation. (Author: Alan Hoenig, ajhjj@cunyvm.cuny.edu) %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% THIS IS A STANDARD \LaTeX (LaTeX2e) FILE. \documentclass{article} \def\TT#1 {{\tt #1} } \newcommand{\vfinst}{\texttt{VFinst}}\let\VFinst=\vfinst \newcommand{\CTAN}{\textsc{ctan}} \newcommand{\TDS}{\textsc{tds}} \newcommand{\helper}[2]{#2 #1} \title{The \TT VFinst virtual font installer (version 1.00)} \author{Alan Hoenig} \begin{document} \maketitle If you've ever wanted to set up outline fonts for use by \TeX\ or \LaTeX, \VFinst\ may be of use to you. \VFinst\ sets these fonts up for use by \TeX\ and \LaTeX, and at the end of the \VFinst\ process, you'll be able to typeset with your new fonts, confident that accents, ligatures, and the like will appear in your document with the usual \TeX\ conventions. Here are the fonts you get at the end of the process. \begin{enumerate} \item For every upright font: you get the upright font, the small caps font, an oblique font, and an underline font. \item For every italic font, you get the italic font, a small caps italic, an unslanted italic, and an underline font. \item Additional fonts: You will also get titling (display) fonts, both upright and italic, and a swash italic font, if the appropriate raw fonts were present. \end{enumerate} \VFinst\ takes care to use expert fonts to build the small caps fonts, if these raw fonts were originally present. You also get test files for plain \TeX\ and \textsc{NFSS} (\LaTeX), to both test the fonts and to provide examples of how to declare and use each of the fonts in a \TeX\ document. At the end of the \VFinst\ process, you get all {\tt.vf} and {\tt.tfm} files for all fonts, which have been renamed for you according to the {\tt fontname2.1} conventions. All oblique and italic fonts use the true italic angle for the font. The {\it dvips\/} map file {\tt psfonts.map} will have been updated for you. All fonts will have been placed in the proper area on your hard disk. You may choose original \TeX\ ({\tt ot1}) or Cork ({\tt t1}) encodings for your fonts, which can be installed according to the \TDS\ (\TeX\ Directory Structure) or `traditional' standard. All raw fonts follow the {\tt 8r TeXBase1Encoding}. All this and more is expanded upon in the remainder of this file. {\bf Please read the file thoroughly.} The first section, a general introduction, is followed by four sections that a new user will need: \begin{itemize} \item`\VFinst\ and what you'll need to run it', \item`Installation and set up', \item `Running \VFinst', and \item `Using your new fonts'. \end{itemize} The remainder can be read later (if at all). If this software proves useful to you, you may also wish to investigate two other packages I wrote, both on \CTAN. {\it MathInst\/} helps install commercial math fonts with your newly installed PostScript fonts so that equations and such come out looking fully compatible with your text. {\it MathKit\/} does the same thing, but it uses Metafont to create symbols from the Computer Modern fonts that match your text fonts. These packages can be found in the \begin{verbatim} fonts/utilities/mathinst fonts/utilities/mathkit \end{verbatim} areas of \textsc{ctan}. \section{Introduction} One thing that {\em should\/} be easy to do with \TeX\ is make commercial outline fonts transparently usable by \TeX\ and \LaTeX. Even though a tool like \TT fontinst does make it easy to do this, \TT fontinst still requires inside knowledge not easily come by. The set of tools called \vfinst\ is my attempt to make the task of installing families of PostScript fonts as simple as possible, but {\bf only\/} for well-formed families of fonts. That is, I am concerned here only with {\em text\/} fonts, roman fonts appearing in medium and other weights, with italic variants, and optionally with small caps or expert fonts, and possibly a few additional matching fonts, like swash italic caps, display fonts, and so on thrown in. Special dingbat fonts, unusual families like Poetica, foreign language fonts, math fonts, and the like will not be reliably installed with this software. Neither will fonts that are narrow, extended, or other `width' variants. (I have prepared two other tools---\textit{MathInst} and \textit{MathKit}---that help typeset documents so that the mathematics is compatible with the text fonts. Both these tools are available on \textsc{ctan}; see above.) Here's the basic idea. You place copies of all the fonts you want to install in a special work place. Then, you activate the \vfinst\ scripts, run all the additional scripts that \vfinst\ produces, and that's it! \vfinst\ does these things for you: \begin{itemize} \item produces all \TT.vf and \TT.tfm files; \item renames the fonts according to version~2.1 of Karl Berry's \TT fontname convention; \item automatically updates the \TT psfonts.map file for {\it dvips}; \item generates two test files, for plain \TeX\ and NFSS (\LaTeX), showing how to use your new fonts; and \item generates a script or batch file for placing all new fonts and other associated files in their proper places (It also generates a script for creating any needed new directories.) \end{itemize} and does these for either `traditional' or {\sc tds}-compliant systems. (TDS stands for `\TeX\ Directory Structure'.) Once you've executed all these scripts or batch files, the fonts are ready for use. Here are the fonts you get: \begin{itemize} \item for each upright font (roman and bold or semibold, usually): \begin{itemize} \item the font itself, \item matching small caps (mock or real), \item a slanted (oblique) font, and \item an underline font. \end{itemize} \item for each italic font (roman and bold or semibold, usually): \begin{itemize} \item the font itself, \item matching small caps, \item an unslanted italic, and \item an underline font. \end{itemize} \item display or titling fonts (both upright and italic), if they are present; and \item swash italic fonts, if they are present. \end{itemize} If you have included expert or small caps fonts among your fonts for installation, \vfinst\ automatically takes them into account when building the virtual fonts. If you have included expert raw fonts, you actually get two font families at the end---both use `expertised' fonts, but one family contains regular digits, and the other contains old style digits. It's not well known, but the angle of inclination for an italic font varies quite a bit from font family to font family. The oblique and unslanted italic fonts that \vfinst\ creates use the true italic angle for that font. You also get several underline fonts, font in which each character is underlined so it is easy to typeset lengthy underlined passages without worrying about line breaks. {\fontsize{9}{10}\selectfont (This paragraph is for reference purposes only; it mentions things that will very likely not be of interest to most people.) The virtual fonts created use raw fonts which follow the `8r' \TT TeXBase1Encoding being promulgated by the international community of \TeX\ developers. (This encoding provides easy access to all characters in the font. Pardon to all for the cryptic acronyms that abound.) The resulting virtual fonts themselves follow either the original \TeX\ encoding (so-called \texttt{OT1} or \texttt{ot1}) or the newer Cork encoding (\texttt{T1} or \texttt{t1}).\endgraf} Pierre MacKay's \TT makevf script helped inspire \vfinst. The remainder of this document describes the \vfinst\ installation procedure, its use, and other important details in greater detail. Although I hope this software is useful, it comes with no warranty whatsoever. I cannot accept responsibility for any harmful effects from this software. \subsection{Changes from prior versions} Separate \textsc{dos} versions of \vfinst\ are no longer supported. Several bug fixes are particularly important. One odd but interesting bug prevented \vfinst\ from working properly with New Century Schoolbook fonts. A second concerned the way \textit{dvips}-map entries were generated for \textsc{tds} systems. Both have been fixed. Speaking of \textsc{tds} systems, this version has been very thoroughly tested with such systems, a fact which has not been true in the past. Several major bugs were uncovered and fixed, and my apologies to all that they persisted for so long. \subsubsection{Lousy afm files} The major problem users may continue to have lies not with {\it this\/} software, but with the \texttt{afm} files that accompany the files. These files provide the metric and other information for a Type1 font analogously to \TeX's \texttt{tfm} files. Apparently, little software takes advantage of these files, and digital foundries are at best sloppy when preparing them. \vfinst\ relies on the \texttt{afm} files to learn things about the fonts it's processing, and sloppily prepared \texttt{afm}s lead to disaster. This version of \vfinst\ attempts to second-guess an \texttt{afm} file as much as possible. A variable called \verb+@sloppy_afms+ contains a list of particularly sloppy \texttt{afm}. Currently, it refers to Adobe Garamond and Minion, Monotype Bulmer, Lucida Bright, and BitStream Chianti. You can add to it if you feel you've discovered another malefactor. (See the beginning of file \texttt{vfinst.lib} for this variable.) Another mechanism for correcting \texttt{afm} files lies in the file \texttt{vfinst.rc}; see below. \subsection{Scope of testing} This software was tested on a Linux box and under WindowsNT~4.0 using both \textsc{tds} and traditional versions of \TeX. \vfinst\ was extensively tested on several popular font families, including the PostScript-resident fonts Times Roman, Palatino, and New Century Schoolbook, as well as Adobe Garamond, Adobe Caslon, Adobe Minion, Monotype Bulmer, and Monotype Baskerville, Lucida Bright, plus many other families of fonts that were lying around on my hard disk. They all installed fine for me. \subsection{Legal jargon and caveats} This software is distributed according to the terms of the \textsc{GNU} `copyleft' agreement. In addition, please note that if you make any alterations to any of the files in this package, you must change the names of the altered files. You are allowed to freely use this material and to pass it along (in the unaltered state!) provided you will not be using it to make money; otherwise, you must get in touch with me to secure permission. While the author hopes that it will prove useful, it is distributed with no guarantee or warranty whatsoever. Users should take \textsc{great care} to carefully back up their data before using. \section{\TT VFinst and what you'll need to run it} \vfinst\ itself consists of Perl scripts and some supporting files. %% These files are named: %% %% \begin{itemize} %% \item \TT 1vfinst and \TT 2vfinst; %% \item \TT vfinst.lib, a library of common routines; %% \item \TT vfinst.par, a set of parameters that everyone who uses %% this material will have to customize for their installation; %% \item \TT vfinst.rc, a file containing some non-invasive corrections %% to particular \TT.afm files (\vfinst\ reads this information without requiring %% you to modify the \TT.afm files themselves); %% \item several map files called \texttt{map.a2d}, \texttt{map.n2a}, %% and \texttt{map.sup} (These have been compiled using information %% from several of the files provided in Karl Berry's \texttt{fontname} %% package.); %% \item example output; and %% \item several miscellaneous other files. %% \end{itemize} \subsection{Example output} In the subdirectory {\tt example}, you'll find the {\tt pfb} and {\tt afm} files for the Roman typeface Utopia, placed in the public domain by URW. In addition, you'll find other files that are the result of the {\tt vfinst} process. \subsection{What you'll need} Here's what you'll need to properly install your fonts using \vfinst: \begin{enumerate} \item a version of \TeX\ that understands virtual fonts (version 3 or better of \TeX); \item the \texttt{fontinst} package available from any \CTAN\ archive or mirror in the area \begin{verbatim} fonts/utilities/fontinst/inputs \end{verbatim} Installation of this package is easy---you simply take {\bf all\/} of the files in this directory and place them in a directory on your system that \TeX\ know how to read from. For traditional systems, this is apt to be a place like `{\tt tex/inputs}' and on a {\sc tds} system, a place like \begin{verbatim} texmf/tex/generic/fontinst \end{verbatim} is appropriate. (There are apparently several different versions on \CTAN. You want version~1.5 or greater. Versions before that may not work.) \item the {\it dvips\/} post-processor; \item a copy of the file \texttt{8r.enc}, part of the \texttt{fontname} package (this package is available from any \CTAN\ archive from the area \texttt{info/fontname}); and \item a copy of Perl. Perl is a powerful language for text processing. I chose Perl because versions of Perl are freely available for every computer platform. You don't need to understand Perl---just get a copy of the executable file, place it on your computer's path, and (if necessary) make it executable. This material has been tested under Perl5 (the current version). Perl should be available from any good software archive and from many \textsc{cdrom} collections of software. \end{enumerate} This material should run on any platform on which runs Perl and \TeX. \section{Installation and set up} \subsection{Installation} To install \vfinst, create a new directory, possibly something like \begin{verbatim} /usr/local/vfinst \end{verbatim} under Unix or \begin{verbatim} \tex\vfinst \end{verbatim} under \textsc{dos}. Copy the all the \vfinst\ files (with the possible exeception of the examples) into that directory. Now create a work directory below this new directory, with a full pathname like \begin{verbatim} /usr/local/vfinst/work \end{verbatim} for Unix or \begin{verbatim} \tex\vfinst\work \end{verbatim} under \textsc{dos}. Switch to this lowest level \TT work subdirectory, which we will call the \vfinst{} {\tt work}ing directory. If you are on a Unix system, make sure you have permission to write files in this working area. Also, make sure that your implementation of \TeX\ contains the {\it parent\/} directory and the {\it current\/} directory on its own search path. There are some things that need setting in the file \TT vfinst.par, which is one of the files in the \vfinst{} directory. {\bf Everyone\/} must set these up properly---\vfinst\ won't work properly otherwise, and there are no default settings for these parameters. Take the time to doublecheck the settings for accuracy. Since this is a Perl file, you must follow Perl syntax in the setup. This isn't difficult; see below for examples of setups. In particular, the Perl comment character is {\tt\char`\#}, which can hide or expose a line to Perl as the `{\tt\char`\%}' does in a \TeX\ document. \subsection{Everybody must set these...} \begin{enumerate} \item \TT \$vfenc is the encoding you'll want to be using. Although many in the \TeX\ community are pushing an encoding called \TT t1, I prefer to use the original \TeX\ encoding called \TT ot1 because there is room in these virtual fonts for many additional characters. Your only choice for this parameter is \TT t1 or \TT ot1. Users of versions of \LaTeX\ predating December 1996 might enter \TT T1 or \TT OT1 instead. {\fontsize{9}{10}\selectfont If you use the lowercase {\tt ot1} or {\tt t1} designations, you'll need to {\em make sure\/} that corresponding files {\tt ot1\char`\*.etx} and {\tt t1\char`\*.etx} are in a \TeX\ input directory. If such named files do not accompany your copy of \TT fontinst, the simplest thing to do is make a copy of all the {\tt OT1\char`\*.etx} and {\tt T1\char`\*.etx} files, which are part of the \TT fontinst package, and give them the appropriate names, eg {\tt cp OT1.etx ot1.etx} (using Unix syntax).\endgraf} %% \item \TT \$vfencoding is the place which %% contains a copy of the file \TT 8r.enc (which describes the %% \TT TeXBase1Encoding promulgated by all good users of \TeX). This %% place merits its own variable only because I've found it convenient to %% place this file somewhere with a short path name---otherwise the %% entries in \TT psfonts.map become uncomfortably long. You don't need %% to set this variable; if it's not set, \vfinst\ will assume that \TT %% 8r.enc appears in the same directory as {\tt\$vfmapdir}. \end{enumerate} In earlier versions of \vfinst, a special variable contained the location of the file \TT 8r.enc. With this release, it is assumed visible to \TT dvips without any path prefix. For traditional users, this may mean placing it in your \TT work directory. For TDS users, this means nothing special, as \TT dvips will be able to find it via the search mechanism that accompanies the TDS installation. \subsection{TDS systems} \TeX\ knows it's a {\sc tds} installation if the variable \TT \$vftexmf is defined; it should have as values the root \TeX/MF directory. One advantage of {\sc tds} is that \vfinst\ can then figure out for itself where most things belong. In a {\sc tds} system, \vfinst\ will ask you later for certain additional information pertaining to your fonts. For each font family, \vfinst\ needs a typeface name (like `\texttt{agaramon}', `\texttt{times}', etc.) and a supplier (\texttt{adobe}, \texttt{monotype}, and so on). \vfinst\ tries to figure this out by itself, and may simply request verification from you. In stubborn cases, it will ask you for this information. \subsection{Traditional systems} On traditional systems, all {\tt.afm}'s go in one place, all {\tt.tfm}'s in another, and so on. Such installations need to define the following variables. Directories are not well-structured in these kinds of systems, so \vfinst\ needs lots of information from you, and this additional information belongs in \texttt{vfinst.par}. \begin{enumerate} \item \TT \$vfvf is the place where virtual fonts are kept. If you have vf's on your system already, use this directory name. Otherwise, you'll need to check your {\it dvips} or driver documentation to see where those programs expect to find the vf's. It should be something like \begin{verbatim} "/usr/lib/tex/fonts/vf" \end{verbatim} (Unix) or perhaps \begin{verbatim} "\\emtex\\fonts\\vf" \end{verbatim} (\textsc{dos}; the backslash must be doubled as shown, or Perl will misunderstand it). \item \TT \$vftfm is the place where \TeX\ looks for your \TT.tfm files. \item \TT \$vfpsfonts records the location of your outline font files, files typically with extensions \TT.pfa or \TT .pfb. \item \TT \$vfafm is the directory containing all the \TT.afm files for the outline font files. Unlike most software out there, \TeX\ needs these files. \item \TT \$vfmapdir is the place where you keep the file \TT psfonts.map that {\it dvips} uses. \item \TT \$vfinputs is the place where the \TT.fd and other input files belong. \end{enumerate} \subsection{Sample setups} The first part of the \vfinst\ setup for a traditional Unix system might look as follows. These declarations are part of the file \TT vfinst.par. On a Unix {\sc tds} system, these settings might have the following form. \begin{verbatim} $vftexmf = "/usr/texmf"; $vfencoding = "/usr"; # where is the file 8r.enc? $vfenc = "ot1"; \end{verbatim} Here is a sample Unix setup for a traditional \TeX\ system. \begin{verbatim} $vfmapdir = "/usr/lib/tex/ps"; $vfinputs = "/usr/lib/tex/inputs"; $vfencoding = "/usr"; $vfenc = "ot1"; $vfvf = "/usr/lib/tex/fonts/vf"; $vftfm = "/usr/lib/tex/fonts/tfm"; $vfpsfonts = "/psfonts"; $vfafm = "/psfonts/afm"; \end{verbatim} On a \textsc{dos} system, these instructions might take the form \begin{verbatim} $vfmapdir = "\\tex\\ps"; $vfinputs = "\\tex\\inputs"; $vfencoding = "$vfinputs"; $vfenc = "t1"; $vfvf = "\\tex\\fonts\\vf"; $vftfm = "\\tex\\fonts\\tfm"; $vfpsfonts = "\\psfonts"; $vfafm = "\\psfonts\\afm"; \end{verbatim} (note the doubled backslashes). \subsection{Other parameters \& considerations} The other `wizards only' parameters should already have been set for you. If your system understands the `shebang' convention (whereby you type the name of script, and it knows to invoke Perl and run like a named program; the first line of the script must begin with `{\tt\#!}'), then all you'll need to do is adjust the initial line of files {\tt1vfinst} and {\tt2vfinst} to reflect the location of your Perl executable. On Unix systems, you'll also need to make these scripts executable via the {\tt\ chmod +x\ } command. If your version of \TeX\ is a multitasking application, such as Tom Rokicki's excellent \TeX View on NextStep, you'll need to make the application quit and restart it to make your new fonts visible to it. \section{Running \TT VFinst } To use \vfinst, simply copy all the fonts (outline file plus \TT.afm file) to the \vfinst\ {\tt work}ing directory. \vfinst\ won't care what filenames these have, nor how many font families are represented. If you have any expert, small caps, extension, or alternate fonts, include them too by all means. \vfinst\ will use them if present to make true small caps fonts. {\bf You MUST make sure that the outline font file and the matching {\tt.afm} have identical filenames.} Then, simply execute the following sequence of commands: \begin{itemize} \item {\tt1vfinst} \item {\tt2vfinst} \end{itemize} Under the `shebang' notation, you need simply enter something like {\tt../1vfinst}; otherwise, type something like {\tt perl ../1vfinst}. These two scripts execute rapidly, although they pause to request information or verification from you. They will try to figure out the font supplier, the font family, and some {\sc tds} directory information, and it is this material that needs to be verified and/or provided. Sometimes digital foundries are sloppy about naming their fonts consistently, and so \vfinst\ may ask you to verify or enter a font family abbreviation for one family more than once. For example, Monotype Baskerville has been assigned to the family named {\tt BaskervilleMT} while the matching expert font is in the family {\tt BskvillExpMT}. (These are the names appearing in the {\tt.afm} file.) A \TeX\ author clearly needs them in the same font family, so verify family {\tt mbv} for the first, and verify family {\tt mbv} for the second, so that \vfinst\ will know they are in the same family. It often pays to briefly examine the files that \TT1vfinst produces. There is a small file \TT duplicat.lst which contains a list of fonts that \vfinst\ thinks are duplicates. It will help later steps proceed faster if you eliminate any duplicates---and if you do, don't forget to remove both \TT.pfb and \TT.afm file. Entries in this file may also indicate a problem with the \TT.afm file; see page~\pageref{afm-error}\ below for more on this. The other output file is \TT fonts.lst, a list of all fonts with their proposed new names, old names, and some information that will be of interest to later steps in the \vfinst\ process. You should examine this list and eliminate any special-purpose fonts, such as special fraction or ornament fonts, from the installation process. It will also be helpful to eliminate all fonts with a width variant (such as Helvetica Narrow, etc.). If you remove any fonts from your working directory, make sure to re-run \TT1vfinst. There are several additional steps. Execute the following scripts, which are outputs of the previous two steps: \begin{itemize} \item {\tt mkdirs.bat} \item {\tt newnames.bat} \end{itemize} to create any missing directories and to rename the fonts according to the {\tt fontname2.1} conventions. These steps take very little time. Then, execute the command \begin{verbatim} tex makefont \end{verbatim} to create the virtual fonts; the file \TT makefont.tex is the output of the original Perl scripts. This step may take a long while. Ignore warnings about missing glyphs. Next, execute the script \begin{itemize} \item {\tt maketfm.bat} \end{itemize} to convert your Ascii property list files into the binary {\tt.tfm} and {\tt.vf} files that \TeX\ expects. Finally, execute the two scripts \begin{itemize} \item {\tt putfonts.bat} \item {\tt putvftv.bat} \end{itemize} These two scripts, which execute rapidly, are responsible for placing all files into places from which \TeX\ can use them for typesetting. {\bf The fonts cannot be said to be installed until these two steps are carried out.} I suppose that users on multi-user systems will have to request their system administrator perform these tasks. One special step is necessary for \textsc{tds} systems only! Whenever new fonts are added to a \textsc{tds} system, it will be necessary to run a small utility which accompanies \TeX. This tool may be named \TT texhash or \TT configure or \TT mktexlsr something else entirely, and is necessary to place the names of the new fonts in database that \textsc{tds} uses to locate files and fonts. Now, your new fonts are ready for use. You can test your fonts by running either of the files {\tt testpln.tex} or {\tt testltx.tex} through \TT plain \TeX\ or through \LaTeX. These files also show what commands to use to select your new fonts. Once the installation has been completed according to the above steps, everything left in the work directory may be deleted. \subsection{Installing `raw' fonts} \vfinst\ is intended for fonts that require auxiliary constructs called \textit{virtual fonts} for proper use by \TeX. This does not include every font you might purchase. For example, dingbat fonts, special alphabets (phonetic fonts, foreign languages, {\sc apl}) and so on don't require the virtual font mechanism. Installation to make these fonts usable by \TeX\ is a much simpler process, but you have to do the work yourself. To illustrate the process, let's suppose you have files {\tt foo.afm} and {\tt foo.pfb} for installation. Follow these steps: \begin{itemize} \item You'll need program \texttt{afm2tfm}, part of the {\it dvips\/} suite. Execute the command \begin{verbatim} afm2tfm foo \end{verbatim} This creates a file {\tt foo.tfm} for use by \TeX, and displays a line like \begin{verbatim} foo AGaramond-Regular \end{verbatim} (or whatever) on your console.. \item Place this displayed line in the file {\tt psfonts.map}. If it's a non-resident font, you'll need to adjust this line as follows: \begin{verbatim} foo AGaramond-Regular