Re: [DOCS] Re: [HACKERS] Re: 7.1 docs

[Tom Lane]

Roberto Mello <[EMAIL PROTECTED]> 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

---(end of broadcast)---
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/users-lounge/docs/faq.html

Re: [DOCS] Re: [HACKERS] Re: 7.1 docs

[Roberto Mello]

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!

---(end of broadcast)---
TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]