Re: restructure libpq docs (WIP)

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