1PKFIX-HELPER(1) PKFIX-HELPER(1)
2
6 pkfix-helper - preprocess dvips-produced PostScript documents before
7 passing them to pkfix
8
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
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 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 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 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 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 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 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
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 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 -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 -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 (usually) two-character
101 dvips font name such as "Fa". fontspec is a font specification
102 that comprises a font name and an optional scale: "font
103 ["@" scale]". Some examples of fontspecs are "cmmi8" and
104 "cmsy10 @ 1.1X".
105 An asterisk used in the name of the font (e.g., "cmti*") will be
107 replaced by all integers from 5 to 17 ("cmti5", "cmti6", ...,
108 "cmti17"). The scale can be written as a multiple of the design
109 size ("X") or as an absolute size in either TeX points ("pt") or
110 PostScript "big" points ("bp"). Hence, "cmsy8 @ 1.5X",
111 "cmsy8 @ 12pt", and "cmsy8 @ 11.96bp" all represent the Computer
112 Modern Math Symbols 8 Point font scaled to 12 TeX points/11.96
113 PostScript points. Instead of specifying an explicit scale, an
114 asterisk can be used (as in "cmsy8 @ *") to request that pkfix-
115 helper find the scale that best matches the original font's
116 metrics.
117 The --force option can be specified repeatedly on the command line.
119 -p filename.ps, --ps=filename.ps
121 Create a PostScript file called filename.ps that shows the dvips
122 name and a font sample of every font used by the input document.
123 -t filename.tex, --tex=filename.tex
125 Create a Plain TeX file called filename.tex that shows the dvips
126 name and a font sample of every font that pkfix-helper used in the
127 output document.
128 -k fontspec, --keep=fontspec
130 Do not substitute a vector font for bitmapped font fontspec ("Fa",
131 "Fb", etc.). This is useful when converting documents that use
132 obscure bitmapped fonts for which there is no vector equivalent.
133 For example, it was somewhat common in the past to include graphics
134 such as university or corporate logos into a document by converting
135 the bitmapped image into a single-character font and using that
136 font in LaTeX. --keep prevents such fonts from being replaced.
137 The --keep option can be specified repeatedly on the command line.
138 -1, --no-repeats
140 Prevent pkfix-helper from associating the same fontspec with more
141 than one dvips font name.
142 Less-frequently Used Options
144 -q, --quiet
145 Instruct pkfix-helper to produce no output during its run except
146 for error and warning messages.
147 -C filename, --cache=filename
149 Speed up TFM file processing by caching character metrics into file
150 filename. On some systems it takes a long time to read a TFM file,
151 spawn tftopl to convert it to PL format, and extract from the PL
152 data the metrics for each character. The first time --cache is
153 specified, pkfix-helper proceeds as normal then writes all of the
154 extracted character metrics to filename. On subsequent runs in
155 which --cache=filename is specified, pkfix-helper reads the
156 previously extracted metrics from filename, going through the
157 tftopl-based process only for TFM files that were not previously
158 encountered.
159 -i fontspec, --include=fontspec
161 Add fontspec to the list of font specifications against which
162 pkfix-helper compares every document font. (In contrast, --force
163 designates a font specification to use only for a specific document
164 font.) The --include option can be specified repeatedly on the
165 command line.
166 -x regexp, --exclude=regexp
168 Remove all font specifications matching regular expression regexp
169 from pkfix-helper's list of known fonts. The --exclude option can
170 be specified repeatedly on the command line.
171 -s, --spp
173 Specify the number of font samples per page to print to the files
174 indicated using the --ps and --tex options. The default value, 25,
175 should work well in most circumstances.
176
178 "Best match for name is rather poor"
179 The best font pkfix-helper found for dvips font name name has a
180 mismatch value greater than or equal to 1.0. (The mismatch value
181 is the sum of the squares of the difference between the character
182 widths of a document font and a potential replacement font.) Use
183 the --force option to designate an alternative replacement font or
184 scaling amount.
185 "name uses characters that don't appear in any candidate font"
187 None of the fonts considered for a match include all of the
188 characters in font name. The user should use the --force option to
189 inform pkfix-helper which font to use or the --keep option to
190 retain the original, bitmapped font.
191 "Processing name ... done (font with mismatch=number, tied with
193 font...)"
194 The best match for name is font font. A perfect match has a number
195 of 0.00000. Worse matches observe larger values. If a tie is
196 reported, this means one or more fonts matched name equally well
197 (i.e., they see the same number). In this case, pkfix-helper
198 selects the qualitatively most likely font as the winner.
199
201 For the purpose of the following examples, assume that oldfile.ps is
202 the name of a PostScript file produced by an old version of dvips and
203 utilizing at least one bitmapped font. It's always worth verifying
204 that pkfix can't convert the file on its own:
205 $ pkfix oldfile.ps newfile.ps
207 PKFIX 1.3, 2005/02/25 - Copyright (c) 2001, 2005 by Heiko Oberdiek.
208 ==> no fonts converted
209 (Alternatively pkfix may issue an error message such as "!!! Error:
211 Parse error (@start parameters)!".) Only when pkfix can't replace
212 bitmapped fonts with vector fonts is pkfix-helper needed. In its
213 simplest form, pkfix-helper takes the name of an input file (oldfile.ps
214 in this example) and the name of an output file (pkfix-oldfile.ps),
215 which will have the same contents as the input file but serve as
216 suitable input for pkfix:
217 $ pkfix-helper oldfile.ps pkfix-oldfile.ps
219 Reading oldfile.ps ... done.
220 Number of Type 3 fonts encountered: 10
221 Bitmapped fonts are typeset at 600 DPI.
222 Finding character widths ... done.
223 Reading TFM files ... done (103 TFMs in 193 scaling variations).
224 Matching fonts:
225 Processing Fi ... done (cmr10 @ 1X, mismatch=0.11683).
226 Processing Fa ... done (cmti10 @ 1X, mismatch=0.08892).
227 Processing Fb ... done (cmr8 @ 1X, mismatch=0.07133).
228 Processing Ff ... done (cmbx12 @ 1.2X, mismatch=0.02948).
229 Processing Fh ... done (cmtt10 @ 1X, mismatch=0.06895).
230 Processing Fd ... done (cmmi10 @ 1X, mismatch=0.03966).
231 Processing Fj ... done (cmbx12 @ 1X, mismatch=0.03972).
232 Processing Fe ... done (cmbx10 @ 1X, mismatch=0.00762).
233 Processing Fg ... done (cmsy10 @ 1X, mismatch=0.00875).
234 Processing Fc ... done (cmr6 @ 1X, mismatch=0.00284).
235 $ pkfix pkfix-oldfile.ps newfile.ps
237 PKFIX 1.3, 2005/02/25 - Copyright (c) 2001, 2005 by Heiko Oberdiek.
238 *** Font conversion: `cmti10' -> `CMTI10'.
239 *** Font conversion: `cmr8' -> `CMR8'.
240 *** Font conversion: `cmr6' -> `CMR6'.
241 *** Font conversion: `cmmi10' -> `CMMI10'.
242 *** Font conversion: `cmbx10' -> `CMBX10'.
243 *** Font conversion: `cmbx12' -> `CMBX12'.
244 *** Font conversion: `cmsy10' -> `CMSY10'.
245 *** Font conversion: `cmtt10' -> `CMTT10'.
246 *** Font conversion: `cmr10' -> `CMR10'.
247 *** Font conversion: `cmbx12' -> `CMBX12'.
248 *** Merging font `CMBX12' (2).
249 ==> 10 converted fonts.
250 ==> 1 merged font.
251 Although pkfix-helper tries to automate as much as possible the font-
253 detection process, some fonts will invariably be incorrectly
254 identified. The program outputs a warning message if it knows a match
255 is bad but the lack of a warning message does not necessarily indicate
256 that pkfix-helper did a good job. It is therefore strongly recommended
257 that the user produce "before" and "after" font sheets:
258 $ pkfix-helper -q oldfile.ps pkfix-oldfile.ps \
260 --ps=oldfonts.ps --tex=newfonts.tex
261 $ tex newfonts.tex
263 This is TeX, Version 3.14159 (Web2C 7.4.5)
264 (./newfonts.tex [1] )
265 Output written on newfonts.dvi (1 page, 1292 bytes).
266 Transcript written on newfonts.log.
267 $ dvips newfonts.dvi -o newfonts.ps
269 This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
270 ' TeX output 2006.06.11:1636' -> newfonts.ps
271 <texc.pro><8r.enc><texps.pro>. <cmr6.pfb><cmsy10.pfb><cmbx10.pfb><cmbx12.pfb>
272 <cmmi10.pfb><cmtt10.pfb><cmr8.pfb><cmti10.pfb><cmr10.pfb>[1]
273 After running the preceding commands, oldfonts.ps shows samples of the
275 fonts in oldfile.ps and newfonts.ps shows samples of the replacement
276 fonts that pkfix-helper used to produce pkfix-oldfile.ps. Print
277 oldfonts.ps and newfonts.ps and compare them carefully for incorrect
278 fonts and sizes.
279 Suppose that the choice of "cmbx12 @ 1.2X" for font "Ff" looks wrong;
281 say the characters look taller in oldfonts.ps than in newfonts.ps.
282 This is where the trial-and-error stage begins. Let's hypothesize that
283 "cmb12" is a better match than "cmbx12" but we don't know how much to
284 scale the font. Fortunately, pkfix-helper allows "*" to be used as a
285 scaling factor to tell the program to automatically detect an optimal
286 scaling factor, even if doing so means choosing a nonstandard font
287 size:
288 $ pkfix-helper oldfile.ps pkfix-oldfile.ps --force="Ff=cmb12 @ *"
290 Reading oldfile.ps ... done.
291 Number of Type 3 fonts encountered: 10
292 Bitmapped fonts are typeset at 600 DPI.
293 Finding character widths ... done.
294 Reading TFM files ... failed.
295 pkfix-helper: Unable to process user-specified TFM file "cmb12"
296 Oops, it looks like we don't have a cmb12.tfm file on our system.
298 Let's try scaling up cmb10.tfm instead:
299 $ pkfix-helper oldfile.ps pkfix-oldfile.ps --force="Ff=cmb10 @ *"
301 Reading oldfile.ps ... done.
302 Number of Type 3 fonts encountered: 10
303 Bitmapped fonts are typeset at 600 DPI.
304 Finding character widths ... done.
305 Reading TFM files ... done (103 TFMs in 193 scaling variations).
306 Matching fonts:
307 Processing Fi ... done (cmr10 @ 1X, mismatch=0.11683).
308 Processing Fa ... done (cmti10 @ 1X, mismatch=0.08892).
309 Processing Fb ... done (cmr8 @ 1X, mismatch=0.07133).
310 Processing Ff ... done (cmb10 @ 1.5X, mismatch=0.00035).
311 Processing Fh ... done (cmtt10 @ 1X, mismatch=0.06895).
312 Processing Fd ... done (cmmi10 @ 1X, mismatch=0.03966).
313 Processing Fj ... done (cmbx12 @ 1X, mismatch=0.03972).
314 Processing Fe ... done (cmbx10 @ 1X, mismatch=0.00762).
315 Processing Fg ... done (cmsy10 @ 1X, mismatch=0.00875).
316 Processing Fc ... done (cmr6 @ 1X, mismatch=0.00284).
317 The match has definitely improved, although 15 pt. is certainly an odd
319 size for a font. Then again, many documents do use nonstandard sizes
320 so this may in fact be correct. The best way to verify is once again
321 to produce, print, and compare a pair of font samples and iterate until
322 all of the fonts look correct. Use one instance of --force for each
323 font you want to alter.
324
326 pkfix-helper honors the following environment variables:
327 GS The name of the Ghostscript interpreter (default: gs)
329 TFTOPL The name of a utility for converting .tfm files to .pl files
331 (default: tftopl)
332
334 pkfix-helper works only with PostScript files produced by dvips, not
335 with arbitrary PostScript files. Only bitmapped fonts loaded by dvips
336 can be analyzed, not bitmapped fonts loaded by embedded graphics.
337 pkfix-helper works by comparing character widths, not the actual
339 glyphs. Consequently, it is misled by sets of fonts with similar
340 character widths (at least for those characters used by a given
341 document). As an extreme example, all Computer Modern Teletype fonts
342 of a given design size (e.g., "cmtt10", "cmsltt10", and "cmitt10") use
343 exactly the same widths for all characters. Human assistance is
344 generally needed to guide pkfix-helper's font-matching procedures,
345 especially for fonts for which relatively few characters appear in the
346 document.
347 There is an astonishing variety of dvips output. Different versions of
349 the program and different command-line options can result in PostScript
350 files with a completely different structure. pkfix-helper works hard
351 to find font information buried in numerous output-file variants, but
352 it is not uncommon for a PostScript file produced by a sufficiently old
353 version of dvips or with sufficiently obscure command-line options to
354 utterly confuse pkfix-helper. In this case, please send your
355 problematic PostScript files to the author of pkfix-helper (see
356 "AUTHOR" below), who may be able to enhance pkfix-helper to handle
357 them.
358
360 Files produced using the --tex option are Plain TeX files and therefore
361 must be compiled with tex (or a variant such as pdftex, luatex, xetex,
362 etc.), not with latex.
363 dvips-produced PostScript files can be structured in sections,
365 demarcated by %DVIPSBeginSection and %DVIPSEndSection. Font names are
366 local to a section. Hence, a font named "Fa" may map to "cmex10" in
367 one section and to "cmmi7" in another. pkfix-helper assigns every font
368 in a multi-section document a unique name by appending a section-number
369 suffix: "Fa_S01", "Fa_S02", etc.
370 Font names are processed in decreasing order of the number of
372 characters they have represented in the document. That is, if the
373 document includes 10 characters from "Fa" and 23 characters from "Fb",
374 pkfix-helper will process "Fb" before "Fa".
375
377 pkfix(1), dvips(1), tex(1), gs(1)
378 PostScript Language Reference, Third Edition. Published by Addison-
380 Wesley, ISBN 0-201-37922-8,
381 <http://www.adobe.com/products/postscript/pdfs/PLRM.pdf>.
382
384 Scott Pakin, scott+pkfh@pakin.org
385
387 Copyright (C) 2009-2020, Scott Pakin
388 This file may be distributed and/or modified under the conditions of
390 the LaTeX Project Public License, either version 1.3c of this license
391 or (at your option) any later version. The latest version of this
392 license is in <http://www.latex-project.org/lppl.txt> and version 1.3c
393 or later is part of all distributions of LaTeX version 2006/05/20 or
394 later.
395v1.6 2020-08-06 PKFIX-HELPER(1)