Subject: Documentation TODO list

From: Rod Taylor <[email-masked]>
Date: 27 Feb 2003 23:05:37 -0500

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?

-- 
Rod Taylor <[email-masked]>

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

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 7 Mar 2003 00:39:04 -0500 (EST)

Oh, sure.  Can you tell me some of them?

---------------------------------------------------------------------------

Rod Taylor wrote:
-- Start of PGP signed section.
> chance of adding a 'Docs' section to the standard to-do list to ensure
-- End of PGP section, PGP failed!

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: Rod Taylor <[email-masked]>
Date: 08 Mar 2003 11:35:04 -0500

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

> Oh, sure.  Can you tell me some of them?

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   [email-masked]

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   [email-masked]

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   [email-masked]

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   [email-masked]

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   [email-masked]

-- 
Rod Taylor <[email-masked]>

---

From: Peter Eisentraut <[email-masked]>
Date: Sun, 9 Mar 2003 17:24:42 +0100 (CET)

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

All of these things are already done in my local copy.  I'm currently
preparing the documentation for a book publisher, so I've been
accumulating a rather massive amount of these kinds of fixes.  I think
once they've passed by the other reviewers involved in this process I'll
commit them.

---

From: Tom Lane <[email-masked]>
Date: Sun, 09 Mar 2003 13:14:47 -0500

> once they've passed by the other reviewers involved in this process I'll

I'd suggest committing sooner rather than later, or you are going to
suffer a daunting merge problem.  You don't think the CVS docs are going
to hold still for long, do you?

I've watched tech writers at both Great Bridge and Red Hat make exactly
this mistake: accumulate huge amounts of editorial fixes, and then
discover that there wasn't any practical way to merge with the community
docs when it came time to do so --- because the community docs had
diverged from what they started from.  Please don't follow in their
footsteps.

			regards, tom lane

PS: a book project sounds cool.  Can you give any details?

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 13 Mar 2003 16:59:15 +0100 (CET)

> PS: a book project sounds cool.  Can you give any details?

We are putting out the PostgreSQL documentation in German.  It will
probably be finished in June.  The "backpatching" of the editorial fixes
to the English original is just a bonus.

The HTML rendition of the translation will be available for free.  I'm
also trying to work with the publisher to use their resources to make us
some decent quality PDFs of the English documentation.