ugh.book

(singke) #1

44 Documentation?


On-line Documentation


The Unix documentation system began as a single program called man.
man was a tiny utility that took the argument that you provided, found the
appropriate matching file, piped the file through nroff with the “man” mac-
ros (a set of text formatting macros used for nothing else on the planet), and
finally sent the output through pg or more.

Originally, these tidbits of documentation were called “man pages”
because each program’s entry was little more than a page (and frequently
less).

man was great for its time. But that time has long passed.

Over the years, the man page system has slowly grown and matured. To its
credit, it has not become a tangled mass of code and confusing programs
like the rest of the operating system. On the other hand, it hasn’t become
significantly more useful either. Indeed, in more than 15 years, the Unix
system for on-line documentation has only undergone two significant
advances:


  1. catman, in which programmers had the “breakthrough” realization
    that they could store the man pages as both nroff source files and as
    files that had already been processed, so that they would appear
    faster on the screen.
    With today’s fast processors, a hack like catman isn’t need any-
    more. But all those nroff’ed files still take up megabytes of disk
    space.

  2. makewhatis, apropos, and key (which was eventually incorporated
    into man -k), a system that built a permuted index of the man pages
    and made it possible to look up a man page without knowing the
    exact title of the program for which you were looking. (These
    utilities are actually shipped disabled with many versions of Unix
    shipping today, which makes them deliver a cryptic error when run
    by the naive user.)


Meanwhile, advances in electronic publishing have flown past the Unix
man system. Today’s hypertext systems let you jump from article to article
in a large database at the click of a mouse button; man pages, by contrast,
merely print a section called “SEE ALSO” at the bottom of each page and
invite the user to type “man something else” on the command line follow-
ing the prompt. How about indexing on-line documentation? These days
you can buy a CD-ROM edition of the Oxford English Dictionary that
Free download pdf