Re: Documentation TODO list

4 or 5 email segments below. Use his signature as a separator.

On Fri, 2003-03-07 at 00:39, Bruce Momjian wrote:
> Oh, sure. Can you tell me some of them?
>
> ---------------------------------------------------------------------------
>
> Rod Taylor wrote:
> -- Start of PGP signed section.
> > Peter sent out a number of documentation to-do items that need to be
> > addressed -- but I've already forgotten what most of them were. Any
> > chance of adding a 'Docs' section to the standard to-do list to ensure
> > they're tracked?

The libpq documentation contains this:

"""
<productname>PostgreSQL</productname> provides a fast-path interface to
send function calls to the backend. This is a trapdoor into system
internals and can be a potential security hole. Most users will not
need
this feature.
"""

Why and under what circumstances is this a security hole, and what is a
user to do about it?

--
Peter Eisentraut peter_e(at)gmx(dot)net

Example 7-5 in the User's Guide is also outdated, because there is now a
function substr for bytea, so the mechanics the example tries to
illustrate are a tad more complicated. New example requested.

--
Peter Eisentraut peter_e(at)gmx(dot)net

User's Guide section 7.2, example 7-1, claims that

SELECT 2 ^ 3 AS "Exp";

will be equivalent, after type resolution, to

SELECT CAST(2 AS double precision) ^ CAST(3 AS double precision) AS
"Exp";

(which is true) or

SELECT 2.0 ^ 3.0 AS "Exp";

which is not true, since 2.0 and 3.0 are nowadays of type numeric.
Rather
than deleting the third branch of this claim (which would also imply
deleting the subsequent Note), does anyone want to think of a new
example?

Related observations: The premise of the example is that the operator ^
only exists for double precision arguments. ^ is implemented using SQL
function dpow, which is implemented using C function dpow. There's also
a
documented SQL function pow, which is implemented using C function dpow.
Wouldn't it be enough to have the documented SQL function pow and the
operator on top of that?

There's also a documented SQL function pow for "numeric", but no
operator
for it. Should that be added?

--
Peter Eisentraut peter_e(at)gmx(dot)net

The documentation of to_char() is unclear regarding the meaning of the
various formatting patterns for plus and minus signs:

S negative value with minus sign (uses locale)
MI minus sign in specified position (if number < 0)
PL plus sign in specified position (if number > 0)
SG plus/minus sign in specified position

Here is what happens: (The quotes in the result are not actually part of
the function result.)

to_char(485.8, 'S9999.999') ' +485.800'
to_char(485.8, 'MI9999.999') ' 485.800'
to_char(485.8, 'PL9999.999') '+ 485.800'
to_char(485.8, 'SG9999.999') '+ 485.800'

to_char(-485.8, 'S9999.999') ' -485.800'
to_char(-485.8, 'MI9999.999') '- 485.800'
to_char(-485.8, 'PL9999.999') ' -485.800'
to_char(-485.8, 'SG9999.999') '- 485.800'

to_char(485.8, '9999.999S') ' 485.800+'
to_char(485.8, '9999.999PL') ' 485.800+'
to_char(485.8, '9999.999MI') ' 485.800 '
to_char(485.8, '9999.999SG') ' 485.800+'

to_char(-485.8, '9999.999S') ' 485.800-'
to_char(-485.8, '9999.999PL') ' -485.800 '
to_char(-485.8, '9999.999MI') ' 485.800-'
to_char(-485.8, '9999.999SG') ' 485.800-'

The SG seems to work okay, and the S could be considered okay if the
documentation were adjusted, but I suspect there are a few bugs in PL
and
MI.

--
Peter Eisentraut peter_e(at)gmx(dot)net

So based on publishing standards, so to speak, it would seem to make
sense
to present the existing PostgreSQL documentation as just one book.

Now having that in mind and considering the all too often heard
complaint
that it is too difficult to find anything in the PostgreSQL
documentation
I would like to tackle this reorganization at the source level.
Initially,
I think we could concatenate the existing "books" approximately in the
order they are right now, relabelling them as "parts".

I know one possible objection is that it takes too long to build the
complete documentation set. But you can do an SGML syntax check that
takes a few seconds on modern machines and catches most mistakes.
Compared to making the documentation easier to use and more "marketable"
I
think this is a price we have to pay.

Thoughts?

--
Peter Eisentraut peter_e(at)gmx(dot)net

--
Rod Taylor <rbt(at)rbt(dot)ca>

PGP Key: http://www.rbt.ca/rbtpub.asc