Re: Escape handling in COPY, strings, psql

Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us> writes:

> Christopher Kings-Lynne wrote:
> >
> > Each comment is supposed to be acted upon (ie. fixed in source), then
> > deleted.
>
> Right, they are more _usage_ comments, but still I think they could be
> consolidated into manual text.

If that's "supposed" to happen it certainly hasn't been the de facto
procedure.

I think they have things partly right here though. A lot of those comments
aren't actually the kinds of things that belong in the canonical reference.
They include things like "watch out for this common error" or "here's a handy
use for this function". Often the "common error" or "handy use" are pretty
bogus but every now and then there's a genuinely useful one.

These kinds of things would just clutter up a reference. A reference should
just state unambiguously this function does XYZ and give examples that help
explain XYZ.

The PHP Docs do have a bit of a problem in that often the comments include
things like "In case X, what happens is Y" which really ought to be covered by
the canonical reference. That's a problem.

--
greg