An introduction to groff -mom
Mom is an excellent and flexible macro system, capable of generating a variety of different output types including books, articles, and memos.
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 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.
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
.COPYSTYLE may be declared, one of
Metadata is followed by a stylesheet, which is introduced by
.PRINTSTYLE and whose argument may be either
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
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 (
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.
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
.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
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.