Groff and the art of letter writing

Introduction

Although I've blogged previously about using LaTeX for academic writing I wanted to try groff out for the less complicated task of letter writing - groff being similar to LaTeX but far less popular. Using a typesetting system such as groff instead of word processing software has several advantages: saving documents in plain text is memory efficient, easily searchable and scores highly for digital preservation (proprietary word processing file formats tending to eventually obsolesce).

Below is a worked example on how to use groff to produce a formal letter on Linux. I'm using groff version 1.22.4, Manjaro Linux 21.0.7 and Zathura 0.4.7.

The letter

Open a file titled complaint.me and copy / paste:

.wh 2c hd \" Top margin (header) set to 2cm
.wh -2c fo \" Bottom margin (footer) set to 2cm
.po 2c \" Right margin set to 2cm
.ll 17c \" Line length set to 17 cm
.in 13c \" Address block indented 13 cm
12 High Street 
.br \" Line break
Leicester
.br
LS1 1AB
.br
01234 567890
.br
another@example.org
.sp \" Spaces one line
8th July 2021
.sp
.in 0 \" Address block indent removed
SuperFibre Broadband
.br
Basildon
.br
PO Box 200
.sp
Dear Sir / Madam,
.pp \" Paragraph start
I am outraged and upset with your response\** \" Places footnote
.(f \" Footnote start
\** Reference C/A/O123 dated 1st July 2021.
.)f \" Footnote end
to my recent complaint.  To suggest that 
.i "my chickens" \" Italics
pecking through 
.i "your broadband wire"
was an event outwith my contract with you is ludicrous.  
Any reputable communications company would ensure that their equipment had been through a testing process which ensures 
.b "fair wear and tear"  \" Bold
caused by farmyard animals.
.pp
I insist that you release me from the remaining twelve months of my broadband contract immediately, and furthermore compensate me for the distress caused to my poultry.
.sp 2 \" Spaces two lines
Yours faithfully,
.sp 2 
A N Other

View on screen with Zathura

Assuming you have the Zathura document viewer installed at the terminal type:

groff -me -dpaper=a4 complaint.me | zathura -

This command pipes postscript into Zathura's standard input with the following result:

Output directly to print

Assuming a default printer has been set, then we can also send the postcript directly to the printer:

groff -me -dpaper=a4 complaint.me | lp

As with the previous command this instructs groff to format for A4 sized paper.

Output pdf file

The previous commands avoided the use of PDF all together, but if you would rather save in that format, then adding the -T flag indicates you want the output something other than default postscript:

groff -me -dpaper=a4 -T pdf complaint.me > complaint.pdf

Me, me, me?

As groff is very low-level then macro facilities are grouped together into packages to allow routine operations (such as footnotes) to be done efficiently. Me is one of these packages, although far from the only option; in fact a new macro package, -mk, was released this very month. The -me flag on the command line informs groff this notation is being used, likewise the recommended file extension to use is .me.

vim-groff-viewer

If you are a Vim / Neovim user then the vim-groff-viewer plugin wraps these commands into a couple of key mappings so you don't have to leave the comfort of Vim for the command line.

Conclusion

I guess the one obvious question is why use groff at all, as opposed to LaTeX? Possibly because there is something satisfying about learning modern uses for an application whose lineage dates back to 1964. Or maybe just, to paraphrase George Mallory, because it is there? Thoughts, observations? Feel free to add below.

Further References

• How to format academic papers on Linux with groff -me. Gentle introduction to groff and the -me package.
• Writing Papers with NROFF using −me. Introductory paper written by Eric P. Allman, author of the -me package.
• -me Reference Manual. Full reference for -me, again written by Allman.
• groff_me man page. Linux groff_me(7) Miscellaneous Information Manual.
• groff/troff: MUH MINIMALIST Documents Luke Smith's introductory video to groff, though uses the -ms package rather than -me.
• The GNU Troff Manual. The definitive groff manual. However only one sentence on the -me package.