406 lines
17 KiB
HTML
406 lines
17 KiB
HTML
<!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>What is mom?</title>
|
|
</head>
|
|
<body bgcolor="#dfdfdf">
|
|
|
|
<!====================================================================>
|
|
|
|
<a href="definitions.html#TOP">Next</a>
|
|
<a href="toc.html">Back to Table of Contents</a>
|
|
|
|
<a name="TOP"></a>
|
|
<a name="INTRO">
|
|
<h1 align="center"><u>WHAT IS MOM?</u></h1>
|
|
</a>
|
|
|
|
<a href="#INTRO_INTRO">Who is mom meant for?</a>
|
|
<br>
|
|
<a href="#INTRO_TYPESETTING">Typesetting with mom</a>
|
|
<br>
|
|
<a href="#INTRO_DOCPROCESSING">Document processing with mom</a>
|
|
<br>
|
|
<a href="#INTRO_PHILOSOPHY">Mom's philosophy</a>
|
|
<br>
|
|
<a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a>
|
|
<br>
|
|
<a href="#CANONICAL">Canonical reference materials</a>
|
|
<br>
|
|
<a href="#MACRO_ARGS">How to read macro arguments</a>
|
|
|
|
<h2><a name="INTRO_INTRO"><u>Who is mom meant for?</u></a></h2>
|
|
|
|
<strong>Mom</strong> ("my own macros", "my other
|
|
macros", "maximum overdrive macros"...) is a macro set for
|
|
groff, designed to format documents for PostScript output.
|
|
She's aimed at three kinds of users:
|
|
<br>
|
|
<ol>
|
|
<li>typesetters who suspect groff might be "the right
|
|
tool for the job" but who are
|
|
frustrated/intimidated by groff's terse, geeky,
|
|
not-always-typographically-intuitive
|
|
<a href="definitions.html#TERMS_PRIMITIVES">primitives</a>;
|
|
<br>
|
|
<li>non-scientific writers (novelists, short story writers,
|
|
journalists, students) who just want their work to
|
|
look good;
|
|
<br>
|
|
<li>newbies to computer typesetting, document processing, or
|
|
groff who need a well-documented macro set to help them get
|
|
started.
|
|
</ol>
|
|
<p>
|
|
As might be inferred from the above, <strong>mom</strong> is two macro
|
|
packages in one: a set of typesetting macros, and a set of document
|
|
processing macros. The typesetting macros govern the physical
|
|
aspects of page layout and provide sane, comprehensible control over
|
|
typographic refinements. The document processing macros let you focus
|
|
on a document's content and logical structure without worrying about
|
|
typesetting or page layout at all.
|
|
<p>
|
|
Because <strong>mom</strong> provides both typesetting and document
|
|
processing macros, it's safe to say she blurs the distinction between
|
|
document processing and document design. While her basic document style
|
|
comes with pretty spiffy defaults (okay--change "spiffy"
|
|
to "typographically professional"), you can easily control
|
|
how all the various document elements look: titles, page headers and
|
|
footers, page numbering, heads, subheads, footnotes and so on can be
|
|
made to come out exactly the way you want. And should you need precise
|
|
typographic control over elements in a document that fall outside the
|
|
range of <strong>mom</strong>'s document element tags, you don't have to
|
|
read up on groff
|
|
<a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
|
|
in order to accomplish what you want; the typesetting macros take
|
|
care of that.
|
|
<p>
|
|
|
|
<a name="INTRO_TYPESETTING">
|
|
<h2><u>Typesetting with mom</u></h2>
|
|
</a>
|
|
|
|
<strong>Mom</strong>'s typesetting macros control the basic parameters
|
|
of type: margins, line length, type family, font, point size,
|
|
linespacing, and so on. In addition, they allow you to move around
|
|
on the page horizontally and vertically, and to set up tabs, indents,
|
|
and columns. Finally, they let you adjust such typographic details as
|
|
justification style, letter spacing, word spacing, hyphenation, and
|
|
kerning.
|
|
|
|
<p>
|
|
In terms of typographic control, these macros resemble the
|
|
commands used on dedicated typesetting computers like Compugraphics and
|
|
Linotronics. Most of them simply give access to groff's typesetting
|
|
primitives in a way that's consistent and easy to use. A few of
|
|
them (tabs and indents, for example) handle fundamental typesetting
|
|
requirements in ways radically different from groff primitives.
|
|
|
|
<p>
|
|
With <strong>mom</strong>'s typesetting macros, you can, if you wish,
|
|
create individual output pages that you design from the ground up.
|
|
Provided you have not signalled to <strong>mom</strong> that you
|
|
want document processing (via the
|
|
<a href="docprocessing.html#START">START</a>
|
|
macro; see below), every macro is a literal command that remains in
|
|
effect until you modify it or turn it off. This means that if you
|
|
want to create flyers, surveys, tabulated forms, curricula vitae and
|
|
so on, you may do so in the good old-fashioned way: one step at a
|
|
time with complete control over every element on the page.
|
|
<p>
|
|
Years of reading various mailing lists dealing with computer
|
|
typesetting (groff, TeX, and friends) have convinced me that no program
|
|
can ever replace the human eye and human input when it comes to high
|
|
quality typesetting. As of this writing, a thread on the subject of
|
|
"micro typography" in groff has been going on for nearly a
|
|
month. The reason for the lengthy thread is obvious; words and
|
|
punctuation on the printed page are too variable, too fluid, to be
|
|
rendered flawlessly by any algorithm, no matter how clever. (For
|
|
whatever it's worth, a similar problem exists with engraving musical
|
|
scores by computer.)
|
|
<p>
|
|
<strong>Mom</strong> does not try to solve the problems posed
|
|
by things like hanging punctuation, left-margin adjustments for
|
|
upper case letters like T and W, and so on. She merely tries to
|
|
provide tools that allow knowledgeable typesetters to come up with
|
|
solutions to these problems in ways that are easier and more
|
|
intuitive than manipulating groff at the
|
|
<a href="definitions.html#TERMS_PRIMITIVES">primitive</a>
|
|
level. As a professional typesetter of more than two decades, and a
|
|
writer, I have encountered few situations that cannot be handled by
|
|
<strong>mom</strong>'s typesetting macros.
|
|
<p>
|
|
<strong>Author's note:</strong> One area where groff itself needs
|
|
serious rethinking is in the matter of an algorithm that takes into
|
|
account both word and letter spacing when
|
|
<a href="definitions.html#TERMS_JUST">justifying</a>
|
|
lines. At present, only word spacing is adjusted, requiring what I
|
|
consider an unnecessary amount of user intervention whenever
|
|
letter spacing is required.
|
|
<p>
|
|
<a name="INTRO_DOCPROCESSING">
|
|
<h2><u>Document processing with mom</u></h2>
|
|
</a>
|
|
|
|
<strong>Mom</strong>'s document processing macros let you format
|
|
documents without having to worry about the typographic details.
|
|
In this respect, <strong>mom</strong> is similar to other groff macro
|
|
packages, as well as to html and LaTeX. Where <strong>mom</strong>
|
|
differs is in the degree of control you have over the look and
|
|
placement of the various elements of a document. For example, if you
|
|
don't want your heads underlined, or you want them bigger/smaller,
|
|
or you'd prefer them to be in a different font, or you'd rather they
|
|
were flush left instead of centred, you can make the changes easily
|
|
and have them apply to the whole document. Temporary and one-off
|
|
changes are easy, too.
|
|
<p>
|
|
<strong>Mom</strong> has some nifty features other macro sets
|
|
don't provide. For example, you can switch between draft-style and
|
|
final-copy output. If you regularly make submissions to publishers
|
|
and editors who insist on "typewritten, double-spaced," there's a
|
|
special macro--
|
|
<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
|
|
--that changes typeset documents into ones that would make your
|
|
high-school typing teacher proud. Footnotes, endnotes, tables of
|
|
contents, multiple columns, nested lists, recto/verso printing and
|
|
user designable headers and footers are also part of the fun.
|
|
<p>
|
|
<a name="INTRO_PHILOSOPHY">
|
|
<h2><u>Mom's philosophy</u></h2>
|
|
</a>
|
|
|
|
Formatting documents should be easy, from soup to nuts. Writers need
|
|
to focus on what they're writing, not on how it looks. From the
|
|
moment you fire up an editor to the moment you add "FINIS"
|
|
to your opus, nothing should interfere with the flow of your words.
|
|
The commands needed to format your work should be easy to remember,
|
|
comprehensible, and stand out well from the text. There shouldn't
|
|
be too much clutter. Your documents should be as readable inside a
|
|
text editor as they are on the printed page.
|
|
<p>
|
|
Unfortunately, in computerland, "easy,"
|
|
"comprehensible," and "readable" often mean
|
|
"you're stuck with what you get." No document formatting
|
|
system can give you exactly what you want all the time, every time.
|
|
Documents, it seems, always need to be tweaked, either to satisfy a
|
|
typographic whim or to clarify some aspect of their content.
|
|
<p>
|
|
Groff has traditionally solved the problem of formatting vs. tweaking
|
|
by requiring users of the common macro packages (mm, ms, me and their
|
|
offspring) to resort to groff
|
|
<a href="definitions.html#TERMS_PRIMITIVES">primitives</a>
|
|
and
|
|
<a href="definitions.html#TERMS_INLINES">inline escapes</a>
|
|
for their special typesetting needs. Not to put too fine a point on
|
|
it, groff primitives tend toward the abstruse, and most inline escapes
|
|
are about as readable in-line as an encrypted password. This does
|
|
not make for happy-camper writers, who either find themselves stuck
|
|
with a document formatting style they don't really like, or are
|
|
forced to learn groff from the ground up--a daunting task, to say
|
|
the least.
|
|
<p>
|
|
<strong>Mom</strong> aims to make creating documents a simple matter,
|
|
but with no corresponding loss of user control. The document
|
|
processing macros provide an excellent set of defaults, but if
|
|
something is not to your liking, you can change it. And in combination
|
|
with the typesetting macros, you have all the tools you need to
|
|
massage passages and tweak pages until they look utterly professional.
|
|
<p>
|
|
One rarely hears the word "user interface" in conjunction
|
|
with document processing. Since the user formatting takes place
|
|
inside a text editor, little thought is given to the look and feel
|
|
of the formatting commands. <strong>Mom</strong> attempts to rectify
|
|
this by providing users with a consistent, readable "coding"
|
|
style. Most of the macros (especially in the document processing set)
|
|
have humanly-readable names. Not only does this speed up learning
|
|
the macros, it makes the sense of what's going on in a document,
|
|
typographically and structurally, easier to decipher.
|
|
<p>
|
|
<strong>Mom</strong> does not try to be all things to all people.
|
|
In contrast to the normal groff philosophy, she does not try to
|
|
produce output that looks good no matter where it's displayed.
|
|
She's designed for printed output, although with
|
|
<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>
|
|
she produces acceptable terminal copy. She makes no attempt to be
|
|
compatible with older versions of troff.
|
|
<p>
|
|
One special feature in <strong>mom</strong>'s design is the attention
|
|
she pays to aligning the bottom margins of every page. Nothing screams
|
|
"shoddy" in typeset documents louder than bottom margins
|
|
that wander, or, in typesetter jargon, "hang." There are,
|
|
of course, situations where whitespace at the bottom of a page may
|
|
be desirable (for example, you wouldn't want a head to appear at the
|
|
bottom of the page without some text underneath it), but in all cases
|
|
where hanging bottom margins can be avoided, <strong>mom</strong> does
|
|
avoid them, by clever adjustments to leading ("line spacing")
|
|
and the spacing between different elements on the page.
|
|
<p>
|
|
<a name="INTRO_DOCUMENTATION">
|
|
<h2><u>A note on mom's documentation</u></h2>
|
|
</a>
|
|
|
|
Writing documentation is tough, no doubt about it. One is never
|
|
quite sure of the user's level of expertise. Is s/he new to the
|
|
application, new to its underlying protocols and programs, new to
|
|
the operating system, new to computers? At some point, one has to
|
|
decide who the documentation is for. Making the wrong decision can
|
|
mean the difference between a program that gets used and a program
|
|
that gets tossed.
|
|
<p>
|
|
<strong>Mom</strong>'s documentation assumes users know their way
|
|
around GNU/Linux. It further assumes they at least know what groff
|
|
is, even if they don't know much about it. Lastly, it assumes that
|
|
everyone--groff newbies and experts alike--learns faster from
|
|
a few well-placed examples than from manpage-style reference docs.
|
|
What <strong>mom</strong>'s documentation doesn't assume is that
|
|
you know everything--not about groff, not about typesetting,
|
|
not about document processing. Even experts have odd lacunae in
|
|
their knowledge base. Therefore, whenever I suspect that a term
|
|
or procedure will cause head scratching, I offer an explanation.
|
|
And when explanations aren't enough, I offer examples.
|
|
<br>
|
|
|
|
<a name="CANONICAL"><h3><u>Canonical reference materials</u></h3></a>
|
|
<p>
|
|
The canonical reference materials for groff are
|
|
<strong>cstr54</strong> (a downloadable PostScript copy of which is
|
|
available
|
|
<a href="http://www.kohala.com/start/troff/">here</a>)
|
|
and the <strong>troff</strong> and <strong>groff_diff</strong>
|
|
manpages. Another excellent source of information (maybe the best)
|
|
is the groff <strong>info</strong> pages, available by typing
|
|
<p>
|
|
<pre>
|
|
info groff
|
|
</pre>
|
|
|
|
at the command line (assuming you have <strong>info</strong>
|
|
installed on your system). And for inputting special characters,
|
|
see <strong>man groff_char.</strong>
|
|
<p>
|
|
I've tried to avoid reiterating the information contained in these
|
|
documents; however, in a few places, this has proved impossible.
|
|
But be forewarned: I have no qualms about sidestepping excruciating
|
|
completeness concerning groff usage; I'm more interested in getting
|
|
<strong>mom</strong> users up and running. <em>Mea culpa.</em>
|
|
<p>
|
|
<strong>Note:</strong> <strong>Mom</strong>'s macro file
|
|
(om.tmac) is heavily commented. Each macro is preceded by a
|
|
description of its arguments, function and usage, which may
|
|
give you information in addition to what's contained in this
|
|
documentation.
|
|
<p>
|
|
<a name="MACRO_ARGS">
|
|
<h3><u>How to read macro arguments</u></h3>
|
|
</a>
|
|
|
|
The concise descriptions of macros in this documentation typically
|
|
look like this:
|
|
<blockquote>
|
|
Macro: <strong>NAME</strong> <nobr>arguments</nobr>
|
|
</blockquote>
|
|
<var>arguments</var> lists the macro's arguments using conventions that
|
|
should be familiar to anyone who has ever read a manpage. Briefly:
|
|
<p>
|
|
<ol>
|
|
<li>Macro arguments are separated from each other by spaces.
|
|
<li>If an argument is surrounded by chevrons
|
|
( < > ), it's a description of the argument,
|
|
not the argument itself.
|
|
<li>If an argument begins with or is surrounded by double-quotes, the
|
|
double quotes MUST be included in the argument.
|
|
<li>If the user has a choice between several arguments, each of the
|
|
choices is separated by the pipe character ( | ),
|
|
which means "or."
|
|
<li>Arguments that are optional are surrounded by square brackets.
|
|
<li><off> in an argument list means that any argument
|
|
other than those in the argument list turns the macro off.
|
|
</ol>
|
|
|
|
<a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a>
|
|
<p>
|
|
Some macros don't require an argument. They simply start something.
|
|
When you need to turn them off, the same macro with <em>any</em>
|
|
argument will do the trick. That's right: ANY argument. This permits
|
|
choosing whatever works for you: OFF, END, QUIT, DONE, Q, X... Hell,
|
|
it could even be I_LOVE_MOM.
|
|
<p>
|
|
Since these macros toggle things on and off, the argument list
|
|
simply reads
|
|
<blockquote>
|
|
<nobr>toggle</nobr>
|
|
</blockquote>
|
|
<br>
|
|
<hr>
|
|
|
|
<h3>Example 1: an argument requiring double-quotes</h3>
|
|
<blockquote>
|
|
Macro: <strong>TITLE</strong> <nobr>"<title of document>"</nobr>
|
|
</blockquote>
|
|
<p>
|
|
The required argument to <strong>TITLE</strong> is the title of your
|
|
document. Since it's surrounded by double-quotes, you must
|
|
include them in the argument, like this:
|
|
<p>
|
|
<pre>
|
|
.TITLE "My Pulitzer Novel"
|
|
</pre>
|
|
|
|
<h3>Example 2: a macro with required and optional arguments</h3>
|
|
<blockquote>
|
|
Macro: <strong>TAB_SET</strong> <nobr><tab #> <indent> <length> [ L | R | C | J [ QUAD ] ]</nobr>
|
|
</blockquote>
|
|
<p>
|
|
The first required argument is a number that identifies the tab (say,
|
|
"3"). The second required argument is an indent from the left margin
|
|
(say, 6 picas). The third required argument is the length of the tab
|
|
(say, 3 picas). Therefore, at a minimum, when using this macro,
|
|
you would enter:
|
|
<p>
|
|
<pre>
|
|
.TAB_SET 3 6P 3P
|
|
</pre>
|
|
|
|
The remaining two arguments are optional. The first is a single
|
|
letter, either L, R, C or J. The second, which is itself optional
|
|
after L, R, C or J, is the word QUAD. Therefore, depending on
|
|
what additional information you wish to pass to the macro,
|
|
you could enter:
|
|
<p>
|
|
<pre>
|
|
.TAB_SET 3 6P 3P L
|
|
or
|
|
.TAB_SET 3 6P 3P L QUAD
|
|
</pre>
|
|
|
|
<a name="TOGGLE_EXAMPLE"></a>
|
|
<h3>Example 3: a sample toggle macro:</h3>
|
|
<blockquote>
|
|
Macro: <strong>QUOTE</strong> <nobr>toggle</nobr>
|
|
</blockquote>
|
|
<p>
|
|
<strong>QUOTE</strong> begins a section of quoted text in a document
|
|
and doesn't require an argument. When the quote's finished,
|
|
you have to tell <strong>mom</strong> it's done.
|
|
<p>
|
|
<pre>
|
|
.QUOTE
|
|
So runs my dream, but what am I?
|
|
An infant crying in the night
|
|
An infant crying for the light
|
|
And with no language but a cry.
|
|
.QUOTE OFF
|
|
</pre>
|
|
|
|
Alternatively, you could have turned the quote off with END, or
|
|
X, or something else.
|
|
|
|
<p>
|
|
<hr>
|
|
<a href="definitions.html#TOP">Next</a>
|
|
<a href="#TOP">Top</a>
|
|
<a href="toc.html">Table of Contents</a>
|
|
</body>
|
|
</html>
|