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
jackv@turnkey.tcc.com (Jack F. Vogel) (12/28/90)
In article <1990Dec28.004756.6019@eci386.uucp> woods@eci386.UUCP (Greg A. Woods) writes: >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. Face it, my experience has been that the difference between the "average" student ( read here 'one seeking new knowledge') and the "extraordinary" student is that the former, needing 'spoon feeding', will wail loudly at the painful difficulty of the material, and, spending most their time raving, will progress slowly if at all in its mastery; whereas the latter takes the task in hand and gets on with it... -- Jack F. Vogel jackv@locus.com AIX370 Technical Support - or - Locus Computing Corp. jackv@turnkey.TCC.COM
bernie@metapro.DIALix.oz.au (Bernd Felsche) (12/29/90)
In <1990Dec28.004756.6019@eci386.uucp> (Greg A. Woods) writes: >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. Me too. What also baffles me is that so many people actually manage to program by "Brownian Motion". They flip open an unfamiliar reference manual at a likely-looking page, and write an entire application based on their mis-conceptions. Problems are tackled at the middle, not the start: i.e. "how do we do this" vs "why do we do this". Application programs are like snakes. If you pick them up by the head, then they can't bite you. Pick them up anywhere else, and it's only a matter of time before you feel the fangs. Some of my least-favourite applications have obviously been developed by people with little or no understanding of the operating environment, be it UNIX or not. UNIX just makes bad applications look worse. -- ______________________________Bernd_Felsche______________________________ Metapro Systems, 328 Albany Highway, Victoria Park Western Australia 6100 Phone: +61 9 362 9355 Fax: +61 9 472 3337 bernie@metapro.DIALix.oz.au
anton@bkj386.uucp (Anton Aylward) (01/05/91)
Greg Woods is right, you do have to read, completely and thoroughly.
This applies just as much to DOS, VMS or MVS or CICS!
[I won't tell you which of those abortions I was forced to use,
but I did read completely and throughly.]
I leant UNIX in 2 weeks back in '78 by reading the manuals.
For two weeks solid. I tried out all the examaples, and some permutations.
Back then there were none of the books Greg mentioned, except the K&R.
Yes, Vol 2 was essential.
The Yellow book (BSTJ 57/6/II) was also useful.
BTW, the two weeks were 20 hour days.
The reading was over, and over, and over!
When I came to use of the abortions mentioned above,
I barely go through all the documentation in a month.
Even so, I only had a vague idea what was going on,
and had to experiment, then give up and write a front-end
that 'emulated' STDIO, i.e. map to a structure that was simple,
regular and comprehensible.
UNIX is S,R&C. The other systems are not simple or regular:
DOS: LPT1: is just one name for the printer, but there is no
guarentee its there and not LPT2:
"echo hello >LPT1:"
make sense
"echo hello >A:"
doesn't make sense, even though the syntax is the same.
UNIX:
"echo hello >/dev/lp"
"echo hello >/dev/fd"
regular, eh ?
OK, we're all cogniscent of this.
Indexes: creating them is an art form. using them is an art.
Don't complain about the UNIX KWIK Index unless you are proven
proficient in using some other major index system, that is,
don't ctiticise unless you have an alternative to offer,
or in the venacular, "Lead, Follow or get out of the way".
/anton aylward A.S.C.I.
12 years with UNIX.
--
____ __________
/ / / | | Anton J Aylward
/ / / | Analysis |
/ | | ,-' | 3355 Don Mills Rd,guy@auspex.auspex.com (Guy Harris) (01/06/91)
>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. Now, if they'd only put "termio(7)" somewhere other than the f*cking *ADMINISTRATOR'S* manual, like in the damn *PROGRAMMER'S* manual, since the people who usually write code that uses the "termio(s)" functions are PROGRAMMERS.... ...and then, while they're at it, think about merging all the little fragments of manual page stuck, in the S5R4 manuals, at the end of stuff like the STREAMS Programmer's Guide and the Network Interfaces Programmer's Guide back into the main Programmer's Reference Manual (and maybe even do some *manual pages* for pseudo-tty stuff other than the library routines, rather than just the "STREAMS-based Terminal Subsystem" section of the STREAMS Programmer's Guide). Yes, it may be nice to have an index that tells you where that stuff is. It's even *nicer* to have it in reasonably-obvious places so you don't have to *check* the index....
dhesi%cirrusl@oliveb.ATC.olivetti.com (Rahul Dhesi) (01/08/91)
>>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... By itself, this is an appropriate comment. But it completely inappropriate as a response to criticism of AT&T's poor documentation. Good research skills let a person survive better in a world of inadequate documentation. They do not justify the existence of such bad documentation. Asking the reader to read all the manuals is a silly resonse to a desire to see better indexes available. It would be like asking somebody to read more books if he complained about not being able to find a decent dictionary. In fact it is experienced users of UNIX, and those more knowledgeable in the English language, who are *more* likely to feel the need for better indexes and more comprehensive dictionaries. You will not usually find an illiterate person pining for an unabridged dictionary, and you will seldom find a person interested in only word processing wishing that the the UNIX commands, library functions, system calls, and file formats were better indexed. -- History never | Rahul Dhesi <dhesi%cirrusl@oliveb.ATC.olivetti.com> becomes obsolete. | UUCP: oliveb!cirrusl!dhesi
woods@eci386.uucp (Greg A. Woods) (01/10/91)
In article <2856@cirrusl.UUCP> dhesi%cirrusl@oliveb.ATC.olivetti.com (Rahul Dhesi) writes: > >>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... > > By itself, this is an appropriate comment. But it completely > inappropriate as a response to criticism of AT&T's poor documentation. Excuse me? Have you read any of AT&T documentation since the 7th Edition? I was over-joyed with the advances AT&T made with their documentation as of Release 3.0, and with 3.2 and 4.0, things are even better. As for the index entries, they are the same basic entries as any other UNIX documentation. I've even had people complain bitterly to me about the SunOS(4.0) Global Index, and it's one of the best I've seen. The problem expressed at the beginning of this thread occured, to the best of my knowledge, because someone quite experienced with UNIX forgot that, all the world's *not* a VAX, so to speak. If you want to complain about poor UNIX documentation in general, that's a different kettle of fish. IMHO, AT&T UNIX SysVr3.0 and up have excellent documentation sets, even in comparison with non-UNIX operating systems. Then only major problem I've had is that some SysV vendors don't include the global permuted index. Some don't even have a good overview to the doc's. The basic problem still boils down to research skills. -- 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
boyd@necisa.ho.necisa.oz.au (Boyd Roberts) (01/11/91)
In article <1991Jan9.200617.25296@eci386.uucp> woods@eci386.UUCP (Greg A. Woods) writes: > >Excuse me? Have you read any of AT&T documentation since the 7th >Edition? I was over-joyed with the advances AT&T made with their >documentation as of Release 3.0, and with 3.2 and 4.0, things are even >better. > Sure, I was over the moon when I saw the V.2 documentation. 12, count them, 12 manuals!! All but two or three of them useful. A whole shelf of useless verbage. Contrast this with the Tenth Edition manuals. There are just two volumes. One containing tutorials, the other containing manuals entries. Just right. Boyd Roberts boyd@necisa.ho.necisa.oz.au ``When the going gets wierd, the weird turn pro...''