Re: Reference manual

Tom Lane writes:

> A complaint that someone made on the lists last night crystallized
> something that's been bothering me for awhile now: the front page of the
> integrated docs (http://www.postgresql.org/devel-corner/docs/postgres/)
> is too sparse.  If you don't already understand the layout of the docs,
> it's not clear where you want to go from here.
>
> I think it would work a lot better if this page showed not just the six
> top-level document names, but the first sublevel (ie, chapter headings)
> within each one.

Agreed.

> I have no idea if this is easy, hard, or impossible to do given our
> current documentation tools, but if it's possible I think it would be
> a good improvement.

I would have said "medium to hard" (but only given that I've been studying
DSSSL this week), but it turns out you just need to change exactly one
character.

If you have the stylesheets installed, locate the file html/dbautoc.dsl.
At the very top you'll find

(define (toc-depth nd)
  (if (string=? (gi nd) (normalize "book"))
      3
      1))

Change the 1 to 2.  The result (just the title page) can be seen at
<http://www.postgresql.org/~petere/set-index.html>.  Yeah.

In order to implement this without patching the stylesheet installation
we'd need to write a style sheet customization layer.  Not that this is
difficult, not that I haven't spent this week writing one, but I wasn't
going to use it until 7.2.  If we wanted this now we could easily use some
of the other customization features that are available, like changing the
file name suffix to .html and numbering the sections as well as the
chapters.

If you want it, you'll have a totally differently looking documentation by
Monday.  ;-)

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