Thread: Docs with index

I've added some index entries to the user's guide as exploration.  The
result can be seen at

http://www.postgresql.org/~petere/doc-with-index/bookindex.html

The patch is at

http://www.postgresql.org/~petere/doc-with-index/patch

Comments are welcome as to whether this seems useful, and if so, about the
selection of the index entries.  (There need to be more, of course.)

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/

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

> I've added some index entries to the user's guide as exploration.  The
> result can be seen at
>
> http://www.postgresql.org/~petere/doc-with-index/bookindex.html
>
> The patch is at
>
> http://www.postgresql.org/~petere/doc-with-index/patch
>
> Comments are welcome as to whether this seems useful, and if so, about the
> selection of the index entries.  (There need to be more, of course.)

Very useful indeed.

The categories seem right to me. Looks like you've got:

1. types (integer, date)
2. keywords (limit, where)
3. concepts (joins, operators)

Can't think of any other categories, just more entries in each. I think it
might prove useful to identify weaknesses in the docs since if it doesn't
index well it probably needs reworking.

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.

Again - if I can be of any use, just holler.

- Richard Huxton

Richard Huxton writes:

> Can't think of any other categories, just more entries in each. I think it
> might prove useful to identify weaknesses in the docs since if it doesn't
> index well it probably needs reworking.

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.

> 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:

|     if ($idx->{'seealso'}) {
|         # it'd be nice to make this a link...
|         if ($lastout) {
|             print OUT "\n  </$lastout>\n";
|             $lastout = "";
|         }
|         print OUT $indent, "<seealsoie>", &escape($idx->{'seealso'}), "</seealsoie>\n";
|     }

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.

> 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.

--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/

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