Библиотека сайта rus-linux.net
Explaining Your Code to═a═Web-Centric World
Table of Contents
- Documentation Concepts
- The Unix Style
- The Zoo of Unix Documentation Formats
- The Present Chaos and a Possible Way Out
- Best Practices for Writing 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.--
Unix's first application, in 1971, was as a platform for document preparation — Bell Labs used it to prepare patent documents for filing. Computer-driven phototypesetting was still a novel idea then, and for years after it debuted in 1973 Joe Ossana's troff(1) formatter defined the state of the art.
Ever since, sophisticated document formatters, typesetting software, and page-layout programs of various sorts have been an important theme in the Unix tradition. While troff(1) has proven surprisingly durable, Unix has also hosted a lot of groundbreaking work in this application area. Today, Unix developers and Unix tools are at the cutting edge of far-reaching changes in documentation practice triggered by the advent of the World Wide Web.
At the user-presentation level, Unix-community practice has been moving rapidly toward ‘everything is HTML, all references are URLs’ since the mid-1990s. Increasingly, modern Unix help browsers are simply Web browsers that know how to parse certain specialized kinds of URLs (for example, ‘man:ls(1)’ interprets the ls(1) man page into HTML). This relieves the problems created by having lots of different formats for documentation masters, but does not entirely solve them. Documentation composers still have to grapple with issues about which master format best meets their particular needs.
In this chapter, we'll survey the rather unfortunate surfeit of different documentation formats and tools left behind by decades of experimentation, and we'll develop guidelines for good practice and good style.