From: Ron Chmara <ron@Opus1.COM>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: Eric Mueller <eric@themepark.com>
Cc: 'PostgreSQL general mailing list' <pgsql-general@postgresql.org>
Cc: pgsql-docs@postgresql.org
Subject: Re: [GENERAL] RE: RE: Re: MySQL and PostgreSQL speed compare
Date: Fri, 05 Jan 2001 03:37:32 -0700
Message-ID: <3A55A3E9.4E27C1FD@opus1.com> (raw)
References: <Pine.LNX.4.30.0101031819070.1310-100000@peter.localdomain>
Peter Eisentraut wrote:
> Just to add a particular point, in addition to Vince's excellent general
> points, as the one who was last to update the function documentation:
> The reason that there's no "detailed" documentation is that there are no
> details. How much can you write about round(), avg(), or current_user?
Usage, history, syntax, a few examples of common use (in actual code), error
messages that may result, times to avoid it, workarounds if it fails to do
what you want and similar ways of accomplishing the same thing, etc.....
Quite a bit, actually.
For example, here's what goes into the PHP round() entry:
http://www.php.net/manual/function.round.php
The inital documentation *is* slim. But the user-added notes (which is
really what makes the php-docs work well) add to the information in a
fast, easy to use, manner, without anyone having to learn docbook,
XML, and Jade (which is what the main PHP docs are written in.).
The same feature exists on the mySQL site:
http://www.mysql.com/documentation/mysql/commented/manual.php?section=Mathematical_functions
But it's used less. They have better examples for round(), however.
Now, compare that to:
a) finding the function in the online pg docs, (what's up with that slow search?)
http://www.postgresql.org/docs/user/x2591.htmhttp://www.postgresql.org/docs/postgres/x2595.htm
b) once you find it, can you add to it?
c) Are there several examples of usage?
d) Can a newbie grasp usage, or see bare-bones examples?
There's lots of details that the new users find interesting. In the php
project, some seasoned developers use a reduced version of the manual,
no notes, because they don't need it. But a newbie, staring at something
for the first time, is more than happy to see long descriptions, long
notes, etc.
The source to do this kind of thing _in_ PHP is available from their CVS,
if it's a good idea for pgsql. However, it does use a mySQL backend,
so it would need some porting. :-)
-Ronabop
--
Personal: ron@opus1.com, 520-326-6109, http://www.opus1.com/ron/
Work: rchmara@pnsinc.com, 520-546-8993, http://www.pnsinc.com/
The opinions expressed in this email are not neccesarrily those of myself,
my employers, or any of the other little voices in my head.
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: ron@Opus1.COM, peter_e@gmx.net, eric@themepark.com, pgsql-general@postgresql.org
Subject: Re: [GENERAL] RE: RE: Re: MySQL and PostgreSQL speed compare
In-Reply-To: <3A55A3E9.4E27C1FD@opus1.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox