1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Mom -- Appendices</title>
</head>
<body bgcolor="#dfdfdf">
<!====================================================================>
<a href="typemacdoc.html#TOP">Prev</a>
<a href="toc.html">Back to Table of Contents</a>
<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="#CODENOTES">Some reflections on mom, with an apology</a>
<li><a href="reserved.html">List of reserved words</a>
<li><a href="#CONTACT">Contact the author</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 leaveing 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, or Netscape, their browser
needs to be one that's fast and light -- Lynx, in other words.
<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: Lynx. People who, for whatever reason (choice
or necessity), use Lynx 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 documenation easier to
write, but would have excluded Lynx-only users. And it goes
without saying that the documentation looks fine if you're
reading it in a graphical browser.
<br>
<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 perpeptual 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 Linux is that it has helped enormously to
get the most out of my poor little boxes.
<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
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>
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 "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 <strong>mom</strong>'s macros should be
able to do so with a minimum of head scratching.
<p>
To all you groff-jocks out there who love the aracana of
groff-as-it-used-to-be, I apologise. To everyone else, I simply say:
Welcome, and enjoy.
<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
<p>
<address align="center">
<a href="mailto:df191@ncf.ca">df191@ncf.ca</a>
</address>
<p>
<hr>
<a href="typemacdoc.html#TOP">Prev</a>
<a href="#TOP">Top</a>
<a href="toc.html">Back to Table of Contents</a>
</body>
</html>
|
