Debian Codegraph @

texmf-dist/doc/man/man1/afm2pl.1

raw
1 .\" Title: afm2pl
2 .\" Author:
3 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
4 .\" Date: May 2009
5 .\" Manual: afm2pl
6 .\" Source:
7 .\"
8 .TH "AFM2PL" "1" "30 August 2022" "" "afm2pl"
9 .\" disable hyphenation
10 .nh
11 .\" disable justification (adjust text to left margin only)
12 .ad l
13 .SH "NAME"
14 afm2pl \- convert AFM font metrics to TeX pl font metrics
15 .SH "SYNOPSIS"
16 .HP 7
17 \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] [\fB\-n\fR] \fIinput_file[\&.afm]\fR [\fIoutput_file[\&.pl]\fR]
18 .HP 7
19 \fBafm2pl\fR [\-\-help] | [\-\-version]
20 .SH "DESCRIPTION"
21 .PP
22 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 normally preserves kerns and ligatures, but also offers additional control over them\&.
23 .PP
24 afm2pl is meant to be a partial replacement for afm2tfm, on which it is based\&. With afm2tfm, preserving kerns and ligatures is possible only in a roundabout way, and handling of them is hard\-wired\&.
25 .PP
26 For text fonts, Y&Y\'s texnansi is a good encoding to be used with afm2pl\&. Its character set includes all the accented characters likely to be needed for Western languages, plus many typographic symbols, without a need for either virtual fonts or a separate text companion font\&.
27 .PP
28 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\&.
29 .PP
30 The distribution contains uppercased and lowercased versions of texnansi, viz\&. texnanuc and texnanlc, 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)\&. However,
31 check your mapfiles
32 if you have old afm2pl\-generated fonts using these\&.
33 .PP
34 Return value: 0 if no error; a negative number indicating the number of missing glyphs if conversion was otherwise successful but glyphs are missing, and 1 in case of error\&.
35 .SH "OPTIONS"
36 .PP
37 \fB\-p\fR \fIencoding_file\fR
38 .RS 4
39 The default is the encoding specified in the afm file, which had better match the encoding in the fontfile (pfa or pfb)\&. If
40 afm2pl\-name\&.enc
41 exists, afm2pl will use this file instead of
42 name\&.enc, unless an option
43 \-n
44 is given\&. The generated mapfile entry (see below) instructs pdftex or the dvi driver to re-encode the font on the fly\&. On\-the\-fly reencoding does not require virtual fonts\&.
45 .RE
46 .PP
47 \fB\-o\fR
48 .RS 4
49 Use octal for all character codes in the pl file\&.
50 .RE
51 .PP
52 \fB\-e\fR \fIextend_factor\fR
53 .RS 4
54 Widen or narrow characters by
55 \fIextend_factor\fR\&. Default is 1\&.0 (natural width)\&. Not recommended\&[1]\&.
56 .RE
57 .PP
58 \fB\-s\fR \fIslant_factor\fR
59 .RS 4
60 Oblique (slant) characters by
61 \fIslant_factor\fR\&. Not recommended either\&.
62 .RE
63 .PP
64 \fB\-f\fR \fIfont_dimensions\fR
65 .RS 4
66 The value is either the keyword
67 afm2tfm
68 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\&. \(oqSpace\(cq 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\&.
69 .TS
70 allbox tab(:);
71 lB lB lB.
72 T{
73 Font dimension
74 T}:T{
75 Default value
76 T}:T{
77 Afm2tfm value
78 T}
79 .T&
80 l l l
81 l l l
82 l l l
83 l l l
84 l l l.
85 T{
86 \fIstretch\fR
87 T}:T{
88 space div 2
89 T}:T{
90 300 \(mu \fIextend_factor\fR
91 T}
92 T{
93 \fIshrink\fR
94 T}:T{
95 space div 3
96 T}:T{
97 100 \(mu \fIextend_factor\fR
98 T}
99 T{
100 \fIextra space\fR
101 T}:T{
102 space div 3
103 T}:T{
104 missing
105 T}
106 T{
107 \fIquad\fR
108 T}:T{
109 2 \(mu width of \(oq0\(cq
110 T}:T{
111 1000 \(mu \fIextend_factor\fR
112 T}
113 T{
114 \fIspace\fR
115 T}:T{
116 (space source font) \(mu \fIextend_factor\fR
117 T}:T{
118 (space source font) \(mu \fIextend_factor\fR
119 T}
120 .TE
121 .sp
122 For fixed\-pitch fonts, different values apply:
123 .TS
124 allbox tab(:);
125 lB lB lB.
126 T{
127 Font dimension
128 T}:T{
129 Default value
130 T}:T{
131 Afm2tfm value
132 T}
133 .T&
134 l l l
135 l l l
136 l l l
137 l l l
138 l l l.
139 T{
140 \fIstretch\fR
141 T}:T{
142 0
143 T}:T{
144 0
145 T}
146 T{
147 \fIshrink\fR
148 T}:T{
149 0
150 T}:T{
151 0
152 T}
153 T{
154 \fIextra space\fR
155 T}:T{
156 space
157 T}:T{
158 missing
159 T}
160 T{
161 \fIquad\fR
162 T}:T{
163 2 \(mu character width
164 T}:T{
165 1000 \(mu \fIextend_factor\fR
166 T}
167 T{
168 \fIspace\fR
169 T}:T{
170 character width
171 T}:T{
172 character width
173 T}
174 .TE
175 .sp
176 Specify just a non\-default stretch and shrink with e\&.g\&.
177 150,70
178 and just a non\-default extra space with
179 ,,10\&.
180 .RE
181 .PP
182 \fB\-k\fR
183 .RS 4
184 Keep original ligatures\&. This option only has effect in combination with positive letterspacing; see the section on
185 letterspacing and extra ligkern info\&.
186 .RE
187 .PP
188 \fB\-m\fR \fIletter_spacing\fR
189 .RS 4
190 Letterspace by
191 \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
192 letterspacing and extra ligkern info
193 for details\&. A better alternative, though, is letting pdftex do the letterspacing\&. The
194 microtype
195 package gives LaTeX users access to this feature\&.
196 .RE
197 .PP
198 \fB\-l\fR \fIligkern_spec\fR, \fB\-L\fR \fIligkern_spec\fR
199 .RS 4
200 See the section on
201 extra ligkern info
202 for details\&.
203 .RE
204 .PP
205 \fB\-n\fR
206 .RS 4
207 No prefix\&. For \&.enc\- and \&.lig files, the program normally first prefixes the name with `afm2pl\-\'\&. Only if the prefixed filename is not found, will it search for the original filename\&. This option prevents searching for the prefixed filename\&.
208 .RE
209 .PP
210 \fB\-V\fR
211 .RS 4
212 Verbose\&. If turned on, it reports the number of missing glyphs to stderr and their names to stdout\&.
213 .RE
214 .PP
215 \fB\-\-help\fR
216 .RS 4
217 Display a short usage message\&.
218 .RE
219 .PP
220 \fB\-\-version\fR
221 .RS 4
222 Display the version number of afm2pl\&.
223 .RE
224 .SH "MAPFILE ENTRIES"
225 .PP
226 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\&. It is assumed that the pfb file has the same basename as the afm file and must be downloaded\&.
227 \fIYou may have to hand\-edit this entry\&.\fR
228 .PP
229 You can configure dvips and pdftex to read this additional mapfile or otherwise add the entry to an existing mapfile\&.
230 .PP
231 \fBCheck your mapfiles!\fR
232 To reduce the likelihood of name conflicts, the \&.enc\- files which are part of afm2pl (ot1, ot1csc, ot1ital, ot1tt, texnanlc and texnanuc) have now been prepended with
233 afm2pl\-\&. The \&.enc files are referenced in mapfiles\&. If you have old afm2pl\-generated \&.tfm files using these, then you should update their mapfile fragments and rerun updmap or updmap\-sys\&. Or you can copy the relevant enc files to your personal or local texmf tree under their previous non\-prefixed names\&.
234 .SH "EXTRA LIGKERN INFO"
235 .PP
236 \fIMost users are well\-advised to leave this mess alone and to accept the default behavior\&.\fR
237 .PP
238 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 [afm2pl\-]default\&.lig\&. A value of 0 for
239 \fIligkern_spec\fR
240 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\&.
241 .PP
242 If afm2pl is compiled with the kpathsea library, then these files will be searched for under $TEXMF/fonts/lig\&.
243 .PP
244 \fINote 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\&.\fR
245 .PP
246 The parser for ligkern info has been inherited from afm2tfm virtually without change\&. A ligkern specification can have one of the following forms:
247 .sp
248 .RS 4
249 .nf
250 \fIglyph_name1\fR \fIglyph_name2\fR \fIlig_op\fR \fIglyph_name3\fR ;
251 .fi
252 .RE
253 .PP
254 This specifies a ligature\&. Possible values for
255 \fIlig_op\fR
256 are
257 =:,
258 |=:,
259 |=:>,
260 =:|,
261 =:|>,
262 |=:|,
263 |=:|>
264 and
265 |=:|>>\&. These correspond to
266 LIG,
267 /LIG,
268 /LIG>,
269 LIG/,
270 LIG/>,
271 /LIG/,
272 /LIG/>,
273 /LIG/>>
274 in \&.pl syntax; see the pltotf documentation and the \&.lig files in the distribution\&.
275 .sp
276 .RS 4
277 .nf
278 \fIglyph_name1\fR <> \fIglyph_name2\fR ;
279 .fi
280 .RE
281 .PP
282 Kern
283 \fIglyph_name1\fR
284 as
285 \fIglyph_name2\fR\&.
286 .sp
287 .RS 4
288 .nf
289 \fIglyph_name1\fR {} \fIglyph_name2\fR ;
290 .fi
291 .RE
292 .PP
293 Remove the kern between
294 \fIglyph_name1\fR
295 and
296 \fIglyph_name2\fR\&. A value of
297 *
298 for either glyph name is interpreted as a wildcard\&.
299 .sp
300 .RS 4
301 .nf
302 || = \fIglyph\fR ;
303 .fi
304 .RE
305 .PP
306 Set the (right) boundary character to
307 \fIglyph\fR\&.
308 \fIglyph\fR
309 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:
310 || = cwm ;\&.
311 .PP
312 You can copy the kerns of an unencoded character to the boundarychar\&. Below,
313 space
314 is the unencoded character:
315 .sp
316 .RS 4
317 .nf
318 || <> space ;
319 .fi
320 .RE
321 .PP
322 This ligkern specification should occur before the one that deletes space kerns\&.
323 .PP
324 A ligkern specification should be contained within one line\&. One line may contain several ligkern specifications, separated by spaces\&. Note that
325 ;
326 (space followed by semicolon) is considered part of the ligkern specification\&. See the lig files included in this distribution\&. Example:
327 .sp
328 .RS 4
329 .nf
330 one {} * ; * {} one ; two {} * ; * {} two ;
331 .fi
332 .RE
333 .PP
334 Lines with ligkern specifications inside an encoding file should start with
335 % LIGKERN\&. Ligkern specifications in a lig file may optionally start this way\&.
336 .SH "LETTERSPACING AND EXTRA LIGKERN INFO"
337 .PP
338 Letterspacing has various side\-effects for ligkern info\&. Instead of simply applying the extra ligkern info (see previous section), the following is done:
339 .sp
340 .IP 1.
341 In case of positive letterspacing, native ligatures are removed, unless the \-k option is specified\&.
342 .sp
343 .IP 2.
344 Extra ligkern info is applied as usual, except that in case of positive letterspacing different defaults apply:
345 \-l 0
346 is quietly ignored, ligkern comments in the encoding file are ignored, and defpre\&.lig is read instead of default\&.lig\&.
347 .sp
348 .IP 3.
349 Letterspacing is applied\&. This adds a lot of kerns, and modifies existing kerns\&.
350 .sp
351 .IP 4.
352 The extra ligkern info specified with \-L is applied\&. The only ligkern specs which are allowed here, are removals of kerning pairs (with the
353 {}
354 operator)\&. Values 0 and 1 have a similar meaning as for the \-l parameter\&.
355 \fIThe tfm format has room for only about 180x180 ligatures and kerning pairs\&.\fR
356 This is enough for OT1 encoding, but for texnansi encoding quite a few ligkern specifications have to be removed\&. The pltotf program will remove
357 \fIall\fR
358 ligkern info if too many ligatures and kerns remain\&. The default lig
359 file is defpost\&.lig\&. This file throws out kerning pairs which are
360 unlikely to be involved in letterspacing, such as kerns involving
361 accents or kerns with a punctuation character or right bracket at the
362 left\&. It does not add letterspacing kerns involving
363 boundarychars\&. Instead, fontspace is increased by twice the
364 letterspacing\&. defpost\&.lig throws out enough kerns in case of
365 texnansi encoding\&. With other encodings, you may have to throw out
366 additional kerning pairs\&.
367
368 .SH "FONT-BASED UPPER- AND LOWERCASING"
369 .PP
370 The distribution includes encoding vectors texnanuc\&.enc and texnanlc\&.enc which produce all\-uppercase and all\-lowercase fonts
371 .PP
372 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\&. Example:
373 .sp
374 .RS 4
375 .nf
376 afm2pl \-p texnanuc ptmr8a ptmup8y
377 pltotf ptmup8y
378 .fi
379 .RE
380 .sp
381 For best results, you should add some letterspacing\&. In LaTeX, this is best done with the
382 microtype
383 package; see the documentation of that package\&. But it can also be done with
384 afm2pl:
385 .sp
386 .RS 4
387 .nf
388 afm2pl \-p texnanuc \-m 100 ptmr8a ptmup8y
389 .fi
390 .RE
391 .sp
392 This requires caution; see
393 above\&.
394 .PP
395 You can use this new font within the context of LaTeX font selection as follows:
396 .sp
397 .RS 4
398 .nf
399
400 <preamble commands>
401 \emakeatletter
402 {\enfss@catcodes
403 \eDeclareFontShape{LY1}{ptm}{m}{upp}{<\-> ptmup8y}{}}
404 \emakeatother
405 \&.\&.\&.
406 \ebegin{document}
407 \&.\&.\&.
408 {\efontshape{upp}\eselectfont uppercase text}
409
410 .fi
411 .RE
412 .sp
413 Note that
414 upp
415 is simply a newly made\-up shape name\&.
416 .SS "The sz ligature \(ss"
417 .PP
418 Note that the texnanuc encoding provides no glyph for the sz ligature \(ss; 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:
419 .sp
420 .RS 4
421 .nf
422
423 \edef\ess{%
424 \esetbox0\ehbox{\echar25}%
425 \eifnum\ewd0=0 ss\eelse\ebox0\efi
426 }
427
428 .fi
429 .RE
430 .PP
431 In LaTeX, this code appears to work well enough, although on occasion you may need to insert
432 \eprotect\&. A better solution might involve the sixth parameter of the
433 \eDeclareFontShape
434 macro, but I failed to get that to work\&.
435 .SH "AFM2PL, FONTINST AND ARTIFICIAL SMALLCAPS"
436 .PP
437 Afm2pl 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\&.
438 .PP
439 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\&.
440 .PP
441 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\&.
442 .SH "CHANGED IN VERSION 0.7.1"
443 .PP
444 In order to avoid name conflicts, the \&.enc\- and \&.lig files distributed with afm2pl got
445 afm2pl\-
446 prepended to their name\&. The program itself now first searches for the thus prepended name\&. If the \&.enc\- or \&.lig file is not found it will look for the original filename\&. The renaming of the afm2pl \&.enc files may require modification of some mapfiles\&.
447 .SH "URLS"
448 .PP
449 The afm2pl homepage is
450 \fIhttp://tex\&.aanhet\&.net/afm2pl/\fR\&.
451 .PP
452 The paper
453 \fIFont installation the shallow way\fR\&[2]
454 (EuroTeX 2006 Proceedings, published as
455 \fITUGboat\fR\&[3]
456 issue 27\&.1) illustrates the use of afm2pl\&.
457 .SH "NOTES"
458 .IP " 1." 4
459 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. Better yet, don't use Courier at all; most TeX distributions offer various good replacements.
460 .IP " 2." 4
461 Font installation the shallow way
462 .RS 4
463 \%https://tug.org/TUGboat/tb27-1/tb86kroonenberg-fonts.pdf
464 .RE
465 afm2pl is maintained as part of TeX Live.
466