path: root/support/pkfix-helper/pkfix-helper.1

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "2020-08-06" "v1.6" " "
.\" 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 (usually) two-character
\&\fBdvips\fR font name such as \f(CW\*(C`Fa\*(C'\fR.  \fIfontspec\fR is a font specification
that comprises a font name and an optional scale: "\fIfont\fR [\f(CW\*(C`@\*(C'\fR\ \fIscale\fR]".  Some examples of \fIfontspec\fRs are \f(CW\*(C`cmmi8\*(C'\fR and
\&\f(CW\*(C`cmsy10\ @\ 1.1X\*(C'\fR.
.Sp
An asterisk used in the name of the font (e.g.,\ \f(CW\*(C`cmti*\*(C'\fR) will be
replaced by all integers from 5 to 17 (\f(CW\*(C`cmti5\*(C'\fR, \f(CW\*(C`cmti6\*(C'\fR,\ ...,
\&\f(CW\*(C`cmti17\*(C'\fR).  The scale can be written as a multiple of the design size
(\f(CW\*(C`X\*(C'\fR) or as an absolute size in either TeX points (\f(CW\*(C`pt\*(C'\fR) or
PostScript \*(L"big\*(R" points (\f(CW\*(C`bp\*(C'\fR).  Hence, \f(CW\*(C`cmsy8\ @\ 1.5X\*(C'\fR, \f(CW\*(C`cmsy8\ @\ 12pt\*(C'\fR, and \f(CW\*(C`cmsy8\ @\ 11.96bp\*(C'\fR all represent the \fIComputer
Modern Math Symbols 8 Point\fR font scaled to 12 TeX points/11.96
PostScript points.  Instead of specifying an explicit scale, an
asterisk can be used (as in \f(CW\*(C`cmsy8\ @\ *\*(C'\fR) to request that
\&\fBpkfix-helper\fR find the scale that best matches the original font's
metrics.
.Sp
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.
.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\-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.
.SS "Less-frequently Used Options"
.IX Subsection "Less-frequently Used Options"
.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 error and warning messages.
.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\-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\-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 \fIname\fP 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.
.ie n .IP """\fIname\fP uses characters that don\*(Aqt appear in any candidate font""" 4
.el .IP "\f(CW\f(CIname\f(CW uses characters that don\*(Aqt appear in any candidate font\fR" 4
.IX Item "name uses characters that dont appear in any candidate font"
None of the fonts considered for a match include all of the characters
in font \fIname\fR.  The user should use the \fB\-\-force\fR option to inform
\&\fBpkfix-helper\fR which font to use or the \fB\-\-keep\fR option to retain
the original, bitmapped font.
.ie n .IP """Processing \fIname\fP ... done (\fIfont\fP with mismatch=\fInumber\fP, tied with \fIfont\fP...)""" 4
.el .IP "\f(CWProcessing \f(CIname\f(CW ... done (\f(CIfont\f(CW with mismatch=\f(CInumber\f(CW, tied with \f(CIfont\f(CW...)\fR" 4
.IX Item "Processing name ... done (font with mismatch=number, tied with font...)"
The best match for \fIname\fR is font \fIfont\fR.  A perfect match has a
\&\fInumber\fR of 0.00000.  Worse matches observe larger values.  If a tie
is reported, this means one or more fonts matched \fIname\fR equally well
(i.e., they see the same \fInumber\fR).  In this case, \fBpkfix-helper\fR
selects the qualitatively most likely font as the winner.
.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 "RESTRICTIONS"
.IX Header "RESTRICTIONS"
\&\fBpkfix-helper\fR works only with PostScript files produced by \fBdvips\fR,
not with arbitrary PostScript files.  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,
especially for fonts for which relatively few characters appear in the
document.
.PP
There is an astonishing variety of \fBdvips\fR output.  Different
versions of the program and different command-line options can result
in PostScript files with a completely different structure.
\&\fBpkfix-helper\fR works hard to find font information buried in numerous
output-file variants, but it is not uncommon for a PostScript file
produced by a sufficiently old version of \fBdvips\fR or with
sufficiently obscure command-line options to utterly confuse
\&\fBpkfix-helper\fR.  In this case, please send your problematic
PostScript files to the author of \fBpkfix-helper\fR (see \*(L"\s-1AUTHOR\*(R"\s0
below), who may be able to enhance \fBpkfix-helper\fR to handle them.
.SH "NOTES"
.IX Header "NOTES"
Files produced using the \fB\-\-tex\fR option are Plain TeX files and
therefore must be compiled with \fBtex\fR (or a variant such as
\&\fBpdftex\fR, \fBluatex\fR, \fBxetex\fR, etc.), \fInot\fR with \fBlatex\fR.
.PP
\&\fBdvips\fR\-produced PostScript files can be structured in sections,
demarcated by \f(CW%DVIPSBeginSection\fR and \f(CW%DVIPSEndSection\fR.  Font
names are local to a section.  Hence, a font named \f(CW\*(C`Fa\*(C'\fR may map to
\&\f(CW\*(C`cmex10\*(C'\fR in one section and to \f(CW\*(C`cmmi7\*(C'\fR in another.  \fBpkfix-helper\fR
assigns every font in a multi-section document a unique name by
appending a section-number suffix: \f(CW\*(C`Fa_S01\*(C'\fR, \f(CW\*(C`Fa_S02\*(C'\fR, etc.
.PP
Font names are processed in decreasing order of the number of
characters they have represented in the document.  That is, if the
document includes 10 characters from \f(CW\*(C`Fa\*(C'\fR and 23 characters from
\&\f(CW\*(C`Fb\*(C'\fR, \fBpkfix-helper\fR will process \f(CW\*(C`Fb\*(C'\fR before \f(CW\*(C`Fa\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBpkfix\fR\|(1), \fBdvips\fR\|(1), \fBtex\fR\|(1), \fBgs\fR\|(1)
.PP
PostScript Language Reference, Third Edition.
Published by Addison-Wesley, \s-1ISBN 0\-201\-37922\-8,\s0
<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) 2009\-2020, 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.