Received: from sss.pgh.pa.us (sss.pgh.pa.us [209.114.132.154]) by mail.postgresql.org (8.11.3/8.11.1) with ESMTP id f2OGWCw68322; Sat, 24 Mar 2001 11:32:12 -0500 (EST) (envelope-from tgl@sss.pgh.pa.us) Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1]) by sss.pgh.pa.us (8.11.3/8.11.3) with ESMTP id f2OGW2w22994; Sat, 24 Mar 2001 11:32:02 -0500 (EST) To: Peter Eisentraut cc: lockhart@fourpalms.org, Tatsuo Ishii , pgsql-hackers@postgresql.org, pgsql-docs@postgresql.org Subject: Re: [HACKERS] Re: 7.1 docs In-reply-to: References: Comments: In-reply-to Peter Eisentraut message dated "Sat, 24 Mar 2001 13:48:35 +0100" Date: Sat, 24 Mar 2001 11:32:02 -0500 Message-ID: <22991.985451522@sss.pgh.pa.us> From: Tom Lane X-Archive-Number: 200103/123 X-Sequence-Number: 557 Peter Eisentraut writes: > All functions are documented (for appropriate values of "all") in the > User's Guide, chapter 4. There was probably once the idea of setting up a > reference page set for the functions, but I don't know if this is > particularly better than what we have now. In fact, I would argue it's > worse. A "page per function" approach is clearly overkill for the vast majority of our functions. I think that's not unrelated to the fact that no one's ever bothered to prepare such documentation ;-) On the other hand, the existing layout of the User's Guide encourages a "line per function" approach, which is insufficient for at least some functions. We've worked around that by adding paragraphs below the main table on each page, but that seems a little awkward in many cases. A reference section in the style of typical Unix section-3 man pages (multiple related functions per page, with text discussion and examples) would be a useful compromise, maybe. Needs more thought. regards, tom lane