From: | "Richard Huxton" <dev(at)archonet(dot)com> |
---|---|
To: | "Peter Eisentraut" <peter_e(at)gmx(dot)net> |
Cc: | <pgsql-docs(at)postgresql(dot)org> |
Subject: | Re: Docs with index |
Date: | 2001-04-03 17:45:05 |
Message-ID: | 004501c0bc65$d34e0b80$1001a8c0@archonet.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-docs |
From: "Peter Eisentraut" <peter_e(at)gmx(dot)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
From | Date | Subject | |
---|---|---|---|
Next Message | Mitesh Shah | 2001-04-04 00:57:25 | eRServer |
Previous Message | Peter Eisentraut | 2001-04-03 16:28:42 | Re: Docs with index |