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.
We discussed the Documenter's Workbench architecture and tools in Chapter 8 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 Example 18.1 for several of the troff codes you might encounter in document sources.
Example 18.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 Example 18.2 for a sample.
Example 18.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.
TeX (pronounced /teH/ with a rough h as though you are gargling) is a very capable typesetting program that, like the Emacs editor, originated outside the Unix culture but is now naturalized in it. It was created by noted computer scientist Donald Knuth when he became impatient with the quality of typography, and especially mathematical typesetting, that was available to him in the late 1970s.
TeX, like troff(1), is a markup-centered system. TeX's request language is rather more powerful than troff's; among other things, it is better at handling images, page-positioning content precisely, and internationalization. TeX is particularly good at mathematical typesetting, and unsurpassed at basic typesetting tasks like kerning, line filling, and hyphenating. TeX has become the standard submission format for most mathematical journals. It is actually now maintained as open source by a working group of the the American Mathematical Society. It is also commonly used for scientific papers.
As with troff(1), human beings usually do not write large volumes of raw TeX macros by hand; they use macro packages and various auxiliary programs instead. One particular macro package, LaTeX, is almost universal, and most people who say they're composing in TeX almost always actually mean they're writing LaTeX. Like troff's macro packages, a lot of its requests are semi-structural.
One important use of TeX that is normally hidden from the user is that other document-processing tools often generate LaTeX to be turned into PostScript, rather than attempting the much more difficult job of generating PostScript themselves. The xmlto(1) front end that we discussed as a shell-programming case study in Chapter 14 uses this tactic; so does the XML-DocBook toolchain we'll examine later in this chapter.
TeX has a wider application range than troff(1) and is in most ways a better design. It has the same fundamental problems as troff in an increasingly Web-centric world; its markup has strong ties to the presentation level, and automatically generating good Web pages from TeX sources is difficult and fault-prone.
TeX is never used for Unix system documentation and only rarely used for application documentation; for those purposes, troff is sufficient. But some software packages that originated in academia outside the Unix community have imported the use of TeX as a documentation master format; the Python language is one example. As we noted above, it is also heavily used for mathematical and scientific papers, and will probably dominate that niche for some years yet.
Texinfo is a documentation markup invented by the Free Software Foundation and used mainly for GNU project documentation — including the documentation for such essential tools as Emacs and the GNU Compiler Collection.
Texinfo was the first markup system specifically designed to support both typeset output on paper and hypertext output for browsing. The hypertext format was not, however, HTML; it was a more primitive variety called ‘info’, originally designed to be browsed from within Emacs. On the print side, Texinfo turns into TeX macros and can go from there to PostScript.
The Texinfo tools can now generate HTML. But they don't do a very good or complete job, and because a lot of Texinfo's markup is at presentation level it is doubtful that they ever will. As of mid-2003, the Free Software Foundation is working on heuristic Texinfo to DocBook translation. Texinfo will probably remain a live format for some time.
Plain Old Documentation is the markup system used by the maintainers of Perl. It generates manual pages, and has all the familiar problems of presentation-level markups, including trouble generating good HTML.
Since the World Wide Web entered the mainstream in the early 1990s, a small but increasing percentage of Unix projects have been writing their documentation directly in HTML. The problem with this approach is that it is difficult to generate high-quality typeset output from HTML. There are particular problems with indexing as well; the information needed to generate indexes is not present in HTML.
DocBook is an SGML and XML document type definition designed for large, complex technical documents. It is alone among the markup formats used in the Unix community in being purely structural. The xmlto(1) tool discussed in Chapter 14 supports rendering to HTML, XHTML, PostScript, PDF, Windows Help markup, and several less important formats.
Several major open-source projects (including the Linux Documentation Project, FreeBSD, Apache, Samba, GNOME, and KDE) already use DocBook as a master format. This book was written in XML-DocBook.
DocBook is a large topic. We'll return to it after summing up the problems with the current state of Unix documentation.