summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/pkfix-helper.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/pkfix-helper.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/pkfix-helper.1516
1 files changed, 516 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/pkfix-helper.1 b/Master/texmf-dist/doc/man/man1/pkfix-helper.1
new file mode 100644
index 00000000000..c0c170fdbe8
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/pkfix-helper.1
@@ -0,0 +1,516 @@
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "PKFIX-HELPER 1"
+.TH PKFIX-HELPER 1 "2011-06-11" "v1.4" " "
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+pkfix\-helper \- preprocess dvips\-produced PostScript documents before passing them to pkfix
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+pkfix-helper
+[\fB\-\-help\fR]
+[\fB\-\-verbose\fR]
+[\fB\-\-force\fR=\fIname\fR=\fIfontspec\fR]
+[\fB\-\-ps\fR=\fIfilename.ps\fR]
+[\fB\-\-tex\fR=\fIfilename.tex\fR]
+[\fB\-\-cache\fR=\fIfilename\fR]
+[\fB\-\-include\fR=\fIfontspec\fR]
+[\fB\-\-exclude\fR=\fIregexp\fR]
+[\fB\-\-keep\fR=\fIfontspec\fR]
+[\fB\-\-quiet\fR]
+[\fB\-\-no\-repeats\fR]
+[\fB\-\-spp\fR=\fInumber\fR]
+[\fIinput.ps\fR [\fIoutput.ps\fR]]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.SS "Motivation"
+.IX Subsection "Motivation"
+PostScript documents created with old versions of \fBdvips\fR almost
+invariably utilize bitmapped (PostScript Type\ 3) fonts. The
+problem with bitmapped fonts is that they target a specific device
+resolution; a PostScript file produced using 300\ \s-1DPI\s0 fonts will
+look grainy on a 600\ \s-1DPI\s0 printer. Even worse, \fIall\fR bitmapped
+fonts look grainy when zoomed in on screen. The solution is to use
+vector (PostScript Type\ 1) fonts, which are resolution-independent
+and appear crisp at any size or scale.
+.PP
+While it is no longer difficult to configure \fBdvips\fR to use vector
+fonts, it is not always possible to rerun \fBdvips\fR on an old \fI.dvi\fR
+file. The \fI.dvi\fR file and document source may have been lost; or,
+the source may no longer compile because packages it depends upon may
+no longer be available.
+.PP
+Heiko Oberdiek's \fBpkfix\fR script replaces bitmapped fonts in
+\&\fBdvips\fR\-produced PostScript files with the corresponding vector
+fonts. It works by parsing the PostScript comments with which
+\&\fBdvips\fR surrounds bitmapped-font definitions. For example, a font
+definition beginning with the comment \f(CW\*(C`%DVIPSBitmapFont: Fi cmss10 11
+28\*(C'\fR and ending with a matching \f(CW%EndDVIPSBitmapFont\fR is known to
+define font \f(CW\*(C`Fi\*(C'\fR as \f(CW\*(C`cmss10\*(C'\fR (Computer Modern Sans Serif at a design
+size of 10\ points) scaled to \f(CW11\fR\ points. Only the \f(CW28\fR
+characters actually used by the document are defined. \fBpkfix\fR then
+replaces the font definition with one that defines \f(CW\*(C`Fi\*(C'\fR using the
+same set of characters but taken from the \fIcmss10.pfb\fR vector font
+file.
+.PP
+Unfortunately, \fBpkfix\fR works only with versions of \fBdvips\fR newer
+than v5.58 (ca.\ 1996). Naturally, the older a PostScript document,
+the less likely its sources still exist and can still be recompiled.
+Older versions of \fBdvips\fR lack \f(CW%DVIPSBitmapFont\fR comments and
+various other PostScript comments on which \fBpkfix\fR relies. Without
+PostScript comments to guide it, \fBpkfix\fR is unable to determine which
+vector fonts correspond with which bitmapped fonts.
+.SS "Overview"
+.IX Subsection "Overview"
+The \fBpkfix-helper\fR script is a preprocessor for \fBpkfix\fR that
+attempts to determine the association between each document-font name
+(e.g.,\ \f(CW\*(C`Fi\*(C'\fR) in a PostScript file and the original font (e.g.,\ \f(CW\*(C`cmss10\*(C'\fR) and fonts size (e.g., \f(CW11\fR\ points). It then
+fabricates the PostScript comments that \fBpkfix\fR expects to see so
+that \fBpkfix\fR can do its job.
+.PP
+\&\fBpkfix-helper\fR works by comparing every document font against every
+\&\fI.tfm\fR font file it knows about (assuming that each such font has a
+corresponding \fI.pfb\fR vector version) and selecting the best matching
+\&\fI.tfm\fR file for every document font. \fBpkfix-helper\fR has access only
+to the widths of characters and only to those characters actually used
+in the document. Also, the program recognizes only a limited set of
+the most popular \fI.tfm\fR files and scaling factors. Consequently, the
+comparison is imperfect and \fBpkfix-helper\fR may attribute an incorrect
+font to a given name. Fonts comprising only one or two characters
+actually used in a document are particularly problematic for
+\&\fBpkfix-helper\fR because many fonts may be near-enough matches to fool
+the problem.
+.PP
+\&\fBpkfix-helper\fR is designed so that a user can guide the
+font-selection process by manually designating matching fonts. With a
+modicum of diligence and patience a user can correct any mismatched
+fonts and help the program provide proper input to \fBpkfix\fR.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+\&\fBpkfix-helper\fR accepts on the command line the filename of a
+PostScript document to process (with the default being the standard
+input device) and the filename of a modified PostScript document to
+create (with the default being the standard output device). The
+program also accepts the following command-line options:
+.SS "Frequently Used Options"
+.IX Subsection "Frequently Used Options"
+.IP "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+Display usage information and exit. The \fB\-\-verbose\fR and \fB\-\-quiet\fR
+options can be used to increase and decrease the amount of information
+presented.
+.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
+.IX Item "-v, --verbose"
+Increase the amount of status information that \fBpkfix-helper\fR
+displays as it runs. Additional instances of \fB\-\-verbose\fR on the
+command line further increase the program's verbosity. By default,
+only major operations are displayed. A single \fB\-\-verbose\fR
+additionally displays information about individual font comparisons.
+A second \fB\-\-verbose\fR additionally displays details about some of the
+program's internal operations.
+.IP "\fB\-f\fR \fIname\fR=\fIfontspec\fR, \fB\-\-force\fR=\fIname\fR=\fIfontspec\fR" 4
+.IX Item "-f name=fontspec, --force=name=fontspec"
+Force \fBpkfix-helper\fR to associate a specific font with a given font
+name appearing the document. \fIname\fR is a two-character \fBdvips\fR font
+name such as \f(CW\*(C`Fa\*(C'\fR. \fIfontspec\fR is a font specification such as
+\&\f(CW\*(C`cmmi8\*(C'\fR or \f(CW\*(C`cmsy10\ @\ 1.1X\*(C'\fR. An asterisk used in the name of the
+base font (e.g.,\ \f(CW\*(C`cmti*\*(C'\fR) will automatically try all integral test
+font sizes from 5 to 17 points (\f(CW\*(C`cmti5\*(C'\fR, \f(CW\*(C`cmti6\*(C'\fR,\ ...,
+\&\f(CW\*(C`cmti17\*(C'\fR). An asterisk used as a scale value (e.g.,\ \f(CW\*(C`cmsy10\ @\ *\*(C'\fR) will be replaced by the scale value that gives the best match to
+the original font's metrics. The \fB\-\-force\fR option can be specified
+repeatedly on the command line.
+.IP "\fB\-p\fR \fIfilename.ps\fR, \fB\-\-ps\fR=\fIfilename.ps\fR" 4
+.IX Item "-p filename.ps, --ps=filename.ps"
+Create a PostScript file called \fIfilename.ps\fR that shows the \fBdvips\fR
+name and a font sample of every font used by the input document.
+.IP "\fB\-t\fR \fIfilename.tex\fR, \fB\-\-tex\fR=\fIfilename.tex\fR" 4
+.IX Item "-t filename.tex, --tex=filename.tex"
+Create a Plain TeX file called \fIfilename.tex\fR that shows the \fBdvips\fR
+name and a font sample of every font that \fBpkfix-helper\fR used in the
+output document.
+.SS "Infrequently Used Options"
+.IX Subsection "Infrequently Used Options"
+.IP "\fB\-C\fR \fIfilename\fR, \fB\-\-cache\fR=\fIfilename\fR" 4
+.IX Item "-C filename, --cache=filename"
+Speed up \s-1TFM\s0 file processing by caching character metrics into file
+\&\fIfilename\fR. On some systems it takes a long time to read a \s-1TFM\s0 file,
+spawn \fItftopl\fR to convert it to \s-1PL\s0 format, and extract from the \s-1PL\s0
+data the metrics for each character. The first time \fB\-\-cache\fR is
+specified, \fBpkfix-helper\fR proceeds as normal then writes all of the
+extracted character metrics to \fIfilename\fR. On subsequent runs in
+which \fB\-\-cache\fR=\fIfilename\fR is specified, \fBpkfix-helper\fR reads the
+previously extracted metrics from \fIfilename\fR, going through the
+\&\fItftopl\fR\-based process only for \s-1TFM\s0 files that were not previously
+encountered.
+.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
+.IX Item "-q, --quiet"
+Instruct \fBpkfix-helper\fR to produce no output during its run except
+for fatal error messages.
+.IP "\fB\-1\fR, \fB\-\-no\-repeats\fR" 4
+.IX Item "-1, --no-repeats"
+Prevent \fBpkfix-helper\fR from associating the same \fIfontspec\fR with
+more than one \fBdvips\fR font name.
+.IP "\fB\-i\fR \fIfontspec\fR, \fB\-\-include\fR=\fIfontspec\fR" 4
+.IX Item "-i fontspec, --include=fontspec"
+Add \fIfontspec\fR to the list of font specifications against which
+\&\fBpkfix-helper\fR compares \fIevery\fR document font. (In contrast,
+\&\fB\-\-force\fR designates a font specification to use only for a
+\&\fIspecific\fR document font.) The \fB\-\-include\fR option can be specified
+repeatedly on the command line.
+.IP "\fB\-x\fR \fIregexp\fR, \fB\-\-exclude\fR=\fIregexp\fR" 4
+.IX Item "-x regexp, --exclude=regexp"
+Remove all font specifications matching regular expression \fIregexp\fR
+from \fBpkfix-helper\fR's list of known fonts. The \fB\-\-exclude\fR option
+can be specified repeatedly on the command line.
+.IP "\fB\-k\fR \fIfontspec\fR, \fB\-\-keep\fR=\fIfontspec\fR" 4
+.IX Item "-k fontspec, --keep=fontspec"
+Do not substitute a vector font for bitmapped font \fIfontspec\fR (\f(CW\*(C`Fa\*(C'\fR,
+\&\f(CW\*(C`Fb\*(C'\fR, etc.). This is useful when converting documents that use
+obscure bitmapped fonts for which there is no vector equivalent. For
+example, it was somewhat common in the past to include graphics such
+as university or corporate logos into a document by converting the
+bitmapped image into a single-character font and using that font in
+LaTeX. \fB\-\-keep\fR prevents such fonts from being replaced. The
+\&\fB\-\-keep\fR option can be specified repeatedly on the command line.
+.IP "\fB\-a\fR, \fB\-\-any\-scale\fR" 4
+.IX Item "-a, --any-scale"
+Allow any value to be used to scale a font when "\f(CW\*(C`*\*(C'\fR" is specified as
+the scale factor. Normally, \fBpkfix-helper\fR considers only integer
+multiples of 0.1 that are greater than or equal to 1.0 (i.e.,
+\&\fIfontname\fR\f(CW@1X\fR, \f(CW\*(C`@1.1X\*(C'\fR, \f(CW\*(C`@1.2X\*(C'\fR, \f(CW\*(C`@1.3X\*(C'\fR, etc.).
+.IP "\fB\-s\fR, \fB\-\-spp\fR" 4
+.IX Item "-s, --spp"
+Specify the number of font samples per page to print to the files
+indicated using the \fB\-\-ps\fR and \fB\-\-tex\fR options. The default
+value,\ 25, should work well in most circumstances.
+.SH "DIAGNOSTICS"
+.IX Header "DIAGNOSTICS"
+.ie n .IP """Best match for \f(CIname\f(CW is rather poor""" 4
+.el .IP "\f(CWBest match for \f(CIname\f(CW is rather poor\fR" 4
+.IX Item "Best match for name is rather poor"
+The best font \fBpkfix-helper\fR found for \fBdvips\fR font name \fIname\fR has
+a mismatch value greater than or equal to\ 1.0. (The mismatch value
+is the sum of the squares of the difference between the character
+widths of a document font and a potential replacement font.) Use the
+\&\fB\-\-force\fR option to designate an alternative replacement font or
+scaling amount.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+For the purpose of the following examples, assume that \fIoldfile.ps\fR
+is the name of a PostScript file produced by an old version of
+\&\fBdvips\fR and utilizing at least one bitmapped font. It's always worth
+verifying that \fBpkfix\fR can't convert the file on its own:
+.PP
+.Vb 3
+\& $ pkfix oldfile.ps newfile.ps
+\& PKFIX 1.3, 2005/02/25 \- Copyright (c) 2001, 2005 by Heiko Oberdiek.
+\& ==> no fonts converted
+.Ve
+.PP
+(Alternatively \fBpkfix\fR may issue an error message such as \f(CW\*(C`!!!
+Error: Parse error (@start parameters)!\*(C'\fR.) Only when \fBpkfix\fR can't
+replace bitmapped fonts with vector fonts is \fBpkfix-helper\fR needed.
+In its simplest form, \fBpkfix-helper\fR takes the name of an input file
+(\fIoldfile.ps\fR in this example) and the name of an output file
+(\fIpkfix\-oldfile.ps\fR), which will have the same contents as the input
+file but serve as suitable input for \fBpkfix\fR:
+.PP
+.Vb 10
+\& $ pkfix\-helper oldfile.ps pkfix\-oldfile.ps
+\& Reading oldfile.ps ... done.
+\& Number of Type 3 fonts encountered: 10
+\& Bitmapped fonts are typeset at 600 DPI.
+\& Finding character widths ... done.
+\& Reading TFM files ... done (103 TFMs in 193 scaling variations).
+\& Matching fonts:
+\& Processing Fi ... done (cmr10 @ 1X, mismatch=0.11683).
+\& Processing Fa ... done (cmti10 @ 1X, mismatch=0.08892).
+\& Processing Fb ... done (cmr8 @ 1X, mismatch=0.07133).
+\& Processing Ff ... done (cmbx12 @ 1.2X, mismatch=0.02948).
+\& Processing Fh ... done (cmtt10 @ 1X, mismatch=0.06895).
+\& Processing Fd ... done (cmmi10 @ 1X, mismatch=0.03966).
+\& Processing Fj ... done (cmbx12 @ 1X, mismatch=0.03972).
+\& Processing Fe ... done (cmbx10 @ 1X, mismatch=0.00762).
+\& Processing Fg ... done (cmsy10 @ 1X, mismatch=0.00875).
+\& Processing Fc ... done (cmr6 @ 1X, mismatch=0.00284).
+\&
+\& $ pkfix pkfix\-oldfile.ps newfile.ps
+\& PKFIX 1.3, 2005/02/25 \- Copyright (c) 2001, 2005 by Heiko Oberdiek.
+\& *** Font conversion: \`cmti10\*(Aq \-> \`CMTI10\*(Aq.
+\& *** Font conversion: \`cmr8\*(Aq \-> \`CMR8\*(Aq.
+\& *** Font conversion: \`cmr6\*(Aq \-> \`CMR6\*(Aq.
+\& *** Font conversion: \`cmmi10\*(Aq \-> \`CMMI10\*(Aq.
+\& *** Font conversion: \`cmbx10\*(Aq \-> \`CMBX10\*(Aq.
+\& *** Font conversion: \`cmbx12\*(Aq \-> \`CMBX12\*(Aq.
+\& *** Font conversion: \`cmsy10\*(Aq \-> \`CMSY10\*(Aq.
+\& *** Font conversion: \`cmtt10\*(Aq \-> \`CMTT10\*(Aq.
+\& *** Font conversion: \`cmr10\*(Aq \-> \`CMR10\*(Aq.
+\& *** Font conversion: \`cmbx12\*(Aq \-> \`CMBX12\*(Aq.
+\& *** Merging font \`CMBX12\*(Aq (2).
+\& ==> 10 converted fonts.
+\& ==> 1 merged font.
+.Ve
+.PP
+Although \fBpkfix-helper\fR tries to automate as much as possible the
+font-detection process, some fonts will invariably be incorrectly
+identified. The program outputs a warning message if it \fIknows\fR a
+match is bad but the lack of a warning message does not necessarily
+indicate that \fBpkfix-helper\fR did a good job. It is therefore
+strongly recommended that the user produce \*(L"before\*(R" and \*(L"after\*(R" font
+sheets:
+.PP
+.Vb 2
+\& $ pkfix\-helper \-q oldfile.ps pkfix\-oldfile.ps \e
+\& \-\-ps=oldfonts.ps \-\-tex=newfonts.tex
+\&
+\& $ tex newfonts.tex
+\& This is TeX, Version 3.14159 (Web2C 7.4.5)
+\& (./newfonts.tex [1] )
+\& Output written on newfonts.dvi (1 page, 1292 bytes).
+\& Transcript written on newfonts.log.
+\&
+\& $ dvips newfonts.dvi \-o newfonts.ps
+\& This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
+\& \*(Aq TeX output 2006.06.11:1636\*(Aq \-> newfonts.ps
+\& <texc.pro><8r.enc><texps.pro>. <cmr6.pfb><cmsy10.pfb><cmbx10.pfb><cmbx12.pfb>
+\& <cmmi10.pfb><cmtt10.pfb><cmr8.pfb><cmti10.pfb><cmr10.pfb>[1]
+.Ve
+.PP
+After running the preceding commands, \fIoldfonts.ps\fR shows samples of
+the fonts in \fIoldfile.ps\fR and \fInewfonts.ps\fR shows samples of the
+replacement fonts that \fBpkfix-helper\fR used to produce
+\&\fIpkfix\-oldfile.ps\fR. Print \fIoldfonts.ps\fR and \fInewfonts.ps\fR and
+compare them carefully for incorrect fonts and sizes.
+.PP
+Suppose that the choice of \f(CW\*(C`cmbx12 @ 1.2X\*(C'\fR for font \f(CW\*(C`Ff\*(C'\fR looks
+wrong; say the characters look taller in \fIoldfonts.ps\fR than in
+\&\fInewfonts.ps\fR. This is where the trial-and-error stage begins.
+Let's hypothesize that \f(CW\*(C`cmb12\*(C'\fR is a better match than \f(CW\*(C`cmbx12\*(C'\fR but
+we don't know how much to scale the font. Fortunately,
+\&\fBpkfix-helper\fR allows \f(CW\*(C`*\*(C'\fR to be used as a scaling factor to tell the
+program to automatically detect an optimal scaling factor, even if
+doing so means choosing a nonstandard font size:
+.PP
+.Vb 7
+\& $ pkfix\-helper oldfile.ps pkfix\-oldfile.ps \-\-force="Ff=cmb12 @ *"
+\& Reading oldfile.ps ... done.
+\& Number of Type 3 fonts encountered: 10
+\& Bitmapped fonts are typeset at 600 DPI.
+\& Finding character widths ... done.
+\& Reading TFM files ... failed.
+\& pkfix\-helper: Unable to process user\-specified TFM file "cmb12"
+.Ve
+.PP
+Oops, it looks like we don't have a \fIcmb12.tfm\fR file on our system.
+Let's try scaling up \fIcmb10.tfm\fR instead:
+.PP
+.Vb 10
+\& $ pkfix\-helper oldfile.ps pkfix\-oldfile.ps \-\-force="Ff=cmb10 @ *"
+\& Reading oldfile.ps ... done.
+\& Number of Type 3 fonts encountered: 10
+\& Bitmapped fonts are typeset at 600 DPI.
+\& Finding character widths ... done.
+\& Reading TFM files ... done (103 TFMs in 193 scaling variations).
+\& Matching fonts:
+\& Processing Fi ... done (cmr10 @ 1X, mismatch=0.11683).
+\& Processing Fa ... done (cmti10 @ 1X, mismatch=0.08892).
+\& Processing Fb ... done (cmr8 @ 1X, mismatch=0.07133).
+\& Processing Ff ... done (cmb10 @ 1.5X, mismatch=0.00035).
+\& Processing Fh ... done (cmtt10 @ 1X, mismatch=0.06895).
+\& Processing Fd ... done (cmmi10 @ 1X, mismatch=0.03966).
+\& Processing Fj ... done (cmbx12 @ 1X, mismatch=0.03972).
+\& Processing Fe ... done (cmbx10 @ 1X, mismatch=0.00762).
+\& Processing Fg ... done (cmsy10 @ 1X, mismatch=0.00875).
+\& Processing Fc ... done (cmr6 @ 1X, mismatch=0.00284).
+.Ve
+.PP
+The match has definitely improved, although 15\ pt. is certainly an
+odd size for a font. Then again, many documents \fIdo\fR use nonstandard
+sizes so this may in fact be correct. The best way to verify is once
+again to produce, print, and compare a pair of font samples and
+iterate until all of the fonts look correct. Use one instance of
+\&\fB\-\-force\fR for each font you want to alter.
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+\&\fBpkfix-helper\fR honors the following environment variables:
+.IP "\s-1GS\s0" 8
+.IX Item "GS"
+The name of the Ghostscript interpreter (default: \fIgs\fR)
+.IP "\s-1TFTOPL\s0" 8
+.IX Item "TFTOPL"
+The name of a utility for converting \fI.tfm\fR files to \fI.pl\fR files
+(default: \fItftopl\fR)
+.SH "BUGS"
+.IX Header "BUGS"
+Even when \fBpkfix-helper\fR finds a perfect match (i.e.,\ the correct
+font in the correct size) the mismatch value is still typically
+nonzero. The same error is probably what causes \fBpkfix-helper\fR
+sometimes to consider the wrong font as being a better match than the
+correct font. Suggestions for fixing these bugs are welcome.
+.SH "RESTRICTIONS"
+.IX Header "RESTRICTIONS"
+\&\fBpkfix-helper\fR works only with PostScript files produced by \fBdvips\fR,
+not with arbitrary PostScript files. The program has not been tested
+with output from versions of \fBdvips\fR older than v5.490 (ca.\ 1992);
+output from older versions may or may not work. Only bitmapped fonts
+loaded by \fBdvips\fR can be analyzed, not bitmapped fonts loaded by
+embedded graphics.
+.PP
+\&\fBpkfix-helper\fR works by comparing character widths, not the actual
+glyphs. Consequently, it is misled by sets of fonts with similar
+character widths (at least for those characters used by a given
+document). As an extreme example, all Computer Modern Teletype fonts
+of a given design size (e.g., \f(CW\*(C`cmtt10\*(C'\fR, \f(CW\*(C`cmsltt10\*(C'\fR, and \f(CW\*(C`cmitt10\*(C'\fR)
+use exactly the same widths for all characters. Human assistance is
+generally needed to guide \fBpkfix-helper\fR's font-matching procedures.
+.SH "NOTES"
+.IX Header "NOTES"
+Files produced using the \fB\-\-tex\fR option are Plain TeX files and
+therefore must be compiled with \fItex\fR (or a variation such as
+\&\fIpdftex\fR, \fIluatex\fR, etc.), \fInot\fR with \fIlatex\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIpkfix\fR\|(1), \fIdvips\fR\|(1), \fItex\fR\|(1), \fIgs\fR\|(1)
+.PP
+PostScript Language Reference, Third Edition.
+Published by Addison-Wesley, \s-1ISBN\s0 0\-201\-37922\-8,
+<http://www.adobe.com/products/postscript/pdfs/PLRM.pdf>.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Scott Pakin, \fIscott+pkfh@pakin.org\fR
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright (C) 2011, Scott Pakin
+.PP
+This file may be distributed and/or modified under the conditions of
+the LaTeX Project Public License, either version 1.3c of this license
+or (at your option) any later version. The latest version of this
+license is in <http://www.latex\-project.org/lppl.txt> and version
+1.3c or later is part of all distributions of LaTeX version 2006/05/20
+or later.