{"id":66260,"date":"2022-08-06T09:01:48","date_gmt":"2022-08-06T09:01:48","guid":{"rendered":"https:\/\/www.cryptocabaret.com\/?p=66260"},"modified":"2022-08-06T09:01:48","modified_gmt":"2022-08-06T09:01:48","slug":"old-school-technical-writing-with-groff","status":"publish","type":"post","link":"https:\/\/www.cryptocabaret.com\/?p=66260","title":{"rendered":"Old-school technical writing with groff"},"content":{"rendered":"

Old-school technical writing with groff<\/span>
\nJim Hall<\/a><\/span>
\nSat, 08\/06\/2022 – 03:00<\/span><\/p>\n

\n
Register<\/a> or Login<\/a> to like<\/div>\n
Register<\/a> or Login<\/a> to like<\/div>\n<\/div>\n
\n

One of my favorite stories about Unix is how it turned into a text processing system. Brian Kernighan tells the story in his book<\/a> 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.<\/p>\n

That new formatting system was called nroff<\/code>, 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.”<\/p>\n

Basic formatting with nroff<\/h2>\n

By default, nroff<\/code>\u00a0collects words and fills paragraphs. When nroff<\/code>\u00a0encounters a blank line, it starts a new paragraph. For example, start with this article’s introduction, which is only a few paragraphs long:<\/p>\n

\n
$ cat intro
\nOld-school technical writing with groff
\nJim Hall
\n\u00a0
\nOne of my favorite stories about Unix is how it turned
\ninto a text processing system. Brian Kernighan tells the
\nstory in his book Unix: A History and a Memoir (chapter 3)
\nbut to summarize:
\nThe Unix team at Bell Labs ran the original Unix on
\na PDP-7 computer, but it was a tiny system and didn't
\nhave sufficient resources to support new work. So Ken
\nThompson and others lobbied to purchase a new PDP-11
\ncomputer. Management denied the request. Around the same
\ntime, the Patents department planned to buy a new computer
\nplatform to produce patent applications using proprietary
\ndocument formatting software. The Unix group proposed
\nthat the Patents department instead buy a new PDP-11 for
\nthe Unix team, and the Unix team would create formatting
\nsoftware for them.
\n\u00a0
\nThat new formatting system was called nroff, short for
\n\"New Roff,\" an updated version of a text formatting program
\ncalled Roff from a 1960s computer system. The name Roff
\ncame from the old expression, \"I'll run off a document.\"<\/div><\/div><\/pre>\n
If you process this file with nroff<\/code>, lines are “glued” together so the output is paragraphs with full justification. Using nroff<\/code> also hyphenates words, if that helps balance lines in the text:<\/p>\n
\n
$ nroff intro | head
\nOld\u2010school technical writing with groff Jim Hall
\n\u00a0
\nOne \u00a0of \u00a0my \u00a0favorite \u00a0stories about Unix is how it turned into a
\ntext processing system. Brian Kernighan tells the \u00a0story \u00a0in \u00a0his
\nbook \u00a0Unix: \u00a0A History and a Memoir (chapter 3) but to summarize:
\nThe Unix team at Bell Labs ran the original Unix on a PDP\u20107 \u00a0com\u2010
\nputer, \u00a0but \u00a0it \u00a0was a tiny system and didn\u2019t have sufficient re\u2010
\nsources to support new work. So Ken Thompson and \u00a0others \u00a0lobbied
\nto purchase a new PDP\u201011 computer. Management denied the request.
\nAround the same time, the Patents department planned to buy a new<\/div><\/div><\/pre>\n
Original Unix systems used a typewriter-style printer that used 66 lines of 80 columns on a US Letter page, and nroff<\/code> 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<\/code> command to show just the first few lines of output because my sample text isn’t very long.<\/p>\n
Breaking lines and centering text<\/h2>\n
The first two lines were meant to be separate lines of text. You can insert a formatting instruction to tell nroff<\/code> to add a line break. All nroff<\/code> instructions start with a dot, followed by a brief command. To add a line break, use the .br<\/code> instruction between the first and second line:<\/p>\n
\nOld-school technical writing with groff\n.br\nJim Hall<\/code><\/pre>\n
When you process this new file, nroff<\/code> prints the title and author on separate lines:<\/p>\n
\n
$ nroff intro | head 
\nOld\u2010school technical writing with groff
\nJim Hall
\n\u00a0
\nOne \u00a0of \u00a0my \u00a0favorite \u00a0stories about Unix is how it turned into a
\ntext processing system. Brian Kernighan tells the \u00a0story \u00a0in \u00a0his
\nbook \u00a0Unix: \u00a0A History and a Memoir (chapter 3) but to summarize:
\nThe Unix team at Bell Labs ran the original Unix on a PDP\u20107 \u00a0com\u2010
\nputer, \u00a0but \u00a0it \u00a0was a tiny system and didn\u2019t have sufficient re\u2010
\nsources to support new work. So Ken Thompson and \u00a0others \u00a0lobbied
\nto purchase a new PDP\u201011 computer. Management denied the request.<\/div><\/div><\/pre>\n
You can add other formatting to make this document look better. To center the top two lines, use the .ce<\/code> formatting request. This takes a number argument, to indicate how many lines nroff<\/code> should center. Here, you can center the top two output lines with the .ce 2<\/code> request:<\/p>\n
\n.ce 2\nOld-school technical writing with groff\n.br\nJim Hall<\/code><\/pre>\n
With this added instruction, nroff<\/code>\u00a0correctly centers the first two lines:<\/p>\n
\n
$ nroff intro | head 
\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0Old\u2010school technical writing with groff
\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 Jim Hall
\n\u00a0
\nOne \u00a0of \u00a0my \u00a0favorite \u00a0stories about Unix is how it turned into a
\ntext processing system. Brian Kernighan tells the \u00a0story \u00a0in \u00a0his
\nbook \u00a0Unix: \u00a0A History and a Memoir (chapter 3) but to summarize:
\nThe Unix team at Bell Labs ran the original Unix on a PDP\u20107 \u00a0com\u2010
\nputer, \u00a0but \u00a0it \u00a0was a tiny system and didn\u2019t have sufficient re\u2010
\nsources to support new work. So Ken Thompson and \u00a0others \u00a0lobbied
\nto purchase a new PDP\u201011 computer. Management denied the request.<\/div><\/div><\/pre>\n<\/p>\n
\n
More Linux resources<\/div>\n
\n
Linux commands cheat sheet<\/a><\/div>\n
Advanced Linux commands cheat sheet<\/a><\/div>\n
Free online course: RHEL technical overview<\/a><\/div>\n
Linux networking cheat sheet<\/a><\/div>\n
SELinux cheat sheet<\/a><\/div>\n
Linux common commands cheat sheet<\/a><\/div>\n
What are Linux containers?<\/a><\/div>\n
Our latest Linux articles<\/a><\/div>\n<\/p><\/div>\n<\/p><\/div>\n
Adding page margins<\/h2>\n
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<\/code> request, with the number of blank lines to add:<\/p>\n
\n
.sp 5
\n.ce 2
\nOld-school technical writing with groff
\n.br
\nJim Hall<\/div><\/div><\/pre>\n
By default, nroff<\/code> 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<\/code> request:<\/p>\n
\n
.po 7
\n.sp 5
\n.ce 2
\nOld-school technical writing with groff
\n.br
\nJim Hall<\/div><\/div><\/pre>\n
Processing the new file with nroff<\/code> produces a plain text page that’s ready to print:<\/p>\n
\n$ nroff intro | head\n \n \n \n \n \n                    Old\u2010school technical writing with groff\n                                   Jim Hall\n \n       One  of  my  favorite  stories about Unix is how it turned into a\n       text processing system. Brian Kernighan tells the  story  in  his<\/code><\/pre>\n
Printing to a laser printer<\/h2>\n
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<\/code> to become the typesetter-specific troff<\/code> program, and a few years later updated it again to become ditroff<\/code>, the device-independent version of troff<\/code>.<\/p>\n
Linux systems provide modern versions of nroff<\/code> and troff<\/code> using the GNU groff<\/code> program. You can still use the old nroff<\/code> program name to generate plain text output, or troff<\/code> to produce ditroff<\/code>compatible output. Using the groff<\/code> program, you can also prepare documents for other kinds of output files, such as Postscript.<\/p>\n
You can process the same input file using groff<\/code>to print on a Postscript-compatible laser printer by selecting a suitable output type using the -T<\/code> option, such as -Tps<\/code> to generate a Postscript file. For example, I can print to a printer with the lpr<\/code> command<\/a> and the HP_LaserJet_CP1525nw<\/code> device, because that’s how my Linux system recognizes my laser printer<\/a>:<\/p>\n
\n$ groff -Tps intro | lpr -P \"HP_LaserJet_CP1525nw\"<\/code><\/span><\/pre>\n
Generating other kinds of output<\/h2>\n
If you instead want to save the output as a PDF file, you can convert the Postscript using the ps2pdf<\/code> tool:<\/p>\n
\n$ groff -Tps intro | ps2pdf - > intro.pdf<\/code><\/span><\/pre>\n
To generate a web page from the same file, use -Thtml<\/code> to set the output type to HTML:<\/p>\n
\n$ groff -Thtml intro > index.html<\/code><\/span><\/pre>\n
The groff<\/code> 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<\/code> implementations of nroff<\/code> and troff<\/code>, refer to chapter 5 in the The GNU Troff Manual<\/a>.<\/p>\n
Formatting documents using these built-in commands takes a lot of effort to keep everything looking the same. Technical writers who use groff<\/code> instead use a collection of formatting requests called macros<\/em>, 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<\/a> on Opensource.com.<\/p>\n<\/div>\n
\n
Take a trip back in time to experience text formatting from a bygone era.<\/p>\n<\/div>\n
\n
\n
  \"Compute<\/div>\n
Image by: <\/span><\/p>\n
LSE Library. Modified by Opensource.com. CC BY-SA 4.0<\/p>\n<\/div>\n<\/article>\n<\/div>\n
\n
Linux<\/a><\/div>\n<\/p><\/div>\n
What to read next<\/div>\n

\n        \"Creative<\/a>This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.<\/div>\n
\n
\n
Register<\/a> or Login<\/a> to post a comment.<\/div>\n<\/p><\/div>\n<\/section>\n
Powered by WPeMatico<\/a><\/small><\/p>\n","protected":false},"excerpt":{"rendered":"
Old-school technical writing with groff Jim Hall Sat, 08\/06\/2022 – 03:00 Register or Login to like Register or Login to like 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 […]<\/p>\n","protected":false},"author":1,"featured_media":66261,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[307],"tags":[],"class_list":["post-66260","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-open-source"],"_links":{"self":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts\/66260","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=66260"}],"version-history":[{"count":0,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/posts\/66260\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=\/wp\/v2\/media\/66261"}],"wp:attachment":[{"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=66260"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=66260"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.cryptocabaret.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=66260"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}