minor tweaks to docs on qr//

p4raw-id: //depot/perl@1513

4 files changed, 20 insertions, 14 deletions

diff --git a/ext/re/re.pm b/ext/re/re.pm
index 5ec012dee6..8b49ca14f4 100644
--- a/ext/re/re.pm
+++ b/ext/re/re.pm
@@ -23,9 +23,9 @@ re - Perl pragma to alter regular expression behaviour
 	/foo${pat}bar/;		   # disallowed (with or without -T switch)
     }
 
-    use re 'debug';
-    /^(.*)$/s;			   # output debugging info 
-				   # during compile and run time
+    use re 'debug';		   # NOT lexically scoped (as others are)
+    /^(.*)$/s;			   # output debugging info during
+    				   #     compile and run time
 
 (We use $^X in these examples because it's tainted by default.)
 
@@ -44,12 +44,13 @@ potential security risk.  Note that this pragma is ignored when the regular
 expression is obtained from tainted data, i.e.  evaluation is always
 disallowed with tainted regular expresssions.  See L<perlre/(?{ code })>.
 
-For the purpose of this pragma, interpolation of preexisting regular 
-expressions is I<not> considered a variable interpolation, thus
+For the purpose of this pragma, interpolation of precompiled regular 
+expressions (i.e., the result of C<qr//>) is I<not> considered variable
+interpolation.  Thus:
 
     /foo${pat}bar/
 
-I<is> allowed if $pat is a preexisting regular expressions, even 
+I<is> allowed if $pat is a precompiled regular expression, even 
 if $pat contains C<(?{ ... })> assertions.
 
 When C<use re 'debug'> is in effect, perl emits debugging messages when 
@@ -59,8 +60,8 @@ B<-Dr> switch. It may be quite voluminous depending on the complexity
 of the match.
 See L<perldebug/"Debugging regular expressions"> for additional info.
 
-I<The directive C<use re 'debug'> is not lexically scoped.>  It has 
-both compile-time and run-time effects.
+The directive C<use re 'debug'> is I<not lexically scoped>, as the
+other directives are.  It has both compile-time and run-time effects.
 
 See L<perlmodlib/Pragmatic Modules>.
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index e271e7dd2e..d3fbae5b87 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -251,9 +251,9 @@ has been seen.
 =head2 New C<qr//> operator
 
 The C<qr//> operator, which is syntactically similar to the other quote-like
-operators, is used to create compiled regular expressions.  This compiled
+operators, is used to create precompiled regular expressions.  This compiled
 form can now be explicitly passed around in variables, and interpolated in
-other regular expressions.  See L<perlop> and L<perlre>.
+other regular expressions.  See L<perlop>.
 
 =head2 C<our> is now a reserved word
 
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 07ff51ac21..3de295faf7 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -913,7 +913,8 @@ A string which is (possibly) interpolated and then compiled as a
 regular expression. The result may be used as a pattern in a match
 
     $re = qr/$pattern/;
-    $string =~ /$re/;
+    $string =~ /foo${re}bar/;	# can be interpolated in other patterns
+    $string =~ $re;		# or used standalone
 
 Options are:
 
@@ -923,8 +924,9 @@ Options are:
     s	Treat string as single line.
     x	Use extended regular expressions.
 
-The benefit from this is that the pattern is compiled into an internal
-representation by the C<qr//> operator and not by the match operator.
+The benefit from this is that the pattern is precompiled into an internal
+representation, and does not need to be recompiled every time a match
+is attempted.  This makes it very efficient to do something like:
 
     foreach $pattern (@pattern_list) {
 	my $re = qr/$pattern/;
@@ -935,6 +937,9 @@ representation by the C<qr//> operator and not by the match operator.
 	}
     }
 
+See L<perlre> for additional information on valid syntax for STRING, and
+for a detailed look at the semantics of regular expressions.
+
 =item qx/STRING/
 
 =item `STRING`
diff --git a/pod/perlre.pod b/pod/perlre.pod
index c72a71c0ac..fc4d969466 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -7,7 +7,7 @@ perlre - Perl regular expressions
 This page describes the syntax of regular expressions in Perl.  For a
 description of how to I<use> regular expressions in matching
 operations, plus various examples of the same, see discussion
-of C<m//>, C<s///>, and C<??> in L<perlop/Regexp Quote-Like Operators>.
+of C<m//>, C<s///>, C<qr//> and C<??> in L<perlop/Regexp Quote-Like Operators>.
 
 The matching operations can have various modifiers.  The modifiers
 that relate to the interpretation of the regular expression inside