[perl #122881] [PATCH] Clarify 'use VERSION' documentation

On Wed Oct 01 20:24:03 2014, madcityzen@gmail.com wrote:
> A coworker came to me with some questions about 'use VERSION' and how
> it enables strict and features. After a bunch of testing and a bit of
> confusion, we figured out the docs were slightly misleading.
> 
> The docs say "Any explicit use of C<use strict> or C<no strict>
> overrides C<use VERSION>, even if it comes before it." but our tests
> say:
> 
> perl -e'no strict "vars"; use 5.012; $foo' # lives because no strict
> overrides use VERSION as desired
> perl -e'use strict "refs"; use 5.012; $foo' # dies because use VERSION
> turned on the rest of strict
> 
> The core tests (t/comp/use.t) confirm that this is expected behavior.
> 
> The docs then say that "In both cases, the F<feature.pm> and
> F<strict.pm> files are not actually loaded."
> 
> Though use VERSION does not load strict.pm or feature.pm, any explicit
> use of strict.pm or feature.pm (use or no) must load the files. use
> VERSION does not prevent strict.pm or feature.pm from getting loaded
> later.
> 
> I've attached patches for these two things.

Thank you for pointing out my clunky wording.  I have a tendency to do that.  However:

-before it.  In both cases, the F<feature.pm> and F<strict.pm> files are
-not actually loaded.
+before it. The F<feature.pm> and F<strict.pm> files are
+not used for C<use VERSION>.

How about saying that C<use VERSION> does not load those files?

And I’m afraid this patch is not correct, though I agree the existing wording is poor:

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 57e8186..09c1450 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -8618,7 +8618,7 @@ not in the requested version's feature bundle.  See L<feature>.
 Similarly, if the specified Perl version is greater than or equal to
 5.12.0, strictures are enabled lexically as
 with C<use strict>.  Any explicit use of
-C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
+C<no strict> overrides C<use VERSION>, even if it comes
 before it. The F<feature.pm> and F<strict.pm> files are
 not used for C<use VERSION>.

‘use strict’ *does* override ‘use VERSION’:

use v5.12;
# strictures on here
{
    use v5.8;
    # strictures off here, because they were turned on implicitly
}

use strict;
use v5.12;
{
    use v5.8;
    # strictures still on here
}

The symptom you are seeing is that strict.pm actually provides three distinct pragmata.  ‘use strict "refs"’ will turn on ‘refs’ explicitly, but ‘vars’ and ‘subs’ are still implicit and can hence be governed by ‘use v5.42’.

I cannot think of a way to word that that is not a mouthful.

> 
> Additionally, I got tripped up by the use of the word "strictures",
> since there is now a CPAN strictures.pm. The word is used about 20
> times in core, so it's not much effort to change, but I'm not sure
> that core should change what it labels things because of CPAN.

I certainly agree with that, but in this case it’s not too much bother.

(What really causes me chagrin is that ‘attribute’ has been used for :attributes for a long time in Perl, but half* of CPAN now talks about object attributes even without the word ‘object’, which can be very confusing.)

* I tend to exaggerate.

> With
> approval, I could change it to just "strict", despite being
> ungrammatical in places. Alternatively, "strictness", though "strict"
> has the benefit of not being able to be taken by someone else on CPAN.
> Also, I'd like a hot pink bike shed.

How about referring to it as C<use strict>?

-- 

Father Chrysostomos


---
via perlbug:  queue: perl5 status: new
https://rt.perl.org/Ticket/Display.html?id=122881

• Re: [perl #122881] [PATCH] Clarify 'use VERSION' documentation by Doug Bell
• [perl #122881] [PATCH] Clarify 'use VERSION' documentation by Father Chrysostomos via RT
• [perl #122881] [PATCH] Clarify 'use VERSION' documentation by Doug Bell
• [perl #122881] [PATCH] Clarify 'use VERSION' documentation by Father Chrysostomos via RT