Debian Codegraph @

upstream/debian-unstable/man1/afmtodit.1

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