Re: Re: [HACKERS] Re: 7.1 docs

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!