All the major Unix documentation formats except the very newest
one are presentation-level markups assisted by macro packages. We
examine them here from oldest to newest.
troff and the Documenter's
Workbench Tools
We discussed the Documenter's Workbench architecture and tools
in Chapter8 as an
example of how to integrate a system of multiple minilanguages. Now
we return to these tools in their functional role as a typesetting
system.
The troff formatter interprets a
presentation-level markup language. Recent implementations like the
GNU project's
groff(1)
emit PostScript by default, though it is possible to get other forms
of output by selecting a suitable driver. See Example18.1 for several of the
troff codes you might encounter in document
sources.
Example18.1.groff(1) markup example.
This is running text.
.\" Comments begin with a backslash and double quote.
.ft B
This text will be in bold font.
.ft R
This text will be back in the default (Roman) font.
These lines, going back to "This is running text", will
be formatted as a filled paragraph.
.bp
The bp request forces a new page and a paragraph break.
This line will be part of the second filled paragraph.
.sp 3
The .sp request emits the number of blank lines given as argument
.nf
The nf request switches off paragraph filling.
Until the fi request switches it back on
whitespace and layout will be preserved.
One word in this line will be in \fBbold\fR font.
.fi
Paragraph filling is back on.
troff(1)
has many other requests, but you are unlikely to see most of them
directly. Very few documents are written in bare
troff. It supports a macro facility, and
half a dozen macro packages are in more or less general use. Of
these, the overwhelmingly most common is the
man(7)
macro package used to write Unix manual pages. See Example18.2 for a sample.
Example18.2.man markup example.
.SH SAMPLE SECTION
The SH macro starts a section, boldfacing the section title.
.P
The P request starts a new paragraph. The I request sets its
argument in
.I italics.
.IP *
This starts an indented paragraph with an asterisk label.
More text for the first bulleted paragraph.
.TP
This first line will become a paragraph label
This will be the first line in the paragraph, further indented
relative to the label.
The blank line just above this is treated almost exactly like a
paragraph break (actually, like the troff-level request .sp 1).
.SS A subsection
This is subsection text.
Two of the other half-dozen historical
troff macro libraries,
ms(7)
and
mm(7)
are still in use. BSD Unix has its own elaborate
extended macro set,
mdoc(7).
All these are designed for writing technical manuals and long-form
documentation. They are similar in style but more elaborate than man
macros, and oriented toward producing typeset output.
A minor variant of
troff(1)
called
nroff(1)
produces output for devices that can only support constant-width
fonts, like line printers and character-cell terminals. When you view
a Unix manual page within a terminal window, it is nroff that has
rendered it for you.
The Documenter's Workbench tools do the technical-documentation
jobs they were designed for quite well, which is why they have
remained in continuous use for more than thirty years while computers
increased a thousandfold in capacity. They produce typeset text of
reasonable quality on imaging printers, and can throw a tolerable
approximation of a formatted manual page on your screen.
They fall down badly in a couple of areas, however. Their stock
selection of available fonts is limited. They don't handle images
well. It's hard to get precise control of the positioning of text or
images or diagrams within a page. Support for multilingual documents
is nonexistent. There are numerous other problems, some chronic but
minor and some absolute showstoppers for specific uses. But the most
serious problem is that because so much of the markup is presentation
level, it's difficult to make good Web pages out of unmodified
troff sources.
Nevertheless, at time of writing man pages remain the single
most important form of Unix documentation.
