<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Mom -- Appendices</title>
</head>
<body bgcolor="#dfdfdf">
<!====================================================================>
<a href="reserved.html#TOP">Next</a>
<a href="macrolist.html#TOP">Prev</a>
<a href="toc.html">Back to Table of Contents</a>
<p>
<a name="TOP"></a>
<a name="APPENDICES">
<h2 align="center"><u>APPENDICES</u></h2>
</a>
<ul>
<li><a href="#MOREDOC">Further notes on this documentation</a>
<li><a href="#FONTS">Adding PostScript fonts to groff</a>
<ul>
<li><a href="#HOWTO">How to create a PostScript font for use with groff</a>
</ul>
<li><a href="#CODENOTES">Some reflections on mom, with an apology</a>
<li><a href="#CONTACT">Contact the author</a>
<li><a href="reserved.html">List of reserved words</a>
</ul>
<a name="MOREDOC">
<h2><u>Further notes on this documentation</u></h2>
</a>
Some <strong>mom</strong> users are sure to ask: "Why is this
documentation in html? If <strong>mom</strong>'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?"
<p>
Valid questions, to be sure, and <strong>mom</strong> has
answers. (Okay -- I have answers, but I speak for
<strong>mom</strong>.)
<p>
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.
<p>
To me, it's essential that people reading <strong>mom</strong>'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.
<p>
Another reason for html is that working with <strong>mom</strong>
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 <strong>mom</strong>,
but I still regularly call on her documentation. Elvis, with its
html capabilities, lets me write and format <strong>mom</strong>
documents AND peruse her documentation, clicking on links as
necessary, without ever leaving the comfy confines of my
text editor.
<p>
Not everyone, of course, uses an editor with html capabilities.
For them, firing up a browser is obviously necessary for reading
<strong>mom</strong>'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".
<p>
Some <strong>mom</strong> 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 <strong>mom</strong> 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.
<br>
<hr>
<!=====================================================================>
<a name="FONTS">
<h2><u>Adding PostScript fonts to groff</u></h2>
</a>
<a name="SMALL_NOTE"></a>
<em><strong>Small note:</strong> 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/<versionfrom source).</em>
<p>
Groff comes with a small library of PostScript
<a href="definitions.html#TERMS_FAMILY">families</a>
(see the
<a href="typesetting.html#FAMILY">FAMILY</a>
macro for a list). The families have four
<a href="definitions.html#TERMS_FONT">fonts</a>
associated with them. These fonts are a combination of
<a href="definitions.html#TERMS_WEIGHT">weight</a>
and
<a href="definitions.html#TERMS_SHAPE">shape</a>:
<br>
<ul>
<li><strong>R</strong> (Roman, usually Medium weight),
<li><strong>I</strong> (Italic, usually Medium weight),
<li><strong>B</strong> (Bold, usually Roman shape) and
<li><strong>BI</strong> (Bold Italic).
</ul>
<p>
If you do a lot of document processing or typesetting with
<strong>mom</strong>, 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.
<p>
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.
<p>
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 <strong>R,
I, B</strong> and <strong>BI</strong> 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).
<p>
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 <a
href="definitions.html#TERMS_WEIGHT">weights</a> Helvetica Thin,
Helvetic Light, Helvetica Regular, Helvetica Bold, Helvetica Heavy,
etc, and all their associated
<a href="definitions.html#TERMS_SHAPE">shapes</a>
(Roman,
Italic, Condensed, Narrow, Extended, Outline, etc).
<p>
Thus, intuitively, when a typesetter gives <strong>mom</strong> a
<kbd>.FAM(ILY)</kbd> directive, s/he reasonably expects that any
subsequent <kbd>.FT</kbd> directive will access the desired font
from the Helvetica family--without the need to state explicitly both
family and font to <kbd>.FT</kbd>, as it is explained one can do in
the
<a href="typesetting.html#FAMILY">FAMILY</a>
and
<a href="typesetting.html#FONT">FT</a>
sections of these documents.
<p>
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 <kbd>.FAM(ILY)</kbd>) and selecting the
desired font (with <kbd>.FT R</kbd> or <kbd>.FT I</kbd>), or
passing <kbd>.FT</kbd> the lengthy family+fontname (.e.g. <kbd>.FT
HLCDI</kbd>).
<p>
Fortunately, groff provides a mechanism whereby it's possible to
extend the basic <strong>R, I, B</strong> and <strong>BI</strong>
fonts ("styles" in groff-speak) so that one can, in
fact, create extensive type families, and access all the fonts
in them with <kbd>.ft</kbd> (groff) or <kbd>.FT</kbd> (mom).
<p>
<strong>mom</strong> uses this mechanism to offer, in addition to
groff's default PostScript font styles, the following:
<p>
<a name="STYLE_EXTENSIONS"></a>
<pre>
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
</pre>
Thus, with <strong>mom</strong>, 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
<p>
<pre>
.FAMILY H
or
.FAM H
</pre>
you can access any of those Helvetica fonts simply by
passing the correct argument from the list above to
<a href="typesetting.html#FONT">FT</a>.
<p>
For example, if you were working in Medium Roman (<kbd>.FT R</kbd>)
and you needed Medium Condensed Italic for a while (assuming it's
installed), you'd just type
<p>
<pre>
.FT CDI
</pre>
to access the Medium Condensed Italic font from the Helvetica
family.
<p>
<strong>Mom</strong>'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.
<p>
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).
<a name="REGISTER_STYLE"></a>
<p>
However, you may, at needs, want to add to <strong>mom</strong>'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
<p>
<pre>
.sty \n[.fp] L \" Light Roman
.sty \n[.fp] LI \" Light Italic
.sty \n[.fp] LCD \" Light Condensed Roman
</pre>
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
<a href="<p>
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
<p>
<pre>
.sty \n[.fp] BO \" Bold Outline
</pre>
to the <kbd>.sty \n[.fp] <font style></kbd> list in om.tmac.
<p>
Be careful, though, that any styles you add do not conflict
with <strong><u>family</u></strong> 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 <kbd>.FT C</kbd> would give you access to font style
once you'd given a <kbd>.FAM(ILY)</kbd> directive, you'd get a nasty
surprise: your type would come out in Courier Roman!
<p>
<strong>VERY IMPORTANT NOTE: mom</strong>'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 <strong>mom</strong>'s font extensions
conflict with your own scheme. Should that be the case, comment out
the <kbd>.sty \n[.fp] <font style></kbd> lines found near the
top of the om.tmac file.
<a name="HOWTO"><h3><u>How to create a PostScript font for use with groff</u></h3></a>
These instructions aren't meant to cover all possibilities, merely
to present one way of making PostScript families/fonts available to
groff and <strong>mom</strong>.
<p>
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.
<p>
What you need before you start:
<br>
<ul>
<li>groff, version 1.18 or higher
<br>
(Debian package: groff)
<li>a full installation of gs and associated tools
<br>
(Debian package: gs or gs-gpl)
<li>a library of gs fonts
<br>
(Debian package: gsfonts)
<li>a utility for converting TrueType fonts to Type1 fonts
<br>
(Debian package: ttf2pt1)
<li>a font manager
<br>
(Debian packages: defoma, psfontmgr, dfontmgr)
<li>perl
<br>
(Debian package: perl)
</ul>
<br>
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.
<p>
Initial preparation (you only have to do this once):
<br>
<ol>
<li>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.
<a name="SITE-FONT"></a>
<li>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
<br>
<ul>
<li>/usr/share/groff,
<li>/usr/local/share/groff
<li>/etc/groff
</ul>
<p>
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.
<li>Locate the file <kbd><prefix>/font/devps/generate/textmap</kbd>
and symlink it to <kbd>textmap</kbd> in the directory that
contains your personal collection of PostScript fonts. (See the
<a href=" above, for the meaning of <prefix>). On my system,
at the time of writing, <prefix> is
/usr/local/share/groff/1.19.2/, therefore, I symlink it in
~/Fonts/Type1 with
<br>
<pre>
ln -s /usr/local/share/groff/1.19.2/font/devps/generate/textmap textmap
</pre>
<li>Locate the file <prefix>/font/devps/text.enc and
symlink it to <kbd>text.enc</kbd> in your personal font
directory. On my system, in ~/Fonts/Type1
<pre>
ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc
</pre>
<li>Make sure you know which directory/ies holds your gs fonts.
You'll need the information later. On a Debian box, some
typical locations are
<br>
<ul>
<li>/usr/lib/ghostscript/fonts
<li>/usr/share/ghostscript/fonts
<li>/usr/share/fonts/type1/gsfonts
</ul>
</ol>
<br>
Font creation/installation:
<br>
<ol>
<li>Acquire the font in either Type1 (.pfb) or TrueType
(.ttf) format.
<li>Place the font in your personal font directory; for me,
that's ~/Fonts/Type1 or ~/Fonts/TrueType.
<li>In your personal font directory, run one of the following:
<br>
<ul>
<li>For Type1 fonts
<br>
<ul>
<li><kbd>getafm fontfilename.pfb | gsnd - > fontfilename.afm</kbd>
<br>
For Type1 fonts, this will generate something called
an .afm (Adobe Font Metrics) file, which is
required to create PostScript fonts for groff.
</ul>
<li>For TrueType fonts
<br>
<ul>
<li><kbd>ttf2pt1 \-b fontfilename.ttf</kbd>
<br>
For TrueType fonts, this will generate a PostScript
.pfb file as well as an .afm file.
</ul>
</ul>
<li>Still in your personal font directory, run
<br>
<ul>
<li><kbd>afmtodit -e text.enc fontfilename.afm textmap GROFF_FONTNAME</kbd>
</ul>
<p>
Q: <em>How do I choose a GROFF_FONTNAME?</em>
<p>
A: Start by considering the
<a href="definitions.html#TERMS_FAMILY">family</a>
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
<a href="typesetting.html#FAMILY">here</a>
for a list of families already installed, along with their groff
names.) Add to that name the appropriate weight/style extension,
listed
<a href="#STYLE_EXTENSIONS">here</a>.
<p>
For example, if you're adding Helvetica Light Roman, your
GROFF_FONTNAME would be <strong>HL</strong>. If you're
adding Helvetica Light Italic, your GROFF_FONTNAME would be
<strong>HLI</strong>.
<p>
If you're adding a font not already in groff's PostScript
families, first choose a meaningful name for the
<a name="definitions.html#TERMS_FAMILY">family</a>
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 <strong>GD</strong>
as the family name for Garamond, your GROFF_FONTNAME would be
<strong>GDBCDI</strong>.
<p>
In <strong>mom</strong>, you can then access the Garamond
family with <kbd>.FAM GD</kbd>, and the Bold Condensed
Italic font wth <kbd>.FT BCDI</kbd>.
<p>
<strong>Note:</strong> 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
<a href="#SITE-FONT">site-font directory</a>,
something like GaramondBCDI will be more meaningful than,
say, GDBCDI.
<li>Copy or move GROFF_FONTNAME to your
<a href="#SITE-FONT">site-font directory</a>,
or change to the site-font directory and make a symlink to
GROFF_FONTNAME in your personal directory.
<li>Copy or move the .pfb file to the directory that
holds your gs fonts, or change to that directory and make a
symlink to the .pfb file in your personal directory.
<li>Do whatever your system or distro requires in order to
register the new PostScript font (the .pfb file). On a
Debian system, as root, you can run dfontmgr for a
graphical interface that will take care of registering the
font.
</ol>
<p>
Written out in full, adding fonts looks like a lot of work. It
isn't. Basically, it's just:
<br>
<ul>
<li>acquire the font
<li>generate an .afm file for the font
<li>create the groff font
<li>put the groff font in <prefix>/font/devps
<li>make sure gs knows about the font
</ul>
<br>
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.
<p>
<pre>
#! /bin/bash
FONT=`basename $1 .pfb`
FONTDIR="$HOME/Fonts/Type1"
GS_FONTDIR="/usr/lib/ghostscript/fonts"
GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps"
GROFF_FONTS="$HOME/Fonts/Groff"
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
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
</pre>
<hr>
<!=====================================================================>
<a name="CODENOTES">
<h2><u>Some reflections on mom</u></h2>
</a>
<p>
<strong>Mom</strong>, 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.
<p>
If, as Eric Raymond asserts, open source begins with a programmer
scratching a personal itch, then <strong>mom</strong> 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.
<p>
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.)
<p>
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.
<p>
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.
<p>
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.
<p>
(ADDENDUM to the previous two paragraphs: A tremendous amount of
effort has gone into creating a groff manual that can be read with
"info," 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.)
<p>
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.
<p>
<strong>Mom</strong>'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 "recognizable" 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 <strong>mom</strong>'s macros should be
able to do so with a minimum of head scratching.
<br>
<hr>
<!=====================================================================>
<a name="CONTACT">
<h2><u>Contact the author</u></h2>
</a>
<p>
If you have any questions or comments about <strong>mom</strong>,
suggestions to make, criticisms to offer, or bugs to report, use the
groff mailing list at
<a href="mailto:groff@ffii.org">groff@ffii.org</a>
(subscription information available
<a href="http://ffii.org/mailman/listinfo/groff/">here</a>)
or contact me, Peter Schaffter, directly at
<i>&or
<i>&
<p>
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. :)
<p>
If you want to visit <strong>mom</strong>'s homepage, you'll find
it
<a href="http://faustus.dyn.ca/mom/mom.html">here</a>.
<p>
<hr>
<a href="reserved.html#TOP">Next</a>
<a href="macrolist.html#TOP">Prev</a>
<a href="#TOP">Top</a>
<a href="toc.html">Back to Table of Contents</a>
</body>
</html>