[doc] perlfunc our section block unclear

[poti1]

Where Perl doc perlfunc end of "our" section.

Description

Please rephrase:

"our differs from use vars, which allows use of an unqualified name only within the affected package, but across scopes."

I had to reread that sentence at least 5 times.

Perhaps at least rephrase as such:

"our differs from use vars, which allows the use of an unqualified name across multiple scopes, while still being limited to the affected package."

[jkeenan]

Where Perl doc perlfunc end of "our" section.

Description

Please rephrase:

"our differs from use vars, which allows use of an unqualified name only within the affected package, but across scopes."

I had to reread that sentence at least 5 times.

Perhaps at least rephrase as such:

"our differs from use vars, which allows the use of an unqualified name across multiple scopes, while still being limited to the affected package."

I agree that the "but across scopes" in the current formulation is somewhat opaque. This language appears to date back 12 years to this commit:

commit 848bab4facdb0e4d55df87ebb5078741d248bb2b
Author:     David Golden <[email protected]>
AuthorDate: Thu Jul 5 20:14:15 2012 -0400
Commit:     David Golden <[email protected]>
CommitDate: Thu Jul 5 20:14:15 2012 -0400

    perlfunc: clarify 'our' again for vars.pm behavior
    
    rjbs discovered that vars.pm docs lie and it works within
    a package, even across file scopes

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 2d730996bb..8e8bccaa25 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4279,8 +4279,8 @@ allocate storage for that name within the current scope.
 This means that when C<use strict 'vars'> is in effect, C<our> lets you use
 a package variable without qualifying it with the package name, but only within
 the lexical scope of the C<our> declaration.  In this way, C<our> differs from
-C<use vars>, which allows a the use of an unqualified name I<only> within the
-affected package.
+C<use vars>, which allows use of an unqualified name I<only> within the
+affected package, but across scopes.

@xdg, can you clarify? Can anyone suggest better language? Thanks.

[book]

From the vars documentation:

Unlike pragmas that affect the $^H hints variable, the "use vars" and "use subs" declarations are not lexically scoped to the block they appear in: they affect the entire package in which they appear. It is not possible to rescind these declarations with "no vars" or "no subs".

Meaning that it even works across different files:

$ echo 'package Foo; use vars q{$bar}; $bar = "bar from A"; 1;' > A.pm
$ echo 'package Foo;                   print "$bar\n";      1;' > B.pm
$ perl -I. -MA -MB -e1
bar from A

Proposing another way to write the sentence (with a link to the documentation for vars):

C<our> is lexically scoped, and as such differs from C<use L<vars>>,
which allows use of an unqualified name I<only> within the affected package,
without consideration for the scopes.

[Leont]

I like the way Book phrased it, it's clear and correct.

[book]

Improved documentation merged as 8c6bc2cf61f33cf709e25f0fef913e2a9ebad73e.