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 (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
106           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
118           The --force option can be specified repeatedly on the command line.
119
120       -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
124       -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
129       -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
139       -1, --no-repeats
140           Prevent pkfix-helper from associating the same fontspec with more
141           than one dvips font name.
142
143   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
148       -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
160       -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
167       -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
172       -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

DIAGNOSTICS

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
186       "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
192       "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

EXAMPLES

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
206           $ pkfix oldfile.ps newfile.ps
207           PKFIX 1.3, 2005/02/25 - Copyright (c) 2001, 2005 by Heiko Oberdiek.
208           ==> no fonts converted
209
210       (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
218           $ 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
236           $ 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
252       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
259           $ pkfix-helper -q oldfile.ps pkfix-oldfile.ps \
260             --ps=oldfonts.ps --tex=newfonts.tex
261
262           $ 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
268           $ 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
274       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
280       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
289           $ 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
297       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
300           $ 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
318       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

ENVIRONMENT

326       pkfix-helper honors the following environment variables:
327
328       GS      The name of the Ghostscript interpreter (default: gs)
329
330       TFTOPL  The name of a utility for converting .tfm files to .pl files
331               (default: tftopl)
332

RESTRICTIONS

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
338       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
348       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

NOTES

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
364       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
371       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

SEE ALSO

377       pkfix(1), dvips(1), tex(1), gs(1)
378
379       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

AUTHOR

384       Scott Pakin, scott+pkfh@pakin.org
385
387       Copyright (C) 2009-2020, Scott Pakin
388
389       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.
395
396
397
398v1.6                              2020-08-06                   PKFIX-HELPER(1)
Impressum