Perverted index (was Re: '386 Unix Wars)

[James Van Artsdalen]

In <357 at metran.UUCP>, jay at metran.UUCP (Jay Ts) wrote:

] Although it was stable and relatively free of bugs, the quality of
] documentation was standard AT&T, which means no indexes, poor
] organization, and nonexistent information about system administration
] procedures.  The Xenix documentation was little better.

| EXCUSE ME?!?!?!  What do you call the permuted index?  I call it the
| best damn index ever invented!

I don't know if it's the best index ever invented, but it's certainly
a far cry from "no indexes".

> Basically, the permuted index works well only for those with enough
> experience and knowledge to already know exactly where to look.  If
> you think there's nothing wrong with having the permuted index as the
> sole index, then I guess you can take this as a compliment.

Just think of it like using a dictionary to check your spelling.
You have to have an idea of what you're looking for.

> What is needed, IMO, is a real index (IN ADDITION to the permuted
> one) that is created the old fashioned way, by a thoughtful human
> reading through the book and making index entries for each subject
> wherever it appears.

One "problem" is that most of us are now used to looking in section 1
for user commands, section 2 for system call documentation, section 3
for library calls, and so forth.  Inventing some new scheme might not
help things even if it were inherently better.

The most obvious area for improvement is in online documentation.
Some vendors are still resisting the trend away from documentation
fortunately.  One start for improving man pages would be to use the
Emacs "info" scheme.  Suitably cross-referenced, the scheme works
well.
-- 
James R. Van Artsdalen          james at bigtex.cactus.org   "Live Free or Die"
Dell Computer Co    9505 Arboretum Blvd Austin TX 78759         512-338-8789