rcd@ico.isc.com (Dick Dunn) (07/12/90)
amull@Morgan.COM (Andrew P. Mullhaupt) writes: > cpcahil@virtech.uucp (Conor P. Cahill) writes: > > Hmm, looks like a real RTFM type of question. Let's see. I think > > we'll start at the permuted index... Lets look up the word "swap"... ... > You can start in the Bermuda index, but that takes a strong stomach; > a lot of people get lost in those and are never heard from again. ... > Has anyone ever made a utility which converts Bermuda indices into > human readable form? A fun posting, but I don't get much from it. What's wrong with a permuted index? Seems pretty obvious to me: Think of useful words that might have something to do with the topic, look them up until you find something that helps. It's far more useful than the traditional index in one particular sense: context. For example, if you want to know how to do something to a directory, it's easy to go to "directory" in the perverted index and scan down the possibilities, with a few words to suggest whether it's what you want, than to come up against a conventional index entry that will look something like: directory: 3, 7-8, 11, 35, 37, 49-51, 103, 119, 128-130, 211, 218 In fact, I've found that a permuted index is one form of computer-ish presentation that non-computer folk can grasp, and appreciate, almost immediately. It takes me about 15 seconds to explain. Obviously you disagree; can you tell us why? What do you find difficult about a permuted index? (I'm skeptical, of course...but I'm always interested in what people have trouble understanding and why.) -- Dick Dunn rcd@ico.isc.com -or- ico!rcd (303)449-2870 ...Never attribute to malice what can be adequately explained by stupidity.
amull@Morgan.COM (Andrew P. Mullhaupt) (07/15/90)
In article <1990Jul12.044550.19213@ico.isc.com>, rcd@ico.isc.com (Dick Dunn) writes: > amull@Morgan.COM (Andrew P. Mullhaupt) writes: > > Has anyone ever made a utility which converts Bermuda indices into > > human readable form? > A fun posting, but I don't get much from it. What's wrong with a permuted > index? Seems pretty obvious to me: Think of useful words that might have > something to do with the topic, look them up until you find something that > helps. It's far more useful than the traditional index in one particular > sense: context. For example, if you want to know how to do something to a > directory, it's easy to go to "directory" in the perverted index and scan More useful? Not in my experience. A permuted index is a good way to inflate the number of references you have to read through to get your hit. I think of the inconvenience as resulting from collisions in a hash table; you cannot locate the desired reference as quickly, and much more importantly (in UNIX manuals) you cannot rapidly determine that you are searching in a manual which doesn't have relevant material. (I.e. the misses are a lot more costly in the Bermuda Index.) My experience with UNIX documentation is that a nontrivial part of the search is finding the set of manuals which have relevant information. I usually have a good idea which manuals are not necessary, but I often check them all anyway; _which_ FM is usually the hard part of RTFM. It seems to me that in those UNIXes which provide normal indices, this doesn't take as long. I think the reason is that Bermuda indices put you in the linear search mode a lot more than the normal indices, where you stay in binary search, and fewer page faults are involved. Now if the thing weren't printed, and you got to search it in an editor, I might not think Bermuda indices were stupid. But the ones I'm talking about generally are printed, and just seem to get in the way. I think they've outsmarted themselves. Just like the people who invented the electric pen. The old fashioned ones were, when properly made, just fine. Later, Andrew Mullhaupt
rick@pcrat.uucp (Rick Richardson) (07/16/90)
In article <1235@s8.Morgan.COM> amull@Morgan.COM (Andrew P. Mullhaupt) writes: >More useful? Not in my experience. A permuted index is a good way to >inflate the number of references you have to read through to get your >hit. I have both the ISC version of the OSF/Motif Programmer's Reference Manual (softcover) and the OSF version (hardcover). The ISC version has a permuted index of 18 pages, and the OSF version has a traditional index of 11 pages (smaller paper, too). Other than that, the documents appear to be more or less identical. If you don't intimately know what each Motif function does, the OSF index won't help, since most of the entries are just the function names. At least in the ISC version, I can look up "search" and see that there's a function XmFileSelectionDoSearch(3X). Granted, the OSF index could be improved by indexing more of the terms that the permuted index already has. And both could be improved by indexing more of the terms in the text itself. The OSF version is for browsing; I keep it in the Computer Science Reading Room, near the TP. The ISC version is well thumbed, and tends to open to the permuted index. Hmm... -Rick -- Rick Richardson | Looking for FAX software for UNIX/386 ??? Ask About: |Mention PC Research,Inc.| FaxiX - UNIX Facsimile System (tm) |FAX# for uunet!pcrat!rick| FaxJet - HP LJ PCL to FAX (Send WP,Word,Pagemaker...)|Sample (201) 389-8963 | JetRoff - troff postprocessor for HP LaserJet and FAX|Output
peter@ficc.ferranti.com (Peter da Silva) (07/17/90)
In article <1235@s8.Morgan.COM> amull@Morgan.COM (Andrew P. Mullhaupt) writes: > More useful? Not in my experience. A permuted index is a good way to > inflate the number of references you have to read through to get your > hit. How do you get this? It reduces the number of references you have to look up. When I see "trees: 134, 145, 279, 394" I have to look up all four places to be sure I'm not going to miss the reference I need. If it said: looking for files in a directory tree 134 search balanced binary tree 145 diseases apple tree 279 a skunk safely how to tree 394 I know exactly where to go. Are we even referring to the same thing, here? The keyword in context index is so far superior to the conventional index I keep a copy of the *3BSD* manual around so I know I'll be have a usable manual handy. Even for System V it's easier to look things up in the wrong manual, if I don't have the right index! -- Peter da Silva. `-_-' +1 713 274 5180. <peter@ficc.ferranti.com>
det@hawkmoon.MN.ORG (Derek E. Terveer) (07/17/90)
In article <1235@s8.Morgan.COM> amull@Morgan.COM (Andrew P. Mullhaupt) writes: > In article <1990Jul12.044550.19213@ico.isc.com>, rcd@ico.isc.com (Dick Dunn) writes: > > [...] Seems pretty obvious to me: Think of useful words that might have > > something to do with the topic, look them up until you find something that > > helps. It's far more useful than the traditional index in one particular > > sense: context. For example, if you want to know how to do something to a > > directory, it's easy to go to "directory" in the perverted index and scan > > More useful? Not in my experience. A permuted index is a good way to > inflate the number of references you have to read through to get your > hit. [...] I think the reason is that Bermuda indices > put you in the linear search mode a lot more than the normal indices, > where you stay in binary search, and fewer page faults are involved. Huh? Perhaps you need to re-examine the format of the permuted index; it is alphabetical and you may therefore circumvent the linear search. Your comments so far seem to imply that you must spend a *great* deal of time looking up English words in a dictionary as well. If i want to find something in the man pages i always look in the permuted index first and i frequently wonder why other vendors (not just for Unix either!) don't include such a useful beast in their documentation efforts... derek -- Derek Terveer det@hawkmoon.MN.ORG
amull@Morgan.COM (Andrew P. Mullhaupt) (07/17/90)
In article <1990Jul16.045730.10521@pcrat.uucp>, rick@pcrat.uucp (Rick Richardson) writes: > I have both the ISC version of the OSF/Motif Programmer's Reference > Manual (softcover) and the OSF version (hardcover). The ISC version > has a permuted index of 18 pages, and the OSF version has a traditional > index of 11 pages (smaller paper, too). Some people would find that factor of 1.6 significant. Think of it as that many more times that you find your references start on one page and end on the next. This is convenience? As a quick test, I just flipped open my OSF/MOTIF _Programmer's Guide_ and found 33 pages of reasonably set normal index. Does the ISC version have a 54 page vacation in Bermuda? Now I don't have the ISC version, so I'm guessing, but if I look up 'No explicit programmatic access' on page Index-16, I can find the rest of the story 'programmatic access...' on the facing page Index-17. I would guess that there's a lot of 'pixmap' stuff intervening in the ISC version, including a page fault. > ...Other than that, the documents > appear to be more or less identical. If you don't intimately know what > each Motif function does, the OSF index won't help, since most of the > entries are just the function names. At least in the ISC version, > I can look up "search" and see that there's a function > XmFileSelectionDoSearch(3X). But this can be a false alarm; Bermuda indices tend to generate more of them than normal indices. The existence of more references to chase is not helpful unless there is more information in them. In my experience the Bermuda index just repeats a lot of information with no great benefit. I can reveal that the worst index I know of is not strictly speaking a Bermuda index. The prize goes to the IMSL User's Manuals for their utterly vexacious 'KWIC' (Key Word In Camouflage) index. IMSL are the real avant-garde of indices, providing no less than three unusual indices at the back of the IMSL User's Manuals. First, the KWIC index, then the 'GAMS' - (Gee - Another Mind Stretcher) index, and the almost usable Alphabetical Index of Routines. The KWIC index is a version of Bermuda index, and it's the most annoying. The GAMS index is a non-starter, so you don't lose much time with it - you ignore it completely. On the rare occasions where you can guess the actual name of the routine you need (lest we forget, IMSL routines are sort of named by convention, e.g. 'DZPORC' is the name of the routine which uses the Jenkins-Traub three-stage algorithm...) you will find nirvana in the Alphabetical Index of Routines. Now some people like nouveau indices, but I find in books which provide them I usually skip the indices unless I can't find what I want by skimming the book. In fact a great deal of the time I find what I want in books this way. Usually I resort to an index to determine that something I'm searching for is _not_ present in the book. The more places a reference could appear in an index, the less pleasant this task is. Now unless you like barking up the wrong tree, I can't see why a Bermuda, (or even worse) indexing scheme is to be preferred. Later, Andrew Mullhaupt