UNIX Documentation (was: '386 Unix Wars)

[Greg A. Woods]

[ NOTE:  I'm moving this thread to comp.unix.misc, where, if it
continues, I hope it will be more appropriate. ]

In article <357 at metran.UUCP> jay at metran.UUCP (Jay Ts) writes:
> [Sorry, but I gotta do this; I've been saving this up for years.]

Well, so have I!  :-) I've seen the same trends over and over in the
complaints about UNIX documentation.

> 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 :-).

Wrong... more later.

> 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.

Naturally everyone uses it!  It *is* the *best* style of index for this!

> 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.

Unfortunately, the permuted index isn't what's causing your problems,
but is only the brunt of your attacks when you get frustrated.

Your true problem is a lack of understanding of the basic structure
and operation of the UNIX O/S, as well as a problem with terminology
(i.e. the jargon).

The solution to your problem is to relieve your ignorance by reading
the "Guide's", not the "Reference".  The "Programmer's Guide" gives a
basic overview of using the UNIX programming environment, and
describes briefly the interface with the O/S.

If you were to "go by the book", you would probably end up using
either full blown curses, or maybe just the low-level terminfo
routines to solve your particular example problem.  No ioctl()'s, and
no weird bits or character arrays in structures, and no terse, and
complex manual pages to read.  Not only that, your programme might
just be portable to non termio(7) based systems!

Mind you, if you did discover that a terminal was a device, and that
devices could be controlled with ioctl(2), you would have immediately
been referred to termio(7) with a fair degree of certainty that you
were headed in the right direction.

I would say your first, and primary mistake in approaching your
problem was to think it was simple.  Your second mistake was to just
grab the Prog. Ref. Manual without knowing what you were looking up.

Trying to do anything with devices under UNIX is rarely simple or
obvious if you haven't mastered some of the O/S internal concepts.

Trying to discover something unknown by chance in the Programmer's
Reference is not supposed to be easy.

Now, using the manuals that come with your system as a sole source of
information, when there are multitudes of books available on the
topic, is not a wise thing to do.  Many UNIX programmers would not be
where they are today without books like K&P's "The UNIX Programming
Environment", Bourne's "The UNIX System", etc.

>[....]
> 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.

It certainly is an easy field to use for a machine generated index.
Naturally the particular descriptive phrase may not be ideal, as has
been pointed out elsewhere in this thread.  (cpcahil at virtech in
<1990Dec23.160807.3207 at virtech.uucp>)

> "RTFM!" :-)

BTW, "RTFM" means *READ*, not browse.  I learned UNIX by reading, and
reading between the lines, and re-reading when a new concept was
understood; each and every man page in the V7 manual, and when I
though I had it right, or if I needed practical experience, I tried
the routine or command in an example.

Unfortunately I did not have immediate access to Volume 2 of the 7th
Edition UNIX manual, which is all of the background information and
"user" guides.  Only later did I realise that if I had read Vol.2
first, life would have been much more obvious.  Never the less, I
managed to gain a sound understanding of UNIX by doing what I did.

Of course another very fine way of learning practical things is to
read working sources.  There are many good examples of various
techniques for dealing with problems in the massive amounts of freely
available code.  This is, of course, often much more difficult than
reading an introductory guide!

> 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.

Exactly:  "with enough experience".  Guess why it's called a reference
manual.  Just how far do you expect someone to go in explaining
concepts in a reference manual.  When I read that same man page I want
to find out the details, not the concepts.  I can usually remember the
concepts after a relatively small number of readings of the
introductions and guides!  :-)

> 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.

There is a real index in each of the Guides.  If you tried to index
the man pages, you'd end up with a massive index, and if you weren't
very careful there would be dozens of references for each indexed word!

What really baffles me is that people who seem to be reasonably well
educated have such poor research skills.  This is a very bad trend
when more and more complex pieces of technology are being introduced
to wider segments of society.
-- 
							Greg A. Woods
woods@{eci386,gate,robohack,ontmoh,tmsoft}.UUCP		ECI and UniForum Canada
+1-416-443-1734 [h]  +1-416-595-5425 [w]  VE3TCP	Toronto, Ontario CANADA
Political speech and writing are largely the defense of the indefensible-ORWELL