summaryrefslogtreecommitdiff
path: root/Build/source/texk/afm2pl/afm2pl.1
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/afm2pl/afm2pl.1')
-rw-r--r--Build/source/texk/afm2pl/afm2pl.1275
1 files changed, 275 insertions, 0 deletions
diff --git a/Build/source/texk/afm2pl/afm2pl.1 b/Build/source/texk/afm2pl/afm2pl.1
new file mode 100644
index 00000000000..91c8282166d
--- /dev/null
+++ b/Build/source/texk/afm2pl/afm2pl.1
@@ -0,0 +1,275 @@
+.\"Generated by db2man.xsl. Don't modify this, modify the source.
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "AFM2PL" 1 "February 2004" "" "afm2pl"
+.SH NAME
+afm2pl \- convert AFM font metrics to TeX pl font metrics
+.SH "SYNOPSIS"
+.ad l
+.hy 0
+.HP 7
+\fBafm2pl\fR [\fB\-p\fR\ \fIencoding_file\fR] [\fB\-o\fR] [\fB\-e\fR\ \fIextension_factor\fR] [\fB\-s\fR\ \fIslant_factor\fR] [\fB\-f\fR\ \fIfont_dimensions\fR] [\fB\-k\fR] [\fB\-m\fR\ \fIletter_spacing\fR] [\fB\-l\fR\ \fIligkern_spec\fR] [\fB\-L\fR\ \fIligkern_spec\fR] {\fIinput_file[\&.afm]\fR} [\fIoutput_file[\&.pl]\fR]
+.ad
+.hy
+.ad l
+.hy 0
+.HP 7
+\fBafm2pl\fR {\fB\-\-help\fR | \fB\-\-version\fR}
+.ad
+.hy
+
+.SH "DESCRIPTION"
+
+.PP
+afm2pl converts an afm (Adobe Font Metric) file into a pl (Property List) file, which in its turn can be converted to a tfm (TeX Font Metric) file\&. It preserves kerns and ligatures\&.
+
+.PP
+afm2pl is meant to be a replacement for afm2tfm, on which it is based\&. With afm2tfm, preserving kerns and ligatures is possible only in a roundabout way\&.
+
+.PP
+For text fonts, Y&Y's texnansi is the recommended encoding to be used with afm2pl\&. This gives you a good character set with all the more important accented characters and many typographic symbols available as single characters, without a need for either virtual fonts or a separate text companion font\&.
+
+.PP
+Full LaTeX support for this encoding is available in the form of the texnansi package, which is already part of TeX Live and teTeX\&. These distributions also contain the encoding file texnansi\&.enc\&.
+
+.PP
+The distribution contains uppercased and lowercased versions of texnansi, viz\&. texnanuc\&.enc and texnanlc\&.enc, to allow font\-based rather than macro\-based uppercasing and lowercasing, and the familiar old ot1 encoding plus some variations in PostScript \&.enc format (I included these because they seem to be absent from teTeX/TeX Live)\&.
+
+.PP
+Return value: 0 if no error; a negative number indicating the number of missing glyphs if conversion was successfull but glyphs are missing, and 1 in case of error\&.
+
+.SH "OPTIONS"
+
+.TP
+\fB\-p\fR \fIencoding_file\fR
+The default is the encoding specified in the afm file, which had better match the encoding in the fontfile (pfa or pfb)\&. The generated mapfile entry (see below) instructs pdftex or the dvi driver to reencode the font on the fly\&. On\-the\-fly reencoding does not require virtual fonts\&.
+
+.TP
+\fB\-o\fR
+Use octal for all character codes in the pl file\&.
+
+.TP
+\fB\-e\fR \fIextend_factor\fR
+Widen or narrow characters by \fIextend_factor\fR\&. Default is 1\&.0 (natural width)\&. Not recommended, except that arguably a narrowed Courier is less jarring than a full\-width Courier, when used in combination with a normal proportional font\&. For Courier, choose \&.833 to match the width of cmtt\&.
+
+.TP
+\fB\-s\fR \fIslant_factor\fR
+Oblique (slant) characters by \fIslant_factor\fR\&. Not recommended\&.
+
+.TP
+\fB\-f\fR \fIfont_dimensions\fR
+The value is either the keyword afm2tfm or a comma\-separated list of up to five integers\&. The parameters are listed below, with their defaults and their value when the afm2tfm keyword is specified\&. 'Space' means the width of a space in the target font, except of course in the last row\&. Keep in mind that the design size is 1000, and that all numbers must be nonnegative integers\&.
+
+.PP
+.TS
+lll
+___
+lll.
+Font dimension Default value Afm2tfm value
+\fIstretch\fR space div 2 300 x \fIextend_factor\fR
+\fIshrink\fR space div 3 100 x \fIextend_factor\fR
+\fIextra space\fR space div 3 missing
+\fIquad\fR 2 x width of '0' 1000 x \fIextend_factor\fR
+\fIspace\fR (space source font) x \fIextend_factor\fR (space source font) x \fIextend_factor\fR
+.TE
+For fixed\-pitch fonts, different values apply:
+
+.PP
+.TS
+lll
+___
+lll.
+Font dimension Default value Afm2tfm value
+\fIstretch\fR 0 0
+\fIshrink\fR 0 0
+\fIextra space\fR space missing
+\fIquad\fR 2 x character width 1000 x \fIextend_factor\fR
+\fIspace\fR character width character width
+.TE
+Specify just a non\-default stretch and shrink with e\&.g\&. 150,70 and just a non\-default extra space with ,,10\&.
+
+.TP
+\fB\-k\fR
+Keep original ligatures\&. This option only has effect in combination with positive letterspacing; see the section on letterspacing and extra ligkern info\&.
+
+.TP
+\fB\-m\fR \fIletter_spacing\fR
+Letterspace by \fIletter_spacing\fR/1000 em (integer)\&. This is useful for making all\-caps typesetting look better\&. Try a value of e\&.g\&. 50 or 100\&. But see the section on letterspacing and extra ligkern info for details\&.
+
+.TP
+\fB\-l\fR \fIligkern_spec\fR, \fB\-L\fR \fIligkern_spec\fR
+See the section on extra ligkern info for details\&.
+
+.TP
+\fB\-V\fR
+Verbose\&. If turned on, it reports the number of missing glyphs to stderr and their names to stdout\&. This is not particularly logical, but this way the glyph names can be captured even under Windows\&.
+
+.TP
+\fB\-\-help\fR
+Display a short usage message\&.
+
+.TP
+\fB\-\-version\fR
+Display the version number of afm2pl\&.
+
+.SH "MAPFILE ENTRIES"
+
+.PP
+afm2pl writes a mapfile entry to a file with the same basename as the pl output file, but with extension \&.map\&. It can be used for the dvips mapfile and for the pdftex mapfile, although, in case of a geometrically transformed font, it may be better to remove the PostScript name for a pdftex mapfile entry\&. It is assumed that the pfb file has the same basename as the afm file and must be downloaded\&. You may have to hand\-edit this entry\&.
+
+.PP
+You can configure dvips and pdftex to read this additional mapfile or otherwise add the entry to an existing mapfile\&. It appears that pdftex automatically will consult a mapfile xxx\&.map for a font xxx\&.
+
+.SH "EXTRA LIGKERN INFO"
+
+.PP
+Most users are well\-advised to leave this mess alone and to accept the default behavior\&.
+
+.PP
+The ligatures and kerns present in the afm file can be modified in various ways\&. Default, the encoding file is scanned for extra ligkern specifications, whose format will be described below\&. If there are no ligkern specifications in the encoding file, then extra ligkern specifications will be read from a file default\&.lig\&. A value of 0 for \fIligkern_spec\fR means that the ligatures and kerns from the afm file won't be tampered with and a value of 1 specifies default behavior\&. One can also specify a comma\-separated list of files with extra ligkerns specs\&.
+
+.PP
+If afm2pl is compiled with the kpathsea library, then these files will be searched for under $TEXMF/fonts/lig\&.
+
+.PP
+Note that ligatures and kerns are hints for the typesetting application; there is no need to download this information to the printer or to make it available to a dvi driver\&.
+
+.PP
+The parser for ligkern info has been inherited from afm2tfm virtually without change\&. A ligkern specification can have one of the following forms:
+
+.IP
+
+\fIglyph_name1\fR \fIglyph_name2\fR \fIlig_op\fR \fIglyph_name3\fR ;
+
+.PP
+This specifies a ligature\&. Possible values for \fIlig_op\fR are =:, |=:, |=:>, =:|, =:|>, |=:|, |=:|> and |=:|>>\&. These correspond to LIG, /LIG, /LIG>, LIG/, LIG/>, /LIG/, /LIG/>, /LIG/>> in \&.pl syntax; see the pltotf documentation and the \&.lig files in the distribution\&.
+
+.IP
+
+\fIglyph_name1\fR <> \fIglyph_name2\fR ;
+
+.PP
+Kern \fIglyph_name1\fR as \fIglyph_name2\fR\&.
+
+.IP
+
+\fIglyph_name1\fR {} \fIglyph_name2\fR ;
+
+.PP
+Remove the kern between \fIglyph_name1\fR and \fIglyph_name2\fR\&. A value of * for either glyph name is interpreted as a wildcard\&.
+
+.IP
+
+|| = \fIglyph\fR ;
+
+.PP
+Set the (right) boundary character to \fIglyph\fR\&. \fIglyph\fR may be either a glyphname or a slot in the encoding vector\&. Choosing a glyph which doesn't occur in the output encoding is equivalent to not specifying a boundarychar at all\&. It is ok to pick an encoded glyphname which does not occur in the afm\&. In fact, this is what default\&.lig does: || = cwm ;\&.
+
+.PP
+You can copy the kerns of an unencoded character to the boundarychar:
+
+.IP
+
+|| <> space ;
+
+.PP
+This ligkern specification should occur before the one that deletes space kerns\&.
+
+.PP
+A ligkern specification should be contained within one line\&. One line may contain several ligkern specifications, separated by spaces\&. Note that ; (space followed by semicolon) is considered part of the ligkern specification\&. See the lig files included in this distribution\&. Example:
+
+.IP
+
+one {} * ; * {} one ; two {} * ; * {} two ;
+
+.PP
+Lines with ligkern specifications inside an encoding file should start with % LIGKERN\&. Ligkern specifications in a lig file may optionally start this way\&.
+
+.SH "LETTERSPACING AND EXTRA LIGKERN INFO"
+
+.PP
+Letterspacing has various side\-effects for ligkern info\&. Instead of simply applying the extra ligkern info (see previous section), the following is done:
+
+.TP 3
+1.
+In case of positive letterspacing, native ligatures are removed, unless the \-k option is specified\&.
+.TP
+2.
+Extra ligkern info is applied as usual, except that in case of positive letterspacing different defaults apply: \-l 0 is quietly ignored, ligkern comments in the encoding file are ignored, and defpre\&.lig is read instead of default\&.lig\&.
+.TP
+3.
+Letterspacing is applied\&. This adds a lot of kerns, and modifies existing kerns\&.
+.TP
+4.
+The extra ligkern info specified with \-L is applied\&. The only ligkern specs which are allowed here, are removals of kerning pairs (with the {} operator)\&. Values 0 and 1 have a similar meaning as for the \-l parameter\&. The tfm format has room for only about 180x180 ligatures and kerning pairs\&. This is enough for OT1 encoding, but for texnansi encoding quite a few ligkern specifications have to be removed\&. The pltotf program will remove all ligkern info if too many ligatures and kerns remain\&. The default lig file is defpost\&.lig\&. This file throws out kerning pairs which are unlikely to be involved in letterspacing, such as kerns involving accents or kerns with a punctuation character or right bracket at the left\&. It does not add letterspacing kerns involving boundarychars\&. Instead, fontspace is increased by twice the letterspacing\&. defpost\&.lig throws out enough kerns in case of texnansi encoding\&. With other encodings, you may have to throw out additional kerning pairs\&.
+.LP
+
+.SH "FONT-BASED UPPER- AND LOWERCASING"
+
+.PP
+The distribution includes encoding vectors texnanuc\&.enc and texnanlc\&.enc which produce all\-uppercase and all\-lowercase fonts\&. The distribution contains an example ucshape\&.tex on how to use such fonts with LaTeX font selection\&.
+
+.PP
+The principal uses for an all\-uppercase font are page headers and section heads\&. If these contain math, then macro\-based uppercasing would create unpleasant complications\&.
+
+.SS "The sz ligature"
+
+.PP
+Note that the texnanuc encoding provides no glyph for the sz ligature; you'll either have to substitute ss or provide a macro\-based solution\&. The following code uses either the usual glyph or substitutes the letters ss, depending on whether the glyph exists in the current font:
+
+.nf
+
+
+\\def\\ss{%
+ \\setbox0\\hbox{\\char25}%
+ \\ifnum\\wd0=0 ss\\else\\box0\\fi
+}
+
+
+.fi
+
+.PP
+In LaTeX, this code appears to work well enough, although on occasion you may need to insert \\protect\&. A better solution might involve the sixth parameter of the \\DeclareFontShape macro, but I failed to get that to work\&.
+
+.SH "AFM2PL, FONTINST AND ARTIFICIAL SMALLCAPS"
+
+.PP
+Afm2pl currently doesn't do virtual fonts\&. That means that for things such as artificial smallcaps you have to turn elsewhere, e\&.g\&. to the fontinst package, which is part of any mainstream TeX distribution\&.
+
+.PP
+Look under texmf/tex/fontinst for fontinst support files, which allow you to generate a smallcaps font (tfm and vf files) from an afm2pl\-generated tfm file\&. This package only supports texnansi encoding\&.
+
+.PP
+There should be no real problem in doing the same for OT1 encoding\&. However, there are several variations of the OT1 encoding to take care of\&. Also, there are as far as I know no officially sanctioned PostScript names for all the variations of the OT1 encoding; the fontinst names contain spaces and are therefore not useable as PostScript names\&.
+
+.SH "FUTURE PLANS"
+
+.PP
+I am considering a revision which makes afm2pl a more complete replacement for afm2tfm\&. In that version, afm2pl can optionally create a second, virtual font, possibly with a different encoding and possibly letterspaced\&. The current option of non\-virtual letterspacing via kerns will be dropped\&. If the encodings differ then it is assumed that the virtual font is intended as a small\-caps version of the main font, and a scaling parameter can be specified for non\-matching glyphs\&.
+
+.SH "COPYRIGHT"
+
+.PP
+The afm2pl distribution is subject to the GNU General Public Licence (GPL)\&. Please refer to the file COPYING for details\&.
+
+.PP
+The afm2pl homepage is http://www\&.ntg\&.nl/afm2pl\&.html: \fIhttp://www.ntg.nl/afm2pl.html\fR\&.
+
+.SH AUTHOR
+Siep Kroonenberg <ntg\-afm2pl@ntg\&.nl>.