Re: Tips needed for contrib doc

A Diumenge 14 Octubre 2007, Peter Eisentraut va escriure:
> Albert Cervera i Areny wrote:
> > The problem is that if we want these docs in the Reference section of
> > the documentation right after "PostgreSQL Server Applications" they
> > can't be chapters nor sections, they need to be <refentry>'s.
>
> That is not true, AFAICT. What do you base this assertion on?

You're right, that's not exactly true:

Reference is a Part. If we still want contrib inside Reference, contrib can be
a <chapter>, <reference> or other elements defined at
http://www.docbook.org/tdg5/en/html/part.html. But I cant' make the contrib
section a <part> inside reference (that means no chapter per module!).

If I make it a chapter the numbering inside Reference becomes:

"I. SQL Commands"
"II. PostgreSQL Client Applications"
"III. PostgreSQL Server Applications"
"43. Standard Modules"

Not sure if that's a problem, but that's why I'm asking. That allows, however,
having each contrib module in a section in this chapter and thus fits in one
page.

Though I agree I should concentrate on content, not style, having lots of very
small pages isn't very nice either. You can see that in the docs I have
online. In that case each module is a chapter as Tom suggests and it's a
completely new Part after "Internals"

IMHO having it in reference would make sense if contrib docs where organized
like, well... references but that's not the case for most of them. After all
you need some introduction to the module, some examples, etc.

--
Albert Cervera i Areny
http://www.NaN-tic.com