ugh.book

48 Documentation?

michael: ls lock*

No match.

michael: cd standard

michael: ls lock*

lockf.z

Oh, goody. It’s compress(1)ed. Why is it compressed, and not stored

as plain text? Did SGI think that the space they would save by com-

pressing the man pages would make up for the enormous RISC bina-

ries that they have lying around? Anyhow, might as well read it while

I’m here.

michael: zcat lockf

lockf.Z: No such file or directory

michael: zcat lockf.z

lockf.z.Z: No such file or directory

Sigh. I forget exactly how inflexible zcat is.

michael: cp lockf.z ~/lockf.Z; cd ; zcat lockf

| more

lockf.Z: not in compressed format

It’s not compress(1)ed? Growl. The least they could do is make it

easily people-readable. So I edit my .cshrc to add /usr/catman to

already-huge MANPATH and try again:

michael: source .cshrc

michael: man lockf

And, sure enough, it’s there, and non-portable as the rest of Unix.

No Manual Entry for “Well Thought-Out”

The Unix approach to on-line documentation works fine if you are inter-

ested in documenting a few hundred programs and commands that you, for

the most part, can keep in your head anyway. It starts to break down as the

number of entries in the system approaches a thousand; add more entries,

written by hundreds of authors spread over the continent, and the swelling,

itching brain shakes with spasms and strange convulsions.

Date: Thu, 20 Dec 90 3:20:13 EST

From: Rob Austein <[email protected]>

To: UNIX-HATERS

Subject: Don’t call your program “local” if you intend to document it