Re: [Groff] The permuted index from Hell

[Larry Kollar]

Werner LEMBERG wrote:

>> What started that was my early experiences with unix where I went
>> to the permuted index and looked for "rename a file".  I was not
>> plesed when the only thing I could find is the rename(2) system call.
>
> For groff.texinfo, I manually add permuted index entries.  I really
> doubt (as others do on this list) that it can be done automatically in
> a sensible way.

Very true. Indexing is actually a specialty profession, best performed by 
someone who *isn't* the writer of the document. Unfortunately, there isn't a 
lot of budget for hiring indexers in the Real World, and even less of one 
elsewhere, so we have to resort to tricks like permuted indexes and systems 
like that in CSTR 128. They often end up substituting quantity for quality, but 
usually it's better than nothing -- and "nothing" is exactly what you would get 
otherwise in most cases.

On the other hand, a good permuted index can show relationships between 
topics that you might not have seen before, or show you things you didn't 
know existed. As a dry run for the MIB permuted index (which I reduced to a 
"mere" 198 pages after adding some unnecessary keywords to the ignore 
list), I did one for the (1) manpages on my system (MacOSX) and found 
several utilities I didn' t know about but could be very useful.


Clarke's example, which I remember reading about before, leaves me shaking 
my head though. It's a perfect example of why one should always concentrate 
on creating a good "Name" line in manpages; that and the See Also blocks are 
the two most likely candidates for extraction & processing. Rather than being 
a "neat" solution, I find it rather sloppy (of AT&T).

And please, other GNU projects, could we have something more out of your 
manpages than a list of command-line options and "see the info file"? If we 
wanted to see the info file, we would have gone there.

Grumble. Off to improve the ptx(1) page....

--
Larry Kollar     k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: "UTP Revival"
http://unixtext.org/