> -----Original Message-----
> From: gsstark@mit.edu [mailto:gsstark@mit.edu]
> Sent: 14 April 2005 18:39
> To: Dave Page
> Cc: Greg Stark; pgsql-hackers@postgresql.org
> Subject: Re: [HACKERS] Interactive docs idea
>
> "Dave Page" <dpage@vale-housing.co.uk> writes:
>
> > We can get from 2 - 10 a day I would guess. They get mailed
> to a closed
> > list for moderation.
>
> Uhm, then where are they?

On the docs. Don't forget, PHP a) probably has a lot more users than we do, b) only keep one version of the docs online, whilst we have many and c) have been doing this a lot longer than us.

> The comments in the PHP docs, while they contain a lot of
> garbage also contain
> a lot of helpful tips and warnings. There's hardly any in the
> Postgres docs.

See above. We do get useful comments as well as rubbish.

> I think the idea of moderating the comments is inherently
> flawed. You can
> either have the deliberate, planned documentation without the
> comments, or you
> can have the wild-west style comments system, but trying to
> have it both ways
> is impossible. It just leads to the current situation where
> the comments are
> moribund.

Here's a couple of example from my inbox this morning:


[pgsql-slavestothewww] Comment 2332 added to page functions-conditional.html of version 8.0
Author: <deleted>
----
Sou do Brasil e gostei do seu site.Prabéns!


[pgsql-slavestothewww] Comment 2333 added to page install-upgrading.html of version 7.4
Author: Shayne Hardesty <0nuty1qz6jv0p1w001@sneakemail.com>
----
If you use pg_dump on an older version (say 7.1.x, 7.2.x, or 7.3.x) you will get complains from psql about carriage returns must be represented as literal \r. The workaround for this is to use the -d argument with pg_dump to dump as insert statements, but that makes restore ungodly slow (prohibitively slow in my case). In one data test I did the restore took 4 days - not workable for a production SQL environment.

The solution I found was to put together a perl script to clean the output of "pg_dump <<dbname>> > <<file>>" to change carriage returns to \r. I'm sharing my script here in hopes someone finds it useful.

-- BEGIN clean-pgdump.pl --
#!/usr/bin/perl -w

use strict;

my $file = shift @ARGV || '';
die "no input file specified\n" unless $file;

open(FILE, $file) || die "cannot read file: $!\n";
while (<FILE>) {
s'\r\\\n'\\r'go;
s'\r'\\r'go;

print;
}
close(FILE);

exit;
-- END clean-pgdump.pl --

Execute the script with ./clean-pgdump.pl <<file>> > <<newfile>>
Then run "psql -d template1 -f <<newfile>>" to import




I think it's clear we need to moderate what gets on there and what doesn't (the first comment basically says 'I'm from Bazil and I like this site').

Whilst I'm on the subject I will also point out that early versions of the the idocs were un-moderated and we still find garbage in there from time to time. If anyone sees any, please email webmaster or pgsql-www with the url so we can clean it up.

Regards, Dave.

---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/docs/faq

On Fri, Apr 15, 2005 at 08:42:45AM +0100, Dave Page wrote:
> [pgsql-slavestothewww] Comment 2333 added to page install-upgrading.html of version 7.4
> Author: Shayne Hardesty <0nuty1qz6jv0p1w001@sneakemail.com>
> ----
> If you use pg_dump on an older version (say 7.1.x, 7.2.x, or 7.3.x) you will get complains from psql about carriage returns must be represented as literal \r. The workaround for this is to use the -d argument with pg_dump to dump as insert statements, but that makes restore ungodly slow (prohibitively slow in my case). In one data test I did the restore took 4 days - not workable for a production SQL environment.
>
> The solution I found was to put together a perl script to clean the output of "pg_dump <<dbname>> > <<file>>" to change carriage returns to \r. I'm sharing my script here in hopes someone finds it useful.
>
> -- BEGIN clean-pgdump.pl --
> #!/usr/bin/perl -w
>
> use strict;
>
> my $file = shift @ARGV || '';
> die "no input file specified\n" unless $file;
>
> open(FILE, $file) || die "cannot read file: $!\n";
> while (<FILE>) {
> s'\r\\\n'\\r'go;
> s'\r'\\r'go;
>
> print;
> }
> close(FILE);
>
> exit;
> -- END clean-pgdump.pl --
>
> Execute the script with ./clean-pgdump.pl <<file>> > <<newfile>>
> Then run "psql -d template1 -f <<newfile>>" to import

I think this comment is a good example of a problem with the current
system; this comment applies to both 7.4 and 8.0, but it's only in the
7.4 version. It's also long enough that it might not get into the
mainline docs (though I'm completely guessing there). It would be useful
if there was a way to have a comment cross versions.
--
Jim C. Nasby, Database Consultant decibel@decibel.org
Give your computer some brain candy! www.distributed.net Team #1828

Windows: "Where do you want to go today?"
Linux: "Where do you want to go tomorrow?"
FreeBSD: "Are you guys coming, or what?"

---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/docs/faq