develooper Front page | perl.perl5.porters | Postings from August 2009

Would updating "Ancient Perl" examples in documentation be a good idea?

Thread Next
From:
Flavio Poletti
Date:
August 28, 2009 08:08
Subject:
Would updating "Ancient Perl" examples in documentation be a good idea?
Message ID:
aeba50980908280639k53ab0l7ab9a3d858929888@mail.gmail.com
Hi,
   I'm wondering if the Perl 5 development team is willing to accept
documentation patches to bring examples in the documentation to something
more in line with what's actually available in 5.10 and what's considered
better practice in 2009.

For example, in perldiag I found the following example:

    open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!";
    while (<STDIN>) {
        print;
        print OUT;
    }
    close OUT;

I think that, were this example written today, it would be more like this:

    open my $out, '>', $ARGV[0] or die "Can't write to $ARGV[0]: $!";
    while (<STDIN>) {
        print;
        print {$out} $_;
    }
    close $out;

i.e. using lexical filehandles and the three-parameter form of open(). And
yes, we could discuss the PBP-ism of writing braces around $out in the print
statement, but you get the idea.

In addition to this, many documents (e.g. perlopentut) work in "incremental
mode", i.e. showing the ancient way of doing stuff first, then telling the
reader about new and exciting features.

For someone that's trying to solve a problem the risk of taking the obsolete
way is high IMHO, so I'd propose to rearrange the docs to show the modern
way first, then talk about how to be compatible with previous versions.

Would patches to update the examples and bring them to 2009 be welcome by
the developers?

Cheers,

   Flavio.

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About