Re: restructure libpq docs (WIP)

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(at)gmx(dot)net