Re: Announcing the Perl 5 Documentation Team

On Fri, Jul 2, 2010 at 10:58, Caleb Cushing <[email protected]> wrote:
> On Thu, Jul 1, 2010 at 7:11 PM, Chas. Owens <[email protected]> wrote:
>> Failure to add a use 5.010; or use 5.012; limits the features that can
>> be used in examples.  For instance, this example won't work even under
>> 5.12 as it is written:
>>
>>    say "foo";
>>
>> It is possible that we should only add use statements to examples that
>> need features in 5.10 or later.
>>
> isn't
>
>    use features 'say';
>
> somewhere on the page
>
> I guess it says...
>
> This keyword is available only when the "say" feature is enabled: see feature.
snip

That is in say's part of perlfunc, I am talking about being able to
use say in examples for other functions, operators, etc.  For
instance, in substr it says

   $x = '1234';
   for (substr($x,1,2)) {
       $_ = 'a';   print $x,"\n";    # prints 1a4
       $_ = 'xyz'; print $x,"\n";    # prints 1xyz4
       $x = '56789';
       $_ = 'pq';  print $x,"\n";    # prints 5pq9
   }

We could cut down the noise somewhat by saying

   my $x = '1234';
   for (substr($x,1,2)) {
       $_ = 'a';   say $x;    # prints 1a4
       $_ = 'xyz'; say $x;    # prints 1xyz4
       $x = '56789';
       $_ = 'pq';  say $x;    # prints 5pq9
   }

But now the example won't run in Perl 5.12.  The example needs

   use 5.010;
   my $x = '1234';
   for (substr($x,1,2)) {
       $_ = 'a';   say $x;    # prints 1a4
       $_ = 'xyz'; say $x;    # prints 1xyz4
       $x = '56789';
       $_ = 'pq';  say $x;    # prints 5pq9
   }

And this is a good idea anyway because this feature (substr's lvalue
being persistant) doesn't work in Perl 5.8.

-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.