Documentation organization - Mailing list pgsql-docs

I've been looking into ways to handle the User/Admin/Programmer vs
Integrated dichotomy a little better. I think the intergrated document as
we know it needs to go. There's too much weirdness in the order (e.g., the
tutorial coming after the FE/BE protocol, release notes somewhere in the
middle, etc.) that is created by just pasting together the "guides". Also,
the chapters are numbered differently, which makes referring to them by
number impossible.

But, it's not like I don't have a better idea. :-) DocBook has a <Set> as
a parent element of <Book>. This would look something like this:

<set>
 <title>PostgreSQL Documentation</>

 &user;
 &admin;
 ...
</set>

where &user and &admin would be the usual entities that contain <book>'s.

When you process this you get admin.html, user.html, etc. as usual, but
you also get a title page that contains links to all the "books". So this
would in essence be the integrated document, just another level added to
the click-hierarchy. (The ToC for the integrated document is way too long
anyway.)

This setup also allows us to make links across books in a transparent
fashion. For example, if I write `See also <XRef id="mvcc">' in the
administrator's guide it comes out as "See also Chapter 13 in the
PostgreSQL User's Guide", with hyperlink.

The question is how to make print documents from this. I haven't found a
way for Jade's RTF backend to split its output into several files. But it
should be possible to take this RTF document and just "save pages x-y" to
get the user's guide, "save pages y-z" to get the admin guide, etc. and
all the page numbers etc. should be in order.


At the same time I've also been pondering what kinds of books/guides we
need. The division that the integrated document already follows with its
"parts" seems like a good idea to me:

* User's guide (everything about query language)

* Administator's guide

* Interfaces guide (everything in src/interfaces, plus pgaccess, psql,
etc.)

* Programmer's guide (server-side programming, SPI, custom types,
functions, procedural languages)

* Developer's guide (to contribute to PostgreSQL)

* Tutorial

I also think we need to seperate out the

* Installation instructions

* Release notes (You really need these before installation or even
download, not after administration.)

Reference pages should be placed at the end of each document that they fit
into. E.g., postmaster in Administorator's guide, psql in Interfaces, etc.


Comments? Suggestions? Better ideas?


--
Peter Eisentraut                  Sernanders väg 10:115
peter_e@gmx.net                   75262 Uppsala
http://yi.org/peter-e/            Sweden