Message-ID: <004501c0bc65$d34e0b80$1001a8c0@archonet.com>
From: "Richard Huxton" <dev@archonet.com>
To: "Peter Eisentraut" <peter_e@gmx.net>
Cc: <pgsql-docs@postgresql.org>
References: <Pine.LNX.4.30.0104031809250.974-100000@peter.localdomain>
Subject: Re: Docs with index
Date: Tue, 3 Apr 2001 18:45:05 +0100
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit

From: "Peter Eisentraut" <peter_e@gmx.net>

> Richard Huxton writes:
>
> The documentation is, despite attempts to make it less so, still mostly in
> reference style.  Thus, you can make a lot of index terms directly out of
> section and chapter headings.  The real trick will be generic terms such
> as "performance", "storage", "hard disk".
>
> You could also look at it the other way around:  the reason that the
> documentation is so much in reference style may be that in the absence of
> an index it would otherwise be impossible to find the relevant places.

Fair point - I must admit I tend to end up running a grep for anything that
isn't an SQL command.

> > The only thing that struck me was the fact that lines like "see macaddr"
> > aren't clickable, but presumably that's down to the stylesheet.
>
> Indeed:

[snipped code]

> It doesn't seem altogether impossible to fix this.  Unfortunately, the
> whole thing looks kind of little-tested to me.  I've already found one
> somewhat obvious bug in the index making code.  None of the other large
> DocBook users in open source land use an index.

Have to admit I've only the dimmest idea of how all the various docbook bits
and pieces fit together. I installed about a dozen RPMs with hundreds of
files and by hacking apart bits of other scripts managed to build a
functioning makefile.

Now if only I knew what all those other files *did*...

> > Again - if I can be of any use, just holler.
>
> You could attack another document, such as the admin or programmer guides,
> in the same way I did.  If you're set up to build the documentation, then
> you need to install the makefile patch and you're ready to go.  You need
> to do make xyz.html twice to get the index right.  Don't even think of
> trying this with a print output format though.

OK - I'll take a stab at admin over the weekend. I take it I need to use the
versions from CVS.

- Richard Huxton