The Art of Unix Programming

haoji

Portability, open standards and open source

Prev Chapter 15. Portability

Next



Portability, open standards and open source

Portability requires standards. Open-source reference implementations are the most effective
method known for both promulgating a standard and for pressuring proprietary vendors into
conforming. If you are a developer, open-source implementations of a published standard
can both tremendously reducing your coding workload and allow your product to benefit (in
ways both expected and unexpected) from the labor of others.

Let's suppose, for example, you are designing image-capture software for a digital camera.
Why write your own format for saving image bits or buy proprietary code when (as we noted
in Chapter 5 (Textuality)) there is a well-tested, full-featured library for writing PNGs in
open source?

The (re)invention of open source has had a significant impact on the standards process as
well. Though it is not formally a requirement, the IETF has since around 1997 grown
increasingly resistent to standard-tracking RFCs that do not have at least one open-source
reference implementation. In the future, it seems likely that conformance to any given
standard will increasingly be measured by conformance to (or outright use of!) open-source
implementations that have been blessed by the standard's authors.

In the end, the most effective step you can take to ensure the portability of your code is to not
rely on proprietary technology. You never know when the closed-source library or tool or
code generator or network protocol you are depending on will be end-of-lifed, or when it will
be changed in some backwards-incompatible way that breaks your project. With open-source
code, you have a path forward even if the leading-edge version changes in a way that breaks
your project; because you have access to source code, you can forward-port it to new
platforms if you need to.

Until the late 1990s this advice would have been been impractical. The few alternatives to
relying on proprietary operating systems and development tools were noble experiments,
academic proofs-of-concept, or toys. But the Internet changed everything; in early 2003
Linux and the other open-source Unixes exist and have proven their mettle as platforms for
delivering production-quality software. Developers have a better option now than being
dependent on short-term business decisions designed to protect someone else's monopoly.

haoji

Practice defensive design 鈥

haoji

Chapter 16. Documentation

Prev Part IV. Community

Next



Chapter 16. Documentation

Explaining Your Code To A Web-Centric World

Table of Contents

Documentation concepts
The Unix style
Technical background
Cultural style



The zoo of Unix documentation formats
troff and the DWB tools
TeX
Texinfo
POD
HTML
DocBook



The present chaos and a possible way out
DocBook
Document Type Definitions
Other DTDs
The DocBook toolchain
Migration tools
Editing tools
Related standards and practices
SGML
XML-Docbook References



How to write Unix documentation


I've never met a human being who would want to read 17,000 pages of documentation, and if
there was, I'd kill him to get him out of the gene pool.

haoji

--Joseph Costello, President of Cadence

Unix's first application, in 1971, was as a platform for document preparation 鈥

haoji

Documentation concepts

Prev Chapter 16. Documentation

Next



Documentation concepts

Our first distinction is between 鈥淲hat You See Is What You Get鈥

haoji

the document has to be combined with a stylesheet that tells the formatter how to translate the
structure markup in the document to a physical layout.

Most markup-centered documentation systems support a macro facility. Macros are user-
defined commands that are expanded by text substitution into sequences of built-in markup
requests. Usually these macros add structural features (like the ability to declare section
headings) to the markup language.

Finally, we note that there are significant differences between the sorts of things composers
want to do with small documents (business and personal letters, brochures, newsletters) and
the things they want to do with large ones (books, long articles, technical papers and
manuals).

Prev Up Next

Chapter 16. Documentation

Home The Unix style

haoji

The Unix style

Prev Chapter 16. Documentation

Next



The Unix style

The Unix style of documentation (and documentation tools) has several technical and
cultural traits that set it apart from the way documentation is done elsewhere. Understanding
these signature traits first will help create context for you to understand why the programs
and the practice look the way they do, and why the documentation reads the way it does.

Technical background

Technically, Unix documentation tools have always been designed primarily for the
challenges involved in composing large documents. Consequently, most Unix developers
learned to love markup-centered documentation tools. Unlike the PC users of the time, the
Unix culture was unimpressed with WYSIWYG word processors when they became
generally available in the late 1980s and early 1990s 鈥

haoji

markup-based formatters like troff(1), it also made them interested in structural markup. The
history of Unix document tools is one of lurching, muddled and erratic movement in a
general direction away from presentation markup and towards structural markup. In early
2003 this journey is not yet over, but the end is distantly in sight.

The development of the World Wide Web meant that the ability to render documents in
multiple media (or, at least, for both print and HTML display) became the central challenge
for documentation tools after about 1993. At the same time, even ordinary users were, under
the influence of HTML, becoming more comfortable with markup-centered systems. This led
directly to an explosion of interest in structural markup and the invention of XML after 1996.
Suddenly the old-time Unix attachment to markup-centered systems started looking prescient
rather than reactionary.

Today, in early 2003, most of the leading-edge development of XML-based documentation
tools using structural markup is taking place under Unix. But, at the same time, the Unix
culture has yet to let go of its older tradition of presentation-level markup systems. The
creaking, clanking, armor-plated dinosaur that is troff(1) has only partly been displaced by
HTML and XML.

Cultural style

Most software documentation is written by technical writers for the least-common-
denominator ignorant 鈥

haoji

and oversimplifying condescension, classic Unix documentation is written to be telegraphic
but complete. It does not hold you by the hand, but it usually points in the right direction.
The style assumes an active reader, one who is able to deduce obvious unsaid consequences
of what is said, and who has the self-confidence to trust those deductions.

Unix programmers tend to be pretty good at writing references, and most Unix
documentation has the flavor of a reference or aide memoire for someone who thinks like the
document-writer but is not yet an expert at his or her software. The results often look much
more cryptic and sparse than they actually are. Read every word carefully, because whatever
you want to know will probably be there, or deducible from what's there. Read every word
carefully, because you will seldom be told anything twice.

Prev Up Next

Documentation concepts

Home The zoo of Unix documentation
formats

haoji

The zoo of Unix documentation formats

Prev Chapter 16. Documentation

Next



The zoo of Unix documentation formats

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 DWB tools

We discussed the DWB architecture and tools in Chapter 8 (Minilanguages) 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(1) 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 16.1 for several of the troff(1) codes you might encounter in
document sources.

Example 16.1. troff(1) markup example

This is running text.
.\" Comments begin with the request named by a backslash and double quote.ft BThis text will be in bold font.
.ft RThis 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.
.bpThe bp request forces a new page and a paragraph break.
This line will be part of the second filled paragraph.
.sp 3The .sp request emits the number of blank lines given as argument.nfThe nf request switches off paragraph filling.
Until the fi request switches it back onwhitespace and layout will be preserved.
One word in this line will be in \fBbold\fR font.
.fiParagraph filling is back on.