summaryrefslogtreecommitdiff
path: root/fonts/utilities/vfinst/vfinst.tex
blob: 64b634dfa6ffd9f8e9bee9563252a5267738529a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
%&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 <foo.pfb
\end{verbatim}
to automatically download the font to the printer at print time.
\item Place the {\tt.afm} and {\tt.pfb} font files where they belong
on your system disk.  Place {\tt foo.tfm} where it belongs.
\item To select this font in a {\tt plain} document, add a line like
\begin{verbatim}
\font\myfont = foo at 13pt
\end{verbatim}
to make \verb+\myfont+ the command that selects this font (at thirteen
points).  In \LaTeX, you can use the undocumented command 
\begin{verbatim}
\newfont{\myfont}{foo at 13pt}
\end{verbatim}
to accomplish the same goal.
\end{itemize}

\section{Using your new fonts}
The files {\tt testpln.tex} or {\tt 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 \TT
plain \TeX.

\LaTeX\ users will, of course, select their 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 \TT foo has no expert
fonts, \vfinst\ installs the raw fonts under the family {\tt foo}.  In
the presence of expert fonts, you will have two families---{\tt foox}
and {\tt foo9}.  Note too the existence of several new font shapes
which may be available for use by {\sc nfss}:
\begin{itemize}
  \item {\tt si} provides italic small caps;
  \item {\tt t}  provides a titling or display font;
  \item {\tt ti} provides a titling or display italic; 
  \item {\tt sw} provides a swash italic variant;
  \item {\tt un} provides an underline upright font; and
  \item {\tt ni} provides an underline italic font.
\end{itemize}
\vfinst\ will only provide these shapes in case the original raw fonts
that were present support these shapes.

\section{Causes for failure and other problems}
\vfinst\ maintains an extensive log file called \TT vfinst.vlg
which contains useful information which may be of use in case of
disaster or other problems.  (Another log file, \texttt{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 so on.

Installing too many fonts may lead to another rare error involving
older versions of \textit{dvips}.  After a while, the
\texttt{psfonts.map} file becomes too lengthy and \textit{dvips}
expires while complaining of being `out of string space'.  The easiest
fix is simply to comment out entries in \texttt{psfonts.map} that you
aren't currently using.  The comment character is \TeX's `{\tt\%}'
symbol.  Even better: simply update to a current version of
\textit{dvips}. 

\vfinst\ warns you on the rare occasion when the {\tt 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
\textsc{dos} users, who should probably remove these fonts from the
\vfinst\ {\tt work} directory and re-run \vfinst.  

\subsection{Fixing {\tt.afm} files}
Virtual fonts that are created but don't typeset as you expect may
indicate a problem with the font {\tt.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.

\label{afm-error}Entries in the file \TT duplicat.lst may 
indicate other problems with the \TT.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 \TT.afm revealed
the problem---the `Weight' entry the \TT.afm file had erroneously been
filled in as `{\tt regular}' even though it was a bold font.
Basically, \TT.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 \TT fontinst and \vfinst\ provide means for correcting
these errors.  It is a bad, bad idea to make corrections to the
\TT.afm file itself.  

Changes to data in the initial portion of an \TT.afm involve creating
a file called \TT vfinst.rc each line of which records three
items---the font name of the deficient font, the name of the
characteristic to change, and the corrected value of that
characteristic.  Each of these fields should be separated by one or
more spaces.  The font name is the long font name that follows the
keyword `FontName' in the first part of the \TT.afm file (within the
the first dozen lines from the top of the file).

The \TT.rc file that comes with the current distribution looks like this:
{\fontsize{8}{9}\selectfont
\begin{verbatim}
CentaurSwashMT            FullName       Centaur Swash Italic MT
Courier                   Weight         Roman
Courier-Oblique           Weight         Roman
Helvetica                 Weight         Roman
JansonExpertMT-BoldItalic ItalicAngle    -14
NewCenturySchlbk-Italic   Weight         Roman
Palatino-Italic           Weight         Roman
AGaramond-Bold            Weight         Bold
AGaramond-Semibold        Weight         Semibold
AGaramond-BoldItalic      Weight         Bold
AGaramond-SemiboldItalic  Weight         Semibold
AGaramondExp-Bold         Weight         Bold
AGaramondExp-Semibold     Weight         Semibold
AGarExpSemIta             Weight         Semibold
AGarExpSemIta             FullName Adobe Garamond Expert Semibold Italic
AGaramondExp-BoldItalic   Weight         Bold
AGaramond-BoldItalic      ItalicAngle    -18.5
AGaramondExp-BoldItalic   ItalicAngle    -18.5
AGarExpSemIta             ItalicAngle    -18.5
AGaramond-SemiboldItalic  ItalicAngle    -18.5
AGaramond-Italic          ItalicAngle    -18.5
AGaramondExp-Italic       ItalicAngle    -18.5
AGaramondAlt-Italic       ItalicAngle    -18.5
NewsGothic-Oblique        Weight         Medium
Garamond-BookItalic       Weight         Book
NewsGothic-BoldOblique    Weight         bold
\end{verbatim}
}%
This file indicates, for example, 
that \vfinst\ is to regard the weight of the font
\TT Courier as Roman, the italic angle of \TT JansonExpertMT-BoldItalic
as $-14^{\circ}$, and the full name of \TT CentaurSwashMT as that 
given here.  (The original font didn't include the
word `italic' in the font name, so \vfinst\ assumed the swash applied
to upright fonts.)  

I'd be grateful to anyone who could send me additional errors of this
nature they encounter in using fonts, so I can encounter them in
future revisions of this file. 

%% Problems with the body of the \TT.afm file can be fixed with special
%% \TT fontinst instructions.  For example, one serious yet common
%% problem involves improper naming of the glyphs within the \TT.afm
%% file.  Suppose an expert font names its lowercase letters
%% `a', `b', and so on instead of `Asmall', `Bsmall', etc.  Then {\tt
%% fontinst}, the engine on which \vfinst\ runs, will not use these
%% glyphs in a small caps font.  Here's how I used \TT fontinst to fix
%% this. 
%% 
%% When installing a font via the command
%% \begin{verbatim}
%% \installfont{foorc9t}{foor8r,foorc8a,latin}%
%%   {OT1c}{OT1}{foox}{m}{sc}{}
%% \end{verbatim}
%% where the {\tt foo} fonts suffer this disability, I ``turn off'' the
%% miniscule (lowercase) information with commands like
%% \begin{verbatim}
%% \unsetglyph{a}
%% \end{verbatim}
%% placed (together with additional syntactical necessities) in a file
%% \TT minoff.mtx.  In the same way, commands in a file \TT numoff.mtx
%% turn off standard digit glyph information.  Then, I make use of the
%% glyph information in the small caps font (here, {\tt foorc8a}) with
%% commands like
%% \begin{verbatim}
%% \SmallCapFrom{Asmall}{a}
%% \end{verbatim}
%% in a file {\tt smcapon.mtx} which also contains a definition of this
%% command.  In the same way, the file {\tt osfon.mtx} sets old style
%% figures from the glyphs in this font.  These four metric \TT.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 {\em by hand\/}:
%% \begin{verbatim}
%% \installfont{foorc9t}{foor8r,minoff,numoff,foorc8a,smcapon,%
%%   osfon,latin}{OT1c}{OT1}{foox}{m}{sc}{}
%% \end{verbatim}
%% Now, run the revised file \TT makefont.tex through \TeX, and continue
%% the \vfinst\ process from this point.

\section{Other operating systems}

{\fontsize{9}{10}\selectfont
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'.  
\begin{enumerate}
\item \TT\$vfsep is the directory separator in paths; for ex, \TT/ in Unix, 
   \verb|\| in \textsc{dos}.
\item \TT\$vfcopy is the copy command (eg, \TT cp and \TT copy in Unix
    and \textsc{dos}.  respectively)
\item \TT\$vfdel is the delete command (for erasing files); it is \TT
    rm in Unix and \TT del in \textsc{dos}.
\item \TT\$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 `\texttt{mv}'.  On {\sc dos}, it is `{\tt call
domove}' where {\tt domove.bat} is a batch file with lines
\begin{verbatim}
copy %1 %2
del %1
\end{verbatim}
(The file {\tt domove.bat} is part of the {\sc dos} distribution.  You must
remember to copy it to the \vfinst\ working directory or to a place on your
system's search path.)
\item \TT\$ren is the command for renaming a file. 
\item \TT\$rem is the string that introduces comments in system {\sc
Ascii} files.  It is `{\tt\#}' and `{\tt rem}' in Unix and {\sc dos}.
\end{enumerate}

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.\par}

\section{Additional info; authorial communications; acknowledgments}
I'm truly grateful for the comments, suggestions, and trapped bugs
reported by folks who took time to wrestle with this software.  I
especially want to acknowledge
\helper{Chang}{Andrew}, 
\helper{Christian}{Burger},
\helper{Courjon}{Daniel}, 
\helper{Marquardt}{Colin},
\helper{Ness}{David} (especially!), 
\helper{Padowitz}{Seth},
\helper{Roggen}{Arend van }, 
\helper{Sullivan}{Wayne},
\helper{Swift}{Matt},
\helper{Walker}{Richard}, and
\helper{Yates}{Michael}.

For some additional information, please consult the book {\it \TeX\
Unbound: \LaTeX\ 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.  

\begin{flushright}
  Alan Hoenig\\
  {\tt ajhjj@cunyvm.cuny.edu}\\
  Department of Mathematics\\
  John Jay College\\
  445 West 59th Street\\
  New York, NY 10019 USA\\[1pc]
  24 August 1998
\end{flushright}

\end{document}