RE: indexing

[Gregory Leblanc <GLeblanc cu-portland edu>]

> -----Original Message-----
> From: John Fleck [mailto:jfleck@inkstain.net]
> Sent: Sunday, July 30, 2000 2:19 PM
> To: gnome-doc-list@gnome.org
> Subject: Re: indexing
> 
> On Sat, Jul 29, 2000 at 11:25:30PM -0700, Gregory Leblanc wrote:
> 
> > And if any of the people who volunteered or know anything 
> about this would
> > care to step forward and point me to some documentation on 
> indexing, I'd be
> > most appreciative.  I've not been able to find anything 
> good, and I've
> > noticed that the docs that the LDP has which do have some 
> index markup
> > (something like 4 of them), aren't really well done.  Thanks,
> 
> Greg -
> There is a brief discussion of docbook indexing tags on Norman Walsh's
> web site:
> 
> http://nwalsh.com/docbook/dsssl/doc/indexing.html
> 
> It also explains how to automatically build an index from marked-up
> sgml using a perl script called collateindex.pl.

I'm fairly proficient with the tools, at least enough to know what's there,
and what it's capable of.  :-)  I'm more curious about how to figure out
what your index terms should be, where they should be located.  It looks
like most books get indexed by professional indexers, and I'm curious about
how we can get the same thing for our free docs.  I'd LOVE to have a good
quality index included as part of, say, the Gnumeric manual, or the Linux
IP-MASQ HOWTO.  

> The script is the cygnus stylesheets package:
> ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/SOURCES/
> stylesheets.tgz
> 
> I've just been playing with it a bit this afternoon, and it seems
> rather cumbersome - not really practical for production work. Building
> an index is a multiple-step process, and I've had to use jade directly
> to make it work rather than db2html. Also, it seems to link to the
> beginning of the section rather than the spot where your indexterm
> occurs. 

Hmm, that doesn't sound ideal, unless it was designed for print media.  It
might be worth asking around on the docbook-tools list or the docbook apps
list about people who are actually using that script.  It would be nice if
we didn't have to re-invent the wheel to get a good index in our
documentation.  Then again, maybe that's the first of "write two programs,
throw the first away".  :-)  Later,
	Greg