Doc indexes (was Re: [GENERAL] Re: PostgreSQL vs Oracle vs DB2 vs MySQL - Which should I use?)

Peter Eisentraut <peter_e@gmx.net> writes:
> One thing we should try to do in the future (i.e., the next big attack I
> have on you) is to maintain a human-edited concept index for the docs,
> like every good non-fiction book has at the end.  The technical details
> for this are mostly worked out, it just needs someone to compose a list of
> all "concepts" and find all the places where they're discussed.

The large documents I've done in the past (product manuals and such)
used automatic index generation in LaTeX.  You add a tag to text that
needs an index entry:

    To fix this problem, frobnitz the foobar<index>foobar</index>.

and then the index will have an entry for "foobar" that references this
page, along with any other pages where <index>foobar</index> appears.
<index>foobar</index> doesn't affect the visible text on the page
however.

Assuming that our SGML tools can do something similar, this would seem
like the way to go.  Getting the docs marked up initially would be a
painful task, but once it's done it'd be relatively easy for doco
contributors to include appropriate index entries in new text.

I think an index that's maintained separately from the text proper would
be doomed to failure ...

            regards, tom lane