Groff I: Whence and Wherefore

INTRODUCTION

I learned a lot about groff in 2023, and used it for a lot of personal projects and documents. I am writing this to share with you what I learned!

This will be an introduction to what groff is, where it came from, and why I enjoy using it. Future posts in this series will go over how to get started actually using it.

WHAT IT IS

groff is plain text markup for typesetting and document formatting.

The markup looks like this:

.TL How To Steal Horses and Rustle Cattle
.AU Billy the Kid
.SH
On Being An Outlaw
.PP
groff is a plain text markup....

And then it outputs beautiful PDFs!

HISTORY

In the 1960s there was a program called `RUNOFF`. As in to "run off" a job to the printer. This eventually became `roff`, and then `troff` for UNIX, which was used to format man pages. When the Bell Labs patent department started using `troff` for word processing, it became the first UNIX program to have an external client. This established UNIX as a credible operating system and secured funding for the project.

In 1990 GNU released a free version of roff called GNU roff, or `groff`, bringing roff to the masses.

But the masses eventually decided they could do better.

In the late 1970s, Donald Knuth created `TeX` to typeset the second edition of his book *The Art of Computer Programming* because he hated the way it looked after the printing industry transitioned from hot metal typesetting to phototypesetting. The popular `LaTeX` macro package for `TeX` seems to have become the standard for typesetting markup in academia and has largely obsoleted `groff`.

Since around 2011, groff is not even used to create man pages anymore, which was like, it's whole deal. BSD, MacOS, and some linux distributions including Alpine now use `mandoc` instead.

And then I came along. In 2023, I read a few posts on text.causal.agency and really enjoyed the novelty and the aesthetic of using man pages as a blog post format. I tried writing a few documents in `mdoc` and then `groff`, and then I just continued with the deep dive into groff over the next couple of months. I wrote some letters and memos, and published a few essays and even a few tabletop roleplaying games using groff, and I used it to format a plain text newsletter.

https://text.causal.agency/

Here are a few of the things I made:

HOW TO DRAW A DUCK IN GROFF WITH GREMLIN AND PIC

VUMPIRE! RPG

resume.toml

CORNQUEST! A choose-your-own-adventure story.

WHY

So what's the deal?

Why bother with this obsolete, obtuse markup language in year 2024?

• It is small and it runs on machines with limited resources. In the Alpine package repository, the core TeX Live distribution is 500mb installed. `groff` is 8mb.

• It is widely available. Because of its history with man pages, groff is available on most linux and POSIX compliant systems.

• It is scriptable and embeddable. Here's an example of how `tkts` uses a small groff template to create a pdf invoice:

https://gitlab.com/Durrendal/tkts/-/blob/master/src/tkts.fnl?ref_type=heads#L22

• It is "medium sized." If I need little to no control of the typesetting or layout of a document, I'm most likely to pipe some markdown through pandoc to create a pdf. If I need an extraordinary amount of typesetting and layout control, I will probably use a word processor or even a desktop publisher like Scribus. If I need a medium to large amount of control, I use groff.

• It is fun. I personally find a great deal of satisfaction in using old, weird software in new and surprising ways.

• It is a suite of tools. groff comes with preprocessors for creating tables (`tbl`), pictures and diagrams (`pic`, `grn`), mathematical equations (`eqn`), charts and graphs (`grap`), and bibliographies (`refer`). I have found `tbl` specifically to be of great use even outside of groff. I sometimes use it to create markdown tables.

CONCLUSION

That's it for this introduction to groff. In the next post in this series, I'll go over how to get started with groff's macro packages.

date: 2024-01-12
title: Groff I: Whence and Wherefore
url: gemini://tilde.town/~dozens/gemlog/18.gmi
file: 18.gmi
keywords: groff
contact: dozens@tilde.team