summaryrefslogtreecommitdiff
path: root/support/pkfix-helper/pkfix-helper.1
diff options
context:
space:
mode:
Diffstat (limited to 'support/pkfix-helper/pkfix-helper.1')
-rw-r--r--support/pkfix-helper/pkfix-helper.1151
1 files changed, 87 insertions, 64 deletions
diff --git a/support/pkfix-helper/pkfix-helper.1 b/support/pkfix-helper/pkfix-helper.1
index c0c170fdbe..648be2b5b3 100644
--- a/support/pkfix-helper/pkfix-helper.1
+++ b/support/pkfix-helper/pkfix-helper.1
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
+.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -38,27 +38,36 @@
. 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 turned on, we'll generate index entries on stderr for
+.\" 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.
-.ie \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
..
-. nr % 0
-. rr F
-.\}
-.el \{\
-. 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.
@@ -124,7 +133,7 @@
.\" ========================================================================
.\"
.IX Title "PKFIX-HELPER 1"
-.TH PKFIX-HELPER 1 "2011-06-11" "v1.4" " "
+.TH PKFIX-HELPER 1 "2020-04-19" "v1.5" " "
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@@ -237,14 +246,23 @@ 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.
+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
@@ -254,8 +272,26 @@ name and a font sample of every font used by the input document.
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\-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
@@ -268,14 +304,6 @@ 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
@@ -288,22 +316,6 @@ repeatedly on the command line.
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
@@ -311,7 +323,7 @@ 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
+.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
@@ -320,6 +332,13 @@ 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.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
For the purpose of the following examples, assume that \fIoldfile.ps\fR
@@ -466,21 +485,12 @@ The name of the Ghostscript interpreter (default: \fIgs\fR)
.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.
+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
@@ -488,25 +498,38 @@ 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.
+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 \fItex\fR (or a variation such as
-\&\fIpdftex\fR, \fIluatex\fR, etc.), \fInot\fR with \fIlatex\fR.
+therefore must be compiled with \fBtex\fR (or a variant such as
+\&\fBpdftex\fR, \fBluatex\fR, \fBxetex\fR, etc.), \fInot\fR with \fBlatex\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
-\&\fIpkfix\fR\|(1), \fIdvips\fR\|(1), \fItex\fR\|(1), \fIgs\fR\|(1)
+\&\fBpkfix\fR\|(1), \fBdvips\fR\|(1), \fBtex\fR\|(1), \fBgs\fR\|(1)
.PP
PostScript Language Reference, Third Edition.
-Published by Addison-Wesley, \s-1ISBN\s0 0\-201\-37922\-8,
+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) 2011, Scott Pakin
+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