An introduction to groff -mom

The groff -mom macros (also just called mom) are a modern macro package for the groff document preparation system. While mom is defined as a set of macros for groff, it's best to think of her as a complete typesetting and document formatting system that uses groff for the backend. Users are mostly insulated from groff itself. The many examples in mom's extensive documentation show how to perform virtually any document formatting or typesetting function with macros alone.

Akin to html, mom documents begin life as plain text interspersed with markup in the form of macros. Completed documents are processed at the command line with pdfmom(1), a wrapper around groff for generating PDFs. The output is redirected to a file:

pdfmom file.mom > file.pdf

Documents requiring UTF-8 support need two additional flags:

pdfmom -Kutf8 -k file.mom > file.pdf

Macros

Macros are invoked by typing a period at the start of a line followed by an uppercase name. Arguments to a macro come after the name, on the same line, separated by spaces, like this:

.PAGE 8.5i 11i 1i 1i 1i 1i

If an argument itself contains spaces, such as a document title, it must be enclosed in double-quotes:

.TITLE "Document Title"

The structure of Mom files

In broad terms, a mom file has four parts: metadata, a stylesheet, the document body, and concluding macros.

A well-formed mom file has no blank lines. Instead, a period by itself at the start of a line should be used. A comment character \# (backslash-pound) with nothing afterwards serves the same purpose.

1. Metadata

A mom file begins with metadata, as much or as little as needed for mom to format covers, set titles, introduce page headers, and so on:

.TITLE  "What I Did This Summer"
.SUBTITLE "My Trip to the Rockies"
.AUTHOR "Joe Blow"
.DOCTYPE DEFAULT

Optionally, a .COPYSTYLE may be declared, one of DRAFT or FINAL.

2. Stylesheet

Metadata is followed by a stylesheet, which is introduced by .PRINTSTYLE and whose argument may be either TYPESET or TYPEWRITE (typewritten, double-spaced). All documents must have a .PRINTSTYLE declaration even when nothing else appears in the stylesheet.

Macros in the stylesheet alter mom's defaults. Every element in mom documents has a suite of "control macros" for establishing the family, font, size, color, leading and other relevant parameters. For example, to set main heads in Helvetica Bold, small caps, two points larger than body text and numbered:

.HEADING_STYLE 1 FAMILY H FONT B SIZE +2 SMALLCAPS NUMBER 

For readability, macros with many arguments may be split into multiple lines with the line-continued backslash:

.HEADING_STYLE 1 \
 FAMILY  H \
 FONT    B \
 SIZE   +2 \
 SMALLCAPS \
 NUMBER 

The number of spaces between arguments doesn't matter, which allows for indenting. Note that the space character should be used, not tabs. 

The stylesheet can run long. You may want to put in a separate file and source it with the .INCLUDE macro.

3. Document body

The stylesheet ends with the .START macro, which initiates document processing proper. Body text is entered and marked up using semantic (also called "logical" or "structural") tags, similar to other markup languages: .PP introduces paragraphs, .HEADING inserts headings, .BLOCKQUOTE formats cited material, and so on.

.START
.
.HEADING 1 "A First Level Heading"
.
.PP
Paragraph text...
.
.BLOCKQUOTE
Offset, cited material...
.BLOCKQUOTE off
.
.PP
Another paragraph...

Some macros need to be closed, similar to HTML tags. One example is the .CODE instruction to include a block of sample code:

.CODE
echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/'
.CODE off

Invoked without an argument, these "toggle" macros begin a block of specially formatted material; afterwards, with any argument at all (off, OFF, QUIT, done, NO, stop, …) they end it.

4. Concluding macros

If a document contains endnotes, "lists of" or a bibliography, the macros to generate them come at the end of the file.

...end of document text
.
.ENDNOTES
.LIST_OF_FIGURES

If a Table of Contents is desired, the .TOC macro comes last. By default, tables of contents are placed at the back of a document. They can be repositioned to the front with the macro .AUTO_RELOCATE_TOC, which should be placed in the stylesheet.

Multi-chapter documents

In documents comprising chapters, each chapter is terminated with .COLLATE. Following any new metadata (chapter number, chapter title, and so on) the next chapter begins after the next .START.

.TITLE "A Multi-chapter Document"
.AUTHOR "Joe Blow"
.
.DOCTYPE CHAPTER
.CHAPTER 1
.CHAPTER_TITLE "The First Chapter"
.
.PRINTSTYLE TYPESET
.
.START

.
.COLLATE
.
.CHAPTER 2
.CHAPTER_TITLE "The Second Chapter"
.
.START

Multi-chapter documents need not be monolithic. Individual files may be created for each chapter. For accuracy when previewing, it's helpful to create a stylesheet that can be sourced at the top of each file. Output of the complete document is accomplished by adding .COLLATE to the end of every file but the last, stitching them together with cat(1), and piping the output through pdfmom.

cat chapter1 chapter2... | pdfmom > complete-doc.pdf

Learn more about mom

For a good introduction to basic mom concepts and how she interacts with groff, see Groff and mom: an overview. The mom macros have their own website, where you can find, amongst other useful information, a full list of mom's features.