Re: [HACKERS] Re: 7.1 docs

Peter Eisentraut <peter_e(at)gmx(dot)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