PATCH: document English.pm sawampersand and thread issues

	Message-Id: <m0zgZWx-000FOgC@feynman.localnet>

p4raw-id: //depot/perl@2362

diff --git a/lib/English.pm b/lib/English.pm
index bbb6bd7..7aa0d84 100644 (file)
--- a/lib/English.pm
+++ b/lib/English.pm
@@ -15,6 +15,14 @@ English - use nice English (or awk) names for ugly punctuation variables
 
 =head1 DESCRIPTION
 
+You should I<not> use this module in programs intended to be portable
+among Perl versions, programs that must perform regular expression
+matching operations efficiently, or libraries intended for use with
+such programs.  In a sense, this module is deprecated.  The reasons
+for this have to do with implementation details of the Perl
+interpreter which are too thorny to go into here.  Perhaps someday
+they will be fixed to make "C<use English>" more practical.
+
 This module provides aliases for the built-in variables whose
 names no one seems to like to read.  Variables with side-effects
 which get triggered just by accessing them (like $0) will still 

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 38fd168..7100af5 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -17,6 +17,15 @@ at the top of your program.  This will alias all the short names to the
 long names in the current package.  Some even have medium names,
 generally borrowed from B<awk>.
 
+Due to an unfortunate accident of Perl's implementation, "C<use English>"
+imposes a considerable performance penalty on all regular expression
+matches in a program, regardless of whether they occur in the scope of
+"C<use English>".  For that reason, saying "C<use English>" in
+libraries is strongly discouraged.  See the Devel::SawAmpersand module
+documentation from CPAN
+(http://www.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme)
+for more information.
+
 To go a step further, those variables that depend on the currently
 selected filehandle may instead (and preferably) be set by calling an
 object method on the FileHandle object.  (Summary lines below for this
@@ -127,6 +136,10 @@ The string matched by the last successful pattern match (not counting
 any matches hidden within a BLOCK or eval() enclosed by the current
 BLOCK).  (Mnemonic: like & in some editors.)  This variable is read-only.
 
+The use of this variable anywhere in a program imposes a considerable
+performance penalty on all regular expression matches.  See the
+Devel::SawAmpersand module from CPAN for more information.
+
 =item $PREMATCH
 
 =item $`
@@ -136,6 +149,10 @@ pattern match (not counting any matches hidden within a BLOCK or eval
 enclosed by the current BLOCK).  (Mnemonic: C<`> often precedes a quoted
 string.)  This variable is read-only.
 
+The use of this variable anywhere in a program imposes a considerable
+performance penalty on all regular expression matches.  See the
+Devel::SawAmpersand module from CPAN for more information.
+
 =item $POSTMATCH
 
 =item $'
@@ -151,6 +168,10 @@ string.)  Example:
 
 This variable is read-only.
 
+The use of this variable anywhere in a program imposes a considerable
+performance penalty on all regular expression matches.  See the
+Devel::SawAmpersand module from CPAN for more information.
+
 =item $LAST_PAREN_MATCH
 
 =item $+