Making references in groff

I like exploring all kinds of markup systems, and one system I keep going back to is groff, the modern version of the classic Unix nroff and troff. I find writing documents with groff is simple: you use dot commands to control the formatting, like .ll to set the line length, or .sp to add vertical space, or .ti to start a new paragraph with temporary indent (for example, a first-line indent).

With a good macro package, you only need to rely on a limited set of dot commands to control specific formatting like headings, paragraphs, bold, and italic text. The macro package does the rest of the work to format the page itself. I first learned nroff using the me macros in the 1990s, but more recently I’ve started using the ms macro package.

I’ve been exploring the different “power features” in groff. One of these is the refer subsystem to provide references and citations.

References and citations

The refer subsystem is an original AT&T Bell Laboratories extension from classic Unix. The original nroff and troff formatters were created to make it easy to write professional documents such as patent applications, technical reports, and academic papers. When writing these kinds of documents, it can be helpful to insert citations to other works, like other patent applications or other papers.

While the ms macro package supports footnotes by typing \** in a paragraph, immediately followed by .FS and .FE to start and end the footnote text, these footnotes are not really the best fit for making citations to other works. Footnotes are great for providing explanatory detail; citations are a different kind of thing in technical and professional writing.

.ds FAM H
.nr PS 14
.TL
Using footnotes in a report
.PP
This is a demonstration in writing a footnote.\**
.FS
.I Footnotes
are useful when you need to write a short note to
provide additional detail about a topic.
.FE
While a footnote could be used to cite another work,
they are not really meant for this.

Generate the report using groff -ms in the usual way. If you want to create PDF for the output document, I prefer using pdfroff instead, which takes the same options as groff but writes PDF version 1.7 documents instead:

$ pdfroff -ms report.ms > report.pdf

Instead, refer provides a system to look up a reference from a database. The power feature of this system is that you don’t need to provide a complete reference; refer can look up a citation in the database using a partial reference, if that is a unique reference in the database. This makes it really easy to focus on the content of your writing, and leave the “heavy lifting” of references and citations to the refer subsystem.

A sample reference

Let’s say I needed write an academic paper that references other works. In this example, let’s assume just a few sample works:

• “Beyond Footnotes” by Smith, A and Johnson, B.
• “The Plagiarism Paradox” by Jones, X.
• “Citation Soup” by Doe, J; Alice, B; and Harry, T.

1. Create a database

To start, let’s create a database that captures all of the references in a form that the refer subsystem can understand. This database is written in plain text, using % to indicate certain fields, like %A for the author, %T for the title, %D for the publication date, and %J for the published journal. Other fields can include %V for the journal’s volume, %N for the journal number, %P for the pages. You can find a complete list of all the fields in the man refer manual page.

Save this file as report.ref. The name and extension aren’t really important, but I like to use ref as the extension as a reminder that this is a list of references that will be used in citations.

%A Smith, A.
%A Johnson, B.
%D 2019
%T Beyond Footnotes: A Meta-Analysis of Citation as a Form of Communication
%J Journal of Information
%V 6
%N 1
%P 11-16
%O doi.org/xx.xxx/yyyy

%A Jones, X.
%D 1996
%T The Plagiarism Paradox: Why Good Citations are Hard to Find
%J Interdisciplinary Discourse
%V 15
%N 3
%P 5-13

%A Doe, J.
%A Alice, B.
%A Harry, T.
%L doe2018 # a label because "Doe" matches two entries in this file
%D 2018
%T Citation Soup: A Culinary Approach to the Art of Research References
%J Writing Center Journal
%V 37
%N 1
%P 67-98
%O example.edu/stable/26537363

2. Write the report

Now write your report using groff. Here’s a sample report that uses New Century Schoolbook at 14 point, with paragraph indents at 0.2 inches. This sample report contains only a title and paragraph, and doesn’t yet include citations, but it’s a good starting point:

.ds FAM N
.nr PS 14
.nr PI .2i
.TL
Title of the report
.PP
This is a sample report that shows how to use citations.
For example, Jones wrote that citations provide authenticity.
Smith and Johnson said that citations are important,
and Doe,
.I "et al"
wrote that citations help with academic standing.

The classic way to process the document using refer is to use refer as a separate command and pipe the output to groff or pdfroff for final processing. However, groff or pdfroff can run the refer pre-processor for you with the -R option:

$ pdfroff -R -ms report.ms > report.pdf

3. Connect to the database

Provide instructions to refer using the .R1 and .R2 macros at the top of the groff source file. At a minimum, you only need to provide the name of the database file, using the database instruction. To cite the sources listed in the database, use .[ and .] in the document where you want to insert a reference. The citation can be incomplete, enough to identify an entry from the database. In this example, the authors are all unique, so we only need to reference the name of an author of each work:

.R1
database report.ref
.R2
.ds FAM N
.nr PS 14
.nr PI .2i
.TL
Title of the report
.PP
This is a sample report that shows how to use citations.
For example, Jones wrote that citations provide authenticity.
.[
Jones
.]
Smith and Johnson said that citations are important,
.[
Smith
.]
and Doe,
.I "et al"
wrote that citations help with academic standing.
.[
Doe
.]

By default, the citations are inserted as footnotes, as each reference is made:

4. Format the citations

You can give other instructions to refer to control the formatting of citations. For example, I prefer to collect my citations as end notes using the accumulate keyword, and sorted alphabetically by author with the sort A instruction. I also change the label using specific formatting that mimics APA citations. Here’s the report with these extra refer controls:

.R1
database report.ref
accumulate
sort A
label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
no-label-in-reference
.R2
.ds FAM N
.nr PS 14
.nr PI .2i
.TL
Title of the report
.PP
This is a sample report that shows how to use citations.
For example, Jones wrote that citations provide authenticity.
.[
Jones
.]
Smith and Johnson said that citations are important,
.[
Smith
.]
and Doe,
.I "et al"
wrote that citations help with academic standing.
.[
Doe
.]

This collects the citations at the end of the document, with each citation listed as the author name and publication date:

Making references in groff

With groff and refer, inserting citations to other documents is easy. Explore what this can do for you by reading the system manual page:

$ man refer