[doc] perlfunc our section block unclear

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 <dagolden@cpan.org>
AuthorDate: Thu Jul 5 20:14:15 2012 -0400
Commit:     David Golden <dagolden@cpan.org>
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.

Perl / perl5

[doc] perlfunc our section block unclear #22424