TranslateProject/sources/tech/20220806 Old-school technical writing with groff.md

[#]: subject: "Old-school technical writing with groff"
[#]: via: "https://opensource.com/article/22/8/old-school-technical-writing-groff"
[#]: author: "Jim Hall https://opensource.com/users/jim-hall"
[#]: collector: "lkxed"
[#]: translator: " "
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "

Old-school technical writing with groff
======
Take a trip back in time to experience text formatting from a bygone era.

![Compute like it's 1989][1]

Image by: LSE Library. Modified by Opensource.com. CC BY-SA 4.0

One of my favorite stories about Unix is how it turned into a text processing system. Brian Kernighan [tells the story in his book][2] Unix: A History and a Memoir (chapter 3) but to summarize: The Unix team at Bell Labs ran the original Unix on a PDP-7 computer, but it was a tiny system and didn't have sufficient resources to support new work. So Ken Thompson and others lobbied to purchase a new PDP-11 computer. Management denied the request. Around the same time, the Patents department planned to buy a new computer platform to produce patent applications using proprietary document formatting software. The Unix group proposed that the Patents department instead buy a new PDP-11 for the Unix team, and the Unix team would create formatting software for them.

That new formatting system was called `nroff`, short for "New Roff," an updated version of a text formatting program called Roff from a 1960s computer system. The name Roff came from the old expression, "I'll run off a document."

### Basic formatting with nroff

By default, `nroff`  collects words and fills paragraphs. When `nroff`  encounters a blank line, it starts a new paragraph. For example, start with this article's introduction, which is only a few paragraphs long:

```
$ cat intro
Old-school technical writing with groff
Jim Hall
 
One of my favorite stories about Unix is how it turned
into a text processing system. Brian Kernighan tells the
story in his book Unix: A History and a Memoir (chapter 3)
but to summarize:
The Unix team at Bell Labs ran the original Unix on
a PDP-7 computer, but it was a tiny system and didn't
have sufficient resources to support new work. So Ken
Thompson and others lobbied to purchase a new PDP-11
computer. Management denied the request. Around the same
time, the Patents department planned to buy a new computer
platform to produce patent applications using proprietary
document formatting software. The Unix group proposed
that the Patents department instead buy a new PDP-11 for
the Unix team, and the Unix team would create formatting
software for them.
 
That new formatting system was called nroff, short for
"New Roff," an updated version of a text formatting program
called Roff from a 1960s computer system. The name Roff
came from the old expression, "I'll run off a document."
```

If you process this file with `nroff`, lines are "glued" together so the output is paragraphs with full justification. Using `nroff` also hyphenates words, if that helps balance lines in the text:

```
$ nroff intro | head
Old‐school technical writing with groff Jim Hall
 
One  of  my  favorite  stories about Unix is how it turned into a
text processing system. Brian Kernighan tells the  story  in  his
book  Unix:  A History and a Memoir (chapter 3) but to summarize:
The Unix team at Bell Labs ran the original Unix on a PDP‐7  com‐
puter,  but  it  was a tiny system and didn’t have sufficient re‐
sources to support new work. So Ken Thompson and  others  lobbied
to purchase a new PDP‐11 computer. Management denied the request.
Around the same time, the Patents department planned to buy a new
```

Original Unix systems used a typewriter-style printer that used 66 lines of 80 columns on a US Letter page, and `nroff` makes the same assumptions. It also adds empty lines so each page of output is 66 lines per page, but I've used the `head` command to show just the first few lines of output because my sample text isn't very long.

### Breaking lines and centering text

The first two lines were meant to be separate lines of text. You can insert a formatting instruction to tell `nroff` to add a line break. All `nroff` instructions start with a dot, followed by a brief command. To add a line break, use the `.br` instruction between the first and second line:

```
Old-school technical writing with groff
.br
Jim Hall
```

When you process this new file, `nroff` prints the title and author on separate lines:

```
$ nroff intro | head 
Old‐school technical writing with groff
Jim Hall
 
One  of  my  favorite  stories about Unix is how it turned into a
text processing system. Brian Kernighan tells the  story  in  his
book  Unix:  A History and a Memoir (chapter 3) but to summarize:
The Unix team at Bell Labs ran the original Unix on a PDP‐7  com‐
puter,  but  it  was a tiny system and didn’t have sufficient re‐
sources to support new work. So Ken Thompson and  others  lobbied
to purchase a new PDP‐11 computer. Management denied the request.
```

You can add other formatting to make this document look better. To center the top two lines, use the `.ce` formatting request. This takes a number argument, to indicate how many lines `nroff` should center. Here, you can center the top two output lines with the `.ce 2` request:

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

With this added instruction, `nroff`  correctly centers the first two lines:

```
$ nroff intro | head 
             Old‐school technical writing with groff
                            Jim Hall
 
One  of  my  favorite  stories about Unix is how it turned into a
text processing system. Brian Kernighan tells the  story  in  his
book  Unix:  A History and a Memoir (chapter 3) but to summarize:
The Unix team at Bell Labs ran the original Unix on a PDP‐7  com‐
puter,  but  it  was a tiny system and didn’t have sufficient re‐
sources to support new work. So Ken Thompson and  others  lobbied
to purchase a new PDP‐11 computer. Management denied the request.
```

### Adding page margins

Printing this to a printer results in text starting on the first line of the page, and against the left edge. To add a few lines of extra space from the top of the page, use the `.sp` request, with the number of blank lines to add:

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

By default, `nroff` formats the output so each line is 65 columns wide. Printing to an 80 column US Letter page leaves 15 empty columns. Adding 7 spaces on the left side neatly balances the output with equal left and right page margins. You can create this page offset using the `.po 7` request:

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

Processing the new file with `nroff` produces a plain text page that's ready to print:

```
$ nroff intro | head
 
 
 
 
 
                    Old‐school technical writing with groff
                                   Jim Hall
 
       One  of  my  favorite  stories about Unix is how it turned into a
       text processing system. Brian Kernighan tells the  story  in  his
```

### Printing to a laser printer

Later, the Unix team at Bell Labs acquired a phototypesetting machine, capable of producing printed text similar to a laser printer. To support the typesetter's new capabilities, the Unix team updated `nroff` to become the typesetter-specific `troff` program, and a few years later updated it again to become `ditroff`, the device-independent version of `troff`.

Linux systems provide modern versions of `nroff` and `troff` using the GNU `groff` program. You can still use the old `nroff` program name to generate plain text output, or `troff` to produce `ditroff` compatible output. Using the `groff` program, you can also prepare documents for other kinds of output files, such as Postscript.

You can process the same input file using `groff` to print on a Postscript-compatible laser printer by selecting a suitable output type using the `-T` option, such as `-Tps` to generate a Postscript file. For example, I can print to a printer with the [lpr command][3] and the `HP_LaserJet_CP1525nw` device, because that's how my Linux system [recognizes my laser printer][4]:

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

### Generating other kinds of output

If you instead want to save the output as a PDF file, you can convert the Postscript using the `ps2pdf` tool:

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

To generate a web page from the same file, use `-Thtml` to set the output type to HTML:

```
$ groff -Thtml intro > index.html
```

The `groff` command supports lots of other built-in formatting requests to provide other kinds of document formatting. If you want to learn the other default formatting requests available to you in the GNU `groff` implementations of `nroff` and `troff`, refer to chapter 5 in the [The GNU Troff Manual][5].

Formatting documents using these built-in commands takes a lot of effort to keep everything looking the same. Technical writers who use `groff` instead use a collection of formatting requests called *macros*, which provide their own commands to generate section headings, paragraphs, block quotes, footnotes, lists, and other useful document formatting. To learn more about one popular macro package, read [How to format academic papers on Linux with groff -me][6] on Opensource.com.

--------------------------------------------------------------------------------

via: https://opensource.com/article/22/8/old-school-technical-writing-groff

作者：[Jim Hall][a]
选题：[lkxed][b]
译者：[译者ID](https://github.com/译者ID)
校对：[校对者ID](https://github.com/校对者ID)

本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出

[a]: https://opensource.com/users/jim-hall
[b]: https://github.com/lkxed
[1]: https://opensource.com/sites/default/files/lead-images/1980s-computer-yearbook.png
[2]: https://opensource.com/article/20/8/unix-history
[3]: https://opensource.com/article/21/9/print-files-linux
[4]: https://opensource.com/article/18/3/print-server-raspberry-pi
[5]: https://www.gnu.org/software/groff/manual/groff.html#gtroff-Reference
[6]: https://opensource.com/article/18/2/writing-academic-papers-groff-me