Re: [HACKERS] Re: 7.1 docs

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