Learning how to use groff -mom

When writing documents with the traditional macro packages for groff like the -me or -ms or -mm macros, you probably learned to use these macros for direct formatting. The macros had a direct and immediate impact on the formatting of your document. For example, you might use groff macros like .sp and .ce and .br to create a title page, .sh or .uh from a macro package to define a section header, and different macros to create internal document formatting.

The -mom (sometimes just called Mom) macros take a slightly different approach. The Mom macro package uses semantic requests and instructions, so the macros will look and act a little different from the traditional macro packages. This different approach lends a more modern feel to using Mom. And with some practice, it's easy to create different kinds of documents with Mom.

Define the metadata first

Let's explore the basics of Mom by creating a sample document. To start, we need to provide Mom with a set of metadata about the document. The minimum are the document title, author, and print style.

The title is the name of your document, and is defined with the .TITLE instruction. If your title has more than one word in it, you must surround the title in double quotes:

.TITLE “This is a sample document”

The author is the person who created the document, set with the .AUTHOR instruction. Like the .TITLE request, write the author's name with double quotes:

.AUTHOR “Jim Hall”

The print style is a stylesheet definition that indicates how the document should be formatted. Use .PRINTSTYLE TYPEWRITE for rough drafts; this assumes certain defaults that will generate output similar to a typewriter-like device: double-spaced lines with a monospace font. These settings are typical for many manuscript drafts as they go for approval by an editor.

If you aren't interested in a draft stage and just want to create a final document, use .PRINTSTYLE TYPESET. This will generate a nice-looking document using the fonts and formatting you would expect to find in a document preparation system.

Minimally, you need .TITLE, .AUTHOR, and .PRINTSTYLE. If any of these are missing, Mom will print an error during processing with groff and your document won't look right. You can also define other settings, but there are the few that are required.

Write a sample document

With the metadata defined, we can start our sample document. To start the document use the .START instruction. This uses the document metadata to start generating the document.

For this sample document, let's just write a few paragraphs. To write paragraphs, use the .PP macro on its own line. Mom will automatically use a left block paragraph at the start of the document and after section headings; following paragraphs will receive a temporary indent.

Here is my sample Mom document. This includes the document metadata at the top, followed by .START and two .PP paragraphs.

.TITLE "This is a sample document"
.AUTHOR "Jim Hall"
.PRINTSTYLE TYPESET
.START
.PP
This is a basic document written using the Mom macros.
Every Mom document must have a TITLE, AUTHOR, and PRINTSTYLE.
You can get by using the defaults for other values.
.PP
To start your document, use the START macro.
This tells Mom to start processing the document.
For new paragraphs, use the PP macro.

Process this document using Mom with the groff -mom command line option. As always, groff writes the output to standard output, so you'll need to redirect the generated document into a new file. For example, if you save the example document to a new file called sample, you can generate a printable PostScript file called sample.ps with this command line:

$ groff -Tps -mom sample > sample.ps

Or if you've installed the pdfmom command, which is part of the groff system, you can run that to streamline generating PDF output.

The result will be a beautiful document formatted in a pleasant way, using bold for the title, italics for the author, and regular paragraphs for the body:

Mom is an excellent addition to the macro packages available with groff. This is only an introduction to writing your first document with Mom; there's lots more to explore with Mom.

For more information about formatting documents with Mom, see Groff and mom: an overview (PDF) and Peter Schaffter's Mom guide.