afmtodit(1)

🌸 NAME 🌸

okay so this is afmtodit(1), straight out of the General Commands Manual, and it is literally the glow-up station for font metrics 💅

afmtodit — adapt Adobe Font Metrics files for groff PostScript and PDF output.

✨ SYNOPSIS ✨

afmtodit [-ckmnqsx] [-a slant] [-d device-description-file]
         [-e encoding-file] [-f internal-name] [-i italic-correction-factor]
         [-o output-file] [-w space-width] afm-file map-file
         font-description-file

afmtodit --help

afmtodit -v

afmtodit --version

💖 DESCRIPTION 💖

So afmtodit makes a font description file for groff(1)'s ps and pdf output devices, starting from an Adobe Font Metric file, afm-file 🎀. The map-file is the matchmaker: it hooks a groff ordinary or special character name up with a PostScript glyph name. Output goes out in groff_font(5) format to font-description-file — a file named for the groff font name you're going for (but lowkey peep the -o option, it can change that 👀).

The map-file should be a sequence of lines shaped like this:

ps-glyph groff-char

where ps-glyph is the PostScript glyph name and groff-char is a groff ordinary (if it's of unit length) or special (if it's longer) character identifier. The same ps-glyph can show up multiple times in the file, no problem — but each groff-char must occur at most once ⚠️. Lines starting with # and blank lines get ignored, ghosted, not invited. If the file isn't chillin' in the current directory, afmtodit goes looking in the devps/generate subdirectory of the default font directory.

If some PostScript glyph never gets mentioned in map-file, and no groff character name can be deduced using the Adobe Glyph List (that's the AGL, built right into afmtodit), then afmtodit just drops the PostScript glyph into the groff font description file as an unnamed glyph, which you can only reach with the \N escape sequence in a roff document 🙈. This is especially true for glyph variants named in the form foo.bar — every single glyph name containing one or more periods gets mapped to unnamed entities, no exceptions. Unless -e is specified, the encoding defined in the AFM file is used (i.e., the entries with non-negative codes). For the full lore on how groff character identifiers get built, check section "Using Symbols" in Groff: The GNU Implementation of troff, the groff Texinfo manual, or groff_char(7) 📚.

Glyphs that aren't encoded in the AFM file (the entries indexed as -1) are still available in groff, bestie — they just get glyph index values greater than 255 (or greater than the biggest code used in the AFM file, in the wildly unlikely case that that's greater than 255) in the groff font description file. Heads up though: unencoded glyph indices have no specific order, so it's genuinely best to access them only via special character identifiers 🫶.

If you've got the actual font file (not just its metrics), listing it in /usr/share/groff/1.24.2/font/devps/download and /usr/share/groff/1.24.2/font/devpdf/download lets it get embedded in the output that grops(1) and gropdf(1) produce, respectively 🔥.

If the -i option is in play, afmtodit automatically generates an italic correction, a left italic correction, and a subscript correction for each glyph (what these even mean is explained in groff_font(5), iykyk). You can also set them for individual glyphs by adding lines like these to the afm-file:

italicCorrection ps-glyph n
leftItalicCorrection ps-glyph n
subscriptCorrection ps-glyph n

where ps-glyph is the PostScript glyph name and n is the value you want for that parameter in thousandths of an em. Ngl these parameters are normally only needed for italic (or oblique) fonts 💜.

The -s option should be given if the font is "special" — meaning groff should go searching for it whenever a glyph isn't found in the current font. To make that search happen, font-description-file can be listed as an argument to the fonts directive in the output device's DESC file; alternatively, a document can designate it with the special request. If the font isn't special, you don't need to do either, because troff(1) will automatically mount it the first time it's used ✨.

🦋 OPTIONS 🦋

--help displays a usage message, while -v and --version show version information — and all of them exit right afterward, bye 👋.

• -a slant — use slant as the slant ("angle") parameter in the font description file; groff uses this when positioning accents. By default afmtodit uses the negative of the ItalicAngle specified in the AFM file, but with true italic fonts it's sometimes cuter to use a slant that's less than that. If your italic font is placing accents over base glyphs too far to the right, hit it with -a and give it a smaller slant 💅
• -c — include comments in the font description file identifying the PostScript font.
• -d device-description-file — the device description file is desc-file rather than the default DESC. If it's not found in the current directory, the devps subdirectory of the default font directory gets searched (this is true for both the default device description file and a file you hand over with option -d) 🔍.
• -e encoding-file — the PostScript font should be reencoded to use the encoding described in enc-file. The format of enc-file is described in grops(1). If it's not found in the current directory, the devps subdirectory of the default font directory gets searched.
• -f internal-name — the internal name of the groff font is set to name.
• -i italic-correction-factor — generate an italic correction for each glyph so that its width plus its italic correction equals italic-correction-factor thousandths of an em plus the amount by which the right edge of the glyph's bounding box is to the right of its origin. If that would result in a negative italic correction, use a zero italic correction instead 🚫.

Also generate a subscript correction equal to the product of the tangent of the slant of the font and four fifths of the x-height of the font. If that would result in a subscript correction greater than the italic correction, use a subscript correction equal to the italic correction instead.

Also generate a left italic correction for each glyph equal to italic-correction-factor thousandths of an em plus the amount by which the left edge of the glyph's bounding box is to the left of its origin. The left italic correction may be negative unless option -m is given ⚠️.

This option is normally needed only with italic (or oblique) fonts. The font description files distributed with groff were created using an option of -i50 for italic fonts 👑.

• -o output-file — write to output-file instead of font-description-file.
• -k — omit any kerning data from the groff font; use only for monospaced (constant-width) fonts.
• -m — prevent negative left italic correction values. Font description files for roman styles distributed with groff were created with -i0 -m to improve spacing with eqn(1) 🎀.
• -n — don't output a "ligatures" command for this font; use with monospaced (constant-width) fonts.
• -q — quieten duplicate mapping warnings; see section "Diagnostics" below 🤫.
• -s — add the "special" directive to the font description file.
• -w space-width — use space-width as the width of inter-word spaces.
• -x — don't use the built-in Adobe Glyph List.

⭐ EXIT STATUS ⭐

afmtodit exits with status 0 on successful operation, status 2 if the program cannot interpret its command-line arguments, and status 1 if it encounters an error during operation. Simple as that, no cap 💀.

🍓 FILES 🍓

• /usr/share/groff/1.24.2/font/devps/DESC — describes the ps output device.
• /usr/share/groff/1.24.2/font/devps/F — describes the font known as F on device ps.
• /usr/share/groff/1.24.2/font/devps/download — lists fonts available for embedding within the PostScript document (or download to the device).
• /usr/share/groff/1.24.2/font/devps/generate/dingbats.map
• /usr/share/groff/1.24.2/font/devps/generate/dingbats-reversed.map
• /usr/share/groff/1.24.2/font/devps/generate/slanted-symbol.map
• /usr/share/groff/1.24.2/font/devps/generate/symbol.map
• /usr/share/groff/1.24.2/font/devps/generate/text.map

These map names in the Adobe Glyph List to groff special character identifiers for Zapf Dingbats (ZD), reversed Zapf Dingbats (ZDR), slanted symbol (SS), symbol (S), and text fonts, respectively 🌈. These map-files produce the font description files provided with groff for the grops output driver.

🙈 DIAGNOSTICS 🙈

AGL name 'x' already mapped to groff name 'y'; ignoring AGL name
'uniXXXX'

You can disregard these if they're in the form shown, where the ignored AGL name contains four hexadecimal digits XXXX 😌. The Adobe Glyph List (AGL) has its own names for glyphs and they're often different from groff's special character names. afmtodit is constructing a mapping from groff special character names to AGL names; that can be one-to-one or many-to-one, but one-to-many simply will not work, so afmtodit discards the excess mappings. For example: if x is Delta, y is *D, and XXXX is 0394, afmtodit is telling you that the groff font description it's writing cannot map the groff special character \[*D] to AGL glyphs Delta and uni0394 at the same time.

If you get a message like this but you're unhappy with which mapping got ignored, the remedy is to craft an alternative map-file and re-run afmtodit using it 🛠️.

When the -q option is used, these messages are suppressed in favor of a count of how many would have been emitted were the option not present.

💜 SEE ALSO 💜

Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. Section "Using Symbols" may be of particular note 👀. You can browse it interactively with info '(groff)Using Symbols'.

groff(1), gropdf(1), grops(1), groff_font(5)

---

okay that's the whole page bestie, you ate that 🫶✨ this was groff 1.24.2, dated 2026-10-01, and it's giving afmtodit(1) main character energy — periodt 💅