BreakingExpress

Old-school technical writing with groff

One of my favourite tales about Unix is the way it became a textual content processing system. Brian Kernighan tells the story in his book Unix: A History and a Memoir (chapter 3) however to summarize: The Unix workforce at Bell Labs ran the unique Unix on a PDP-7 laptop, but it surely was a tiny system and did not have enough sources to help new work. So Ken Thompson and others lobbied to buy a brand new PDP-11 laptop. Management denied the request. Around the identical time, the Patents division deliberate to purchase a brand new laptop platform to supply patent functions utilizing proprietary doc formatting software program. The Unix group proposed that the Patents division as a substitute purchase a brand new PDP-11 for the Unix workforce, and the Unix workforce would create formatting software program for them.

That new formatting system was referred to as nroff, quick for “New Roff,” an up to date model of a textual content formatting program referred to as Roff from a Sixties laptop system. The identify Roff got here from the previous expression, “I’ll run off a document.”

Basic formatting with nroff

By default, nroff collects phrases and fills paragraphs. When nroff encounters a clean line, it begins a brand new paragraph. For instance, begin with this text’s introduction, which is only some paragraphs lengthy:

$ cat intro
Old-school technical writing with groff
Jim Hall
 
One of my favourite tales about Unix is the way it turned
right into a textual content processing system. Brian Kernighan tells the
story in his guide Unix: A History and a Memoir (chapter 3)
however to summarize:
The Unix workforce at Bell Labs ran the unique Unix on
a PDP-7 laptop, but it surely was a tiny system and did not
have enough sources to help new work. So Ken
Thompson and others lobbied to buy a brand new PDP-11
laptop. Management denied the request. Around the identical
time, the Patents division deliberate to purchase a brand new laptop
platform to supply patent functions utilizing proprietary
doc formatting software program. The Unix group proposed
that the Patents division as a substitute purchase a brand new PDP-11 for
the Unix workforce, and the Unix workforce would create formatting
software program for them.
 
That new formatting system was referred to as nroff, quick for
"New Roff," an up to date model of a textual content formatting program
referred to as Roff from a Sixties laptop system. The identify Roff
got here from the previous expression, "I'll run off a document."

If you course of this file with nroff, strains are “glued” collectively so the output is paragraphs with full justification. Using nroff additionally hyphenates phrases, if that helps steadiness strains within the textual content:

$ nroff intro | head
Old‐college technical writing with groff Jim Hall
 
One  of  my  favourite  tales about Unix is the way it became a
textual content processing system. Brian Kernighan tells the  story  in  his
guide  Unix:  A History and a Memoir (chapter 3) however to summarize:
The Unix workforce at Bell Labs ran the unique Unix on a PDP‐7  com‐
puter,  however  it  was a tiny system and didn’t have enough re‐
sources to help new work. So Ken Thompson and  others  lobbied
to buy a brand new PDP‐11 laptop. Management denied the request.
Around the identical time, the Patents division deliberate to purchase a brand new

Original Unix methods used a typewriter-style printer that used 66 strains of 80 columns on a US Letter web page, and nroff makes the identical assumptions. It additionally provides empty strains so every web page of output is 66 strains per web page, however I’ve used the head command to point out simply the primary few strains of output as a result of my pattern textual content is not very lengthy.

Breaking strains and centering textual content

The first two strains had been meant to be separate strains of textual content. You can insert a formatting instruction to inform nroff so as to add a line break. All nroff directions begin with a dot, adopted by a short command. To add a line break, use the .br instruction between the primary and second line:

Old-school technical writing with groff
.br
Jim Hall

When you course of this new file, nroff prints the title and writer on separate strains:

$ nroff intro | head
Old‐college technical writing with groff
Jim Hall
 
One  of  my  favourite  tales about Unix is the way it became a
textual content processing system. Brian Kernighan tells the  story  in  his
guide  Unix:  A History and a Memoir (chapter 3) however to summarize:
The Unix workforce at Bell Labs ran the unique Unix on a PDP‐7  com‐
puter,  however  it  was a tiny system and didn’t have enough re‐
sources to help new work. So Ken Thompson and  others  lobbied
to buy a brand new PDP‐11 laptop. Management denied the request.

You can add different formatting to make this doc look higher. To heart the highest two strains, use the .ce formatting request. This takes a quantity argument, to point what number of strains nroff ought to heart. Here, you’ll be able to heart the highest two output strains with the .ce 2 request:

.ce 2
Old-school technical writing with groff
.br
Jim Hall

With this added instruction, nroff appropriately facilities the primary two strains:

$ nroff intro | head
             Old‐college technical writing with groff
                            Jim Hall
 
One  of  my  favourite  tales about Unix is the way it became a
textual content processing system. Brian Kernighan tells the  story  in  his
guide  Unix:  A History and a Memoir (chapter 3) however to summarize:
The Unix workforce at Bell Labs ran the unique Unix on a PDP‐7  com‐
puter,  however  it  was a tiny system and didn’t have enough re‐
sources to help new work. So Ken Thompson and  others  lobbied
to buy a brand new PDP‐11 laptop. Management denied the request.

Adding web page margins

Printing this to a printer ends in textual content beginning on the primary line of the web page, and towards the left edge. To add a number of strains of additional house from the highest of the web page, use the .sp request, with the variety of clean strains so as to add:

.sp 5
.ce 2
Old-school technical writing with groff
.br
Jim Hall

By default, nroff codecs the output so every line is 65 columns broad. Printing to an 80 column US Letter web page leaves 15 empty columns. Adding 7 areas on the left facet neatly balances the output with equal left and proper web page margins. You can create this web page offset utilizing the .po 7 request:

.po 7
.sp 5
.ce 2
Old-school technical writing with groff
.br
Jim Hall

Processing the brand new file with nroff produces a plain textual content web page that is able to print:

$ nroff intro | head
 
 
 
 
 
                    Old‐college technical writing with groff
                                   Jim Hall
 
       One  of  my  favourite  tales about Unix is the way it became a
       textual content processing system. Brian Kernighan tells the  story  in  his

Printing to a laser printer

Later, the Unix workforce at Bell Labs acquired a phototypesetting machine, able to producing printed textual content much like a laser printer. To help the typesetter’s new capabilities, the Unix workforce up to date nroff to turn out to be the typesetter-specific troff program, and some years later up to date it once more to turn out to be ditroff, the device-independent model of troff.

Linux methods present fashionable variations of nroff and troff utilizing the GNU groff program. You can nonetheless use the previous nroff program identify to generate plain textual content output, or troff to supply ditroffsuitable output. Using the groff program, it’s also possible to put together paperwork for different kinds of output information, reminiscent of Postscript.

You can course of the identical enter file utilizing groffto print on a Postscript-compatible laser printer by deciding on an acceptable output sort utilizing the -T choice, reminiscent of -Tps to generate a Postscript file. For instance, I can print to a printer with the lpr command and the HP_LaserJet_CP1525nw system, as a result of that is how my Linux system recognizes my laser printer:

$ groff -Tps intro | lpr -P "HP_LaserJet_CP1525nw"

Generating other forms of output

If you as a substitute wish to save the output as a PDF file, you’ll be able to convert the Postscript utilizing the ps2pdf software:

$ groff -Tps intro | ps2pdf - > intro.pdf

To generate an online web page from the identical file, use -Thtml to set the output sort to HTML:

$ groff -Thtml intro > index.html

The groff command helps plenty of different built-in formatting requests to offer other forms of doc formatting. If you wish to study the opposite default formatting requests out there to you within the GNU groff implementations of nroff and troff, consult with chapter 5 within the The GNU Troff Manual.

Formatting paperwork utilizing these built-in instructions takes numerous effort to maintain every little thing trying the identical. Technical writers who use groff as a substitute use a group of formatting requests referred to as macros, which give their very own instructions to generate part headings, paragraphs, block quotes, footnotes, lists, and different helpful doc formatting. To study extra about one well-liked macro bundle, learn How to format academic papers on Linux with groff -me on Opensource.com.

Exit mobile version