Modern groff macros with -mom

Groff is a light but powerful document preparation system. With groff, technical writers can create any kind of document, including letters, memos, articles, and books. If you've explored groff, you probably know that groff provides macro packages like -mm, -ms, and -me, all of which are based on original macro packages built in the 1960s and 1970s.

More recently, Peter Schaffter created a new macro system for groff. The -mom macros are becoming more popular for creating modern documentation. I asked Peter about how he created the -mom macros and what they do.

What's your background with groff and technical communication?

Zilch. My background is in music, languages, and typesetting. I'm a classical composer, novelist, typographer and groff advocate. I wrote and continue to develop the Mom macroset for groff along with her extensive documentation.

That said, when I came to groff in the late 1990s, the documentation was impenetrably dense, like Jello powder without water. I wanted Mom to bring groff to the masses, so to speak, which entailed writing her documentation in a style that didn't scare off new users. It was a huge challenge and gave me a real feel for what technical writers face. 

I should add that the readability of groff documentation has improved enormously in recent years. Branden Robinson, our lead developer, has done such a bang-up job of recasting said documentation that, had he done so back when I started, I might never have had a reason to create Mom.

What are the Mom macros? What do they do?

Mom is the largest of the macrosets that ship with groff. She provides a complete typesetting and document formatting system. Her target format is PDF or Postscript output. It's best to think of her as an application that sits on top of groff. Everything required for document design and typesetting is moved into macro space, making it a straightforward matter to tailor documents to your needs. If you want to make a poster for a lost dog today and write a technical report tomorrow, Mom handles both.

Images can be embedded in Mom documents and full pre-processor support is implemented. Lists of Figures, Tables, and Equations can be auto-generated and set to auto-number. Footnotes, endnotes, margin notes, tables of contents and bibliographies are also available.

Because Mom is integrated with Deri James' gropdf driver, she also provides PDF linking (internal and external), automatic PDF outline generation, table of contents relocation within the source file, shaded backgrounds, and PDF slide transition effects. Documents requiring these functions are processed with pdfmom(1), a wrapper around the groff program that processes forward references.

How did you create the Mom macros?

With much weeping and wailing and gnashing of teeth. The groff language has more gotchas than… well, anything.

I created Mom because groff needed to be yanked into the twenty-first century. TeX was all the rage for typesetting at the turn of the millennium. Groff had pretty much been demoted to the status of "manpage" formatter. Something had to be done to restore it to its former and well-deserved reputation as a lean, mean typesetting machine. An entirely new macroset that bore no resemblance to the past, took advantage of groff extensions (groff is the GNU implementation of troff), and implemented features that no one had thought of before seemed like the way to go.

I started from scratch. The only part of Mom for which I consulted another macroset (-ms) was her refer(1) support. One look at Mom's macro file, om.tmac, and it's obvious she comes from a different universe altogether than the canonical macrosets.

When I started writing the macros, I dumped them in a directory called "own macros" because "my macros," acronymized, would have resulted in a conflict with -mm. Plus, to be perfectly honest, my mother was a wholly admirable woman and it pleased me to name one of my projects after her. I should also add that I enjoy using "she" instead of "it" in the documentation. It allows me to be a bit playful at times.

What's the process to create a new macro package?

I don't know if there's a generalized process for creating a macroset. I suppose it begins by determining the need for one, deciding what macros should go in it, choosing macro names, getting familiar with the ins and outs of page layout, and mastering groff requests, i.e. the low-level typesetting instructions used in macros. The latter is not easy. There's a reason why the old joke of "What does it take to be a computer guru?" puts "Writes own groff macros" at the top.

My process was to start small and work up. I began by writing what the Mom documentation calls the "typesetting macros," macros for manipulating the fundamentals of type: family, font, size, leading, line length, indents, tabs, and so on, as well as necessary refinements like letter-, word-, and sentence-space control, pairwise kerning, etc. Some fancy stuff like drop caps and pseudo-fonts.

Once that was taken care of, I began work on the "document processing macros," which form the heart of Mom's formatting capabilities. Mom is essentially a markup language, much like html, and my goal (as much as possible) was to separate semantic from presentational markup so that source files would be clean and easy to follow.

I added the semantic macros one at a time (PP, HEADING, QUOTE, etc.), complementing each with separate "control macros" for changing every relevant aspect of their behavior and appearance. Control macros are grouped into stylesheets (internal or sourced), which lets users create templates and helps keep presentational markup out of the body copy.

After that, I attacked page layout - headers, footers, pagination, page transitions - and page balancing, then the trickier stuff like footnotes, endnotes, margin notes, and tables of contents.

Working this way, I was able to make an initial release of Mom after about three years. From the beginning, I followed a self-imposed rule: Write the documentation as it would appear in the manual before defining a macro. These weren't descriptions of what I intended to do, but careful instructions for using as-yet unwritten macros. Documenting an already-written macro can lead to getting all twisted up, but implementing a macro that has to follow the documentation keeps you on top of things.

How do the Mom macros make technical writing easier?

The canonical macrosets all simplify creating documents of the type they were designed for. What they don't do is make it easy to format in other styles. That's where Mom shines. Whatever a document's requirements, Mom can accommodate. The granularity of the control macros is staggering. Hierarchical headings alone have nearly twenty settings. The flexibility makes it possible to format any kind of document, with complete control over every aspect of its appearance.

Mom is equally suited to all types of writing projects. A bold claim, but true. tbl(1), pic(1), eqn(1), refer(1), pic(1) and grap(1) are all supported, making her ideal for technical articles and books, but she is at home formatting novels and producing one-off articles, too. Her macros run the gamut from cover to colophon.

Here are some examples:

• Linux Midi Orchestration: A technical book, loaded with tables, diagrams, and images
• The Binbrook Caucus: A press-ready novel
• Groff and mom: an overview: A sample one-off article

It's worth noting that because Mom has full PDF integration, none of these examples would have been possible with the canonical macro sets, at least not without a lot of trouble. I sometimes refer to Mom as a "PDF authoring tool" when describing it to people who wouldn't understand "it's a macro set for groff."

How do the Mom macros make groff documents look more modern?

I'd say, rather, the Mom macros pay more attention to how things look and stop there.

The canonical macrosets seem to have been written by developers whose primary expertise was computing. Mom was written by a professional typographer. It is not enough that a document be formatted intelligently, it must also be formatted beautifully. The devil is in the details and, under the hood, Mom is obsessed with details.

The Mom macros use longer names like .CENTER. Why the longer names?

When the canonical macro sets were written, memory was exorbitantly expensive and every byte mattered. Two letters were the maximum for naming everything: macros, requests, strings, number registers. Groff lifted that restriction, which allowed me to implement a sort of natural language based markup style new users find reassuring. Mom documents are ridiculously easy to visualize because the markup tells you, in plain English, what's going on.

In part, using uppercase was one of the easiest ways to make markup stand out from text. It was also to ensure that nothing in Mom conflicted with the groff language, which uses lowercase naming exclusively. Tutorials on macro writing usually suggest upper case names for precisely that reason.

Thanks to Peter Schaffter for this interesting insight to the -mom macros. If you want to get started with using -mom for document markup start with Groff and mom: an overview. The -mom macros should be included in any full groff installation.