Обсуждение: 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

On Sat, Mar 24, 2001 at 11:32:02AM -0500, Tom Lane wrote:
>
> 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 ;-)

    Agreed.

> 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.

    Again I agree. The functions docs are insufficient for most functions
I would say.
    I like the way the Oracle functions are documented, except for the
fact that they have one huge page for all functions, which is hard on
those on slow connections reading docs online.
    They have functions in tables grouped per functionality (e.g. character
functions that returning character values, character functions returning
number values) and with each function name (which is all that is in the
table) is linked to a larger explanation of the function with the complete
syntax and examples (usually two).
    http://oradoc.photo.net/ora81/DOC/server.815/a67779/function.htm#1028572

    -Roberto
--
+----| http://fslc.usu.edu USU Free Software & GNU/Linux Club|------+
  Roberto Mello - Computer Science, USU - http://www.brasileiro.net
      http://www.sdl.usu.edu - Space Dynamics Lab, Web Developer
If it wasn't for C, we would be using BASI, PASAL and OBOL!

Roberto Mello <rmello@cc.usu.edu> writes:
>     I like the way the Oracle functions are documented, except for the
> fact that they have one huge page for all functions, which is hard on
> those on slow connections reading docs online.
>     They have functions in tables grouped per functionality (e.g. character
> functions that returning character values, character functions returning
> number values) and with each function name (which is all that is in the
> table) is linked to a larger explanation of the function with the complete
> syntax and examples (usually two).

Yes, it'd be cool to have the User's Guide contain the existing function
tables with each entry hotlinked to a more extensive reference entry.
We could eliminate some of the nitty-gritty details from the User's
Guide that way, which I think is good.  I don't want to reduce the
function tables to just names a la Oracle --- I think the tables are
good as they are.  But there are places, such as in the discussion of
the pattern-match functions, where we have reference-page-like material
that doesn't fit very well in the U.G.

            regards, tom lane