487 lines
18 KiB
HTML
487 lines
18 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!--
|
|
This file is part of groff, the GNU roff type-setting system.
|
|
|
|
Copyright (C) 2004-2020 Free Software Foundation, Inc.
|
|
Written by Peter Schaffter (peter@schaffter.ca).
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
|
Texts.
|
|
|
|
A copy of the Free Documentation License is included as a file called
|
|
FDL in the main directory of the groff source package.
|
|
-->
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html;charset=utf-8"/>
|
|
<title>What is mom?</title>
|
|
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
|
|
</head>
|
|
|
|
<body style="background-color: #f5faff;">
|
|
|
|
<!-- ==================================================================== -->
|
|
|
|
<div id="top" class="page">
|
|
|
|
<!-- Navigation links -->
|
|
<table style="width: 100%;">
|
|
<tr>
|
|
<td><a href="toc.html">Back to Table of Contents</a></td>
|
|
<td style="text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h1 id="intro" class="docs">What is mom?</h1>
|
|
|
|
<div style="text-align: center;">
|
|
<ul class="no-enumerator" style="margin-left: -2.5em;">
|
|
<li ><a href="#intro-intro">Who is mom meant for?</a></li>
|
|
<li ><a href="#intro-typesetting">Typesetting with mom</a></li>
|
|
<li ><a href="#intro-docprocessing">Document processing with mom</a></li>
|
|
<li ><a href="#intro-philosophy">Mom’s philosophy</a></li>
|
|
<li ><a href="#intro-documentation">A note on mom’s documentation</a></li>
|
|
<li ><a href="#canonical">Canonical reference materials</a></li>
|
|
<li ><a href="#macro-args">How to read macro arguments</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="rule-short" style="margin-top: 18px;"><hr/></div>
|
|
|
|
<h2 id="intro-intro" class="docs">Who is mom meant for?</h2>
|
|
|
|
<p>
|
|
Mom (“my own macros”, “my other macros”,
|
|
“maximum overdrive macros”...) is a macro set for groff,
|
|
designed to format documents in Portable Document Format (.pdf) and
|
|
PostScript (.ps). She’s aimed at three kinds of users:
|
|
</p>
|
|
|
|
<ol style="margin-top: -.5em; margin-bottom: -.5em;">
|
|
<li>Typesetters who suspect groff might be the right
|
|
tool for the job but who are frustrated,
|
|
intimidated, or puzzled by groff’s terse,
|
|
not-always-typographically-intuitive
|
|
<a href="definitions.html#primitives">primitives</a>;
|
|
</li>
|
|
<li>Writers who need to format their work easily, with a
|
|
minimum of clutter;
|
|
</li>
|
|
<li>Newcomers to groff, typesetting, or document processing
|
|
who need a well-documented macro set to get them started.
|
|
</li>
|
|
</ol>
|
|
|
|
<p>
|
|
Mom is actually two macro packages in one: a very complete set
|
|
of typesetting macros, and an equally thorough set of document
|
|
formatting macros. The typesetting macros afford fine-grained
|
|
control over all visible aspects of page layout and design (margins,
|
|
fonts, sizes, kerning, etc), while the document formatting macros
|
|
focus on the logical structure of a document (titles, headings,
|
|
paragraphs, lists, etc) and call on groff to render logical
|
|
structure into pleasing type.
|
|
</p>
|
|
|
|
<h2 id="intro-typesetting" class="docs">Typesetting with mom</h2>
|
|
|
|
<p>
|
|
Mom’s typesetting macros control the basic parameters
|
|
of type: margins, line lengths, 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>
|
|
|
|
<p>
|
|
The typesetting macros also provide the means to create horizontal
|
|
and vertical rules, rectangles (boxes, frames), and ellipses
|
|
(circles).
|
|
</p>
|
|
|
|
<p>
|
|
In terms of typographic control, the typesetting macros provide
|
|
access to groff’s primitives in a way that’s consistent,
|
|
sensible, and easy to use. With them, you can create individual
|
|
pages designed from the ground up. Provided you have not signalled
|
|
to mom that you want document processing (via the
|
|
<a href="docprocessing.html#start">START</a>
|
|
macro; see below), every typesetting 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>
|
|
|
|
<p>
|
|
Years of experience have convinced me that no program can ever
|
|
replace the human eye and human input when it comes to high quality
|
|
typesetting. Words and punctuation on the printed page are too
|
|
variable, too fluid, to be rendered flawlessly by any algorithm,
|
|
no matter how clever.
|
|
</p>
|
|
|
|
<p>
|
|
Mom, therefore, does not try to guess solutions for issues like
|
|
hanging punctuation, or left-margin adjustments for troublesome
|
|
letters like T, V and W. Rather, she provides tools that allow
|
|
knowledgeable typesetters to handle these typographic challenges in
|
|
ways that are easier and more intuitive than manipulating groff at
|
|
the primitive level.
|
|
</p>
|
|
|
|
<h2 id="intro-docprocessing" class="docs">Document processing with mom</h2>
|
|
|
|
<p>
|
|
Mom’s document processing macros let you format documents
|
|
without having to worry about the typographic details. In this
|
|
respect, mom is similar to other groff macro packages, as well as
|
|
to html and LaTeX. Where mom 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’d like your headings underlined,
|
|
or in caps, or centred rather than flush left, you can make the
|
|
changes easily and have them apply to the whole document. Temporary
|
|
and one-off changes are easy, too.
|
|
</p>
|
|
|
|
<p>
|
|
Mom has some 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 <kbd>TYPEWRITE</kbd></a>—
|
|
that changes typeset documents into ones that would make an
|
|
old-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>
|
|
|
|
<h2 id="intro-philosophy" class="docs">Mom’s philosophy</h2>
|
|
|
|
<p>
|
|
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>
|
|
|
|
<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 always need to be tweaked, either
|
|
to satisfy a typographic whim or to clarify some aspect of their
|
|
content.
|
|
</p>
|
|
|
|
<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#primitives">primitives</a>
|
|
and
|
|
<a href="definitions.html#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 as an encrypted password. This does
|
|
not make for happy-camper writers, who either find themselves stuck
|
|
with a formatting style they don’t like, or are forced to
|
|
learn groff from the ground up—a daunting task, to say the
|
|
least.
|
|
</p>
|
|
|
|
<p>
|
|
Mom aims to make creating documents a simple matter, but with no
|
|
corresponding loss of user control. The document processing macros
|
|
provide an initial set of reasonable defaults, but anything that
|
|
is not to your liking can be changed. 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>
|
|
|
|
<p>
|
|
One rarely hears the term “user interface” in
|
|
conjunction with document processing. Since formatting takes
|
|
place inside a text editor, little thought is given to the
|
|
look and feel of the formatting commands. Mom 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 easier to decipher,
|
|
typographically and structurally.
|
|
</p>
|
|
|
|
<p>
|
|
Mom 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 primarily for PDF or PostScript output, although
|
|
with
|
|
<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>
|
|
she produces acceptable terminal copy. No attempt is made to be
|
|
compatible with older versions of troff.
|
|
</p>
|
|
|
|
<p>
|
|
One special feature in mom’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 unavoidable (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,
|
|
mom does avoid them, by clever adjustments to leading (“line
|
|
spacing”) and the spacing between different elements on the
|
|
page.
|
|
</p>
|
|
|
|
<h2 id="intro-documentation" class="docs">A note on mom’s documentation</h2>
|
|
|
|
<p>
|
|
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? At some point, one has to decide for whom
|
|
the documentation is intended. Making the wrong choice can mean the
|
|
difference between a program that gets used and a program that gets
|
|
tossed.
|
|
</p>
|
|
|
|
<p>
|
|
Mom’s documentation assumes users know their way around
|
|
their own operating system (basic file management, how to use
|
|
the command line, how to use a text editor, etc). I run GNU/Linux,
|
|
and while the documentation may exhibit a GNU/Linux bias, mom
|
|
and groff can, in fact, be run on other platforms.
|
|
</p>
|
|
|
|
<p>
|
|
The documentation further assumes users 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 mom’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.
|
|
</p>
|
|
|
|
<h3 id="canonical" class="docs">Canonical reference materials</h3>
|
|
|
|
<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/cstr54.ps">here</a>)
|
|
and the <strong>troff</strong> and <strong>groff_diff</strong>
|
|
manpages. The most complete and up-to-date source of information is
|
|
the groff info pages, available by typing <kbd>info groff</kbd> at
|
|
the command line (assuming you have the TeXinfo standalone browser
|
|
installed on your system, which is standard for most GNU/Linux
|
|
distributions). And for inputting special characters, see <kbd>man
|
|
groff_char</kbd>.
|
|
</p>
|
|
|
|
<p style="margin-top: 24px;">
|
|
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 mom users up and running.
|
|
<i>Mea culpa.</i>
|
|
</p>
|
|
|
|
<p>
|
|
Groff has ancillary programmes (pre-processors) for generating
|
|
tables (<strong>tbl</strong>), diagrams (<strong>pic</strong>), and
|
|
equations (<strong>eqn</strong>), which may be used in conjunction
|
|
with mom. The manuals describing their usage are found at:
|
|
<br/>
|
|
<span style="display:block; margin-top: .5em">
|
|
<kbd> tbl</kbd> <a href="http://www.kohala.com/start/troff/v7man/tbl/tbl.ps">http://www.kohala.com/start/troff/v7man/tbl/tbl.ps</a>
|
|
<br/>
|
|
<kbd> pic</kbd> <a href="http://www.kohala.com/start/troff/gpic.raymond.ps">http://www.kohala.com/start/troff/gpic.raymond.ps</a>
|
|
<br/>
|
|
<kbd> eqn</kbd> <a href="http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps">http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps</a>
|
|
</span>
|
|
</p>
|
|
|
|
<div class="box-tip">
|
|
<p class="tip-top" style="padding-bottom: 9px;">
|
|
<b>Note:</b> Mom’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>
|
|
</div>
|
|
|
|
<div class="rule-short" style="padding-top: 6px; padding-bottom: 3px;"><hr/></div>
|
|
|
|
<h2 id="macro-args" class="docs">How to read macro arguments</h2>
|
|
|
|
<p>
|
|
The concise descriptions of macros in this documentation typically
|
|
look like this:
|
|
</p>
|
|
|
|
<div class="box-macro-args">
|
|
Macro: <b>MACRO_NAME</b> <kbd class="macro-args">arguments</kbd>
|
|
</div>
|
|
|
|
<p>
|
|
<kbd>arguments</kbd> 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>
|
|
<li>If an argument is surrounded by chevrons
|
|
(<kbd>< ></kbd>), it’s a description
|
|
of the argument, not the argument itself.
|
|
</li>
|
|
<li>If an argument begins with or is surrounded by double-quotes, the
|
|
double quotes must be included in the argument.
|
|
</li>
|
|
<li>If the user has a choice between several arguments, each of the
|
|
choices is separated by the pipe character
|
|
(<kbd>|</kbd>), which means “or.”
|
|
</li>
|
|
<li>Arguments that are optional are surrounded by square brackets.</li>
|
|
<li><kbd><off></kbd> or <kbd><anything></kbd> in an argument
|
|
list means that any argument other than those in the argument
|
|
list turns the macro off.
|
|
</li>
|
|
</ol>
|
|
|
|
<h3 id="toggle-macro" class="docs">Toggle macros</h3>
|
|
|
|
<p>
|
|
Some macros don’t require an argument. They simply start
|
|
something. When you need to turn them off, the same macro with
|
|
any argument will do the trick. That’s right: <em>any</em>
|
|
argument (in caps, lowercase, or a mixture thereof). This permits
|
|
choosing whatever works for you: <kbd>OFF</kbd>, <kbd>end</kbd>,
|
|
<kbd>Quit</kbd>, <kbd>Q</kbd>, <kbd>X</kbd>, and so on.
|
|
</p>
|
|
|
|
<p>
|
|
Since these macros toggle things on and off, the argument list
|
|
simply reads <kbd>toggle</kbd>.
|
|
</p>
|
|
|
|
<div id="examples" class="examples-container">
|
|
<h2 class="docs" style="margin-top: .5em;">Examples</h2>
|
|
|
|
<div class="examples">Example 1: An argument requiring double-quotes</div>
|
|
|
|
<div class="box-macro-args" style="max-width: 684px;">
|
|
Macro: <b>TITLE</b> <kbd class="macro-args">"<title of document>"</kbd>
|
|
</div>
|
|
|
|
<p>
|
|
The required argument to TITLE is the title of your document.
|
|
Since it’s surrounded by double-quotes, you must include
|
|
them in the argument, like this:
|
|
<br/>
|
|
<span class="pre-in-pp">
|
|
.TITLE "My Pulitzer Novel"
|
|
</span>
|
|
</p>
|
|
|
|
<div class="examples" style="margin-top: -1em;">Example 2: A macro with required and optional arguments</div>
|
|
|
|
<div class="box-macro-args" style="width: 684px;">
|
|
Macro: <b>TAB_SET</b> <kbd class="macro-args"><tab number> <indent> <length> [ L | R | C | J [ QUAD ] ] </kbd>
|
|
</div>
|
|
|
|
<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:
|
|
<br/>
|
|
<span class="pre-in-pp">
|
|
.TAB_SET 3 6P 3P
|
|
</span>
|
|
The remaining two arguments are optional. The first is a
|
|
single letter, either <kbd>L, R, C</kbd> or
|
|
<kbd>J</kbd>. The second, which is itself
|
|
optional after <kbd>L, R, C</kbd> or
|
|
<kbd>J</kbd>, is the word <kbd>QUAD</kbd>.
|
|
Therefore, depending on what additional information you wish to
|
|
pass to the macro, you could enter:
|
|
<br/>
|
|
<span class="pre-in-pp">
|
|
.TAB_SET 3 6P 3P L
|
|
</span>
|
|
or
|
|
<br/>
|
|
<span class="pre-in-pp">
|
|
.TAB_SET 3 6P 3P L QUAD
|
|
</span>
|
|
</p>
|
|
|
|
<div id="toggle-example" class="examples" style="margin-top: -1em;">Example 3: A sample toggle macro:</div>
|
|
|
|
<div class="box-macro-args" style="max-width: 684px;">
|
|
Macro: <b>QUOTE</b> <kbd class="macro-args">toggle</kbd>
|
|
</div>
|
|
|
|
<p>
|
|
<kbd>QUOTE</kbd> begins a section of quoted text
|
|
in a document and doesn’t require an argument. When the
|
|
quote’s finished, you have to tell mom it’s done.
|
|
<span class="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
|
|
</span>
|
|
</p>
|
|
|
|
<p>
|
|
Alternatively, you could have turned the quote off with
|
|
<kbd>END</kbd>, or <kbd>X</kbd>, or something else.
|
|
</p>
|
|
</div>
|
|
|
|
<!-- Navigation links -->
|
|
<table style="width: 100%; margin-top: 12px;">
|
|
<tr>
|
|
<td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
|
|
<td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
|
|
<td style="width: 33%; text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
</div>
|
|
|
|
<div class="bottom-spacer"><br/></div>
|
|
|
|
</body>
|
|
</html>
|