Tyler's Site

Abstract

Some people may be familiar with groff as a typesetting format for man pages, however, groff can also produce PDF documents. These produced documents give a very similar level of control and consistency as something like LaTeX can provide. In this blog post, I will be going over some basics of using groff to produce PDFs though don’t necessarily have a lot of justification as to why one should use it over something like LaTeX or Markdown with pandoc.

Brief History

While groff is the modern program to work with nroff macros, the family tree for groff and related software starts with RUNOFF, which released in 1964 and was one of the earliest text formatting programs. RUNOFF was originally written for the Compatible Time-Sharing System, then was re-written a few times in a few different languages. Fast forward to the 1970’s when Ken Thompson wanted to upgrade the current PDP-7 to a PDP-11 which would be a very expensive upgrade at the time. The justification given to upper management for needing this new system was for word processing, which is where roff came from. It was originally “transliterated” from MAD-assembler to PDP-7 assembler, then transliterated again once they acquired the PDP-11. Some time later, a more flexible language was needed so, nroff or “newer roff” was created and will provide the basis for all future versions of the programs. Another version called Troff was later created to support multiple fonts and proportional spacing. Groff was written in 1990 for the GNU system as a free software implementation of troff, which is still in use today.

Getting started and basics

Working with groff, much like many other typesetting systems, is as easy as opening a text editor and knowing how to run the command to actually convert the text into a document. This article will be focusing on GNU roff (groff) as that is the implementation that I have installed on all of my machines.

This is a very basic document with Groff just to get started and make sure things compile properly. Save the following text into a file called test.ms.

.TL
Test Document
.AU
Tyler Clark
.PP
Hello World!

Then open a terminal and type the following in the same directory as the test.ms file.

groff -ms -Tpdf test.ms > test.pdf

From there, a PDF document should be generated looking as follows:

Groff PDF Document

Now that we have compiled a basic document to make sure that everything is working properly, let’s get into the macros that handle the formatting for the text. groff has a very large variety of macros and even different sets of macros; this post will focus exclusively on the ‘ms’ macros.

.TL
This would be a title

.AU
Author's Name Here

.AB
The abstract section is initiated with the '.AB' and ended with the '.AE'
.AE

.PP
A new paragraph with a serif font is initiated by the '.PP' macro.

.NH 1
Heading
.PP
Headings are initiated by the '.NH' macro with a number following for the level of heading desired.

.NH 2
Subheading
.PP
This heading was followed by a '2' which means that it will be a subheading.
The higher the number following the macro, the more of a subheading it is.

.B
Text can also be bold with '.B'.

.I
Text can be italicized with '.I'.

.BI
The two an be combined for bold italics.

.CW
For monospace fonts, the '.CW' macro can be used.

.PP

Table of contents

.TL
Document with table of contents
.AU
Tyler Clark

.AB
This document will show how to do a table of contents.
.AE

.NH 1
Heading
.XS
Heading
.XE

.PP
This is going to be the first heading for our document with the table of contents.
The heading must be followed by a set of tags '.XS' and '.XE' respectively with the heading in between;
these macros will add the text between them to the table of contents.

.NH 1
Another heading
.XS
Another Heading
.XE

.PP
This will be another heading for the table of contents.
The '.TC' macro provides the table of contents for us.

.TC

What is noteworthy here is that the table of contents macro .TC comes at the end of the document. This is because if it comes at the beginning, it will not find any macros telling it about the headings as they have not occurred in the document yet. However, if we use the same compilation command, the table of contents will be at the end of the document. How do we fix that? Easy, we change the compilation command. There is another utility called pdfroff that is effectively a wrapper around the original groff command that does some nice things, such as moving the table of contents from the end of the document to the beginning. The command looks as follows:

pdfroff test.ms -mspdf > test.pdf

Closing thoughts and more resources

Groff is a very large program that has a lot of other components to add more functionality to it for things like images and math equations. If I were to try to cover all of these topics, this blog post would be massive. So rather, I included a bit to get started, then am also including some more resources to hopefully aide further exploration of groff and its related programs.

Resources for learning and getting better with groff