On Fri, Jul 2, 2010 at 07:18, David Golden <xda...@gmail.com> wrote:
> On Thu, Jul 1, 2010 at 7:11 PM, Chas. Owens <chas.ow...@gmail.com> 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.
>
> I think we should write good documentation aimed at competent people
> and only "intro" level material needs to be pedantic and include the
> "standard" pragmata list. (That could be one for your style guide --
> anything perl*intro|tut|quick should have them, everything else should
> not.)
>
> I just don't think every snippet of example needs to have "use 5.014"
> or "use strict" or "use warnings" or whatever. It just clutters the
> examples. Certainly, the introduction section of documentation files
> could make a point to say that examples assume those three pragmas,
> but the main content of the documents (even ones accessed via -f like
> perlfunc) don't need to be that pedantic if omitting make the
> documentation more streamlined.
>
> To the extent that certain features of something being documented are
> only available as of Perl version N, that could be noted in the text.
>
> -- David
>
It isn't just that say wasn't added until 5.10, it is that say doesn't
even work without a "use 5.010;" or similar statement. This means
that the person coming to the Perl for the first time will encounter
one of three scenarios:
1. None of the examples use features that are turned on by pragmas
2. Some of the examples use features that are turned on by pragmas,
but the pragmas are not visible in the example, so when the novice
tries to run the example he or she gets an error message that is not
very helpful ("Undefined subroutine &main::say called" not "To use the
say function use the feature pragma or add 'use 5.012;' to your
program"). This leads to confusion and thinking that the
documentation has broken examples.
3. Every non-trivial example contains a use statement that lets you
know what version of Perl this code will run on. This has the handy
side effect of turning on the features available in that version of
Perl.
While the third scenario is somewhat annoying to the more advanced
users, it is a lifesaver for novices.
A fourth scenario where each document has an intro section that
explains that the examples will be run under the following X pragmas
would be better than scenario 2, but only marginally. In my
experience, people just don't read those introductory statements. So,
all that would do is give experienced users the opportunity to say
"Did you read the introductory material? Well, no wonder the examples
didn't work, you need to add these X lines. The document tells you
that at the top." Adding an introductory section will also not help
people who are using perldoc -q, -f, -v, and the possible -O (for
operator help) or Padre's context sensitive help, since those only
spit out the section being referenced.
A fifth scenario where there is an introductory statement that
examples will work on 5.8 or later unless otherwise marked and then
pragmas are added to the examples that need features like say would
also work quite well. Heck, you wouldn't even need the introductory
statement. This really isn't about what versions of Perl the example
works on, it is about being able to use the features that are hidden
because of backwards compatibility concerns.
--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
