Writing an academic article in 'groff -ms'

Technical and scientific authors can leverage a wide array of tools to write and submit articles. One tool that used to be quite popular is troff, part of the Unix system by Bell Labs. Today, troff is usually implemented as groff, by the GNU Project.

While authors could write technical and scientific articles in troff using low-level “dot commands” such as .br to cause a line break or .ti 4 to create a temporary (first-line) indent of 4 spaces, authors developed macro packages to do the formatting for them. One popular macro package is the -ms macros, from Bell Labs. With the -ms macros, authors use the .TL macro to format the title, the .NH macro to start a section heading, and .PP for a new first-line indented paragraph. For academic journals, authors could add the .2C macro before the first paragraph to format the body as two columns. Technical and scientific authors can also use add-ons like eqn to format equations and pic to draw diagrams and pictures.

Writing an academic article

I wanted to demonstrate how to write an academic article using groff -ms, so I wrote a sample based on a recent article I published about how to calculate pi by counting pixels. This was a follow-up to an article I wrote a few years ago on the same topic. In this sample “academic” paper, I describe how the method to calculate pi by counting pixels is flawed.

More importantly, the paper demonstrates how to use the more advanced features of -ms to format an academic paper, including choosing a new font and font size, defining a new paragraph indent size, and including equations and diagrams. If you want to explore how to write academic papers using groff -ms, use this paper as a guide.

The full source is quite long, at almost 400 lines. I’ve included the first 40 lines as a sample, below. You can download the original source⤓ and process it on your own.

.ds FAM N
.nr PS 12
.nr PI .2i
.TL
Why measuring pi by counting pixels doesn't work
.AU
Jim Hall, MS
.AI
Technically We Write
.AB
This paper explores a naive approach to \*[Q]measure\*[U] the value of pi by
counting pixels on a screen to approximate the circumference.
This approach does not yield the correct value of pi. This paper shows the
flaws in the approach and why the calculated value is similar to but different
from the pi=4 estimation using a square to approximate the circumference. The
paper concludes by demonstrating another program that counts pixels inside a
circle to estimate the area, which results in a more accurate calculation of
pi.
.AE
.2C
.NH
Introduction
.EQ
delim $$
.EN
.PP
I used to write for Opensource.com, and every year on Pi Day (March 14,
or 3/14) various authors would write at least one article about $pi$.
Several years ago, I wrote an article about how to calculate the value of
$pi$ by writing a program to draw a circle to the screen, \*[Q]measuring\*[U]
the circumference of the circle by counting the pixels, then calculating the
value for $pi$ by dividing the circumference by the diameter:
.EQ
C = 2 pi r = pi d
.EN
.LP
the value of $pi$ may be calculated as:
.EQ
pi = C over d
.EN

The first three lines define various parameters for the document. This includes setting the font family to N, or New Century Schoolbook, which is a professional looking font for academic journals. I also set the font size to a more readable 12 point size and defined the paragraph first-line indent to 0.2 inches:

.ds FAM N
.nr PS 12
.nr PI .2i

The next few lines define the title, author, author institution, and abstract:

.TL
Why measuring pi by counting pixels doesn't work
.AU
Jim Hall, MS
.AI
Technically We Write
.AB
This paper explores a naive approach to \*[Q]measure\*[U] the value of pi by
counting pixels on a screen to approximate the circumference.
This approach does not yield the correct value of pi. This paper shows the
flaws in the approach and why the calculated value is similar to but different
from the pi=4 estimation using a square to approximate the circumference. The
paper concludes by demonstrating another program that counts pixels inside a
circle to estimate the area, which results in a more accurate calculation of
pi.
.AE

After the abstract, I defined two-column mode with .2C and wrote the rest of the article body.

Processing the document

To process the document, you can use the groff program with the -Tpdf option to generate a PDF file. However, the pdfroff version of the groff program generates much better PDF files; the PDF files are version 1.7 instead of PDF version 1.4, and the PDF files are smaller. This is the command I used:

$ pdfroff -ms -p -e -U pi.ms > pi.pdf

The -ms option specifies the macro set. (This is actually the s macro set, and the -m option tells groff which macro package to load.) The -p and -e options invoke the pic and eqn groff preprocessors, respectively. Because the article also uses the .PDFPIC macro to insert an image, I needed to add the -U (unsafe) option.

I’ve included an image of page 1 from the article. I’ve also provided the final formatted PDF file if you’d like to read the full copy of the article.

Included files

This article includes external source files for two versions of a C program to calculate pi: pi.c⤓ and pi2.c⤓.

The image is inserted using the .PDFPIC macro. The screenshot was originally a PNG graphic⤓ but needs to be in PDF format so .PDFPIC can use it. I converted the image to PDF format⤓ using the ImageMagick command line program:

$ magick circle200_cropped.png circle200_cropped.pdf