Lacking Natural Simplicity

TL;DR: Look here for documentation for the Documenter's Workbench mm Memorandum Macros for groff, based on the original paper MM - Memorandum Macros. If you read that far there is a bonus at the end.

When I learned troff it was actually on a VAX running VMS (used by MPL Corporation) using a port of troff called xroff [1], probably around 1986. (The VAX also had TeX and LaTeX, and I used them too. Both supported the DEC LNO3 laserprinter that MPL had.) While I don't know who produced xroff and can't find anything out about it on the Internet, it was a complete port of troff to VMS, including all the standard utilities and macro packages, including documentation for ms, me, and, significantly for this post mm.

The mm documentation was the paper MM - Memorandum Macros, by D. W. Smith, J. R. Mashey, E. C. Pariser, and N. W. Smith, AT&T Bell Laboratories, June 1980. I tried out all the macro packages, but found mm most to my liking. I think a large part of that was the mm documentation — it described the many features of that macro package pretty well, in a user guide sort of way, teaching you how to use the features as it went along, rather than being a pure reference manual. And I found mm most comparable in features to LaTeX of the troff macro packages. While configuring mm documents is somewhat quirky [2], I felt that the added features over those found in me and ms made it worthwhile. So I wrote a lot of documents using mm.

Years later when I first got access to groff on Unix machines (early 90s?) the documentation supplied with it for mm was the groff_mm(7) man page. It was very complete as a reference, but very poor for teaching you how to use mm. I continued to use mm off and on, but I think the lack of the user guide documentation of the mm paper made mm less popular among the users of groff than it could have been. So when modern features for PDF appeared for groff later on (the pdfmark macros), they were adapted to ms but not mm. (me was left out, as well.) I was sad to see mm's apparently low popularity, and the mm paper apparently is not available on the Internet in a form that copyright allows to be copied around, unlike the papers on ms and me, which come with groff. I suspect this is because mm was used heavily in AT&T's Documenter's Workbench, a commercial product that was distributed separately from UNIX System V, if I understand correctly.

However, eventually the sources to the Documenter's Workbench became available under the Eclipse Public License, and they are available in the n-t-roff github repository (along with Heirloom Docutils, a descendant of the original ditroff with native UTF-8 input and easy use of fonts). This includes the source to documentation that is derived from the mm paper! Unfortunately, I haven't been able to find a PDF of this on the Internet.

I think that having this available might help those who might want to try out mm, or are returning to it after a long break, so I've posted a version that I built a while ago here.

As a bonus for reading down this far, here is how I add PDF outline/table-of-contents entries for sections in groff mm, using the HZ user-defined heading exit macro (see groff_mm(7)):

.\" pdf outline fold level
.nr PDFOUTLINE.FOLDLEVEL 3
.\" start out in outline view
.pdfview /PageMode /UseOutlines
.de HZ
.pdfhref O \\$2 \\*[}0] \\$3
..

And here's how to do it in Heirloom Docutils troff:

.de HY
.nr HYtmp (\\$1-1)
\\X'PDFMark: Bookmark \\n[HYtmp] \\$3'
..

This version uses the HY user-defined heading exit macro and doesn't include the section numbers.

I'm not sure why the two use different macros. All I can say is that I wrote them at different times for slightly different purposes.

Last edited: 2021-07-17 19:09:27 EDT