Add note about scope to strict documentation

[p5pRT]

Migrated from rt.perl.org#126843 (status was 'resolved')

Searchable as RT126843$

[p5pRT]

From madcityzen@gmail.com

This patch adds an introductory paragraph to the strict docs, and mentions that it applies only to the current file or scope. Reported by KES.

Doug Bell
madcityzen@​gmail.com

[p5pRT]

From madcityzen@gmail.com

0001-add-note-about-scope-in-strict-docs.patch

From 479ecf8380cf30a390e8bbc6176ace2603a8a760 Mon Sep 17 00:00:00 2001
From: Doug Bell <madcityzen@gmail.com>
Date: Tue, 8 Dec 2015 09:35:15 -0600
Subject: [PATCH] add note about scope in strict docs

The strict pragma only effects the current file or block scope, but we
never mention that in the docs. Thanks KES for reporting this.
---
 lib/strict.pm | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/strict.pm b/lib/strict.pm
index 03ed21c..6505f09 100644
--- a/lib/strict.pm
+++ b/lib/strict.pm
@@ -94,6 +94,9 @@ strict - Perl pragma to restrict unsafe constructs
 
 =head1 DESCRIPTION
 
+The C<strict> pragma restricts constructs in the current file or scope
+block that could be unsafe, turning them into errors.
+
 If no import list is supplied, all possible restrictions are assumed.
 (This is the safest mode to operate in, but is sometimes too strict for
 casual programming.)  Currently, there are three possible things to be
-- 
2.4.9 (Apple Git-60)

[p5pRT]

From @jkeenan

On Tue Dec 08 07​:43​:55 2015, madcityzen@​gmail.com wrote​:

This patch adds an introductory paragraph to the strict docs, and
mentions that it applies only to the current file or scope. Reported
by KES.

Doug Bell
madcityzen@​gmail.com

The patch​:

#####
+The C<strict> pragma restricts constructs in the current file or scope
+block that could be unsafe, turning them into errors.
+
#####

At the risk of splitting stylistic hairs ...

When I hear the phrase, "The strict pragma restricts constructs ...," I expect there to be either a "to" or a "by" coming down the pike. I.e., I expect something like

"The strict pragma restricts constructs by making them jump through hoops."

or​:

"The strict pragma restricts constructs to two meals a day."

Comments?

Thanks for the patch.

--
James E Keenan (jkeenan@​cpan.org)

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From madcityzen@gmail.com

On Dec 8, 2015, at 6​:28 PM, James E Keenan via RT <perlbug-followup@​perl.org> wrote​:

On Tue Dec 08 07​:43​:55 2015, madcityzen@​gmail.com wrote​:

This patch adds an introductory paragraph to the strict docs, and
mentions that it applies only to the current file or scope. Reported
by KES.

Doug Bell
madcityzen@​gmail.com

The patch​:

#####
+The C<strict> pragma restricts constructs in the current file or scope
+block that could be unsafe, turning them into errors.
+
#####

At the risk of splitting stylistic hairs ...

When I hear the phrase, "The strict pragma restricts constructs ...," I expect there to be either a "to" or a "by" coming down the pike. I.e., I expect something like

"The strict pragma restricts constructs by making them jump through hoops."

or​:

"The strict pragma restricts constructs to two meals a day."

Comments?

It is a bit awkward. How about​:

  "The strict pragma disables certain unsafe Perl expressions in the current file or scope block, turning them into errors."

Instead of "expressions", it could say "practices". I'd not want to use "features" there, though it is accurate, it's easy to misinterpret. It can't be "parsing rules", as not everything's done at parse time. "syntax" seems, to me, to have the same problem as "parsing rules" (though I'm not sure).

Doug Bell
madcityzen@​gmail.com

[p5pRT]

From @kentfredric

On 9 December 2015 at 15​:03, Doug Bell <madcityzen@​gmail.com> wrote​:

It is a bit awkward. How about​:

    "The strict pragma disables certain unsafe Perl expressions in the current file or scope block\, turning them into errors\."

Instead of "expressions", it could say "practices". I'd not want to use "features" there, though it is accurate, it's easy to misinterpret. It can't be "parsing rules", as not everything's done at parse time. "syntax" seems, to me, to have the same problem as "parsing rules" (though I'm not sure).

+1

My head positively spins when I read

  <x> restricts constructs by <y>

Because there's a competing interpretation of "constructs" as a verb ,
so part of me gets confused wondering what is being constructed,
because skim reading can make it so you're seeing

  constructs by <y>

As your context.

Though I wouldn't use the words "unsafe", because I don't think
there's anything inherently unsafe about disabling strictures.

Its more a guard against mis-practice to me, and the things strictures
trips up are things you typically didn't intend to do.

--
Kent

KENTNL - https://metacpan.org/author/KENTNL

[p5pRT]

From madcityzen@gmail.com

On Dec 8, 2015, at 9​:54 PM, Kent Fredric <kentfredric@​gmail.com> wrote​:

On 9 December 2015 at 15​:03, Doug Bell <madcityzen@​gmail.com> wrote​:

It is a bit awkward. How about​:

   "The strict pragma disables certain unsafe Perl expressions in the current file or scope block\, turning them into errors\."

Though I wouldn't use the words "unsafe", because I don't think
there's anything inherently unsafe about disabling strictures.

Its more a guard against mis-practice to me, and the things strictures
trips up are things you typically didn't intend to do.

Yeah, I don't know a better way to describe that, and the abstract uses "unsafe". I could say "unexpected" perhaps, or maybe "difficult to debug". Or why not both?

  The strict pragma disables certain Perl expressions that could behave unexpectedly or are difficult to debug,
  turning them into errors. The effect of this pragma is limited to the current file or scope block.

The more I read the rest of this doc, the more I think it needs more detail, but that can be done in another ticket. Attached is the patch for the above paragraph.

Doug Bell
madcityzen@​gmail.com

[p5pRT]

From madcityzen@gmail.com

0001-add-note-about-scope-in-strict-docs.patch

From 6daab1a9cc8c7b5f0d8842c1d5f4a260ae76bca0 Mon Sep 17 00:00:00 2001
From: Doug Bell <madcityzen@gmail.com>
Date: Tue, 8 Dec 2015 09:35:15 -0600
Subject: [PATCH] add note about scope in strict docs

The strict pragma only effects the current file or block scope, but we
never mention that in the docs. Thanks KES for reporting this.
---
 lib/strict.pm | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lib/strict.pm b/lib/strict.pm
index 03ed21c..e9cf572 100644
--- a/lib/strict.pm
+++ b/lib/strict.pm
@@ -94,6 +94,10 @@ strict - Perl pragma to restrict unsafe constructs
 
 =head1 DESCRIPTION
 
+The C<strict> pragma disables certain Perl expressions that could behave
+unexpectedly or are difficult to debug, turning them into errors. The
+effect of this pragma is limited to the current file or scope block.
+
 If no import list is supplied, all possible restrictions are assumed.
 (This is the safest mode to operate in, but is sometimes too strict for
 casual programming.)  Currently, there are three possible things to be
-- 
2.4.9 (Apple Git-60)

[p5pRT]

From @rjbs

Thanks, applied as 55fe01c. (I amended the commit to bump the version in strict.)

--
rjbs

[p5pRT]

@rjbs - Status changed from 'open' to 'resolved'

[p5pRT]

From @rjbs

Thanks, applied as 55fe01c. (I amended the commit to bump the version in strict.)

--
rjbs