A primer on font installation for groff (was: gropdf(1)'s 'Font installation' section is opaque to me)

[G. Branden Robinson]

Hi Alex,

At 2024-04-19T00:29:37+0200, Alejandro Colomar wrote:
> While the above is interesting, I've already read similar explanations
> from you in related threads.  However, I still have no clue of how to
> drop TINOR from the Linux man-pages repo and generate it from
> something coming from a package.  :(

Well, it's tedious, which is why Peter Schaffter and others have written
shell scripts to help with the process.

Here's a file- and program-centric overview of what's required.

1.  You grab a modern font file from some place.  This will be a TTF or
    OTF file.

2.  You use FontForge or a similar tool to generate TWO files from a
    TTF/OTF file.

    2a.  A PostScript Type 1 font in PFA and/or PFB format.  If you want
    to embed this font in a groff-generated PostScript file, you have to
    use PFA, because that is all grops(1) understands.  If you want to
    embed this font in a groff-generated PDF, you can use either,
    because gropdf(1) understands both formats.

    2b.  If you have a PFB file and need PFA, you can use groff's
    utility pfbtops(1) to produce the latter.

    2c.  You will also have to produce an AFM file.  This stands for
    "Adobe Font Metrics".  This describes the dimensions of the glyphs
    in the proper font file.  The font metrics are not the font itself;
    they merely describe it in some respects.

3.  The formatter, troff(1), must have font metrics so that it can
    correctly position glyphs on the page.  But GNU troff, like AT&T
    troff before it, does not use AFM files directly for this purpose;
    AT&T troff is older than Adobe PostScript.  Instead it uses a "font
    description file", which includes the metrics and other information
    important to the formatter.  The font description file is what
    corresponds to the short, shouty *roff font names we're used to,
    like "TR" or "S" or "CBI".

4.  The *roff font description files must be placed where the formatter
    can find them when it runs.  They must appear in the
    GROFF_FONT_PATH, or the formatter must be told where to look with an
    `-f` command-line option.

5.  When embedding fonts in PostScript or PDF, the _output driver_
    (grops or gropdf) must be told where to look to find them.  Each
    driver consults a "download" file for this information.

A package manager has a few things to keep track of to ensure that the
state of all these remains coherent.

A.  If a new "modern" (TTF/OTF) font is installed, a program to generate
    PFA/PFB and AFM files must be run to make it available to groff.

B.  afmtodit(1) must be run to produce a groff font description file
    from the AFM file.

C.  The font description files must be placed in groff's "font search
    path".  In practice this means two places, one for PostScript and
    one for PDF.

D.  The "download" files for the grops and gropdf programs must be
    updated to list the PFA/PFB file in the correct locations.

When a font is removed, the foregoing artifacts must be updated or
deleted as appropriate.

When a font is updated, some or all of the foregoing artifacts must be
regenerated, depending on whether the font files changed their names
(this happens regularly to the URW "base" fonts).  The AFM files and
therefore the corresponding groff font description files must be updated
if any glyphs were added, removed, or changed their dimensions.

The foregoing procedure offers several points of failure.  That is, I
suspect, why no distribution has ever yet bothered.

Does this help?

Regards,
Branden

signature.asc
Description: PGP signature