The VFinst virtual font installer (version 0.93)

Alan Hoenig

April 30, 1997

If you’ve ever wanted to set up outline fonts for use by TEX or L^{A}TEX, VFinst may be of use to you. 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.

1. For every upright font: you get the upright font, the small caps font, an oblique font, and an underline font.

2. For every italic font, you get the italic font, a small caps italic, an unslanted italic, and an underline font.

3. 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.

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 NFSS (L^{A}TEX), 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 .vf and .tfm files for all fonts, which have been renamed for you according to the fontname2.1 conventions. All oblique and italic fonts use the true italic angle for the font. The dvips map file 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 (ot1) or Cork (t1) encodings for your fonts, which can be installed according to the tds (TEX Directory Structure) or ‘traditional’ standard. All raw fonts follow the 8r

TeXBase1Encoding.

All this and more is expanded upon in the remainder of this file. Please read the file thoroughly. The first section, a general introduction, is followed by four sections that a new user will need:

• ‘VFinst and what you’ll need to run it’,

• ‘Installation and set up’,

• ‘Running VFinst’, and

• ‘Using your new fonts’.

The remainder can be read later (if at all).

1 Introduction

One thing that should be easy to do with TEX is make commercial outline fonts transparently usable by TEX and L^{A}TEX. Even though a tool like fontinst does make it easy to do this, fontinst still requires inside knowledge, knowledge that is not easily come by in any case. The set of tools called VFinst is my attempt to make the task of installing families of PostScript fonts as simple as possible, but only for well-formed families of fonts. That is, I am concerned here only with 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

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:

• produces all .vf and .tfm files;

• renames the fonts according to version 2.1 of Karl Berry’s fontname convention;

• automatically updates the psfonts.map file for dvips;

• generates two test files, for plain TEX and NFSS (L^{A}TEX), showing how to use your new fonts; and

• 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.)

and does these for both ‘traditional’ or 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:

• for each upright font (roman and bold or semibold, usually):

– the font itself,

– matching small caps (mock or real),

– a slanted (oblique) font, and

– an underline font.

• for each italic font (roman and bold or semibold, usually):

– the font itself,

– matching small caps, – an unslanted italic, and

– an underline font.

• display or titling fonts (both upright and italic), if they are present; and

• swash italic fonts, if they are present.

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.

(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’ TeXBase1Encoding being promulgated by the international community of TEX developers. (This encoding provides easy access to all characters in the font.) The resulting virtual fonts themselves follow either the original TEX encoding (so-called OT1 or ot1) or the newer Cork encoding (T1 or t1).

The software is distributed in two incarnations—for the Unix C-shell and for ms-dos. See below for tips on adapting it to other operating systems. Pierre MacKay’s makevf script inspired VFinst.

The remainder of this document describes the VFinst installation procedure, its use, and other important details in greater detail. WARNING: THIS SOFTWARE IS BETA VERSION, SO PEOPLE WHO USE IT SHOULD TAKE GREAT CARE TO HAVE BACKUP COPIES OF ALL THEIR FILES IN SOME ACCESSIBLE PLACE. Although I hope this software is useful, it comes with no warranty whatsoever. I cannot accept responsibility for any harmful effects from this software.

1.1 Changes from the prior version

This version has been re-coded virtually from scratch. The user interface is quite different from before to make it easy to bail out in the middle of the process if something backfires. I am grateful for the comments of several people who tested prior versions, including Matt Swift, Richard Walker, and (especially) David Ness. Any earlier versions of VFinst should be deleted as quickly as possible.

1.2 Legal jargon and caveats

This software is distributed according to the terms of the 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 great care to carefully back up their data before using.

2 VFinst and what you’ll need to run it

VFinst itself consists of Perl scripts and some supporting files. These files are named:

• 1vfinst and 2vfinst;

• vfinst.lib, a library of common routines;

• vfinst.par, a set of parameters that everyone who uses this material will have to customize for their installation; and

• several map files called map.a2d, map.n2a, and map.sup. (These have been compiled using information from several of the files provided in Karl Berry’s fontname package.)

Here’s what you’ll need to properly install your fonts using VFinst:

1. a version of TEX that understands virtual fonts (version 3 or better of TEX);

2. the fontinst package (available from any ctan archive or mirror in the area fonts/utilities/fontinst/inputs; installation of this package is easy—you simply 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 ‘tex/inputs’ and on a tds system, a place like

texmf/tex/generic/fontinst

3. the dvips post-processor;

4. a copy of the file 8r.enc, part of the fontname package (this package is available from any ctan archive from the area info/fontname); and 5. 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 cdrom collections of software.

2.1 Operating system

This material should run on any platform on which runs Perl and TEX. I (the author) tested it on Unix. It has also been tested on Windows NT.

3 Installation and set up

There are some things that need setting in the file vfinst.par. 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.

3.1 Everybody needs to set these...

1. $vfenc is the encoding you’ll want to be using. Although many in the TEX community are pushing an encoding called t1, I prefer to use the original TEX encoding called ot1 because there is room in these virtual fonts for many additional characters. Your only choice for this parameter is t1 or ot1. Users of versions of L^{A}TEX predating December 1996 might enter T1 or OT1 instead.

2. $vfencoding is the place which contains a copy of the file 8r.enc (which describes the 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 psfonts.map become uncomfortably long. You don’t need to set this variable; if it’s not set, VFinst will assume that 8r.enc appears in the same directory as $vfmapdir.

3.2 TDS systems

TEX knows it’s a tds installation if the variable $vftexmf is defined; it should have as value the root TEX/MF directory. One advantage of tds is that VFinst can then figure out for itself where most things belong.

In a 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 ‘agaramon’, ‘times’, etc.) and a supplier (adobe, 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.

3.3 Traditional systems

On traditional systems, all .afm’s go in one place, all .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.

1. $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 dvips or driver documentation to see where those programs expect to find the vf’s. It should be something like

           "/usr/lib/tex/fonts/vf"

(Unix) or perhaps

           "\\emtex\\fonts\\vf"

(dos; the backslash must be doubled as shown, or Perl will misunderstand it).

2. $vftfm is the place where TEX looks for your .tfm files.

3. $vfpsfonts records the location of your outline font files, files typically with extensions .pfa or .pfb.

4. $vfafm is the directory containing all the .afm files for the outline font files. Unlike most software out there, TEX needs these files.

5. $vfmapdir is the place where you keep the file psfonts.map that dvips uses.

6. $vfinputs is the place where the .fd and other input files belong.

3.4 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 vfinst.par.

On a Unix tds system, these settings might have the following form.

$vftexmf    = "/usr/local/texmf";
$vfencoding = "/usr"; # where is the file 8r.enc?
$vfenc      = "ot1";

Here is a sample Unix setup for a traditional TEX system.

$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";

On a dos system, these instructions might take the form

$vfmapdir   = "\\tex\\ps";
$vfinputs   = "\\tex\\inputs";
$vfencoding = "$vfinputs";
$vfenc      = "t1";
$vfvf       = "\\tex\\fonts\\vf";
$vftfm      = "\\tex\\fonts\\tfm";
$vfpsfonts  = "\\psfonts";
$vfafm      = "\\psfonts\\afm";

(note the doubled backslashes).

3.5 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 ‘#!’), then all you’ll need to do is adjust the initial line of files 1vfinst and 2vfinst to reflect the location of your Perl executable. On Unix systems, you’ll also need to make these scripts executable via the chmod +x command.

If your version of TEX is a multitasking application, such as Tom Rokicki’s excellent TEXView on NextStep, you’ll need to make the application quit and restart it to make your new fonts visible to it.

3.6 Installation

To install VFinst, create a new directory, possibly something like

 /usr/local/vfinst

or

 \tex\vfinst

under dos. Copy the VFinst files into that directory.

Now create a work directory below this new directory, with a full pathname like

 /usr/local/vfinst/work

for Unix or

 \tex\vfinst\work

under dos. Switch to this lowest level work subdirectory, which we will call the VFinst working 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 implemenation of TEX contains the parent directory and the current directory on its own search path.

4 Running VFinst

To use VFinst, simply copy all the fonts (outline file plus .afm file) to the VFinst working 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. You MUST make sure that the outline font file and the matching .afm have identical filenames.

Then, simply execute the following sequence of commands:

   • 1vfinst
   • 2vfinst

Under the ‘shebang’ notation, you need simply enter something like ../1vfinst; otherwise, type something like 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 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 BaskervilleMT while the matching expert font is in the family BskvillExpMT. (These are the names appearing in the .afm file.) A TEX author clearly needs them in the same font family, so verify family mbv for the first, and verify family mbv for the second, so that VFinst will know they are in the same family.

It often pays to briefly examine the files that 1vfinst produces. There is a small file 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 .pfb and .afm file. Entries in this file may also indicate a problem with the .afm file; see page 11 below for more on this.

The other output file is 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. In the interest of efficiency, you may be able to examine this list and decide that some fonts, such as special fraction or ornament fonts, can be eliminated from the installation process. (If you leave them in, they won’t effect the final fonts, but the ‘tex’ step may just take longer to run.) 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

1vfinst.

There are five additional steps. Execute the following scripts (outputs of the previous two steps)

   • mkdirs.bat
   • newnames.bat

to create any missing directories and to rename the fonts according to the fontname2.1 conventions. These steps take very little time.

Then, execute the command

tex makefont

to create the virtual fonts; the file makefont.tex is the output of the original Perl scripts. This step may take quite a long while—over an hour on certain systems for large font families. Ignore warnings about missing glyphs.

Finally, execute two more scripts:

   • maketfm.bat
   • putfonts.bat

These two scripts, which execute rapidly, are responsible for converting Ascii property list files into the binary .tfm and .vf files that TEX expects, and for placing all files into places from which TEX can use them for typesetting.

Once you’ve executed these seven (7) steps, the fonts are ready for use. You can test your fonts by running either of the files testpln.tex or testltx.tex through plain TEX or through L^{A}TEX. These files also show what commands to use to select your new fonts.

Once the installation has been completed according to the above seven (7) steps, everything left in the work directory may be deleted.

4.1 Installing ‘raw’ fonts

VFinst is intended for fonts that require auxiliary constructs called 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, 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 foo.afm and foo.pfb for installation. Follow these steps:

• Use an editor to examine foo.afm. Near the top of this file (half a dozen lines or so) is a line beginning with the phrase

FontName

Make careful note of the font name following this keyword. We will need this information, and it is important to follow the spelling and the use of upper- and lowercase characters exactly. In this case, let’s suppose the font name is FooRoman.

• Place the .afm and .pfb font files where they belong on your system disk.

• Add an entry line like

foo FooRoman < /psfonts/foo.pfb

in the file psfonts.map. Of course, make changes to this line as appropriate.

• To select this font in a plain document, add a line like

\font\myfont = foo at 13pt

to make \myfont the command that selects this font (at thirteen points). In L^{A}TEX, you can use the undocumented command

\newfont{\myfont}{foo at 13pt}

to accomplish the same goal.

5 Using your new fonts

The files testpln.tex or testltx.tex can help you test and preview your new fonts. These files also can be consulted to see how these fonts were selected; this will be most useful for users of plain TEX.

L^{A}TEX users will, of course, select these fonts by selecting the proper family, series, and shape. Note that in the presence of expert fonts, VFinst creates two families—one that is expertised but with standard numerals, and another that is expertised and uses old style figures. In the absence of expert fonts, VFinst installs a single family (and creates small caps by means of judicious scaling of the font majuscules. Thus, if the font family name foo has no expert fonts, VFinst installs the raw fonts under the family foo. In the presence of expert fonts, you will have two families—foox and foo9. Note too the existence of several new font shapes which may be available for use by nfss:

• si provides italic small caps; • t provides a titling or display font;

• ti provides a titling or display italic;

• sw provides a swash italic variant;

• un provides an underline upright font; and

• ni provides an underline italic font.

VFinst will only provide these shapes in case the original raw fonts that were present support these shapes.

6 Causes for failure and other problems

VFinst was extensively tested on several popular font families, including Adobe Garamond, Adobe Caslon, Adobe Minion, Monotype Bulmer, and Monotype Baskerville, plus many other families of fonts that were lying around on my hard disk. They all installed fine for me.

VFinst maintains an extensive log file called vfinst.vlg which contains useful information which may be of use in case of disaster or other problems. (Another log file, maketfm.vlg, records information about the making of the binary font files but is generally of less usefulness.)

You may find that when you install too many fonts at once, TEX won’t have enough font memory to load all of them at once. You may have to compile the test documents in parts—comment out a portion, test the remainder, and vice versa.

Installing too many fonts may lead to another rare error involving dvips. After a while, the psfonts.map file becomes too lengthy and dvips expires while complaining of being ‘out of string space’. The easiest fix is simply to comment out entries in psfonts.map that you aren’t currently using. The comment character is TEX’s ‘%’ symbol.

VFinst warns you on the rare occasion when the fontname name of a font exceeds eight characters; an example is the swash italic display characters in Adobe Minion. This is only a problem for dos users, who should probably remove these fonts from the VFinst work directory and re-run VFinst. (It’s likely that such fonts are not crucial for the installation, at least in this version

of VFinst.)

6.1 Fixing .afm files

Virtual fonts that are created but don’t typeset as you expect may indicate a problem with the font .afm files rather than with VFinst. Font providers are often careless (at best!) with these files. Errors that I have encountered include misspelling the words ‘bold’ and ‘italic’ (now really!), improper specifying an x-height to be 0, and improperly naming the glyphs of the fonts. All these will effect the resulting fonts.

Entries in the file duplicat.lst may indicate other problems with the .afm file. While testing, I many times received warning that VFinst thought that one font was a duplicate of another when in fact one font was a regular weight and the second was bold. Closer inspection of the bold .afm revealed the problem— the ‘Weight’ entry the .afm file had erroneously been filled in as ‘regular’ even though it was a bold font. Basically, .afm problems involve correcting metric data in the body of the file or correcting non-metric data in the initial portion of the file. Both fontinst and VFinst provide means for correcting these errors. It is a bad, bad idea to make corrections to the .afm file itself.

Changes to data in the initial portion of an .afm involve creating a file called vfinst.rc each line of which records three items—the name of the deficient .afm file, the name of the category to change, and the corrected value. Each of these fields should be separated by one or more spaces. For example, a typical such file might look like this:

## This is vfinst.rc!
xxxxx   Weight       bold
yyyyy   ItalicAngle  -13
zzzzz   FullName     Centaur Swash Italic MT

This file indicates that VFinst is to regard the weight of the font described by xxxxx.afm as bold, the italic angle of yyyyy.afm as −13^{∘}, and the full name of zzzzz.afm as given here. (This last is an interesting example. The original font didn’t include the word ‘italic’ in the font name, so VFinst assumed the swash applied to upright fonts.) This .rc file belongs in the work directory.

Problems with the body of the .afm file can be fixed with special fontinst instructions. For example, one serious yet common problem involves improper naming of the glyphs within the .afm file. Suppose an expert font names its lowercase letters ‘a’, ‘b’, and so on instead of ‘Asmall’, ‘Bsmall’, etc. Then fontinst, the engine on which VFinst runs, will not use these glyphs in a small caps font. Here’s how I used fontinst to fix this.

When installing a font via the command

\installfont{foorc9t}{foor8r,foorc8a,latin}%
  {OT1c}{OT1}{foox}{m}{sc}{}

where the foo fonts suffer this disability, I “turn off” the miniscule (lowercase) information with commands like

\unsetglyph{a}

placed (together with additional syntactical necessities) in a file minoff.mtx. In the same way, commands in a file numoff.mtx turn off standard digit glyph information. Then, I make use of the glyph information in the small caps font (here, foorc8a) with commands like

\SmallCapFrom{Asmall}{a}

in a file smcapon.mtx which also contains a definition of this command. In the same way, the file osfon.mtx sets old style figures from the glyphs in this font. These four metric .mtx files are part of the VFinst distribution; please use them as examples for solving similar kinds of problems. We use them in this instance by modifying the above install command by hand:

\installfont{foorc9t}{foor8r,minoff,numoff,foorc8a,smcapon,%
  osfon,latin}{OT1c}{OT1}{foox}{m}{sc}{}

Now, run the revised file makefont.tex through TEX, and continue the VFinst process from this point.

7 Other operating systems

I designed these scripts to be easy to adapt to other operating systems. That, in fact, motivated my choice of Perl. All of the testing and development work was done in Unix, however.

Here are some things that need attention in going to another operating system. Change the three environment variables marked for ‘wizards only’.

1. $vfsep is the directory separator in paths; for ex, / in Unix, \ in dos.

2. $vfcopy is the copy command (eg, cp and copy in Unix and dos. respectively)

3. $vfdel is the delete command (for erasing files); it is rm in Unix and del in dos.

4. $mv is the move command—the command that will move one file onto another even if the destination file already exists. In Unix, this command is ‘mv’. On dos, it is ‘call domove’ where domove.bat is a batch file with lines

     copy %1 %2
     del %1

(The file domove.bat is part of the dos distribution. You must remember to copy it to the VFinst working directory or to a place on your system’s search path.)

5. $ren is the command for renaming a file.

6. $rem is the string that introduces comments in system Ascii files. It is ‘#’ and ‘rem’ in Unix and dos.

Other places in the Perl files where it seemed to me would require system dependent changes are marked by the phrase ‘system dependent’ in comments in the code.

8 Additional info; authorial communications

For some additional information, please consult the book TEX Unbound: L^{A}TEX and TEX Strategies for Fonts, Graphics, and More by Alan Hoenig (New York and Oxford: Oxford University Press, 1998).

I’d love to hear from anyone with comments, criticisms, suggestions for improvements, and (of course) bugs that need fixing.

Alan Hoenig

                                             ajhjj@cunyvm.cuny.edu

Department of Mathematics

John Jay College 445 West 59th Street

New York, NY 10019 USA