A Linux and Unix experiment – Part 2: Preparing a document using nroff

Here's what preparing a document using nroff was like using Unix from fifty years ago.

This article is a part of a series called “A throwback experiment with Linux and Unix.” Read the Introduction and set-up and part 1 of the series.

For my “throwback” experiment, I wanted to demonstrate that you can still do real work on Linux, using just a terminal and the command line, just like the original Unix.

As a proof of concept, I worked for a week in Linux like it was Unix from fifty years ago. During this experiment, I assigned myself three tasks. The second task was to prepare a document using nroff. This is my experience.

For reference, I’ve included a list of all user commands in Unix 4th edition.

---

Unix 4th edition commands reference guide

---

Prepare a document using nroff

My favorite story about early Unix is how it added the nroff document markup system. The short version of that story is the Unix team wanted to buy a new computer to work on the next version of Unix, but management said “No.” At around that time, the Legal team planned to purchase a new system they could use to write patent applications, but the software wasn’t ready yet.

The Unix team cut a deal: The Legal team would purchase a new computer for the Unix team, and the Unix team would update the existing roff document markup system to support the specific formatting to write patent applications.

And that’s why Unix added the nroff (“new roff”) document preparation system. But nroff only worked on typewriter-like output devices, such as the TeleType terminal. An author could use a program called type to print out a document formatted by nroff, on separate US Letter pages, as though it had been typed on a typewriter.

Later, the Unix team purchased a phototypesetter, and they updated nroff to become troff (“typesetter roff”).

Modern Linux systems use groff as a replacement for both nroff and troff. With groff, an author might start a new paragraph by adding a single line of blank space:

.sp 1

To add a temporary indent of 4 spaces, you can add this instruction:

.ti 4

When writing documents, you can expect to start many new paragraphs, so it usually makes sense to use a macro package with these common commands in them. In nroff and troff, you can define a new macro with the .de instruction, such as this to define a macro called PP to start a new first-line indented paragraph:

.de PP
.sp 1
.ti 4
..

Rather than write these macros yourself, the Unix team created a common set of macros that nroff or troff could load using the -m command line option. Technical writers at Bell Labs used the s macro package, referenced as -ms on the command line. And that’s how I wrote a new document, written in nroff -ms, using the ed editor:

$ ed paper.ms

Read more: Getting started with the Unix ‘ed’ editor

Let’s start with a simple document, explaining the format of a research paper. To add the title, use the .TL instruction, and add the title on the line after it. To include your name as an author, use the .AU instruction, and your name on the line after it. Since we’re editing in ed, start inserting new lines with the i command:

i
.TL
What is a research paper?
.AU
Jim Hall
.

You can insert a numbered heading with the .NH macro, optionally with a number. For example, .NH 1 creates a major heading (“first-level heading”), and .NH 2 defines a subheading (“second-level heading”), and so on for other numbers. Without a number, the .NH macro assumes 1 for a major heading.

a
.NH
Introduction
.

If you don’t want a numbered heading, you can use the .SH macro instead. This is the same as .NH but doesn’t print a number.

The -ms macros provide two kinds of regular paragraphs: .LP to create left-aligned paragraphs and .PP for first-line indented paragraphs. Formal technical documents usually start with a left-aligned paragraph after a heading or subheading, and first-line indented paragraphs after that. For this reason, I usually associate .LP with “leading paragraph” because it’s the first paragraph after a heading.

Let’s add a brief paragraph that describes a research paper. Formal research papers use an IMRaD outline: Introduction, Methods, Results, and Discussion.

a
.PP
In a research paper that follows typical IMRaD
organization, you should start with an introduction, 
followed by a description of your methods, then an overview of your results,
Analyze your findings in the discussion section,
and make any recommendations for your reader.
.

While writing that, I realized I made a mistake on the third line of the paragraph; I used a comma instead of a period. To fix this, use ? to search backwards for then line, then s to swap the comma for a period:

?results,
followed by a description of your methods, then an overview of your results,
s/,$/./ 
p
followed by a description of your methods, then an overview of your results.

The s (swap) command uses regular expressions. For example, ^ matches the start of a line, and $ matches the end of a line. Using ,$ as my search text matched a comma at the end of a line.

The -ms macros also support text formatting like bold with .B and italic text with the .I macro. Let’s set the IMRaD acronym in italic text. To do that, we need to remove IMRaD from the end of the line, and add a new line after it that uses the .I macro for italic text:

?IMRaD
In a research paper that follows typical IMRaD
s/IMRaD//
a
.I IMRaD
.
-2,.p
.PP
In a research paper that follows typical 
.I IMRaD

The s/IMRaD// swaps the IMRaD text with nothing, effectively deleting it. Then the a command appended new lines of text, ending with . on a line by itself. After that, I printed the results of the edit with -2,.p to print (p) starting two lines above the current line (-2) and ending at the current line (.).

If I wanted to use bold type instead, I can swap the .I instruction for .B like this:

s/I/B/
p
.B IMRaD

And from there, I finished the paragraph, leaving me with this nroff file:

.TL
What is a research paper?
.AU
Jim Hall
.NH
Introduction
.LP
In a research paper that follows typical
.B IMRaD
organization, you should start with an introduction,
followed by a description of your methods, then an overview of your results.
Analyze your findings in the discussion section,
and make any recommendations for your reader.

On original Unix systems, you could use nroff to produce output suitable for a typewriter-like device, such as a TeleType terminal or a video terminal. On modern Linux systems, the groff package includes an nroff command that acts like the classic nroff:

$ nroff -ms paper.ms > paper.txt

Starting with Unix 4th Edition, you could use troff to generate output for a phototypesetter. We don’t have phototypesetters in 2024; instead, we would likely generate a PDF file for viewing locally, or a PostScript file for printing. The groff command acts like the classic troff, and creates PostScript files by default:

$ groff -ms paper.ms > paper.ps

More from We Love Open Source

• Read: A throwback experiment with Linux and Unix: Introduction and set-up
• Read part one of this tutorial series: Writing a FORTRAN 66 program
• Read part three of this tutorial series: Writing several C programs
• Read: Technology history: Where Unix came from