woods@eci386.uucp (Greg A. Woods) (12/28/90)
[ NOTE: I'm moving this thread to comp.unix.misc, where, if it continues, I hope it will be more appropriate. ] In article <357@metran.UUCP> jay@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@virtech in <1990Dec23.160807.3207@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