1PKFIX-HELPER(1)                                                PKFIX-HELPER(1)
2
3
4

NAME

6       pkfix-helper - preprocess dvips-produced PostScript documents before
7       passing them to pkfix
8

SYNOPSIS

10       pkfix-helper [--help] [--verbose] [--force=name=fontspec]
11       [--ps=filename.ps] [--tex=filename.tex] [--cache=filename]
12       [--include=fontspec] [--exclude=regexp] [--keep=fontspec] [--quiet]
13       [--no-repeats] [--spp=number] [input.ps [output.ps]]
14

DESCRIPTION

16   Motivation
17       PostScript documents created with old versions of dvips almost
18       invariably utilize bitmapped (PostScript Type 3) fonts.  The problem
19       with bitmapped fonts is that they target a specific device resolution;
20       a PostScript file produced using 300 DPI fonts will look grainy on a
21       600 DPI printer.  Even worse, all bitmapped fonts look grainy when
22       zoomed in on screen.  The solution is to use vector (PostScript Type 1)
23       fonts, which are resolution-independent and appear crisp at any size or
24       scale.
25
26       While it is no longer difficult to configure dvips to use vector fonts,
27       it is not always possible to rerun dvips on an old .dvi file.  The .dvi
28       file and document source may have been lost; or, the source may no
29       longer compile because packages it depends upon may no longer be
30       available.
31
32       Heiko Oberdiek's pkfix script replaces bitmapped fonts in
33       dvips-produced PostScript files with the corresponding vector fonts.
34       It works by parsing the PostScript comments with which dvips surrounds
35       bitmapped-font definitions.  For example, a font definition beginning
36       with the comment "%DVIPSBitmapFont: Fi cmss10 11 28" and ending with a
37       matching %EndDVIPSBitmapFont is known to define font "Fi" as "cmss10"
38       (Computer Modern Sans Serif at a design size of 10 points) scaled to
39       11 points.  Only the 28 characters actually used by the document are
40       defined.  pkfix then replaces the font definition with one that defines
41       "Fi" using the same set of characters but taken from the cmss10.pfb
42       vector font file.
43
44       Unfortunately, pkfix works only with versions of dvips newer than v5.58
45       (ca. 1996).  Naturally, the older a PostScript document, the less
46       likely its sources still exist and can still be recompiled.  Older
47       versions of dvips lack %DVIPSBitmapFont comments and various other
48       PostScript comments on which pkfix relies.  Without PostScript comments
49       to guide it, pkfix is unable to determine which vector fonts correspond
50       with which bitmapped fonts.
51
52   Overview
53       The pkfix-helper script is a preprocessor for pkfix that attempts to
54       determine the association between each document-font name (e.g., "Fi")
55       in a PostScript file and the original font (e.g., "cmss10") and fonts
56       size (e.g., 11 points).  It then fabricates the PostScript comments
57       that pkfix expects to see so that pkfix can do its job.
58
59       pkfix-helper works by comparing every document font against every .tfm
60       font file it knows about (assuming that each such font has a
61       corresponding .pfb vector version) and selecting the best matching .tfm
62       file for every document font.  pkfix-helper has access only to the
63       widths of characters and only to those characters actually used in the
64       document.  Also, the program recognizes only a limited set of the most
65       popular .tfm files and scaling factors.  Consequently, the comparison
66       is imperfect and pkfix-helper may attribute an incorrect font to a
67       given name.  Fonts comprising only one or two characters actually used
68       in a document are particularly problematic for pkfix-helper because
69       many fonts may be near-enough matches to fool the problem.
70
71       pkfix-helper is designed so that a user can guide the font-selection
72       process by manually designating matching fonts.  With a modicum of
73       diligence and patience a user can correct any mismatched fonts and help
74       the program provide proper input to pkfix.
75

OPTIONS

77       pkfix-helper accepts on the command line the filename of a PostScript
78       document to process (with the default being the standard input device)
79       and the filename of a modified PostScript document to create (with the
80       default being the standard output device).  The program also accepts
81       the following command-line options:
82
83   Frequently Used Options
84       -h, --help
85           Display usage information and exit.  The --verbose and --quiet
86           options can be used to increase and decrease the amount of
87           information presented.
88
89       -v, --verbose
90           Increase the amount of status information that pkfix-helper
91           displays as it runs.  Additional instances of --verbose on the
92           command line further increase the program's verbosity.  By default,
93           only major operations are displayed.  A single --verbose
94           additionally displays information about individual font
95           comparisons.  A second --verbose additionally displays details
96           about some of the program's internal operations.
97
98       -f name=fontspec, --force=name=fontspec
99           Force pkfix-helper to associate a specific font with a given font
100           name appearing the document.  name is a two-character dvips font
101           name such as "Fa".  fontspec is a font specification such as
102           "cmmi8" or "cmsy10 @ 1.1X".  An asterisk used in the name of the
103           base font (e.g., "cmti*") will automatically try all integral test
104           font sizes from 5 to 17 points ("cmti5", "cmti6", ..., "cmti17").
105           An asterisk used as a scale value (e.g., "cmsy10 @ *") will be
106           replaced by the scale value that gives the best match to the
107           original font's metrics.  The --force option can be specified
108           repeatedly on the command line.
109
110       -p filename.ps, --ps=filename.ps
111           Create a PostScript file called filename.ps that shows the dvips
112           name and a font sample of every font used by the input document.
113
114       -t filename.tex, --tex=filename.tex
115           Create a Plain TeX file called filename.tex that shows the dvips
116           name and a font sample of every font that pkfix-helper used in the
117           output document.
118
119   Infrequently Used Options
120       -C filename, --cache=filename
121           Speed up TFM file processing by caching character metrics into file
122           filename.  On some systems it takes a long time to read a TFM file,
123           spawn tftopl to convert it to PL format, and extract from the PL
124           data the metrics for each character.  The first time --cache is
125           specified, pkfix-helper proceeds as normal then writes all of the
126           extracted character metrics to filename.  On subsequent runs in
127           which --cache=filename is specified, pkfix-helper reads the
128           previously extracted metrics from filename, going through the
129           tftopl-based process only for TFM files that were not previously
130           encountered.
131
132       -q, --quiet
133           Instruct pkfix-helper to produce no output during its run except
134           for fatal error messages.
135
136       -1, --no-repeats
137           Prevent pkfix-helper from associating the same fontspec with more
138           than one dvips font name.
139
140       -i fontspec, --include=fontspec
141           Add fontspec to the list of font specifications against which
142           pkfix-helper compares every document font.  (In contrast, --force
143           designates a font specification to use only for a specific document
144           font.)  The --include option can be specified repeatedly on the
145           command line.
146
147       -x regexp, --exclude=regexp
148           Remove all font specifications matching regular expression regexp
149           from pkfix-helper's list of known fonts.  The --exclude option can
150           be specified repeatedly on the command line.
151
152       -k fontspec, --keep=fontspec
153           Do not substitute a vector font for bitmapped font fontspec ("Fa",
154           "Fb", etc.).  This is useful when converting documents that use
155           obscure bitmapped fonts for which there is no vector equivalent.
156           For example, it was somewhat common in the past to include graphics
157           such as university or corporate logos into a document by converting
158           the bitmapped image into a single-character font and using that
159           font in LaTeX.  --keep prevents such fonts from being replaced.
160           The --keep option can be specified repeatedly on the command line.
161
162       -a, --any-scale
163           Allow any value to be used to scale a font when ""*"" is specified
164           as the scale factor.  Normally, pkfix-helper considers only integer
165           multiples of 0.1 that are greater than or equal to 1.0 (i.e.,
166           fontname@1X, "@1.1X", "@1.2X", "@1.3X", etc.).
167
168       -s, --spp
169           Specify the number of font samples per page to print to the files
170           indicated using the --ps and --tex options.  The default value, 25,
171           should work well in most circumstances.
172

DIAGNOSTICS

174       "Best match for name is rather poor"
175           The best font pkfix-helper found for dvips font name name has a
176           mismatch value greater than or equal to 1.0.  (The mismatch value
177           is the sum of the squares of the difference between the character
178           widths of a document font and a potential replacement font.)  Use
179           the --force option to designate an alternative replacement font or
180           scaling amount.
181

EXAMPLES

183       For the purpose of the following examples, assume that oldfile.ps is
184       the name of a PostScript file produced by an old version of dvips and
185       utilizing at least one bitmapped font.  It's always worth verifying
186       that pkfix can't convert the file on its own:
187
188           $ pkfix oldfile.ps newfile.ps
189           PKFIX 1.3, 2005/02/25 - Copyright (c) 2001, 2005 by Heiko Oberdiek.
190           ==> no fonts converted
191
192       (Alternatively pkfix may issue an error message such as "!!!  Error:
193       Parse error (@start parameters)!".)  Only when pkfix can't replace
194       bitmapped fonts with vector fonts is pkfix-helper needed.  In its
195       simplest form, pkfix-helper takes the name of an input file (oldfile.ps
196       in this example) and the name of an output file (pkfix-oldfile.ps),
197       which will have the same contents as the input file but serve as
198       suitable input for pkfix:
199
200           $ pkfix-helper oldfile.ps pkfix-oldfile.ps
201           Reading oldfile.ps ... done.
202           Number of Type 3 fonts encountered: 10
203           Bitmapped fonts are typeset at 600 DPI.
204           Finding character widths ... done.
205           Reading TFM files ... done (103 TFMs in 193 scaling variations).
206           Matching fonts:
207               Processing Fi ... done (cmr10 @ 1X, mismatch=0.11683).
208               Processing Fa ... done (cmti10 @ 1X, mismatch=0.08892).
209               Processing Fb ... done (cmr8 @ 1X, mismatch=0.07133).
210               Processing Ff ... done (cmbx12 @ 1.2X, mismatch=0.02948).
211               Processing Fh ... done (cmtt10 @ 1X, mismatch=0.06895).
212               Processing Fd ... done (cmmi10 @ 1X, mismatch=0.03966).
213               Processing Fj ... done (cmbx12 @ 1X, mismatch=0.03972).
214               Processing Fe ... done (cmbx10 @ 1X, mismatch=0.00762).
215               Processing Fg ... done (cmsy10 @ 1X, mismatch=0.00875).
216               Processing Fc ... done (cmr6 @ 1X, mismatch=0.00284).
217
218           $ pkfix pkfix-oldfile.ps newfile.ps
219           PKFIX 1.3, 2005/02/25 - Copyright (c) 2001, 2005 by Heiko Oberdiek.
220           *** Font conversion: `cmti10' -> `CMTI10'.
221           *** Font conversion: `cmr8' -> `CMR8'.
222           *** Font conversion: `cmr6' -> `CMR6'.
223           *** Font conversion: `cmmi10' -> `CMMI10'.
224           *** Font conversion: `cmbx10' -> `CMBX10'.
225           *** Font conversion: `cmbx12' -> `CMBX12'.
226           *** Font conversion: `cmsy10' -> `CMSY10'.
227           *** Font conversion: `cmtt10' -> `CMTT10'.
228           *** Font conversion: `cmr10' -> `CMR10'.
229           *** Font conversion: `cmbx12' -> `CMBX12'.
230           *** Merging font `CMBX12' (2).
231           ==> 10 converted fonts.
232           ==> 1 merged font.
233
234       Although pkfix-helper tries to automate as much as possible the font-
235       detection process, some fonts will invariably be incorrectly
236       identified.  The program outputs a warning message if it knows a match
237       is bad but the lack of a warning message does not necessarily indicate
238       that pkfix-helper did a good job.  It is therefore strongly recommended
239       that the user produce "before" and "after" font sheets:
240
241           $ pkfix-helper -q oldfile.ps pkfix-oldfile.ps \
242             --ps=oldfonts.ps --tex=newfonts.tex
243
244           $ tex newfonts.tex
245           This is TeX, Version 3.14159 (Web2C 7.4.5)
246           (./newfonts.tex [1] )
247           Output written on newfonts.dvi (1 page, 1292 bytes).
248           Transcript written on newfonts.log.
249
250           $ dvips newfonts.dvi -o newfonts.ps
251           This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
252           ' TeX output 2006.06.11:1636' -> newfonts.ps
253           <texc.pro><8r.enc><texps.pro>. <cmr6.pfb><cmsy10.pfb><cmbx10.pfb><cmbx12.pfb>
254           <cmmi10.pfb><cmtt10.pfb><cmr8.pfb><cmti10.pfb><cmr10.pfb>[1]
255
256       After running the preceding commands, oldfonts.ps shows samples of the
257       fonts in oldfile.ps and newfonts.ps shows samples of the replacement
258       fonts that pkfix-helper used to produce pkfix-oldfile.ps.  Print
259       oldfonts.ps and newfonts.ps and compare them carefully for incorrect
260       fonts and sizes.
261
262       Suppose that the choice of "cmbx12 @ 1.2X" for font "Ff" looks wrong;
263       say the characters look taller in oldfonts.ps than in newfonts.ps.
264       This is where the trial-and-error stage begins.  Let's hypothesize that
265       "cmb12" is a better match than "cmbx12" but we don't know how much to
266       scale the font.  Fortunately, pkfix-helper allows "*" to be used as a
267       scaling factor to tell the program to automatically detect an optimal
268       scaling factor, even if doing so means choosing a nonstandard font
269       size:
270
271           $ pkfix-helper oldfile.ps pkfix-oldfile.ps --force="Ff=cmb12 @ *"
272           Reading oldfile.ps ... done.
273           Number of Type 3 fonts encountered: 10
274           Bitmapped fonts are typeset at 600 DPI.
275           Finding character widths ... done.
276           Reading TFM files ... failed.
277           pkfix-helper: Unable to process user-specified TFM file "cmb12"
278
279       Oops, it looks like we don't have a cmb12.tfm file on our system.
280       Let's try scaling up cmb10.tfm instead:
281
282           $ pkfix-helper oldfile.ps pkfix-oldfile.ps --force="Ff=cmb10 @ *"
283           Reading oldfile.ps ... done.
284           Number of Type 3 fonts encountered: 10
285           Bitmapped fonts are typeset at 600 DPI.
286           Finding character widths ... done.
287           Reading TFM files ... done (103 TFMs in 193 scaling variations).
288           Matching fonts:
289               Processing Fi ... done (cmr10 @ 1X, mismatch=0.11683).
290               Processing Fa ... done (cmti10 @ 1X, mismatch=0.08892).
291               Processing Fb ... done (cmr8 @ 1X, mismatch=0.07133).
292               Processing Ff ... done (cmb10 @ 1.5X, mismatch=0.00035).
293               Processing Fh ... done (cmtt10 @ 1X, mismatch=0.06895).
294               Processing Fd ... done (cmmi10 @ 1X, mismatch=0.03966).
295               Processing Fj ... done (cmbx12 @ 1X, mismatch=0.03972).
296               Processing Fe ... done (cmbx10 @ 1X, mismatch=0.00762).
297               Processing Fg ... done (cmsy10 @ 1X, mismatch=0.00875).
298               Processing Fc ... done (cmr6 @ 1X, mismatch=0.00284).
299
300       The match has definitely improved, although 15 pt. is certainly an odd
301       size for a font.  Then again, many documents do use nonstandard sizes
302       so this may in fact be correct.  The best way to verify is once again
303       to produce, print, and compare a pair of font samples and iterate until
304       all of the fonts look correct.  Use one instance of --force for each
305       font you want to alter.
306

ENVIRONMENT

308       pkfix-helper honors the following environment variables:
309
310       GS      The name of the Ghostscript interpreter (default: gs)
311
312       TFTOPL  The name of a utility for converting .tfm files to .pl files
313               (default: tftopl)
314

BUGS

316       Even when pkfix-helper finds a perfect match (i.e., the correct font in
317       the correct size) the mismatch value is still typically nonzero.  The
318       same error is probably what causes pkfix-helper sometimes to consider
319       the wrong font as being a better match than the correct font.
320       Suggestions for fixing these bugs are welcome.
321

RESTRICTIONS

323       pkfix-helper works only with PostScript files produced by dvips, not
324       with arbitrary PostScript files.  The program has not been tested with
325       output from versions of dvips older than v5.490 (ca. 1992); output from
326       older versions may or may not work.  Only bitmapped fonts loaded by
327       dvips can be analyzed, not bitmapped fonts loaded by embedded graphics.
328
329       pkfix-helper works by comparing character widths, not the actual
330       glyphs.  Consequently, it is misled by sets of fonts with similar
331       character widths (at least for those characters used by a given
332       document).  As an extreme example, all Computer Modern Teletype fonts
333       of a given design size (e.g., "cmtt10", "cmsltt10", and "cmitt10") use
334       exactly the same widths for all characters.  Human assistance is
335       generally needed to guide pkfix-helper's font-matching procedures.
336

NOTES

338       Files produced using the --tex option are Plain TeX files and therefore
339       must be compiled with tex (or a variation such as pdftex, luatex,
340       etc.), not with latex.
341

SEE ALSO

343       pkfix(1), dvips(1), tex(1), gs(1)
344
345       PostScript Language Reference, Third Edition.  Published by Addison-
346       Wesley, ISBN 0-201-37922-8,
347       <http://www.adobe.com/products/postscript/pdfs/PLRM.pdf>.
348

AUTHOR

350       Scott Pakin, scott+pkfh@pakin.org
351
353       Copyright (C) 2011, Scott Pakin
354
355       This file may be distributed and/or modified under the conditions of
356       the LaTeX Project Public License, either version 1.3c of this license
357       or (at your option) any later version.  The latest version of this
358       license is in <http://www.latex-project.org/lppl.txt> and version 1.3c
359       or later is part of all distributions of LaTeX version 2006/05/20 or
360       later.
361
362
363
364v1.4                              2011-06-11                   PKFIX-HELPER(1)
Impressum