summaryrefslogtreecommitdiff
path: root/Build/source/texk/afm2pl/afm2pl.txt
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-17 21:41:51 +0000
committerKarl Berry <karl@freefriends.org>2006-01-17 21:41:51 +0000
commit487ca4806cc046076293cf6cc5fbba0db282bac7 (patch)
tree847b412ab5158dd7bdd7ed7e5a4cc3fbca94be32 /Build/source/texk/afm2pl/afm2pl.txt
parenta3d3111bfe26b8e5f5bc6049dfb2a4ca2edc7881 (diff)
texk 1
git-svn-id: svn://tug.org/texlive/trunk@1485 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/afm2pl/afm2pl.txt')
-rw-r--r--Build/source/texk/afm2pl/afm2pl.txt295
1 files changed, 295 insertions, 0 deletions
diff --git a/Build/source/texk/afm2pl/afm2pl.txt b/Build/source/texk/afm2pl/afm2pl.txt
new file mode 100644
index 00000000000..936a9cc46d9
--- /dev/null
+++ b/Build/source/texk/afm2pl/afm2pl.txt
@@ -0,0 +1,295 @@
+
+afm2pl
+
+Siep Kroonenberg
+
+ <[1]ntg-afm2pl@ntg.nl>
+
+ Copyright © 2004 Siep Kroonenberg
+ _________________________________________________________________
+
+ Table of Contents
+
+ [2]afm2pl - convert AFM font metrics to TeX pl font metrics
+
+Name
+
+ afm2pl -- convert AFM font metrics to TeX pl font metrics
+
+Synopsis
+
+ afm2pl [-p encoding_file ] [-o] [-e extension_factor ] [-s
+ slant_factor ] [-f font_dimensions ] [-k] [-m letter_spacing ] [-l
+ ligkern_spec ] [-L ligkern_spec ] {input_file[.afm]}
+ [output_file[.pl]]
+
+ afm2pl {[--help] | [--version]}
+
+Description
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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).
+
+ 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.
+
+Options
+
+ -p encoding_file
+ 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.
+
+ -o
+ Use octal for all character codes in the pl file.
+
+ -e extend_factor
+ Widen or narrow characters by extend_factor. 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.
+
+ -s slant_factor
+ Oblique (slant) characters by slant_factor. Not recommended.
+
+ -f font_dimensions
+ font_dimensions is a comma-separated list of up to three
+ integers, for successively stretch and shrink of the interword
+ space, and extra space for between sentences (cf. spacefactor).
+ Default values: one-half, one-third and one-third of the width
+ of a space. Specify just a non-default stretch and shrink with
+ e.g. 150,70 and just a non-default extra space with ,,10. For a
+ fixed-pitch font this parameter is ignored.
+
+ -k
+ Keep original ligatures. This option only has effect in
+ combination with positive letterspacing; see the section on
+ [3]letterspacing and extra ligkern info.
+
+ -m letter_spacing
+ Letterspace by letter_spacing/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 [4]letterspacing and
+ extra ligkern info for details.
+
+ -l ligkern_spec, -L ligkern_spec
+ See the section on [5]extra ligkern info for details.
+
+ -V
+ 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.
+
+ --help
+ Display a short usage message.
+
+ --version
+ Display the version number of afm2pl.
+
+Mapfile entries
+
+ 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.
+
+ 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.
+
+Extra ligkern info
+
+ Most users are well-advised to leave this mess alone and to accept the
+ default behavior.
+
+ 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
+ ligkern_spec 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.
+
+ If afm2pl is compiled with the kpathsea library, then these files will
+ be searched for under $TEXMF/fonts/lig.
+
+ 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.
+
+ The parser for ligkern info has been inherited from afm2tfm virtually
+ without change. A ligkern specification can have one of the following
+ forms:
+glyph_name1 glyph_name2 lig_op glyph_name3 ;
+
+ This specifies a ligature. Possible values for lig_op 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.
+glyph_name1 <> glyph_name2 ;
+
+ Kern glyph_name1 as glyph_name2.
+glyph_name1 {} glyph_name2 ;
+
+ Remove the kern between glyph_name1 and glyph_name2. A value of * for
+ either glyph name is interpreted as a wildcard.
+|| = glyph ;
+
+ Set the (right) boundary character to glyph. glyph 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
+ ;.
+
+ You can copy the kerns of an unencoded character to the boundarychar:
+|| <> space ;
+
+ This ligkern specification should occur before the one that deletes
+ space kerns.
+
+ 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:
+one {} * ; * {} one ; two {} * ; * {} two ;
+
+ Lines with ligkern specifications inside an encoding file should start
+ with % LIGKERN . Ligkern specifications in a lig file may optionally
+ start this way.
+
+Letterspacing and extra ligkern info
+
+ Letterspacing has various side-effects for ligkern info. Instead of
+ simply applying the extra ligkern info (see previous section), the
+ following is done:
+ 1. In case of positive letterspacing, native ligatures are removed,
+ unless the -k option is specified.
+ 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.
+ 3. Letterspacing is applied. This adds a lot of kerns, and modifies
+ existing kerns.
+ 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.
+
+Font-based upper- and lowercasing
+
+ 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.
+
+ 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.
+
+The sz ligature ß
+
+ 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:
+
+\def\ss{%
+ \setbox0\hbox{\char25}%
+ \ifnum\wd0=0 ss\else\box0\fi
+}
+
+ 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.
+
+Afm2pl, fontinst and artificial smallcaps
+
+ 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.
+
+ 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.
+
+ 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.
+
+Future plans
+
+ 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.
+
+Copyright
+
+ The afm2pl distribution is subject to the GNU General Public Licence
+ (GPL). Please refer to the file COPYING for details.
+
+ The afm2pl homepage is [6]http://www.ntg.nl/afm2pl.html.
+
+References
+
+ 1. mailto:ntg-afm2pl@ntg.nl
+ 2. file://localhost/home/siepo/afm2pl/afm2pl-0.7/afm2pl.html#id2447180
+ 3. file://localhost/home/siepo/afm2pl/afm2pl-0.7/afm2pl.html#lspace
+ 4. file://localhost/home/siepo/afm2pl/afm2pl-0.7/afm2pl.html#lspace
+ 5. file://localhost/home/siepo/afm2pl/afm2pl-0.7/afm2pl.html#lspecs
+ 6. http://www.ntg.nl/afm2pl.html