'386 Unix Wars

[Jay Ts]

In article <1990Dec20.175625.17487 at eci386.uucp>, woods at eci386.uucp (Greg A. Woods) writes:
> In article <2812 at cirrusl.UUCP> dhesi%cirrusl at oliveb.ATC.olivetti.com (Rahul Dhesi) writes:
>
> > 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!

Omigod!  I'll run for the fire hose, you call 911 for the fire department!

[Sorry, but I gotta do this; I've been saving this up for years.]

Of all parts of AT&T's (or anyone else's) documentation, I think the permuted
index is the most flammable by far!  If it works, it works great, but if it
doesn't, you have nothing left to do but sit back and meditate (which usually
works for me :-).

Unfortunately, the permuted index is the *only* index for the Reference
Manuals, and this seems to be standard practice for not just AT&T/ESIX,
but other vendors as well.

The problem is, it's essentially produced by machine.  To get it to work,
you have to think of the right keyword in UNIXspeak.  For example, I recently
had to write a small program to do unbuffered, character-at-a-time terminal
I/O.  I thought, "This should be simple, I'll just grab the Programmer's
Reference Manual, and take a look at the wonderful permuted index."  Searches
based on "character", "buffer", "canonical", and everything else I could
think of all utterly failed to bring me nearer to termio(7) in the *System
Administrator's* Reference manual.  (Looking in the SA's Ref Manual in the
first place would not have worked any better.)  And once I found termio(7) with
a combination of my understanding of UNIX, clairvoyance and exhaustive search,
I still had to read carefully before I discovered it really was the right place
to look!  The programming method was simple; just do a ioctl() to clear the
ICANON bit, and a few other things.  I just can't believe how hard it was to
look up.

Now get this:  I just looked through the whole permuted index (in the SARM)
and every reference to termio(7) is generated from the line

termio(7): general terminal interface

which is what is listed under NAME on the termio(7) manual page!  Now, feel
free to flame at me if you think I'm misguided (I've got the firehose now)
but I think this method of indexing is a little deficient.  (But it was
great back when I was working in a research environment with a number of
UNIX gurus, at least one of which would tell me something other than
"RTFM!" :-)

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.

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.

Am I crazy or stupid, or is that not a good idea?

				Jay Ts, Director
				Metran Technology
				uunet!pdn!tscs!metran!jay