Lacking Natural Simplicity

Currently install-font.sh is not part of groff. We've had some discussion on the list recently and in the past about integrating it into the groff distribution, and in response to recent discussion there is a new bug, #60930, requesting integrating it, including documentation, etc.

In the meantime, if you want to install fonts in OpenType or TrueType formats for use with devps and devpdf, install-font.sh greatly simplifies the process.

The install-font.sh script was written by Peter Schaffter, the author of the mom macros for groff, and is distributed on mom's download page and can be downloaded directly. It has a -H option that prints the documentation for it.

Fontforge is a free and open source font editor. It can run scripts to manipulate fonts and convert between font formats. (I only use fontforge to install fonts with install-font.sh, so I use a version that is command line only, but the normal build has a GUI for interactively building fonts.) The install-font.sh script uses Fontforge to convert OpenType and TrueType fonts to PostScript Type42 (.t42) and Type1 (.pfa), from which a groff font is generated by the groff utility afmtodit. Then the necessary files are moved to site-font/devps and registered in its download file for use by grops. Optionally the same can be done for site-font/devpdf for the use of gropdf. Then the fonts are available for use by groff -Tps and groff -Tpdf.

So, suppose you wanted to use Cormorant Garamond, a free font. You could download the Regular, Italic, Bold, and Bold Italic variants of the font, since groff tends to expect there to be R, I, B, and BI variants of the fonts it uses, though that is not mandatory. This would give you the files CormorantGaramond-Regular.ttf, CormorantGaramond-Italic.ttf, CormorantGaramond-Bold.ttf, and CormorantGaramond-BoldItalic.ttf. You would then use install-font.sh to convert them and install the resulting files into proper places under groff's site-font directory.

So, for instance, you'd cd to the directory that holds the .ttf files you downloaded. Then, to install the Regular variant of Cormorant Garamond you'd run the command

$(IFDIR)/install-font.sh -n -P "$DEST" -d -F CormorantGaramond -f +R CormorantGaramond-Regular.ttf

where IFDIR is an environment variable indicating the directory where install-font.sh is located and DEST is an environment variable indicating the directory that contains groff's site-font directory (not the actual site-font directory itself). The -n option means don't try to copy the TrueType file to where the system font files are located. The -P option takes as its argument the directory that contains the groff's site-font directory. Usually this is some place like /usr/share/groff or /usr/local/share/groff, but not all distributions create the site-font directory. If you don't specify -P install-font.sh will guess the location. (If the site-font directory doesn't exist, or you don't have write access to it I think you can use the environment variable GROFF_FONT_PATH to tell groff where to find it, but I've never used that and don't know the specifics. I often build groff from git and install it someplace my normal user has write access to, so I haven't had to worry about it.) The -d option says to make the font available to gropdf. The -F option takes an argument that specifies the font family name to use. This is the name that you would use with the .fam request or the -f option to groff to let it know you want to use this font family. The -f option takes an argument that specifies the font style to use, +R, +I, +B, or +BI. (The -f option can instead take a name, but I don't use that form and can't explain the distinctions.) The style (R, I, B, or BI) is appended to the font family name specified with -F to produce the name of the groff font, and consequently the name of the groff font file that is written to the devps and devpdf directories under site-font. So, in this example, the name of the groff font and the groff font file would be CormorantGaramondR. The last argument to the script is the name of the Truetype or OpenType file you are converting.

To complete the example, here are the commands to install the Italic, Bold, and Bold Italic variants of Cormorant Garamond:

$(IFDIR)/install-font.sh -n -P "$DEST" -d -F CormorantGaramond -f +I CormorantGaramond-Italic.ttf
$(IFDIR)/install-font.sh -n -P "$DEST" -d -F CormorantGaramond -f +B CormorantGaramond-Bold.ttf
$(IFDIR)/install-font.sh -n -P "$DEST" -d -F CormorantGaramond -f +BI CormorantGaramond-BoldItalic.

As I said in an earlier email to the list, I tend to put all four commands into a script so I can run them again if something goes wrong or when I need to install them on a new machine or in a new installation of groff. In the case of Cormorant Garamond I named the file install-cormorant-garamond.sh.

Later: Peter Schaffter pointed out that the simple use of install-font.sh is:

sudo install-font.sh fontfile

and then answer the questions the script asks. He also pointed out that it creates the site-font directory and necessary subdirectories if needed in, and here I quote: “the only two locations it's ever likely to be”. Looking at install-font.sh reveal those locations are /usr/local/share/groff and /usr/share/groff, defaulting to /usr/local/share/groff; to get it to use /usr/share/groff you specify the -s option.

For a walk-through of the simple use see the follow-up.

Last edited: 2021-07-15 17:46:40 EDT