Mom -- Appendices

Back to Table of Contents | Next: Reserved words

# Appendices

- Notes on the documentation
- Adding PostScript fonts to groff
  - How to create a PostScript font for use with groff
- Some reflections on mom
- Contact the author

## Notes on the documentation

Some mom users are sure to ask: “Why is the documentation in html? If mom’s so great, why not pdfs to show her off? And if groff’s so great, why not write a man page?”

Valid questions, to be sure, and mom has answers. (Okay—I have answers, but I speak for mom.)

The documentation is in html because I still find it the best tool for navigating lengthy manuals. Html, with its anchors and links, came into being precisely so people could do something they’d never been able to with the printed word: instantly track down internal and external references in a document.

It’s essential that people reading mom’s documentation never have difficulty finding precisely the macro they need for a particular task. Equally, when reading up on a macro, they should never be presented with terms or other macro names for which they cannot instantly find accurate explanations. Short of having written the documentation in TeX for the info browser (and TeX bloat is one of the reasons I prefer to typeset with groff), I can think of no better way to achieve the kind of truly useful documentation I wanted than html.

## Adding PostScript fonts to groff

Note: The term `<prefix>` in this section refers to the directory in which groff is installed, typically something like `/usr/share/groff/<version>` (for distro-specific, pre-compiled groff packages) or `/usr/local/share/groff/<version>` (if you’ve built groff from source).

Groff comes with a small library of PostScript families (see the FAMILY macro for a list). The families have four fonts associated with them. These fonts are a combination of weight and shape:
R (Roman, usually Medium weight), I (Italic, usually Medium weight), B (Bold, usually Roman shape) and BI (Bold Italic) If you work with mom a lot, you’ll find, sooner or later, that these families and their associated fonts aren’t sufficient. You’ll want to supplement them, either with more fonts for the families already provided—Damn! I need Helvetica Bold Condensed Italic!—or with entire new families.

Without going into the gory details (yet), while it’s true that adding fonts to groff is a relatively straightforward process, extending existing families or adding new ones requires some planning.

The traditional approach to extending groff families has been to create new families for non-default weights and shapes (e.g. Light, which is a weight; Condensed, which is a shape), then to associate them with groff’s predefined R, I, B and BI font styles. An example of this can be seen in the groff PostScript font library itself (<prefix>/font/devps/): there’s one “family” for Helvetica (HR, HI, HB, HBI) and another for Helvetica Narrow (HNR, HNI, HNB, HNBI).

The difficulty with this approach is that typographers tend to think of families as referring to the entire set of font weights and shapes associated with a particular family name. For example, when a typesetter says “the Helvetica family”, s/he is including the weights Helvetica Thin, Helvetic Light, Helvetica Regular, Helvetica Bold, Helvetica Heavy, etc, and all their associated shapes (Roman, Italic, Condensed, Narrow, Extended, Outline, etc).

Thus, intuitively, when a typesetter gives mom a `.FAM(ILY) H` directive, s/he reasonably expects that any subsequent `.FT` directive will access the desired font from the Helvetica family—without the need to state explicitly both family and font to `.FT`, as it is explained one can do in the FAMILY and FT sections of these documents.

If one had, say, the fonts, Helvetica Light Roman and Helvetica Light Italic as well as Helvetica Light Condensed Roman and Helvetica Light Condensed Italic, the established groff approach would require two “partial” families: HLR/HLI and HLCDR/HLCDI. Accessing these family/font combos routinely throughout a document would then require changing family (with `.FAM(ILY)`) and selecting the desired font (with `.FT R` or `.FT I`), or passing `.FT` the lengthy family+fontname (.e.g. `.FT HLCDI`).

Fortunately, groff provides a mechanism whereby it’s possible to extend the basic R, I, B and BI fonts (“styles” in groff-speak) so that one can, in fact, create extensive type families, and access all the fonts in them with `.ft` (groff) or `.FT` (mom).

Mom uses this mechanism to offer, in addition to groff’s default PostScript font styles, the following:

L = Light Roman LI = Light Italic LCD = Light Condensed Roman LCDI = Light Condensed Italic LEX = Light Extended Roman LEXI = Light Extended Italic CD = Medium/Book Condensed Roman CDI = Medium/Book Condensed Italic EX = Medium/Book Extended Roman EXI = Medium/Book Extended Italic DB = DemiBold Roman DBI = DemiBold Italic BCD = Bold Condensed Roman BCDI = Bold Condensed Italic BEX = Bold Extended Roman
BEXI = Bold Extended Italic HV = Heavy Roman HVI = Heavy Italic HVCD = Heavy Condensed Roman HVCDI = Heavy Condensed Italic HVEX = Heavy Extended Roman HVEXI = Heavy Extended Italic BL = Black Roman BLI = Black Italic BLCD = Black Condensed Roman BLCDI = Black Condensed Italic BLEX = Black Extended Roman BLEXI = Black Extended Italic UBL = Ultra-Black Roman UBLI = Ultra-Black Italic

Thus, with mom, if you’ve installed, say, some extra Helvetica fonts and named them according to the convention `<F><S>` (where `<F>` means family and `<S>` means font style), once having entered
.FAMILY H or .FAM H you can access any of those Helvetica fonts simply by passing the correct argument to FT. from the list, above.

For example, if you were working in Medium Roman (`.FT R`) and you needed Medium Condensed Italic for a while (assuming it’s installed), you’d just type
.FT CDI to access the Medium Condensed Italic font from the Helvetica family.

Mom’s list of font styles doesn’t pretend to be exhaustive, but rather tries to cover the basic weight/shape combinations likely to be found in any reasonably complete type family.

The actual extension names are arbitrary and can be used in a flexible manner. For example, if you create a family that has a DemiBold font (DB) but no Bold font (B), you might find it more convenient to give the DemiBold font the extension “B”. Equally, if the family has an ExtraBold font, you might find it more convenient to use the extension “HV” (Heavy).

However, you may, at needs, want to add to mom’s list of font styles. You can do this by editing the file, om.tmac (typical location: `<prefix>tmac/om.tmac`). Near the top, you’ll see lines of the form
.sty \n[.fp] L \" Light Roman .sty \n[.fp] LI \" Light Italic .sty \n[.fp] LCD \" Light Condensed Roman Simply add your new font style by imitating what you see, above, and plugging in your new font style (having, of course, first created the font, correctly named, in groff’s PostScript font directory; see How to create a PostScript font for use with groff).

For example, if you already have some fonts from the Univers family installed and have called the family UN, you might decide at some point to add the Bold Outline font (UNBO). In which case, you’d add
.sty \n[.fp] BO \" Bold Outline to the `.sty \n[.fp] <font style>` list in om.tmac.

Important: Be careful that any styles you add do not conflict with family names that already exist. “C”, for example, conflicts with the Courier family (CR, CI, CB, CI). Were you to create a font style “C”, thinking that `.FT C` would give you access to font style once you’d given a `.FAM(ILY)` directive, you’d get a nasty surprise: your type would come out in Courier Roman!

Note: Mom’s font extensions are not “user-space” controllable via a macro. If you’ve been using groff for a long time, and have already rolled your own solution to adding PostScript families, fonts, weights, shapes, etc. to groff, you may find that mom’s font extensions conflict with your own scheme. Should that be the case, comment out the `.sty \n[.fp] <font style>` lines found near the top of the `om.tmac` file.

## How to create a PostScript font for use with groff

These instructions aren’t meant to cover all possibilities, merely to present one way of making PostScript families/fonts available to groff and mom.

GNU/Linux distributions being what they are, directory locations may differ and the presence of some executables can’t be guaranteed. I run a Debian system. The instructions reflect that. Users of other distros will have to interpret them according to the way their distro operates.

### 1. What you need before you start

- groff, version 1.18 or higher
  (Debian package: groff)
- a full installation of ghostscript and associated tools
  (suggested Debian package: ghostscript-x)
- a library of PostScript fonts
  (suggest Debian packages: gsfonts, gsfonts-x11, gsfonts-other)
- a utility for converting TrueType fonts to Type1 fonts
  (Debian package: ttf2pt1)
- a font manager
  (Debian packages: defoma, psfontmgr)
- perl
  (Debian package: perl)

A reasonably complete installation of any major GNU/Linux distro should already have these on your system, except perhaps for the utility to convert TrueType fonts to Type1 fonts (ttf2pt2).

### 2. Initial preparation (you only need do this once)

1. If you don’t already have one, create a directory in your home directory to hold new fonts. Any directory name will do. I use `~/Fonts`, with subdirectories for `Type1`, `TrueType` and `Groff` fonts. Thus,
   ~/Fonts/Type1 ~/Fonts/TrueType ~/Fonts/Groff
2. Locate the groff directory, `site-font`. The exact location is difficult to predict, owing to differences between distros and whether you’re using a pre-packaged groff or have built it from source. Some typical locations are:
   /usr/share/groff /usr/local/share/groff /etc/groff If you can’t find the site-font directory, locate groff’s `site-tmac` directory, and, as root, create site-font in the same directory as the one that holds site-tmac. E.g., if you find site-tmac in `/usr/share/groff`, create site-font in `/usr/share/groff`.
3. Locate the file `<prefix>/font/devps/generate/textmap` and symlink it to the name `textmap` in the directory that contains your personal collection of PostScript fonts. (See the note, above, for the meaning of `<prefix>`). On my system, at the time of writing, `<prefix>` is
   /usr/local/share/groff/1.20.1/ therefore, I symlink it in `~/Fonts/Type1/` with
   ln -s /usr/local/share/groff/1.20.1/font/devps/generate/textmap textmap
4. Locate the file `<prefix>/font/devps/text.enc` and symlink it to the name `text.enc` in your personal font directory. On my system, in `~/Fonts/Type1/`
   ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc
5. Make sure you know which directory holds your PostScript fonts. You’ll need the information later. On a Debian box, a typical location is `/usr/share/fonts/type1/gsfonts`

### 3. Font creation/installation

1. Acquire the font as either Type1 (.pfb) or TrueType (.ttf).
2. Place the font in your personal font directory; for me, that’s
   ~/Fonts/Type1 or
   ~/Fonts/TrueType
3. In your personal font directory, run one of the following.
   - for Type1 fonts:
     getafm fontfilename.pfb | gsnd - > fontfilename.afm (This generates something called an .afm (Adobe Font Metrics) file from the .pfb file, which is required to create PostScript fonts for groff.)
   - for TrueType fonts:
     ttf2pt1 \-b fontfilename.ttf (For TrueType fonts, this generates a PostScript .pfb file as well as an .afm file.)
4. Still in your personal font directory, run
   afmtodit -e text.enc fontfilename.afm textmap <GROFF_FONTNAME>

   Q: How do I choose a `GROFF_FONTNAME`?

   A: Start by considering the family to which the font belongs. If you’re adding to a family that already exists in groff’s `<prefix>/font/devps` directory, that will be the first part of the font name. (See here for a list of families already installed, along with their groff names.) Add to that name the appropriate weight/style extension, listed here.

   For example, if you’re adding Helvetica Light Roman, your `GROFF_FONTNAME` would be `HL`. If you’re adding Helvetica Light Italic, your `GROFF_FONTNAME` would be `HLI`.

   If you’re adding a font not already in groff’s PostScript families, first choose a meaningful name for the family to which the font belongs. The name can be anything you like. If, for example, the family is Garamond, you could choose `GARAMOND`, `GARA`, `GD`, or even just plain G as the family name. Then tack on the appropriate style/weight extension. Thus, if you were installing Garamond Bold Condensed Italic and had chosen `GD` as the family name for Garamond, your `GROFF_FONTNAME` would be `GDBCDI`.

   In mom, you can then access the Garamond family with `.FAM GD`, and the Bold Condensed Italic font wth `.FT BCDI`.

   Note: The family name need not be in upper case, and there’s no limit to the length of the name. “Garamond”, for example, could be the name you give the Garamond family. In fact, you might find it preferable, since a) you wouldn’t have to remember how you’d named the family, and b) should you be scanning your site-font directory, something like GaramondBCDI will be more meaningful than, say, GDBCDI.

5. Copy or move `GROFF_FONTNAME` to your site-font directory, or change to the site-font directory and make a symlink to `GROFF_FONTNAME` in your personal directory.
6. Copy or move the .pfb file to the directory that holds your PostScript fonts, or change to that directory and make a symlink to the .pfb file in your personal directory.

Written out in full, adding fonts looks like a lot of work. It isn’t. Basically, it’s just:

- generate an .afm (and .pfb if the font is TrueType)
- create the groff font
- put the groff font in`<prefix>/font/devps`
- put the .pfb file (the actual font) with your other PostScript fonts

After you’ve done it a couple of times, it all makes sense and is really quite easy. Not to mention that once you understand the process, you can write a bash script to automate the process. Here’s an example, which you can adapt to your own needs. The script, for installing TrueType fonts, requires an argument (the .ttf filename), then prompts for a family directory name (e.g. AmericanTypewriter or Futura) and a name to give the groff font (see here for suggestions concerning groff font naming.) The script assumes a `~/Font` directory with subdirectories `Type1`, `TrueType` and `Groff`.

Code:
#!/bin/sh # # Converts .ttf file to .pfb and generates .afm # Moves the .afm and .pfb to $HOME/Fonts/Type1 # Generates a groff font from the .afm file and installs it # in $HOME/Fonts/Groff # Symlinks the groff font to groff's site-font/devps directory # Symlinks the .afm and .pfb to /usr/share/fonts/type1/gsfonts # FONT=`basename $1 .ttf` FONTDIR="$HOME/Fonts/TrueType" T1_FONTDIR="$HOME/Fonts/Type1" GS_FONTDIR="/usr/share/fonts/type1/gsfonts" GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps" GROFF_FONTS="$HOME/Fonts/Groff" TEXTMAP="$T1_FONTDIR/textmap" TEXTENC="$T1_FONTDIR/text.enc" echo -n "Family directory name: " read FAMILYDIR if [ ! -d "$T1_FONTDIR/$FAMILYDIR" ] ; then echo "Creating $FAMILYDIR in $T1_FONTDIR" mkdir $T1_FONTDIR/$FAMILYDIR fi echo -n "Groff name for this font: " read FONTNAME echo "Creating .pfb and .afm files from $FONT.ttf" (ttf2pt1 \-b $FONT.ttf) echo "Moving .afm and .pfb file to $T1_FONTDIR/$FAMILYDIR.." mv $FONT.afm $T1_FONTDIR/$FAMILYDIR mv $FONT.pfb $T1_FONTDIR/$FAMILYDIR echo "Changing to $T1_FONTDIR/$FAMILYDIR.." cd $T1_FONTDIR/$FAMILYDIR echo "Creating $FONTNAME.." afmtodit -e $TEXTENC $T1_FONTDIR/$FAMILYDIR/$FONT.afm $TEXTMAP $FONTNAME mv -i $FONTNAME $GROFF_FONTS echo "Linking $FONTNAME in $GROFF_SITE_FONTDIR.." sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME echo "Linking $FONT.pfb and $FONT.afm in $GS_FONTDIR.." cd $GS_FONTDIR sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.afm $FONT.afm sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.pfb $FONT.pfb echo "Font installation complete" exit 0

## Some reflections on mom

If, as Eric Raymond asserts, open source begins with a programmer scratching a personal itch, then mom can truly be called open source.

Mom had her origins in a library of groff routines I wrote over the years to handle various aspects of typesetting and document processing that weren’t adequately covered by ms, me, mm, and friends. Typically, I’d use the library to cobble together macro sets for new challenges as they came my way.

As a writer living in a perpetual state of penury, all the computers I’ve ever owned have been hand-me-downs—several generations out-of-date and resource challenged. Disk space has always been an issue, as has processor speed and available RAM. One of the reasons I run GNU/Linux rather than the offering from Redmond is that it has helped enormously to get the most out of my poor little boxes.

In Linux-land (all Unix variants, in fact), the choice of typesetting systems basically comes down to groff or TeX. Both are wonderful—monumental achievements if you ask me—and both have their own particular strengths. However, for people in my financial position (and there are millions of us around the globe, in both developed and developing countries), TeX and groff have one big difference: size. TeX is huge. Even its most ardent supporters agree it suffers from bloat, on top of being complex and unwieldy to manage. Groff is tiny by comparison, occupying minimal disk space and having only a small memory footprint while at the same time being flexible and powerful, typographically speaking. Back in the Jurassic Period, I ran it successfully on a 386 with 8 megs of RAM and a 250 meg hard disk.

However, groff has always had a liability: it’s incredibly geeky. Owing to its very long history, it—and its “power users” —seem to have remained stuck in a time warp. The canonical macro packages still look as they did back in those decades when memory was exorbitantly expensive and every byte mattered.

For some time now, groff users and macro writers have had the option to use “long” names for macros (i.e. longer than two letters, the original limit), yet have mostly chosen not to. With long names, it’s possible to create macro sets that are humanly readable and easy to interpret, encouraging development and evolution. What’s more, the macros themselves need not be terse, intimidating, and easily forgotten 1- or 2-letter commands inserted in the body of a document. They can be sensible and helpful to everyone, groff newbies and old hands alike.

Mom’s macro file, om.tmac, uses long names, aliases, and a host of other groff goodies that have become part of the whole groff picture under the unflagging guidance of groff’s current maintainer, Werner Lemberg. The function of nearly every macro, number register and string can be infered simply from its name. The file is heavily commented. A consistent, if idiosyncratic, indenting style is used as well, significantly improving readability. Anyone wanting to futz around with mom’s macros should be able to do so with a minimum of head scratching.

Addendum: As of version 1.4-a, the main macro file, om.tmac, is now stripped of comments when groff is built from sources. om.tmac in the sources themselves still contains the comments, as do the tarballs posted on mom’s homepage.

## Contact the author

If you have any questions or comments about mom, suggestions to make, criticisms to offer, or bugs to report, use the groff mailing list at groff@ffii.org (subscription information available here) or contact me, Peter Schaffter, directly at of the following address:
peter@schaffter.ca Please include the word “mom” or “groff” in the Subject: line of any message sent to my personal address, or you risk the wrath of my implacable spam filters. :)

If you want to visit mom’s website, you’ll find a link to it at
http://www.schaffter.ca The site contains links to some of my fiction, all of which was typeset with mom and groff.

Back to Table of Contents | Top | Next: Reserved words