Re: restructure libpq docs (WIP)
От | Peter Eisentraut |
---|---|
Тема | Re: restructure libpq docs (WIP) |
Дата | |
Msg-id | Pine.LNX.4.44.0303140012300.1617-100000@peter.localdomain обсуждение исходный текст |
Ответ на | restructure libpq docs (WIP) (Neil Conway <neilc@samurai.com>) |
Ответы |
Re: restructure libpq docs (WIP)
|
Список | pgsql-patches |
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
В списке pgsql-patches по дате отправления: