Thread: restructure libpq docs (WIP)

I'd like to improve the libpq documentation, as it is (IMHO) not very
good at the moment.

The first thing I'm working on is restructuring the libpq docs to use
the DocBook "refsect" tags -- so that each function is documented in a
page similar to the existing reference documentation for SQL commands,
with separate sections for the function prototype, parameters, return
value, and description. I've done this for most (80%+) of the functions
in the libpq docs, but a few sections still need to be converted
(asynch. query processing and COPY-related functions).

While doing this, I've also made some miscellaneous improvements to the
libpq documentation throughout, improved some of the markup in
ecpg.sgml, arch-dev.sgml, and history.sgml, and made some
cosmetic-but-pervasive changes to the SGML in libpgctl.sgml.

I figured I'd send this in now, so that people can take a look at the
resulting documentation layout -- if you'd like me to do things
differently or if you have a suggestion, please speak up.

The patch is attached -- it's 420KB uncompressed, so I've gzip'ed it.

Cheers,

Neil
--
Neil Conway <neilc@samurai.com> || PGP Key ID: DB3C29FC

Neil Conway writes:

> The first thing I'm working on is restructuring the libpq docs to use
> the DocBook "refsect" tags -- so that each function is documented in a
> page similar to the existing reference documentation for SQL commands,

I don't think this makes the libpq documentation better.  In the current
layout, the documentation is organized by topic, and a user looking for
information about a particular topic (e.g., connecting, evaluating query
results) can get easily get an overview over all the interfaces that apply
to that topic, while also getting general information about the topic.
If you organize it in reference pages then you're addressing only users
who already know the interface and want to look for particular details
about particular functions.  If you just want to know, "what's the deal
with async connections", you need to know/guess/find out the function that
deals with it and, if there is more than one relevant function, you need
to gather the information you want from several places.  (And you seemed
to have realized that half-way and left some sections as normal sections
and converted some sections to refsects.)

Granted, reference pages could coexist with, but cannot be a replacement
for, a narrative documentation organized by topic.  Since you mentioned
it, we learned that lesson from the SQL command reference.  For years the
only information you could get about important SQL topics such as
transactions or foreign keys were hidden behind reference pages with
less-than-obvious names like CREATE TABLE or BEGIN.  Nowadays, the User's
Guide has a parallel narrative description of those topics and the number
of complaints has dropped noticeably.

--
Peter Eisentraut   peter_e@gmx.net

On Fri, 2003-03-14 at 08:44, Peter Eisentraut wrote:
> I don't think this makes the libpq documentation better.  In the current
> layout, the documentation is organized by topic, and a user looking for
> information about a particular topic (e.g., connecting, evaluating query
> results) can get easily get an overview over all the interfaces that apply
> to that topic, while also getting general information about the topic.

I think users with those kinds of requirements will still be satisfied
by the new documentation layout. The functions themselves are organized
into reference subsections (e.g. "Function Reference: Connection to the
Database", "Function Reference: Executing Queries", etc.), and each
function name has a brief description of its intent in the TOC. In your
asynch. connection example, it seems pretty straight-forward to me: look
in the database connection reference: the entry for PQconnectStart
clearly denotes that it should be used to initial a non-blocking
database connection.

Also, there's no reason why someone else can't contribute additional
narrative documentation. The actual content of the existing libpq docs
was largely reference material, so IMHO it makes more sense to convert
that over to a format in which individual reference entries can be more
easily located.

> (And you seemed
> to have realized that half-way and left some sections as normal sections
> and converted some sections to refsects.)

Not really half-way: there is some existing material that shouldn't be
in refsects (e.g. info on the usage of files by libpq, example
applications, threading behavior, etc.). As I said before, there
probably should be more of this kind of narrative documentation, but
someone needs to go ahead and write it first.

Cheers,

Neil

--
Neil Conway <neilc@samurai.com> || PGP Key ID: DB3C29FC