Next Prev Back to Table of Contents
Some mom users are sure to ask: "Why is this documentation in html? If mom's so great, why not typeset the whole thing 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.
To me, 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.
Another reason for html is that working with mom necessarily involves creating files inside a text editor. I use elvis, a truly fabulous vi clone that does a terrific job of rendering basic (text only) html. I may have written mom, but I still regularly call on her documentation. Elvis, with its html capabilities, lets me write and format mom documents AND peruse her documentation, clicking on links as necessary, without ever leaving the comfy confines of my text editor.
Not everyone, of course, uses an editor with html capabilities. For them, firing up a browser is obviously necessary for reading mom's documentation. Browsers being what they are, and not everyone on the globe having the cash for muscle machines to run Galeon, or Konqueror or Mozilla, their browser needs to be fast and light — and probably "text-only".
Some mom users may notice the absence of graphics, frames, and (for the most part) tables in this documentation. The reason is simple: text-only browsers. People who, for whatever reason (choice or necessity), use lynx, or links or w3m to read the documentation must be able to make sense of it. All of it. Graphical examples of mom in action might have made some parts of the documentation easier to write, but would have excluded text-only browser users. And it goes without saying that the documentation looks fine if you're reading it in a graphical browser.
Robert Valiant has set up a web page containing information, instructions and strategies for adding PostScript and TrueType fonts to groff. The page is directed at Debian GNU/Linux users, but knowledgable users of other GNU/Linux distributions should have no difficulty adapting it to their needs. The site is located at
http://russia.shaps.hawaii.edu/software/software.html
Small 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 do a lot of document processing or typesetting with mom, 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
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) 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 traditional 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
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:
Mom's extensions to groff's basic font styles
=============================================
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 FS (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 from the list above to
FT.
For example, if you were working in Medium Roman
.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. 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 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
Be careful, though, 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
VERY IMPORTANT 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
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.
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.
ln -s /usr/local/share/groff/1.19.2/font/devps/generate/textmap textmap
ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc
Written out in full, adding fonts looks like a lot of work. It isn't. Basically, it's just:
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 requires an argument (the .pfb filename), then prompts for the GROFF_FONTNAME.
#!/bin/bash
#
# A script for installing Type1 fonts.
#
# Builds .afm files from .pfb files, generates a groff font from the
# .afm file, makes a symlink in /usr/lib/ghostscript/font/ to the
# .pfb file, and a symlink in site-font to the groff font
#
# .pfb filename, stripped of .pfb extension
FONT=`basename $1 .pfb`
# Directory holding my personal collection of type1 fonts
FONTDIR="$HOME/Fonts/Type1"
# Directory holding system ghostscript fonts
GS_FONTDIR="/usr/lib/ghostscript/fonts"
# Location of site-font/devps
GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps"
# Personal groff fonts directory
GROFF_FONTS="$HOME/Fonts/Groff"
# Symlinks to textmap and text.enc
TEXTMAP="$FONTDIR/textmap"
TEXTENC="$FONTDIR/text.enc"
if [ ! `pwd` = "$FONTDIR" ] ; then
echo "Changing into $FONTDIR directory.."
cd $FONTDIR
sleep 1
else
sleep 1
fi
echo -n "Groff name for this font: "
read FONTNAME
sleep 1
echo "Getting .afm.."
getafm $FONT.pfb | gsnd - > $FONT.afm
sleep 1
echo "Creating $FONTNAME.."
afmtodit -e $TEXTENC $FONTDIR/$FONT.afm $TEXTMAP $FONTNAME
mv -i $FONTNAME $GROFF_FONTS
sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME
sleep 1
echo "Linking $FONT in $GS_FONTDIR.."
cd $GS_FONTDIR
sudo ln -s $FONTDIR/$FONT.afm $FONT.afm
sudo ln -s $FONTDIR/$FONT.pfb $FONT.pfb
sleep 1
# This next bit is Debian specific. If you're not running a
# Debian system, replace it with whatever your distro requires
# in order to register Type1 fonts.
if [ !`pidof -x /usr/bin/dfontmgr` ] ; then
echo "I will now run dfontmgr so you can register the font."
exec sudo dfontmgr &
else
echo "You may now register the font with dfontmgr."
fi
Mom, as a complete macro set, 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 so on. Typically, I'd use the library to cobble together macro sets for new challenges as they came my way.
If, as Eric Raymond asserts, open source begins with a programmer scratching a personal itch, then mom can truly be called open source, even if, a mere humble set of macros standing on the shoulders of a giant named troff, she isn't programming at all.
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 is that it has helped enormously to get the most out of my poor little boxes. (It has been pointed out to me that NetBSD might be an even better choice of operating systems for computers with limited resources.)
In Linux-land, 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. I've run 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" — have remained stuck in a time warp. Most common macro packages still look as they did in those decades when memory was exorbitantly expensive and every byte mattered. Documentation — not always easy to find — is written as if all readers are computer whizzes, or at least have a university degree in one of the higher sciences.
By no means a stupid man, nor unfamiliar with the precepts of programming, I've more than once torn my hair out over the terseness and ambiguity of groff's documentation. Making sense of certain primitives has often involved days of testing, interpreting the documentation instead of just using the primitive.
(ADDENDUM to the previous two paragraphs: A tremendous amount of effort has gone into creating a groff manual that can be read with the info browser, as well as creating truly useful man pages. The info manual is clear and well-written, so my comments are actually out of date. I leave them in for the benefit of groff newbies, who may still find the documents a bit intimidating.)
For some time now, groff users and macro writers have had the option to use "long" names, 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. Nearly every macro, number register and string is "recognisable" simply by 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.
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:
pschaffter@magma.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 homepage, you'll find it at
http://gretchen.homelinux.org/mom/mom.html.