Debian Codegraph @

upstream/debian-trixie/man1/afmtodit.1

raw
1 .TH afmtodit 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 afmtodit \- adapt Adobe Font Metrics files for
4 .I groff
5 PostScript and PDF output
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
13 .\"
14 .\" Permission is granted to make and distribute verbatim copies of this
15 .\" manual provided the copyright notice and this permission notice are
16 .\" preserved on all copies.
17 .\"
18 .\" Permission is granted to copy and distribute modified versions of
19 .\" this manual under the conditions for verbatim copying, provided that
20 .\" the entire resulting derived work is distributed under the terms of
21 .\" a permission notice identical to this one.
22 .\"
23 .\" Permission is granted to copy and distribute translations of this
24 .\" manual into another language, under the above conditions for
25 .\" modified versions, except that this permission notice may be
26 .\" included in translations approved by the Free Software Foundation
27 .\" instead of in the original English.
28 .
29 .
30 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
31 .do nr *groff_afmtodit_1_man_C \n[.cp]
32 .cp 0
33 .
34 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
35 .nr do-fallback 0
36 .if !\n(.f .nr do-fallback 1 \" mandoc
37 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
38 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
39 .if \n[do-fallback] \{\
40 . de MR
41 . ie \\n(.$=1 \
42 . I \%\\$1
43 . el \
44 . IR \%\\$1 (\\$2)\\$3
45 . .
46 .\}
47 .rr do-fallback
48 .
49 .
50 .\" ====================================================================
51 .SH Synopsis
52 .\" ====================================================================
53 .
54 .SY afmtodit
55 .RB [ \-ckmnsx ]
56 .RB [ \-a\~\c
57 .IR slant ]
58 .RB [ \-d\~\c
59 .IR device-description-file ]
60 .RB [ \-e\~\c
61 .IR encoding-file ]
62 .RB [ \-f\~\c
63 .IR internal-name ]
64 .RB [ \-i\~\c
65 .IR italic-correction-factor ]
66 .RB [ \-o\~\c
67 .IR output-file ]
68 .RB [ \-w\~\c
69 .IR space-width ]
70 .I afm-file
71 .I map-file
72 .I font-description-file
73 .YS
74 .
75 .
76 .SY afmtodit
77 .B \-\-help
78 .YS
79 .
80 .
81 .SY afmtodit
82 .B \-v
83 .
84 .SY afmtodit
85 .B \-\-version
86 .YS
87 .
88 .
89 .\" ====================================================================
90 .SH Description
91 .\" ====================================================================
92 .
93 .I \%afmtodit
94 adapts an
95 Adobe Font Metric
96 file,
97 .IR afm-file ,
98 for use with the
99 .B ps
100 and
101 .B pdf
102 output devices of
103 .MR \%troff 1 .
104 .
105 .I map-file
106 associates a
107 .I groff
108 ordinary or special character name with a PostScript glyph name.
109 .
110 Output is written in
111 .MR groff_font 5
112 format to
113 .I font-description-file,
114 a file named for the intended
115 .I groff
116 font name
117 (but see the
118 .B \-o
119 option).
120 .
121 .
122 .LP
123 .I map-file
124 should contain a sequence of lines of the form
125 .
126 .RS
127 .EX
128 .I ps-glyph groff-char
129 .EE
130 .RE
131 .
132 where
133 .I ps-glyph
134 is the PostScript glyph name and
135 .I groff-char
136 is a
137 .I groff
138 ordinary
139 (if of unit length)
140 or special
141 (if longer)
142 character identifier.
143 .
144 The same
145 .I ps-glyph
146 can occur multiple times in the file;
147 each
148 .I groff-char
149 must occur at most once.
150 .
151 Lines starting with \[lq]#\[rq] and blank lines are ignored.
152 .
153 If the file isn't found in the current directory,
154 it is sought in the
155 .I devps/generate
156 subdirectory of the default font directory.
157 .
158 .
159 .LP
160 If a PostScript glyph is not mentioned in
161 .IR map-file ,
162 and a
163 .I groff
164 character name can't be deduced using the Adobe Glyph List
165 (AGL,
166 built into
167 .IR afmtodit ),
168 then
169 .I \%afmtodit
170 puts the PostScript glyph into the
171 .I groff
172 font description file as an unnamed glyph which can only be accessed
173 by the \[lq]\eN\[rq] escape sequence in a
174 .I roff
175 document.
176 .
177 In particular,
178 this is true for glyph variants named in the form
179 .RI \[lq] foo . bar \[rq];
180 all glyph names containing one or more periods are mapped to unnamed
181 entities.
182 .
183 Unless
184 .B \-e
185 is specified,
186 the encoding defined in the AFM file
187 (i.e.,
188 entries
189 with non-negative codes)
190 is used.
191 .
192 Refer to section \[lq]Using Symbols\[rq] in
193 .IR "Groff: The GNU Implementation of troff" ,
194 the
195 .I groff
196 Texinfo manual,
197 or
198 .MR groff_char 7 ,
199 which describe how
200 .I groff
201 character identifiers are constructed.
202 .
203 .
204 .LP
205 Glyphs not encoded in the AFM file
206 (i.e.,
207 entries indexed as \[lq]\-1\[rq])
208 are still available in
209 .IR groff ;
210 they get glyph index values greater than 255
211 (or greater than the biggest code used in the AFM file in the unlikely
212 case that it is greater than 255)
213 in the
214 .I groff
215 font description file.
216 .
217 Unencoded glyph indices don't have a specific order;
218 it is best to access them only via special character identifiers.
219 .
220 .
221 .P
222 If the font file proper
223 (not just its metrics)
224 is available,
225 listing it in the files
226 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%download
227 and
228 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devpdf/\:\%download
229 enables it to be embedded in the output produced by
230 .MR grops 1
231 and
232 .MR gropdf 1 ,
233 respectively.
234 .
235 .
236 .P
237 If the
238 .B \-i
239 option is used,
240 .I \%afmtodit
241 automatically generates an italic correction,
242 a left italic correction,
243 and a subscript correction for each glyph
244 (the significance of these is explained in
245 .MR groff_font 5 );
246 they can be specified for individual glyphs by
247 adding to the
248 .I afm-file
249 lines of the form:
250 .
251 .RS
252 .EX
253 .RI italicCorrection \~ps-glyph\~n
254 .RI leftItalicCorrection \~ps-glyph\~n
255 .RI subscriptCorrection \~ps-glyph\~n
256 .EE
257 .RE
258 .
259 where
260 .I ps-glyph
261 is the PostScript glyph name,
262 and
263 .I n
264 is the desired value of the corresponding parameter in thousandths of an
265 em.
266 .
267 Such parameters are normally needed only for italic
268 (or oblique)
269 fonts.
270 .
271 .
272 .P
273 The
274 .B \-s
275 option should be given if the font is \[lq]special\[rq],
276 meaning that
277 .I groff
278 should search it whenever a glyph is not found in the current font.
279 .
280 In that case,
281 .I font-description-file
282 should be listed as an argument to the
283 .B fonts
284 directive in the output device's
285 .I DESC
286 file;
287 if it is not special,
288 there is no need to do so,
289 since
290 .MR \%troff 1
291 will automatically mount it when it is first used.
292 .
293 .
294 .br
295 .ne 7v
296 .\" ====================================================================
297 .SH Options
298 .\" ====================================================================
299 .
300 .B \-\-help
301 displays a usage message,
302 while
303 .B \-v
304 and
305 .B \%\-\-version
306 show version information;
307 all exit afterward.
308 .
309 .
310 .TP
311 .BI \-a\~ slant
312 Use
313 .I slant
314 as the slant (\[lq]angle\[rq]) parameter in the font description file;
315 this is used by
316 .I groff
317 in the positioning of accents.
318 .
319 By default
320 .I \%afmtodit
321 uses the negative of the
322 .B \%ItalicAngle
323 specified in the AFM file;
324 with true italic fonts it is sometimes desirable to use a slant that is
325 less than this.
326 .
327 If you find that an italic font places accents over base glyphs
328 too far to the right,
329 use
330 .B \-a
331 to give it a smaller slant.
332 .
333 .
334 .TP
335 .B \-c
336 Include comments in the font description file identifying the PostScript
337 font.
338 .
339 .
340 .TP
341 .BI \-d\~ device-description-file
342 The device description file is
343 .I desc-file
344 rather than the default
345 .IR DESC .
346 .
347 If not found in the current directory,
348 the
349 .I devps
350 subdirectory of the default font directory is searched
351 (this is true for both the default device description file and a file
352 given with option
353 .BR \-d ).
354 .
355 .
356 .TP
357 .BI \-e\~ encoding-file
358 The PostScript font should be reencoded to use the encoding described
359 in
360 .IR enc-file .
361 .
362 The format of
363 .I enc-file
364 is described in
365 .MR grops 1 .
366 .
367 If not found in the current directory,
368 the
369 .I devps
370 subdirectory of the default font directory is searched.
371 .
372 .
373 .TP
374 .BI \-f\~ internal-name
375 The internal name of the
376 .I groff
377 font is set to
378 .IR name .
379 .
380 .
381 .TP
382 .BI \-i\~ italic-correction-factor
383 Generate an italic correction for each glyph so that its width plus its
384 italic correction is equal to
385 .I italic-correction-factor
386 thousandths of an em
387 plus the amount by which the right edge of the glyph's bounding box is
388 to the right of its origin.
389 .
390 If this would result in a negative italic correction,
391 use a zero italic correction instead.
392 .
393 .
394 .IP
395 Also generate a subscript correction equal to the
396 product of the tangent of the slant of the font and
397 four fifths of the x-height of the font.
398 .
399 If this would result in a subscript correction greater than the italic
400 correction,
401 use a subscript correction equal to the italic correction instead.
402 .
403 .
404 .IP
405 Also generate a left italic correction for each glyph equal to
406 .I italic-correction-factor
407 thousandths of an em
408 plus the amount by which the left edge of the glyph's bounding box is to
409 the left of its origin.
410 .
411 The left italic correction may be negative unless option
412 .B \-m
413 is given.
414 .
415 .
416 .IP
417 This option is normally needed only with italic
418 (or oblique)
419 fonts.
420 .
421 The font description files distributed with
422 .I groff
423 were created using an option of
424 .B \-i50
425 for italic fonts.
426 .
427 .
428 .TP
429 .BI \-o\~ output-file
430 Write to
431 .I output-file
432 instead of
433 .I font-description-file.
434 .
435 .
436 .TP
437 .B \-k
438 Omit any kerning data from the
439 .I groff
440 font;
441 use only for monospaced (constant-width) fonts.
442 .
443 .
444 .TP
445 .B \-m
446 Prevent negative left italic correction values.
447 .
448 Font description files for roman styles distributed with
449 .I groff
450 were created with
451 .RB \[lq] \-i0\~\-m \[rq]
452 to improve spacing with
453 .MR \%eqn 1 .
454 .
455 .
456 .TP
457 .B \-n
458 Don't output a
459 .B ligatures
460 command for this font;
461 use with monospaced (constant-width) fonts.
462 .
463 .
464 .TP
465 .B \-s
466 Add the
467 .B special
468 directive to the font description file.
469 .
470 .
471 .TP
472 .BI \-w\~ space-width
473 Use
474 .I space-width
475 as the with of inter-word spaces.
476 .
477 .
478 .TP
479 .B \-x
480 Don't use the built-in Adobe Glyph List.
481 .
482 .
483 .\" ====================================================================
484 .SH Files
485 .\" ====================================================================
486 .
487 .TP
488 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:DESC
489 describes the
490 .B ps
491 output device.
492 .
493 .
494 .TP
495 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/ F
496 describes the font known
497 .RI as\~ F
498 on device
499 .BR ps .
500 .
501 .
502 .TP
503 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%download
504 lists fonts available for embedding within the PostScript document
505 (or download to the device).
506 .
507 .
508 .TP
509 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%generate/\:\%dingbats.map
510 .TQ
511 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%generate/\:\%dingbats\-reversed.map
512 .TQ
513 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%generate/\:\%slanted\-symbol.map
514 .TQ
515 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%generate/\:\%symbol.map
516 .TQ
517 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devps/\:\%generate/\:\%text.map
518 map names in the Adobe Glyph List to
519 .I groff
520 special character identifiers for Zapf Dingbats
521 .RB ( ZD ),
522 reversed Zapf Dingbats
523 .RB ( ZDR ),
524 slanted symbol
525 .RB ( SS ),
526 symbol
527 .RB ( S ),
528 and text fonts,
529 respectively.
530 .
531 These
532 .IR map-file s
533 are used to produce the font description files provided with
534 .I groff
535 for the
536 .I \%grops
537 output driver.
538 .
539 .
540 .\" ====================================================================
541 .SH Diagnostics
542 .\" ====================================================================
543 .
544 .TP
545 .RI "AGL name \[aq]" x "\[aq] already mapped to groff name \[aq]" y\c
546 .RI "\[aq]; ignoring AGL name \[aq]uni" XXXX \[aq]
547 You can disregard these if they're in the form shown,
548 where the ignored AGL name contains four hexadecimal digits
549 .IR XXXX .
550 .
551 The Adobe Glyph List (AGL) has its own names for glyphs;
552 they are often
553 different from
554 .IR groff 's
555 special character names.
556 .
557 .I \%afmtodit
558 is constructing a mapping from
559 .I groff
560 special character names to AGL names;
561 this can be a one-to-one or many-to-one mapping,
562 but one-to-many will not work,
563 so
564 .I \%afmtodit
565 discards the excess mappings.
566 .
567 For example,
568 if
569 .I x
570 is
571 .BR *D ,
572 .I y
573 is
574 .BR \%Delta ,
575 and
576 .I z
577 is
578 .BR uni0394 ,
579 .I \%afmtodit
580 is telling you that the
581 .I groff
582 font description that it is writing cannot map the
583 .I groff
584 special character
585 .B \[rs][*D]
586 to AGL glyphs
587 .B \%Delta
588 and
589 .B uni0394
590 at the same time.
591 .
592 .
593 .IP
594 If you get a message like this but are unhappy with which mapping is
595 ignored,
596 a remedy is to craft an alternative
597 .I map-file
598 and re-run
599 .I \%afmtodit
600 using it.
601 .
602 .
603 .\" ====================================================================
604 .SH "See also"
605 .\" ====================================================================
606 .
607 .IR "Groff: The GNU Implementation of troff" ,
608 by Trent A.\& Fisher and Werner Lemberg,
609 is the primary
610 .I groff
611 manual.
612 .
613 Section \[lq]Using Symbols\[rq] may be of particular note.
614 .
615 You can browse it interactively with \[lq]info \[aq](groff)Using
616 \%Symbols\[aq]\[rq].
617 .
618 .
619 .LP
620 .MR groff 1 ,
621 .MR gropdf 1 ,
622 .MR grops 1 ,
623 .MR groff_font 5
624 .
625 .
626 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
627 .cp \n[*groff_afmtodit_1_man_C]
628 .do rr *groff_afmtodit_1_man_C
629 .
630 .
631 .\" Local Variables:
632 .\" fill-column: 72
633 .\" mode: nroff
634 .\" End:
635 .\" vim: set filetype=groff textwidth=72: