Re: [DOCS] 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! ---(end of broadcast)--- TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
Re: [DOCS] Re: [HACKERS] Re: 7.1 docs
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: [HACKERS] Re: 7.1 docs
Peter Eisentraut [EMAIL PROTECTED] 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 ---(end of broadcast)--- TIP 2: you can get off all lists at once with the unregister command (send "unregister YourEmailAddressHere" to [EMAIL PROTECTED])