| Back to Table of Contents | Next: Inserting images |
Once you’ve completed the setup for a document (see Setting up a mom document), formatting it is a snap. Simply invoke the appropriate tag for each document element as you need it. The tags are macros that tell mom: “This is a paragraph; this is a heading; this is a footnote,” and so on.
Generally, for each tag, there are control macros for the tag’s family, font and point size. Where appropriate, there are macros to control leading, indents, quad and special features as well. Mom has tasteful defaults for all the tags, hence you only use the control macros when you want to change the way she does things. This is usually done prior to START, but can, in fact, be done at any time in the course of a document. Any change to a tag’s style affects all subsequent invocations of the tag.
The control macros for document processing tags let you design the look of all the parts of your documents—should you wish. At a bare minimum, all tags have macros to change mom’s defaults for family, font, point size and colour. Where appropriate, there are macros to control leading, indents and quad as well.
In addition, many tags have special macros to control features that are pertinent to those tags alone. Have a look at the section dealing with any particular tag to find out what macros control the tag, and what mom’s defaults for the tag are.
The control macros may be used at any time during the course of a document (ie before or after START). The changes you make alter all subsequent invocations of the affected tag until you make another change, either by passing new arguments to the tag’s control macro, or toggling a particular feature of the tag on or off.
And don’t forget: the typesetting macros can be used at any time, including inside toggle tags (affecting only that particular invocation of the tag). Equally, inline escapes can be used in tags that take string arguments.
Tip: Get familiar with mom at her default settings before exploring the control macros. Put her through her paces. See how she behaves. Get to know what she feels like and how she looks, both in your text editor and on the printed page. Then, if you don’t like something, use this documentation to find the precise macro you need to change it. There are tons of control macros. Reading up on them and trying to remember them all might lead you to think that mom is complex and unwieldy, which is not only untrue, but would offend her mightily.
Important: The family, font, point size, colour and leading control macros have no effect in PRINTSTYLE TYPEWRITE, except where noted throughout this documentation.
Please also note that the defaults listed with the control macros apply only to PRINTSTYLE TYPESET unless a default for TYPEWRITE is also given.
The arguments to the control macros that end in _FAMILY or _FONT are the same as for FAMILY and FT.
Control macros that end in _SIZE always take
the form +<n> or -<n> where
<n> is the number of
points
larger (+) or smaller (-) than the point size of paragraphs
you want the document element to be. For example, to set
blockquotes 2 points smaller than the type in paragraphs, do
.BLOCKQUOTE_SIZE -2
There’s no need for a
unit of measure
with the _SIZE control macros; points is assumed.
Control macros that end in _COLOR take as their argument a colour
name pre-defined (or “initialized”) with
NEWCOLOR
or
XCOLOR.
For example, if you want your
author linebreaks
to be red, once you’ve defined or initialized the colour, red,
.LINEBREAK_COLOR red
will turn them red.
Control macros that end in _AUTOLEAD take the same argument as
AUTOLEAD,
viz. a digit that represents the number of points to add to
the tag’s point size to arrive at its
leading.
For example, to set footnotes
solid, do
.FOOTNOTE_AUTOLEAD 0
To set footnotes with a 1-point lead (ie with the line spacing
one point greater than the footnote’s point size), do
.FOOTNOTE_AUTOLEAD 1
Note: _AUTOLEAD control macros do not have a FACTOR argument.
Except for PARA_INDENT, the argument to control macros that end in _INDENT can take either a single numeral (whole numbers only, no decimal fractions) without a unit of measure appended to it, or a digit (including decimal fractions) with a unit of measure appended.
A digit without a unit of measure appended represents by
how much you want your paragraph first-line indents (set with
PARA_INDENT) multiplied to achieve the correct indent for a
particular tag. For example,
.PARA_INDENT 2m
.BLOCKQUOTE_INDENT 2
means that blockquotes will be indented from the left and right
margins by twice the size of the paragraph indent, or 4
ems.
A digit with a unit of measure appended defines an absolute
indent, relative to nothing. In the following, blockquotes will be
indented by 3
picas
and 6
points,
regardless of the paragraph indent.
.PARA_INDENT 2m
.BLOCKQUOTE_INDENT 3P+6p
Control macros that end in _QUAD take the same arguments as QUAD.
If mom gives the option to underline a document element, the weight of the underline and its distance from the baseline are controlled by macros that end in _UNDERLINE.
Page elements that are separated from running text by a rule (ie page headers, page footers and footnotes) are controlled by macros that end in _RULE_WEIGHT.
The weight argument to _UNDERLINE macros is the same as the argument to RULE_WEIGHT, as is the argument to _RULE_WEIGHT macros.
Epigraphs colour, flavour, or comment on the document they precede. Typically, they are centred at the top of a document’s first page (underneath the title) and set in a smaller point size than that of paragraph text.
By default, mom sets epigraphs centred and unfilled; this lets you input them on a line for line basis. This behaviour can be changed to accomodate filled epigraph “blocks.”
EPIGRAPH is a toggle, used like this:
.EPIGRAPH
<text of epigraph>
.EPIGRAPH OFF
OFF, above, could be anything—say, Q or
X—since any argument other than BLOCK
turns it off.
If given the argument, BLOCK, EPIGRAPH sets epigraphs filled, justified or quadded in the same direction as paragraphs, indented equally from both the left and right margins.
If a block-style epigraph runs to more than one paragraph (unlikely, but conceivable), you must introduce every paragraph—including the first—with the PP tag.
Note: EPIGRAPH should only be used at the top of a document (ie just after START) or after headings. The latter is not especially recommended, but it does work. In all other places where you want quotes or cited text, use QUOTE or BLOCKQUOTE.
Tip:
If you’re setting a document in
columns
and you’d like to add or subtract space after the epigraph,
the place to do it is inside the epigraph, like this:
.EPIGRAPH
A notable quote.
.SP 1v
.EPIGRAPH OFF
If you were to add the .SP 1v outside the epigraph, the
space would be added to the top of the leftmost column only,
resulting in unbalanced columns.
See Arguments to the control macros.
.EPIGRAPH_FAMILY default = prevailing document family; default is Times Roman .EPIGRAPH_FONT default = roman .EPIGRAPH_SIZE default = -1.5 (points) .EPIGRAPH_COLOR default = black .EPIGRAPH_AUTOLEAD default = 2 points (The next two apply to “block” style epigraphs only) .EPIGRAPH_QUAD default = same as paragraphs .EPIGRAPH_INDENT* (see Note on EPIGRAPH_INDENT, below) *Indent here refers to the indent from both the left and right margins that centres block style epigraphs on the page.If you pass EPIGRAPH_INDENT an integer with no unit of measure appended, the integer represents the amount by which to multiply PARA_INDENT to arrive at an indent for block style epigraphs. If you append a unit of measure to the argument, the indent will be precisely the amount specified.
Please also note that if your PARA_INDENT is 0 (ie no indenting of the first line of paragraphs), you must set an EPIGRAPH_INDENT yourself, with a unit of measure appended to the argument. Mom has no default for EPIGRAPH_INDENT if paragraph first lines are not being indented.
The default value for EPIGRAPH_INDENT is 3 (for PRINTSTYLE TYPESET) and 2 (for PRINTSTYLE TYPEWRITE).
The paragraph macro is the one you use most often. Consequently, it’s one of most powerful, yet simplest to use—just the letters PP. No arguments, nothing. Just .PP on a line by itself any time, in any document element, tells mom you want to start a new paragraph. The spacing and indent appropriate to where you are in your document are taken care of automatically.
By default, mom does not indent the first paragraph of a document, nor paragraphs that fall immediately after headings. The first paragraphs of blockquotes and block-style epigraphs are also not indented. This behaviour can be changed with the control macro INDENT_FIRST_PARAS.
Mom does not deposit a blank line between paragraphs. If you want her to do so, use the control macro PARA_SPACE. (I don’t recommend using this macro with PRINTSTYLE TYPEWRITE.)
Tip:
If you'd like to add a small amount of space between paragraphs,
less than the full linespace provided by PARA_SPACE,
you can create a macro that adds it automatically, like this:
.MAC PP2 END
. ALD .25v
. PP
.END
Introducing a paragraph with .PP2 will add a space equal
to one-quarter of the prevailing linespace before the start of the
paragraph. Initial paragraphs, ie those at the start of a document,
or after a heading or
linebreak,
should still be introduced with
.PP.
Note that mom does not provide widow or orphan control for paragraphs (ie even if only one line of a paragraph fits at the bottom of a page, she will set it on that page). The reason for this is that writers of fiction often have single-line paragraphs (eg in dialogue). Groff’s simplistic orphan control will break these one-liners—if they fall at the bottom of the page—to a new page, which is not what you want.
Tip: The last thing you want while you’re writing and editing drafts of a document (particularly stories and chapters) is a text file cluttered up with .PP’s. The visual interruption in the flow of text is a serious obstacle to creativity and critiquing.
I use the tab key on my keyboard to indent paragraphs by four spaces when I'm writing, producing a text file that looks pretty much like what you see on a printed page. When it comes time to format and print the file, I run it through a sed script that (amongst other things) converts the intial four spaces into .PP (plus a new line) and pipes the output to groff for processing and printing.
Another solution would be to insert a blank line between paragraphs
of your text files. The blank lines can then be sedded out at
print time, as above (.PP plus a newline), or, more
conveniently, you could use the .blm
primitive
(blank line macro) to tell groff (and mom) that blank lines should
be interpreted as PP’s.
.blm PP
tells groff that blank lines are really the macro PP.
.PP (on a line by itself, of course) tells mom to start a new paragraph. See above for more details. In addition to regular text paragraphs, you can use PP in epigraphs, blockquotes, endnotes and footnotes.
The PP macro being so important, and representing, as it were, the basis of everything that goes on in a document, its control is managed in a manner somewhat different from other document element tags.
The paragraph family is set with FAMILY prior to START, or DOC_FAMILY afterwards. Please note that both globally affect the family of every element in the document.
If you wish to change the family for regular text paragraphs only,
invoke .FAMILY immediately after .PP in every
paragraph whose family you wish to differ from the prevailing
document family. Alternatively, set the family and font for
paragraphs with PP_FONT, giving it a complete family+font name, eg
PP_FONT TI
which would make the font used in paragraphs Times Roman Italic.
Mom’s default paragraph (and document) family is Times Roman.
Note: Neither FAMILY nor DOC_FAMILY has any effect when the PRINTSTYLE is TYPEWRITE.
To change the font used in regular text paragraphs, use PP_FONT, which takes the same argument as FT. PP_FONT may be used before or after START. Only regular text paragraphs are affected; paragraphs in epigraphs, blockquotes, endnotes, and footnotes remain at their default setting (medium roman) unless you change them with the appropriate control macros.
Mom’s default paragraph font is medium roman.
Note: PP_FONT has no effect when the PRINTSTYLE is TYPEWRITE. If you wish to set whole typewritten paragraphs in italic, invoke invoke .FT I immediately after .PP. Depending on which of UNDERLINE_ITALIC or ITALIC_MEANS_ITALIC is currently enabled, the paragraph will be set underlined or in italic. Neither persists past the end of the paragraph.
Mom has no special control macro for colourizing paragraphs. If you wish a colourized paragraph, you must use the macro, COLOR, or the inline escape, \*[<colourname>], after .PP. The colour must be one pre-defined (or “initialized”) with NEWCOLOR or XCOLOR.
Please note that unless you change the colour back to it’s default (usually black) at the end of the paragraph, all subsequent paragraphs will be set in the new colour, although most other elements of your document will continue to be set in the default colour (usually black).
For example, assuming you have defined the colour, blue,
.PP
.COLOR blue
<first paragraph>
.HEAD "Monty Python"
.SUBHEAD "The Origins of Spam"
.PP
<second paragraph>
the first paragraph will be blue, the head and subhead will be in
the document’s default colour (usually black), and the second
paragraph will be in blue.
The paragraph leading is set with LS prior to START, or DOC_LEAD afterwards. Please note that either method globally affects the leading and spacing of every document element (except headers and footers).
If you wish to change the leading of regular text paragraphs only, invoke .LS immediately after .PP in every paragraph whose leading you wish to change.
Warning: It is extremely unwise to change a paragraph’s leading with LS as it will, in all cases, screw up mom’s ability to balance the bottom margin of pages. Should you absolutely need to change paragraph leading with LS, and subsequently want mom to get back on the right leading track, use the SHIM macro.
Mom’s default paragraph leading (document leading) is 16 points, adjusted to fill the page.
The justification/quad-direction of regular text paragraphs (ie justified, or filled and quadded left/right/centre) is set with JUSTIFY or QUAD prior to START, and with DOC_QUAD afterwards.
Please note that either method of setting the paragraph justification/quad-direction also affects epigraphs, footnotes, and endnotes, but not blockquotes (whose default is quad left unless you change it with BLOCKQUOTE_QUAD). The justification/quad-direction of epigraphs and footnotes may be changed with their own control macros.
If you wish to change the justification/quad-direction of individual paragraphs, invoke .JUSTIFY or .QUAD on the line immediately after .PP. Only the paragraph in question gets justified or quadded differently; subsequent paragraphs remain unaffected.
Mom’s default justification/quad-direction for paragraphs when the PRINTSTYLE is TYPESET is justified; for PRINTSTYLE TYPEWRITE, the default is quad left.
The first-line indent of paragraphs is controlled by PARA_INDENT,
which takes one argument: the size of the indent. PARA_INDENT may be
used before or after
START.
A
unit of measure
is required; fractional sizes are allowed. Thus, to set the
paragraph indent to 4-1/2
ems, do
.PARA_INDENT 4.5m
In addition to establishing the basic first line-indent of
paragraphs, PARA_INDENT also affects
epigraphs,
quotes
and
blockquotes,
whose overall indenting from the left and (where applicable)
right margins is relative to PARA_INDENT if
the _INDENT control macro for these tags has
no
unit of measure
appended to it. Furthermore, the first-line indent of paragraphs
within these document elements (as well as footnotes) is also
relative to PARA_INDENT (always 1/2 of PARA_INDENT), hence they are
also affected.
Mom’s default PARA_INDENT is 2 ems for PRINTSTYLE TYPESET and 3 picas (1/2 inch) for PRINTSTYLE TYPEWRITE.
By default, mom does not indent the first paragraph of a document, nor the first paragraph after a heading or linebreak, nor the first paragraphs of epigraphs, blockquotes, endnotes or footnotes that run to more than one paragraph.
If you wish to have first paragraphs indented, invoke the macro .INDENT_FIRST_PARAS without an argument, either before or after START. INDENT_FIRST_PARAS is a toggle macro, therefore passing it any argument (OFF, QUIT, Q, X...) cancels its effect, meaning that first paragraphs will once again not be indented.
By default, mom does not insert a blank line between paragraphs. If you would like her to do so, invoke the macro, .PARA_SPACE, without an argument, either before or after START. PARA_SPACE is a toggle macro, therefore passing it any argument (OFF, QUIT, Q, X...) cancels its effect, meaning that paragraphs will once again not be separated by a blank line.
PARA_SPACE is not recommended for use with PRINTSTYLE TYPEWRITE unless you give PRINTSTYLE the SINGLESPACE option.
Note: If PARA_SPACE is on, mom spaces only those paragraphs that come after an initial paragraph. Initial paragraphs are those that come immediately after the docheader (ie the start of a document), epigraphs, headings, and linebreaks. (The first paragraph after these document elements requires no blank line to separate it from other paragraphs.)
Sometimes, you can be fairly deep into a document before using PP for the first time, and when you do, because mom is still waiting for that initial paragraph, she doesn’t space it with a blank line, even though you expect her to. The simple workaround for this is to invoke .PP twice (in succession) at the point you expect the blank line to appear.
If you would like to space paragraphs by less than a full linespace,
the way to do it is by creating a wrapper macro around PP that adds
space before each paragraph, like this,
.MAC PP2 END
. ALD 6p
. PP
.END
which inserts 6
points
of space before each paragraph. Initial paragraphs, as described
above, should still be introduced with PP; only subsequent
ones require .PP2.
If you would like the extra space to be a fraction of the current leading, use the groff number register, \n[.v] and divide it by the fraction you want. For example, .ALD \n[.v]/4 inserts 1/4 linespacing between paragraphs.
You may write the macro, above, in low-level groff if you wish:
.de PP2
. sp 6p
. PP
..
Heads, subheads, and deeper levels of section headings are handled by a single macro, HEADING, to which you pass an argument stating the desired level. .HEADING 1 "<text>", for example, would be a main head; .HEADING 2 "<text>" would be a subhead; etc.
In addition to printing headings in the body of your document, HEADING collects the heading as an entry for the Table of Contents, if the document is to have one, and the PDF outline. With the NAMED argument, it furthermore acts as a bookmark for PDF links.
Headings can also be numbered on a per-heading-level basis,
hierarchically and concatenatively, eg
1.
1.1
1.2
1.2.1
2.
2.1
2.2
2.2.1
By default, a blank line precedes headings, regardless of the level.
Mom initially sets up a very basic style for nine levels of heading,
of which you can have an infinite number, although as has been said,
if you need more than four levels of heading, you should consider
re-organizing your material. The pared-down style of mom’s
defaults is intentional; it is expected that you will design
headings to your own specifications with the
control macro,
HEADING_STYLE.
It is very good practice, and strongly recommended, that you respect the hierarchy of headings, using level-1 for main heads, level-2 for subheads, level-3 for subsubheads, etc. The ease of designing and re-designing the style for each level, plus mom’s very basic defaults, are meant, in part, to prevent the whimsical misuse of a particular heading level just because its style appeals to you.
The first argument to HEADING is the level. Level 1 is analogous to a main head; level 2 is analogous to a subhead; level 3 is analogous to a subsubhead; etc.
The second (optional) argument, PARAHEAD, instructs mom that the heading should be treated as a paragraph head. If HEADING is being used to create a parahead, it must come after PP, not before.
The indent applied to a parahead is the same as what would be expected from a paragraph without the parahead (see Indenting initial paragraphs). If you wish that a paragraph introduced by a parahead not be indented, use PARA_INDENT to set the paragraph indent to zero, then reset the indent for subsequent paragraphs.
The optional third argument, NAMED <id>, gives the heading a unique, non-printing identifier that allows it to referenced from anywhere in the final PDF document with the PDF_LINK macro, provided the mom file is processed with pdfmom. PDF_LINK usage is explained in the manual, Producing PDFs with groff and mom.
The final argument is the text of the heading, surrounded by double
quotes. Long headings that are likely to exceed the current
line length should be broken into chunks, each surrounded by
double-quotes, like this:
.HEADING 1 "A needlessly long but instructive" "first level heading"
Note: If a heading falls near the bottom of an output page and mom is unable to fit the heading plus at least one line of text underneath it, she will set the head at the top of the next page.
As described above, mom inserts a blank line before each heading. If the leading of your document never changes, and you introduce no additional space into the text—as, for example, between paragraphs—this will result in perfectly equal whitespace before each heading.
If, however, you disrupt the regular placement of text on mom’s baseline grid, HEADING adds as much whitespace to the blank line as is necessary to get things back on track. The extra whitespace is always less than the current leading and therefore usually doesn't draw attention to itself. This, along with a similar strategy for whitespace around quotes and blockquotes, is what allows mom to balance the bottom margins of pages effectively. The manual, Producing PDFs with groff and mom, demonstrates this well: the inter-paragraph spacing is 1/3 of the leading, yet mom is able to produce a document with good page-rhythm and evenly balanced bottom margins.
It occasionally happens that the extra whitespace becomes noticeable,
typically when the amount of whitespace approaches the value of the
current leading. The result looks like two blank lines instead of
one. When this happens, a simple but effective fix is to reduce the
space before the heading by backing up one line, either with
.SPACE -1v
or
.RLD -1v
This results in slightly less whitespace than normal, but the
difference is usually not apparent.
If you’d prefer that mom not add flexible whitespace to
headings, invoke the macro
.NO_SHIM
either in the style sheet section of your document (ie after
PRINTSTYLE but before START), which will globally disable whitespace
adjustment not only before headings, but around quotes and
blockquotes as well, or on a per-instance basis. .NO_SHIM
is disabled by issuing
.NO_SHIM OFF
Please note that .NO_SHIM also disables mom’s
automatic shimming around quotes, blockquotes, after PDF images and
floats, and
SHIM
macro itself.
By default, mom pre-initializes nine levels of headings to use the bold font of the prevailing document family, with a baseline adjustment of 1/10 of the current leading. In addition, level-1 headings are 3 points larger than running text, level-2 headings 2 points larger, and level 3-headings 1 point larger. The remaining 6 levels are the same size as running text. A single blank line precedes all levels of heading.
Styling heads is accomplished with a single macro,
.HEADING_STYLE <level>
where <level> is the numeric heading level to which
the style applies.
HEADING_STYLE takes any or all of the following arguments,
which may be given in any order:
FAMILY <family>
FONT <font>
SIZE <+|-size>
QUAD <direction>
COLOR <colour>
UNDERSCORE <weight> <gap> | NO_UNDERSCORE
UNDERSCORE2 <weight> <gap1> <gap2> | NO_UNDERSCORE2
CAPS | NO_CAPS
BASELINE_ADJUST <amount to raise heading from the baseline>
SPACE_AFTER | NO_SPACE_AFTER
NUMBER | NO_NUMBER
The arguments to FAMILY, FONT, SIZE, QUAD, and COLOR are the same as those you’d give to the control macros ending in _FAMILY, _FONT, _SIZE, _QUAD, or _COLOR. See Arguments to the control macros.
UNDERSCORE and UNDERSCORE2 require that a weight for the underscore be given, in points (decimal fractions allowed), but without the unit of measure p appended. They also require that the underscore's distance from the baseline be supplied; in the case of UNDERSCORE2, an additional gap argument representing the distance between the two underscores must be provided.
The CAPS argument capitalizes the text of a heading level in the body of a document but not in the Table of Contents, where capitalization of entries is controlled by TOC_ENTRY_STYLE <n>.
BASELINE_ADJUST allows you to raise a heading slightly above the baseline on which it would otherwise sit. For aesthetic reasons, it is often desirable to introduce a small amount of space between a heading and the text following it. Since headings are preceded by a blank line, it is preferable to move the heading upward than to lower the text following it. The argument to BASELINE_ADJUST is the amount by which to raise the heading. It requires no + or - sign, and must have a unit of measure appended to it.
SPACE_AFTER inserts a blank line equal to the current leading after a HEADING. If you'd like a full linespace after a heading level, use SPACE_AFTER. If you'd like additional space before a heading level, you must introduce it yourself with SPACE or ALD.
NUMBER and NO_NUMBER allow you to determine whether mom prepends a hierarchic numbering scheme to a heading level in the body of a document. Numbering of Table of Contents entries is controlled separately with TOC_ENTRY_NUMBERS. Mom also has a special macro to toggle whether to prefix a chapter number to numbered headings and Table of Contents entries, PREFIX_CHAPTER_NUMBER.
The argument list is long, so you may want to break it into
several lines by using the backslash character (\).
Here's an example of how you might style a level 1 heading:
.HEADING_STYLE 1 \
FONT B \
QUAD C \
UNDERSCORE .5 2p \
BASELINE_ADJUST 3p \
NUMBER
This creates a level-1 heading style that's bold, centered,
underscored and numbered, raised by 3 points from the baseline.
If you’ve requested numbering for any level of heading and you’d like mom, in addition, to prefix a chapter number to the numbering scheme, you can do so with PREFIX_CHAPTER_NUMBER.
After you invoke .PREFIX_CHAPTER_NUMBER, mom will prepend
the current chapter number to all headings you have requested be
numbered with
.HEADING_STYLE <n> NUMBER.
Thus, assuming chapter number twelve (12):
1. LEVEL 1 HEADING
1.1. Level 2 heading
would become
12.1. LEVEL 1 HEADING
12.1.1. Level 2 heading
When you invoke .PREFIX_CHAPTER_NUMBER without an argument, mom checks to see whether the argument you passed to CHAPTER is a digit. If it is, she immediately starts pre-pending the current chapter number to numbered head elements. If it isn’t (say you’ve called your chapter “One” instead of “1”), mom will abort with a request that you pass PREFIX_CHAPTER_NUMBER a digit representing the current chapter number.
In collated documents, mom automatically increments
the digit used by PREFIX_CHAPTER_NUMBER by one
(current chapter digit + 1) every time you invoke .COLLATE, even if
you’ve (temporarily) turned off the prefixing of chapter
numbers. Thus, even if you call your chapters “One”,
“Two”, “Three” instead of “1”,
“2”, “3”, mom will Do The Right Thing
with respect to numbering head elements in all collated chapters
following the first invocation of PREFIX_CHAPTER_NUMBER (assuming,
of course, that the collated chapters are in incrementing order; if
not, you must must put
.PREFIX_CHAPTER_NUMBER <chapter number>
somewhere after the invocation of COLLATE and before the first
numbered head element of each collated document).
PREFIX_CHAPTER_NUMBER can be disabled by passing it any argument other than a digit (eg OFF, QUIT, END, X, etc), although, as noted above, mom will keep, and—in the case of collated documents—increment the chapter number, allowing you to turn prefixing of chapter numbers to numbered head elements off and on according to your needs or whims.
Note: Because PREFIX_CHAPTER_NUMBER takes an (optional) digit representing the chapter number, it’s use need not be restricted to DOCTYPE CHAPTER. You can use it with any document type. Furthermore, even if your doctype isn’t CHAPTER, you can identify the document as a chapter for the purposes of numbering head elements by invoking the macro, .CHAPTER, with a numeric argument in your document setup.
In versions of mom prior to 2.0, headings were entered by their commonly used names, viz. HEAD, SUBHEAD, and SUBSUBHEAD. The new HEADING scheme allows for greater flexibility, and permits seamless integration with PDF output.
Documents created with pre-2.0 versions may still use the oldstyle heading names, as may new documents, however there are some differences in their behaviour.
Whenever mom encounters an oldstyle heading, she loads the default style formerly associated with the oldstyle name. See below for a description of the default styles in the sections HEAD (now HEADING 1), SUBHEAD (now HEADING 2), and SUBSUBHEAD (now HEADING 3). Mom also emits a message to stderr alerting you to what she's doing.
The control macros formerly associated with oldstyle headings are no
longer present in mom's macro file, which means that if you
made changes to mom's default for those headings, you must recreate
the changes with the
HEADING_STYLE
macro. The entire style need not be recreated, only those
parameters that differed from mom's defaults. Thus, if your HEADs
were set flush left, instead of the oldstyle default, centered, but
otherwise kept mom's settings, you need only do
.HEADING_STYLE 1 QUAD L
Important:
The macro, PARAHEAD, is no longer available. You must create paragraph
heads using the
HEADING
macro. Mom will abort with an informational message whenever she
encounters PARAHEAD. Assuming a heading level of 3 for your
paraheads, the former defaults for PARAHEAD can be set up like this:
.HEADING STYLE 3 FONT BI SIZE -.25 \" For PRINTSTYLE TYPESET
.HEADING STYLE 3 FONT I SIZE +0 \" For PRINTSTYLE TYPEWRITE
Equally, the macro NUMBER_PARAHEADS is no longer available. You
must enable numbering of the correct level for paraheads with
HEADING_STYLE. Again assuming a heading level of 3 for paraheads,
it's simply done:
.HEADING_STYLE 3 NUMBER
It is tempting to choose an arbitrary heading level for paraheads, since they are sometimes needed out-of-sequence; for example, immediately after a main head (level-1) in a document that subsequently requires subheads (level-2). In such a circumstance, choosing level-3 for all your paraheads might seem to make sense, but in fact doesn’t, since it disrupts the hierarchy of both the Table of Contents (if your document has one) and the PDF outline.
Correct use of the PARAHEAD option to HEADING under such
circumstances requires always assigning PARAHEAD to
the next logical level in the heading hierarchy. For example, if
there are no headings before the parahead, it should be assigned to
level-1. If subsequently there is a main head to be followed by
more paraheads, the main head should be level-1, and the paraheads
level-2. This will almost certainly require assigning new style
parameters to level-1 (with
HEADING_STYLE)
and to the level now being used for paraheads. The following
example demonstrates.
.HEADING_STYLE 1 FONT BI SIZE +.25 \" parahead style, level-1
.PP
.HEADING 1 PARAHEAD <parahead>
<paragraph text>
.PP
.HEADING 1 PARAHEAD <parahead>
<paragraph text>
\# main head style, level-1
.HEADING_STYLE 1 FONT B SIZE +3 QUAD CENTER UNDERSCORE .5 2p
.HEADING_STYLE 2 FONT BI SIZE +.25 \" parahead style, level-2
.HEADING 1 <main head>
.PP
<paragraph text>
.PP
.HEADING 2 PARAHEAD <parahead>
<paragraph text>
OLDSTYLE_HEADINGS requires no argument. It instructs mom to set the first three levels of heading to the parameters of her old defaults for HEAD, SUBHEAD, and SUBSUBHEAD. Use of OLDSTYLE_HEADINGS will also prevent mom from generating the message she issues the first time she encounters HEAD, SUBHEAD, and SUBSUBHEAD.
When invoked for the first time, with or without OLDSTYLE_HEADINGS, HEAD sets the parameters for level-1 headings to mom’s old HEAD defaults, then prints the head as a level-1 heading. The NAMED <id> optional argument is explained in the description of HEADING.
If, prior to invoking HEAD, you have given any parameters to level-1 heads with HEADING STYLE, they will be preserved; any you give afterwards will be respected.
The former style defaults for HEAD were:
FAMILY = prevailing document family
FONT = bold (TYPESET); roman (TYPEWRITE)
SIZE = +1 (TYPESET); +0 (TYPEWRITE)
QUAD = C
UNDERSCORE .5 2p
CAPS
Note:
The macro, NUMBER_HEADS, from pre-2.0 versions of mom, can still be
used, though it is now a wrapper for
.HEADING_STYLE 1 NUMBER
Mom will alert you to this on stderr.
When invoked for the first time, with or without OLDSTYLE_HEADINGS, SUBHEAD sets the parameters for level-2 headings to mom’s old SUBHEAD defaults, then prints the subhead as a level-2 heading. The NAMED <id> optional argument is explained in the description of HEADING.
The former style defaults for SUBHEAD were:
FAMILY = prevailing document family
FONT = bold (TYPESET); italic, ie underlined (TYPEWRITE)
SIZE = +.5 (TYPESET); +0 (TYPEWRITE)
QUAD = L
BASELINE_ADJUST = 1/8 the current leading
Note:
The macro, NUMBER_SUBHEADS, from pre-2.0 versions of mom, can still be
used, though it is now a wrapper for
.HEADING_STYLE 2 NUMBER
Mom will alert you to this on stderr.
When invoked for the first time, with or without OLDSTYLE_HEADINGS, SUBSUBHEAD sets the parameters for level-3 headings to mom’s old SUBSUBHEAD defaults, then prints the subsubhead as a level-3 heading. The NAMED <id> optional argument is explained in the description of HEADING.
The former style defaults for SUBSUBHEAD were:
FAMILY = prevailing document family
FONT = italic (TYPESET); roman (TYPEWRITE)
SIZE = +.5 (TYPESET); +0 (TYPEWRITE)
QUAD = L
BASELINE_ADJUST = 1/8 the current leading
Note:
The macro, NUMBER_SUBSUBHEADS, from pre-2.0 versions of mom, can still be
used, though it is now a wrapper for
.HEADING_STYLE 3 NUMBER
Mom will alert you to this on stderr.
Linebreaks (“author linebreaks”, “section breaks”) are gaps in the vertical flow of running text that indicate a shift in content (eg a scene change in story). They are frequently set off by typographic symbols, sometimes whimsical in nature.
Alias: SECTION
LINEBREAK takes no arguments. Simply invoke it (on a line by itself, of course) whenever you want to insert an author linebreak.
By default, mom marks author linebreaks with three centred asterisks (stars) in the prevailing colour of the document (by default, black). You can alter this with the control macros
Alias: SECTION_CHAR
• The third optional argument requires a unit of measure.
LINEBREAK_CHAR determines what mom prints when LINEBREAK is invoked. It takes 3 optional arguments: the character you want deposited at the line break, the number of times you want the character repeated, and a vertical adjustment factor.
The first argument is any valid groff character (eg * [an asterisk], \[dg] [a dagger], \f[ZD]\N'141\fP [an arbitrary character from Zapf Dingbats], \l'4P' [a 4-pica long rule]). Mom sets the character centred on the current line length. (See man groff_char for a list of all valid groff characters.)
The second argument is the number of times to repeat the character.
The third argument is a +|-value by which to raise (+) or lower (-) the character in order to make it appear visually centred between sections of text. This lets you make vertical adjustments to characters that don’t sit on the baseline (such as asterisks). The argument must be preceded by a plus or minus sign, and must include a unit of measure.
If you enter LINEBREAK_CHAR with no arguments, sections of text will be separated by two blank lines when you invoke .LINEBREAK.
Mom’s default for LINEBREAK_CHAR is
.LINEBREAK_CHAR * 3 -3p
ie three asterisks, lowered 3 points from their normal vertical
position (for
PRINTSTYLE TYPESET;
the vertical adjustment is -2 points for
PRINTSTYLE TYPEWRITE).
Alias: SECTION_COLOR
To change the colour of the linebreak character(s), simply invoke .LINEBREAK_COLOR with the name of a colour pre-defined (or “initialized”) with NEWCOLOR or XCOLOR.
Quotes are always set in nofill mode, flush left. This permits entering quotes on a line for line basis in your text editor and have them come out the same way on output copy. (See Blockquotes for how quotes, in the present sense, differ from longer passages of cited text.)
Since mom originally came into being to serve the needs of creative writers (ie novelists, short story writers, etc.—not to cast aspersions on the creativity of mathematicians and programmers), she sets quotes in italics (PRINTSTYLE TYPESET) or underlined (PRINTSTYLE TYPEWRITE), indented from the left margin. Obviously, she’s thinking “quotes from poetry or song lyrics”, but with the QUOTE control macros you can change her defaults so QUOTE serves other needs, eg entering verbatim snippets of programming code, command line instructions, and so on. (See the CODE for a convenience macro to assist in including code snippets in documents.)
Besides indenting quotes, mom further sets them off from running text with a small amount of vertical whitespace top and bottom. In PRINTSTYLE TYPEWRITE, this is always one full linespace. In PRINTSTYLE TYPESET, it’s 1/2 of the prevailing leading if the quote fits fully on the page (ie with running text above and below it), otherwise it’s a full linespace either above or below as is necessary to balance the page to the bottom margin. This behaviour can be changed with the control macro ALWAYS_FULLSPACE_QUOTES.
If your quote (or blockquote) leading differs from the document leading, mom attempts to observe the same rules for vertical whitespace outlined above; however, she will also insert a small, flexible amount of extra whitespace around the quotes to make sure the whitespace is equal, top and bottom. Since she does this on a quote by quote basis, rather than by figuring out how much extra whitespace is needed to adjust all quotes on a page, the spacing around multiple quotes on the same page will differ slightly, although each will be balanced between lines of normal running text, top and bottom. (The inability to scan an entire page and insert equalized whitespace at marked places is a limitation of groff, which, by and large, processes text on a line-per-line basis.)
If you don’t want the behaviour described above (ie you
don’t want mom shimming
quotes and blockquotes), issue the macro
.NO_SHIM
in the style sheet section of your document (ie after PRINTSTYLE but
before START), which will disable shimming globally, or on a
per-instance basis prior to .QUOTE or .BLOCKQUOTE.
If you’ve disabled shimming of quotes and blockquotes with .NO_SHIM and you want mom to return to her default behaviour in this matter, invoke .NO_SHIM OFF (or QUIT, END, X, etc).
Please note that NO_SHIM disables shimming before headings, and the SHIM macro itself.
If you don’t provide mom with a QUOTE_AUTOLEAD, quotes are leaded at the default for normal running text, meaning that multiple quotes on the same page are all spaced identically.
QUOTE is a toggle macro. To begin a section
of quoted text, invoke it with no argument, then type in your
quote. When you’re finished, invoke .QUOTE with any
argument (eg OFF, END, X, Q...) to turn it off. Example:
.QUOTE
Nymphomaniacal Jill
Used a dynamite stick for a thrill
They found her vagina
In North Carolina
And bits of her tits in Brazil.
.QUOTE END
See Arguments to the control macros.
.QUOTE_FAMILY default = prevailing document family; default is Times Roman .QUOTE_FONT default = italic; underlined in TYPEWRITE .QUOTE_SIZE default = +0 (ie same size as paragraph text) .QUOTE_AUTOLEAD default = none; leading of quotes is the same as paragraphs .QUOTE_COLOR default = black .QUOTE_INDENT (see below, "Quote indent")QUOTE_INDENT takes one of two kinds of argument: an integer representing the amount by which to multiply the argument passed to .PARA_INDENT (by default, 2 ems for TYPESET, 3 picas for TYPEWRITE) to arrive at the quote indent, or a distance with a unit of measure appended. Both result in quotes being indented equally from the left and right margins.
The default value for QUOTE_INDENT is 3 (for PRINTSTYLE TYPESET) and 1 (for PRINTSTYLE TYPEWRITE).
Note: If your PARA_INDENT is 0 (ie no indenting of the first line of paragraphs), you must set a QUOTE_INDENT yourself, with a unit of measure appended to the argument. Mom has no default for QUOTE_INDENT if paragraph first lines are not being indented.
Additional note: QUOTE_INDENT also sets the indent for blockquotes.
If you’d like mom always to put a full linespace above and
below quotes, invoke
.ALWAYS_FULLSPACE_QUOTES
with no argument. If you wish to restore mom’s
default behaviour regarding the spacing of quotes (see
above),
invoke the macro with any argument (OFF, QUIT, END, X...)
Note: This macro also sets mom’s spacing policy for blockquotes.
By default in PRINTSTYLE TYPEWRITE, mom underlines quotes. If you’d rather she didn’t, invoke .UNDERLINE_QUOTES with any argument (OFF, QUIT, END, X...) to disable the feature. Invoke it without an argument to restore mom’s default underlining of quotes.
If you not only wish that mom not underline quotes, but also that she set them in italic, you must follow each instance of QUOTE with the typesetting macro FT I. Furthermore, since mom underlines all instances of italics by default in PRINTSTYLE TYPEWRITE, you must also make sure that ITALIC_MEANS_ITALIC is enabled (see PRINTSTYLE TYPEWRITE control macros).
Blockquotes are used to cite passages from another author’s work. So that they stand out well from running text, mom indents them from both the left and right margins and sets them in a different point size (PRINTSTYLE TYPESET only). Output lines are filled, and, by default, quadded left.
Besides indenting blockquotes, mom further sets them off from running text with a small amount of vertical whitespace top and bottom. (See above for a complete explanation of how this is managed, and how to control it.)
Aliases: CITE, CITATION
BLOCKQUOTE is a toggle macro. To begin a cited passage, invoke
the tag with no argument, then type in your blockquote. When
you’re finished, invoke .BLOCKQUOTE with any
argument (eg OFF, END, X, Q...) to turn it off.
Example:
.BLOCKQUOTE
Redefining the role of the United States from enablers to keep
the peace to enablers to keep the peace from peacekeepers is
going to be an assignment.
.RIGHT
\[em]George W. Bush
.BLOCKQUOTE END
If the cited passage runs to more than one paragraph, you must
introduce each paragraph—including the first—with
.PP.
Note: The aliases CITE and CITATION may be used in place of the BLOCKQUOTE tag, as well as in any of the control macros that begin or end with BLOCKQUOTE_.
See Arguments to the control macros.
.BLOCKQUOTE_FAMILY default = prevailing document family; default is Times Roman .BLOCKQUOTE_FONT default = roman .BLOCKQUOTE_SIZE default = -1 (point) .BLOCKQUOTE_AUTOLEAD default = none; leading of blockquotes is the same as paragraphs .BLOCKQUOTE_COLOR default = black .BLOCKQUOTE_QUAD default = left .BLOCKQUOTE_INDENT (see below)BLOCKQUOTE_INDENT takes one of two kinds of argument: an integer representing the amount by which to multiply the argument passed to .PARA_INDENT (by default, 2 ems for TYPESET, 3 picas for TYPEWRITE) to arrive at the blockquote indent, or a distance with a unit of measure appended. Both result in blockquotes being indented equally from the left and right margins.
The default value for BLOCKQUOTE_INDENT is 3 (for PRINTSTYLE TYPESET) and 1 (for PRINTSTYLE TYPEWRITE).
Note: If your PARA_INDENT is 0 (ie no indenting of the first line of paragraphs), you must set a BLOCKQUOTE_INDENT yourself, with a unit of measure appended to the argument. Mom has no default for BLOCKQUOTE_INDENT if paragraph first lines are not being indented.
Additional note: BLOCKQUOTE_INDENT also sets the indent for quotes.
If you’d like mom always to put a full linespace above and
below blockquotes, invoke
.ALWAYS_FULLSPACE_QUOTES
with no argument. If you wish to restore mom’s default
behaviour regarding the spacing of blockquotes (see
above),
invoke the macro with any argument (OFF, QUIT, END,
X...).
Note: This macro also sets mom’s spacing policy for quotes.
CODE is a convenience macro that facilitates entering code snippets into documents. Its use is not restricted to documents created using mom’s document processing macros; it can be used for “manually” typeset documents as well.
Inline escape: \*[CODE]
When you invoke .CODE without an argument, or use the inline escape, \*[CODE], mom changes the font to a fixed-width font (Courier, by default) and turns SMARTQUOTES off. Additionally, if you invoke .CODE inside QUOTE while in PRINTSTYLE TYPEWRITE with the default underlining of quotes turned on, it disables the underlining for the duration of CODE.
Passing any argument other than BR, BREAK or SPREAD to CODE (eg OFF, QUIT, END, X, etc.) turns CODE off and returns the family, font, smartquotes and (if applicable) underlining of quotes to their former state. If you’ve used the inline escape, \*[CODE], to initiate a section of code, \*[CODE OFF] equally returns things to their former state.
Note: If your code snippet includes the backslash character, which is groff’s escape character, you will have to change the escape character temporarily to something else with the macro, ESC_CHAR. Mom has no way of knowing what special characters you’re going to use in code snippets, therefore she cannot automatically replace the escape character with something else.
Important: .CODE does not cause a line break when you’re in a fill mode (ie JUSTIFY or QUAD LEFT, CENTER, or RIGHT). If you want CODE to deposit a break, invoke .CODE with the argument BR (or BREAK). If, in addition to having mom break the line before .CODE, you want her to force justify it as well, invoke .CODE with the argument, SPREAD. If, in addition to breaking the line before CODE you want a break afterwards, you must supply it manually with BR unless what follows immediately is a macro that automatically causes a break (eg PP).
In all likelihood, if you want the situation described above (ie a
break before and after CODE), what you probably want is to use
QUOTE
in conjunction with CODE, like this:
.QUOTE
.CODE
$ echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/'
.CODE OFF
.QUOTE OFF
QUOTE takes care of breaking both the text and the code, as well as
indenting the code and offsetting it from
running text
with vertical whitespace.
Note: BR, BREAK and SPREAD have no effect when used with the inline escape, \*[CODE]. The assumption behind \*[CODE] is that you’re inserting a bit of code into a line, not creating a distinct code block.
See Arguments to the control macros.
.CODE_FAMILY default = Courier .CODE_FONT default = roman; see Note .CODE_COLOR default = black Note: Unlike other control macros, CODE_FONT sets the code font for both PRINTSTYLE TYPESET and PRINTSTYLE TYPEWRITE.
CODE_SIZE works a little differently from the other _SIZE macros
(see Arguments to the control
macros). The argument you pass it is a percentage of the
prevailing document point size. It does not require a pre-pended
plus (+) or minus (-) sign, nor an appended
percent sign (%). Thus, is you want the point size of your CODE font to be
90% of the prevailing document point size, you enter:
.CODE_SIZE 90
Fixed-width fonts have notoriously whimsical
x-heights,
meaning that they frequently look bigger (or, in some cases,
smaller) than the type surrounding them, even if they're technically
the same point size. CODE_SIZE lets you choose a percentage of the
prevailing point size for your fixed-width CODE font so it doesn't look
gangly or miniscule in relation to the type around it. All
invocations of .CODE or \*[CODE] will use this
size, so that if you decide to change the prevailing point size of your
document, the CODE font will be scaled proportionally.
Lists are points or items of interest or importance that are separated from running text by enumerators. Some typical enumerators are en-dashes, bullets, digits and letters.
Setting lists with mom is easy. First, you initialize a list with the LIST macro. Then, for every item in the list, you invoke the macro, .ITEM, followed by the text of the item. When a list is finished, you exit the list with .LIST OFF (or QUIT, END, BACK, etc.)
By default mom starts each list with the enumerator flush with the
left margin of running text that comes before it, like this:
My daily schedule needs organizing. I can’t
seem to get everything done I want.
o an hour’s worth of exercise
o time to prepare at least one healthy
meal per day
o reading time
o work on mom
o writing
- changes from publisher
- current novel
o a couple of hours at the piano
In other words, mom does not, by default, indent entire lists.
Indenting a list is controlled by the macro,
SHIFT_LIST.
(This is a design decision; there are too many instances where a
default indent is not desirable.) Equally, mom does not add any
extra space above or below lists.
Lists can be nested (as in the example above). In other words, you can set lists within lists, each with an enumerator (and possibly, indent) of your choosing. In nested lists, each invocation of .LIST OFF (you may prefer to use .LIST BACK) takes you back to the previous depth (or level) of list, with that list’s enumerator and indent intact. The final .LIST OFF exits lists completely and returns you to the left margin of running text.
Finally, lists can be used in documents created with either the document processing macros or the typesetting macros.
Invoked by itself (ie with no argument), LIST initializes a list (with bullets as the default enumerator). Afterwards, each block of input text preceded by .ITEM, on a line by itself, is treated as a list item.
Note: Every time you invoke .LIST to start a list (as opposed to exiting one), you must supply an enumerator (and optionally, a separator) for the list, unless you want mom’s default enumerator, which is a bullet. Within nested lists, mom stores the enumerator, separator and indent for any list you return backwards to (ie with .LIST OFF), but does not store any information for lists you move forward to.
There are a lot of arguments (be sure to side-scroll through them all, above), so I’ll discuss them one at a time here.
The optional arguments BULLET, DASH, DIGIT (for Arabic numerals), ALPHA (for uppercase letters), alpha (for lowercase letters), ROMAN<n> (for uppercase roman numerals), roman<n> (for lowercase roman numerals) tell mom what kind of enumerator to use for a given list.
The arguments, ROMAN<n> and roman<n>, are special. You must append to them a digit (arabic, eg "1" or "9" or "17") saying how many items a particular roman-numeralled LIST is going to have. Mom requires this information in order to align roman numerals sensibly, and will abort—with a message — if you don’t provide it.
A roman-numerall