additional documentation for qr//

	Message-Id: <199811260751.CAA24560@monk.mps.ohio-state.edu>
	Subject: [PATCH 5.005_*] Documentation (fwd)

p4raw-id: //depot/perl@2366

3 files changed, 42 insertions, 17 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 58d372a7b2..370353bb2a 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2804,7 +2804,7 @@ but is more efficient.  Returns the new number of elements in the array.
 
 =item qw/STRING/
 
-Generalized quotes.  See L<perlop>.
+Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta EXPR
 
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 8e50ec36ea..857b951486 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -910,12 +910,47 @@ A double-quoted, interpolated string.
 
 =item qr/STRING/imosx
 
-A string which is (possibly) interpolated and then compiled as a
-regular expression. The result may be used as a pattern in a match
+Quote-as-a-regular-expression operator.  I<STRING> is interpolated the
+same way as I<PATTERN> in C<m/PATTERN/>.  Returns a Perl value which
+may be used instead of the corresponding C</STRING/imosx> expression.
+
+For example,
+
+    $rex = qr/my.STRING/is;
+    s/$rex/foo/;
+
+is equivalent to
+
+    s/my.STRING/foo/is;
+
+The result may be used as a subpattern in a match:
 
     $re = qr/$pattern/;
     $string =~ /foo${re}bar/;	# can be interpolated in other patterns
     $string =~ $re;		# or used standalone
+    $string =~ /$re/;		# or this way
+
+Since Perl may compile the pattern at the moment of execution of qr()
+operator, using qr() may have speed advantages in I<some> situations,
+notably if the result of qr() is used standalone:
+
+    sub match {
+	my $patterns = shift;
+	my @compiled = map qr/$_/i, @$patterns;
+	grep {
+	    my $success = 0;
+	    foreach my $pat @compiled {
+		$success = 1, last if /$pat/;
+	    }
+	    $success;
+	} @_;
+    }
+
+Precompilation of the pattern into an internal representation at the
+moment of qr() avoids a need to recompile the pattern every time a
+match C</$pat/> is attempted.  (Note that Perl has many other
+internal optimizations, but none would be triggered in the above
+example if we did not use qr() operator.)
 
 Options are:
 
@@ -925,19 +960,6 @@ Options are:
     s	Treat string as single line.
     x	Use extended regular expressions.
 
-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/;
-	foreach $line (@lines) {
-	    if($line =~ /$re/) {
-		do_something($line);
-	    }
-	}
-    }
-
 See L<perlre> for additional information on valid syntax for STRING, and
 for a detailed look at the semantics of regular expressions.
 
diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index d20d62d06a..7fa8290f1d 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -171,7 +171,8 @@ here and in commands:
 					(the quotes are optional)
 		    L</"sec">		ditto
 		same as above but only 'text' is used for output.
-		(Text can not contain the characters '|' or '>')
+		(Text can not contain the characters '/' and '|', 
+		and should contain matched '<' or '>')
 		    L<text|name>
 		    L<text|name/ident>
 		    L<text|name/"sec">
@@ -184,6 +185,8 @@ here and in commands:
     E<escape>   A named character (very similar to HTML escapes)
 		    E<lt>		A literal <
 		    E<gt>		A literal >
+		    E<sol>		A literal /
+		    E<verbar>		A literal |
 		    (these are optional except in other interior
 		     sequences and when preceded by a capital letter)
 		    E<n>		Character number n (probably in ASCII)