Back to Table of Contents Next: The typesetting macros

Using mom

Introduction

As explained in the section What is mom?, mom can be used in two ways: for straightforward typesetting or for document processing. The difference between the two is that in straightforward typesetting, every macro is a literal instruction that determines precisely how text following it will look. Document processing, on the other hand, uses markup tags (e.g. .PP for paragraphs, .HEADING for different levels of heads, .FOOTNOTE for footnotes, etc.) that perform typesetting operations automatically.

You tell mom that you want to use the document processing macros with the START macro. After START, mom determines the appearance of text following the markup tags automatically, although you, the user, can easily change how the tags are interpreted.

How to input mom’s macros

Regardless of whether you’re preparing a term paper or making a flyer for your lost dog, the following apply.

  1. You need a good text editor for inputting mom files.
    I cannot recommend highly enough that you use an editor that lets you write syntax highlighting rules for mom’s macros and inline escapes. Simply colourizing macros and inlines to half-intensity can be enough to make text stand out clearly from formatting commands. Mom herself comes with a complete set of syntax highlighting rules for the vim editor. A number of freely available editors come with groff syntax highlighting rules, which are sufficient for mom files, though not as colourful or complete as the vim rules that ship with mom.
  2. Macros begin with a period (dot) at the left margin of your text editor’s screen, and must be entered in upper case (capital) letters.
  3. Macro arguments are separated from the macro itself by spaces. Multiple arguments to the same macro are separated from each other by spaces. Any number of spaces may be used.
  4. Arguments to a macro must appear on the same line as the macro.
    If the argument list is very long, you may use the backslash character (\) to break the line visually. From groff’s point of view, the backslash and newline are invisible. Thus, for example, .HEADING_STYLE 1 FAMILY Garamond FONT B SIZE +2 and .HEADING_STYLE 1 \ FAMILY Garamond \ FONT B \ SIZE +2 are exactly equivalent.
  5. Any argument (except a string argument) that is not a digit must be entered in upper case (capital) letters.
  6. Any argument that requires a plus or minus sign must have the plus or minus sign prepended to the argument with no intervening space (e.g. +2).
  7. Any argument that requires a unit of measure must have the unit appended directly to the argument, with no intervening space (e.g. .5i).
  8. String arguments, in the sense of this manual, must be surrounded by double-quotes (e.g. "text"). Multiple string arguments are separated from each other by spaces (with each argument surrounded by double-quotes).
    If a string argument becomes uncomfortably long, you may break it into two or more lines with the backslash character. .SUBTITLE "An In-Depth Consideration of the \ Implications of Forty-Two as the Answer to Life, \ The Universe, and Everything"

Tip: It’s important that your documents be easy to read and understand in a text editor. One way to achieve this is to group macros that serve a similar purpose together, and separate them from other groups of macros with a comment line. In groff, that’s done with \# (backslash-pound) or .\" (period-backslash-doublequote) on a line by itself. Either instructs groff to ignore the remainder of the line, which may or may not contain text. Consider the following, which is a template for starting the chapter of a book.
\# Reference/meta-data .TITLE "My Pulitzer Novel" .AUTHOR "Joe Blow" .CHAPTER 1 \# Template .DOCTYPE CHAPTER .PRINTSTYLE TYPESET \# Type style .FAM P .PT_SIZE 10 .LS 12 \# .START You may also, if you wish, add a comment to the end of a line with \" (no period), like this:
.FAMILY P \" Maybe Garamond instead?

Processing and viewing documents

The most basic command-line usage for processing a file formatted with the mom macros is
groff -mom filename.mom > filename.ps which processes the .mom file and dumps the output into a viewable/printable PostScript file.

Mom and PDF

Adobe’s Portable Document Format (PDF) has largely supplanted PostScript, of which it is a subset, as the standard for typeset documents. While printed versions of documents in either format will be identical, PDF documents, when viewed at the screen, may also contain clickable links and a number of other special features.

As of version 2.0, mom supports full PDF integration. The creation and processing of mom files into PostScript documents remains unchanged from 1.x, but the expected and recommended format of final documents is now PDF.

The manual, Producing PDFs with groff and mom, explains and demonstrates the PDF-specific macros that are available in mom, as well as the use of pdfmom, the recommended way to process mom files.

pdfmom

Groff provides more than one way to generate PDF documents, but when processing files formatted with the mom macros, pdfmom is the recommended and most robust way to do it:
pdfmom filename.mom > filename.pdf pdfmom is a wrapper around groff, and accepts all groff’s command-line options as listed in the groff manpage. Full usage is explained in the manual, Producing PDFs with groff and mom.

PDF links in a document, including linked entries in the Table of Contents, are identified by colour. When printing documents with links, you will most likely not want the link text coloured. The groff option, -c, disables colour throughout a document; thus, when preparing a document for printing, you should use:
pdfmom -c filename.mom > filename.pdf pdfmom tends to produce large files. You may reduce their size by piping them through ps2pdf:
pdfmom -c filename.mom | ps2pdf - filename.pdf Be aware, though, that files piped through ps2pdf will lose some pdf metadata, notably the document window title set with PDF_TITLE.

Automatic previewing of documents

Most PDF viewers have a “Watch File” option, which automatically updates a displayed document whenever there’s a change. This is useful when preparing documents that require judgment calls. I recommend creating a keymapping in your text editor that both saves the mom file and processes it with pdfmom. The displayed PDF then automatically reflects whatever changes you save to the mom file.

Back to Table of Contents Top Next: The typesetting macros