Writing books in groff

As an undergraduate student in the 1990s, I used nroff and groff to write class papers and other documents. I continue to find groff to be an enjoyable document preparation system.

I also find it fascinating to interview others who also use groff to write technical documents. And that's why I reached out to Dr. Marshall Kirk McKusick for an interview.

While at the University of California at Berkeley, Kirk implemented the 4.2BSD fast file system (FFS) which is still in wide use today in most variants of the UNIX operating system. Following the completion of his doctoral degree, he was the Research Computer Scientist at the Berkeley Computer Systems Research Group (CSRG) overseeing the development and release of 4.3BSD and 4.4BSD. He also played a key role in ensuring that the final release of 4.4BSD-Lite from Berkeley be freely distributable as open-source software.

Kirk continues to write books and articles, teach classes on UNIX- and BSD-related subjects, and provide expert-witness testimony on software patent, trade secret, and copyright issues particularly those related to operating systems and file systems.

I asked Kirk about how he uses groff to write his books:

Did you write your books with troff or groff?

These are the books. All used a variant of troff (ditroff or groff).

S. Leffler, M. McKusick, M. Karels, J. Quarterman. The Design and Implementation of the 4.3BSD UNIX Operating System. Addison-Wesley Publishing Company, Reading, MA. January 1989, ISBN 0-201-06196-1.

(German Translation published June 1990, ISBN 3-89319-239-5. Japanese Translation published June 1991, ISBN 4-621-03607-6.)

The Design and Implementation of the 4.3BSD UNIX Operating System Answer Book. Addison-Wesley Publishing Company, Reading, MA. April 1991, ISBN 0-201-54629-9.

(Japanese Translation published January 1992, ISBN 4-8081-8039-5.)

M. McKusick, K. Bostic, M. Karels, J. Quarterman. The Design and Implementation of the 4.4BSD Operating System. Addison-Wesley Publishing Company, Reading, MA. April 1996, ISBN 0-201-54979-4.

(French Translation published 1997, International Thomson Publishing, Paris, France, ISBN 2-84180-142-X. Japanese Translation published 2003, ISBN 4-7561-4346-6. Chinese Translation published 2003, ISBN 7-5083-1508-1.)

M. McKusick, G. Neville-Neil. The Design and Implementation of the FreeBSD Operating System. Addison-Wesley Publishing Company, Reading, MA. July 2004, ISBN 0-201-70245-2.

(Chinese Translation published 2005, ISBN 7-115-13685-8. Japanese Translation published 2006, ISBN 4-7561-4679-1.)

M. McKusick, G. Neville-Neil, R. Watson. The Design and Implementation of the FreeBSD Operating System, 2nd Edition. Pearson Education, Boston, MA September 2014, ISBN-13: 978-0-321-96897-5, ISBN-10: 0-321-96897-2.

Did you use an existing macro package, or did you write your own?

We started with the -ms macros which were then adapted by Jaap Akkerhuis with an extended set of macros that dealt with the style guidelines for the book such as headers, footers, chapter headers, section headers, figure and table layout, glossary and indexing, etc.

I did further extensions to handle orphan and widow elimination. Further issues that require remediation are that no paragraph can end with a line less than five characters. And no paragraph can have more than two contiguous lines that end with a hyphenated line. These issues are fixed by increasing or decreasing the inter-word spacing by one or more points for the offending paragraph.

Lastly, facing pages must be balanced (i.e., text ends at the same place on the facing pages). This is done by adding or removing space below figures at the top of pages or above figures at the bottom of pages. Similarly spacing can be added above or below section headings.

The above features are generally done by diverting a paragraph into a diversion and then inspecting whether it breaks any rules. If it does, it can be reformatted using an extra point or one less point between words then plus 2 and minus 2 until a value is found that creates a paragraph that meets all the rules.

Sadly, page balancing has to be done by hand as diverting entire pages is too hard.

Are the macros best suited for books, or have you used them for other kinds of documents?

I have never considered using these macros for any other purpose, but the ideas in them could be applied to other uses.

How did you collaborate using groff to write your books?

As noted above, we have used these macros only for our books. Over the years we have always used the current fad for version control. So we have used SCCS, RCS, subversion, and most recently git.

Why did you select groff to write the books?

For our first book, we had to provide a camera-ready copy, and ditroff was our only option that could provide what we had to produce. For our second book (and all later books) we still had to provide camera ready PDFs, so we just kept using the tools that we had that worked. Note that we also used many other components of the troff family such as tbl, eqn, pic, xfig, etc.

Thank you to Kirk for this excellent interview about writing books in troff and groff! In addition to writing books, Kirk has twice been president of the board of the Usenix Association, was a member of the FreeBSD Foundation Board of Directors, a senior member of the IEEE, and a member of ACM and AAAS.

In his spare time, he enjoys swimming, scuba diving, and wine collecting. The wine is stored in a specially constructed wine cellar in the basement of the house that he shares with Eric Allman, his partner of 44 years and husband since 2013.