Permuted indices

[Andrew P. Mullhaupt]

In article <1990Jul16.045730.10521 at pcrat.uucp>, rick at 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