From: Richard Huxton <dev@archonet.com>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: pgsql-docs@postgresql.org
Subject: Re: Docs with index
Date: Tue, 3 Apr 2001 18:45:05 +0100
Message-ID: <004501c0bc65$d34e0b80$1001a8c0@archonet.com> (raw)
References: <Pine.LNX.4.30.0104031809250.974-100000@peter.localdomain>
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: dev@archonet.com, peter_e@gmx.net
Subject: Re: Docs with index
In-Reply-To: <004501c0bc65$d34e0b80$1001a8c0@archonet.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox