From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: lockhart@fourpalms.org, Tatsuo Ishii <t-ishii@sra.co.jp>
Cc: pgsql-hackers@postgresql.org
Cc: pgsql-docs@postgresql.org
Subject: Re: [HACKERS] Re: 7.1 docs
Date: Sat, 24 Mar 2001 11:32:02 -0500
Message-ID: <22991.985451522@sss.pgh.pa.us> (raw)
In-Reply-To: <Pine.LNX.4.30.0103241339310.2319-100000@peter.localdomain>
References: <Pine.LNX.4.30.0103241339310.2319-100000@peter.localdomain>
Peter Eisentraut <peter_e@gmx.net> 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, peter_e@gmx.net, t-ishii@sra.co.jp, pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] Re: 7.1 docs
In-Reply-To: <22991.985451522@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox