pod and comments: Note escape vs quote

Fixes #15221

The documentation and comments were misleading about conflating quoting
a metacharacter and escaping it.  Since \Q stands for quote, we have to
continue to use that terminology.  This commit clarifies that the two
terms are often equivalent.

This also adds detail about quotemeta and \Q.

Author: khwilliamson

pod/perldiag.pod

@@ -2602,8 +2602,8 @@ and perl's F</dev/null> emulation was unable to create an empty temporary file.
 (W regexp)(F) A character class range must start and end at a literal
 character, not another character class like C<\d> or C<[:alpha:]>.  The "-"
 in your false range is interpreted as a literal "-".  In a C<(?[...])>
-construct, this is an error, rather than a warning.  Consider quoting
-the "-", "\-".  The S<<-- HERE> shows whereabouts in the regular expression
+construct, this is an error, rather than a warning.  Consider escaping
+the "-" as "\-".  The S<<-- HERE> shows whereabouts in the regular expression
 the problem was discovered.  See L<perlre>.
 
 =item Fatal VMS error (status=%d) at %s, line %d
@@ -5453,7 +5453,7 @@ S<<-- HERE> in m/%s/
 (F) Within regular expression character classes ([]) the syntax beginning
 with "[." and ending with ".]" is reserved for future extensions.  If you
 need to represent those character sequences inside a regular expression
-character class, just quote the square brackets with the backslash: "\[."
+character class, just escape the square brackets with the backslash: "\[."
 and ".\]".  The S<<-- HERE> shows whereabouts in the regular expression the
 problem was discovered.  See L<perlre>.
 
@@ -5463,7 +5463,7 @@ S<<-- HERE> in m/%s/
 (F) Within regular expression character classes ([]) the syntax beginning
 with "[=" and ending with "=]" is reserved for future extensions.  If you
 need to represent those character sequences inside a regular expression
-character class, just quote the square brackets with the backslash: "\[="
+character class, just escape the square brackets with the backslash: "\[="
 and "=\]".  The S<<-- HERE> shows whereabouts in the regular expression the
 problem was discovered.  See L<perlre>.
 

pod/perlfunc.pod

@@ -6536,6 +6536,11 @@ the C<\Q> escape in double-quoted strings.
 
 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
 
+The motivation behind this is to make all characters in EXPR match their
+literal selves.  Otherwise any metacharacters in it could trigger
+their "magic" matching behaviors.  The characters this function has been
+applied to are said to be "quoted" or "escaped".
+
 quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into
 regular expressions, because by default an interpolated variable will be
 considered a mini-regular expression.  For example:

pod/perlre.pod

@@ -1350,32 +1350,61 @@ X</p> X<p modifier>
 
 =head2 Quoting metacharacters
 
-Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
-C<\w>, C<\n>.  Unlike some other regular expression languages, there
-are no backslashed symbols that aren't alphanumeric.  So anything
-that looks like C<\\>, C<\(>, C<\)>, C<\[>, C<\]>, C<\{>, or C<\}> is
-always
-interpreted as a literal character, not a metacharacter.  This was
-once used in a common idiom to disable or quote the special meanings
-of regular expression metacharacters in a string that you want to
-use for a pattern. Simply quote all non-"word" characters:
+(Also known as "escaping".)
 
-    $pattern =~ s/(\W)/\\$1/g;
+To cause a metacharacter to match its literal self, you precede it with
+a backslash.  Unlike some other regular expression languages, any
+sequence consisting of a backslash followed by a non-alphanumeric
+matches that non-alphanumeric, literally.  So things like C<\\>, C<\(>,
+C<\)>, C<\[>, C<\]>, C<\{>, or C<\}> are always interpreted as the
+literal character that follows the backslash.
+
+(That's not true when an alphanumeric character is preceded by a
+backslash.  There are a few such "escape sequences", like C<\w>, which have
+special matching behaviors in Perl.  All such are currently limited to
+ASCII-range alphanumerics.)
+
+The best method to escape metacharacters is to use the
+C<L<quotemeta()|perlfunc/quotemeta>> function, or the equivalent, but the
+more flexible, and often more convenient, C<\Q> metaquoting escape
+sequence
+
+    quotemeta $pattern;
+
+This changes C<$pattern> so that the metacharacters are quoted.  You can
+then do
+
+    $string =~ s/$pattern/foo/;
 
-(If C<use locale> is set, then this depends on the current locale.)
-Today it is more common to use the C<L<quotemeta()|perlfunc/quotemeta>>
-function or the C<\Q> metaquoting escape sequence to disable all
-metacharacters' special meanings like this:
+and be assured that any metacharacters in C<$pattern> will match their
+literal selves.  If you instead use C<\Q>, like:
 
-    /$unquoted\Q$quoted\E$unquoted/
+    $string =~ s/\Qpattern/foo/;
+
+you don't have to have a separate C<$pattern> variable.  Further, there
+is an additional escape sequence, C<\E> that can be combined with C<\Q>
+to allow you to escape whatever portions of the pattern you desire:
+
+    $string =~ s/$unquoted\Q$quoted\E$unquoted/foo/;
 
 Beware that if you put literal backslashes (those not inside
 interpolated variables) between C<\Q> and C<\E>, double-quotish
 backslash interpolation may lead to confusing results.  If you
 I<need> to use literal backslashes within C<\Q...\E>,
 consult L<perlop/"Gory details of parsing quoted constructs">.
 
-C<quotemeta()> and C<\Q> are fully described in L<perlfunc/quotemeta>.
+In older code, you may see something like this:
+
+    $pattern =~ s/(\W)/\\$1/g;
+    $string =~ s/$pattern/foo/;
+
+This simply adds backslashes before all non-"word" characters to disable
+any special meanings they might have.  (If S<C<use locale>> is in
+effect, the current locale can affect the results.)  This paradigm is
+inadequate for Unicode.
+
+C<quotemeta()> and C<\Q> are more fully described in
+L<perlfunc/quotemeta>.
 
 =head2 Extended Patterns
 

pod/perlrebackslash.pod

@@ -90,8 +90,8 @@ as C<Not in [].>
  \o{}              Octal escape sequence.
  \p{}, \pP         Match any character with the given Unicode property.
  \P{}, \PP         Match any character without the given property.
- \Q                Quote (disable) pattern metacharacters till \E.  Not
-                   in [].
+ \Q                Quote (disable) pattern metacharacters till \E.
+                   (Also called "escape".)  Not in [].
  \r                Return character.
  \R                Generic new line.  Not in [].
  \s                Match any whitespace character.
@@ -350,11 +350,11 @@ them, until either the end of the pattern or the next occurrence of
 C<\E>, whichever comes first. They provide functionality similar to what
 the functions C<lc> and C<uc> provide.
 
-C<\Q> is used to quote (disable) pattern metacharacters, up to the next
-C<\E> or the end of the pattern. C<\Q> adds a backslash to any character
-that could have special meaning to Perl.  In the ASCII range, it quotes
-every character that isn't a letter, digit, or underscore.  See
-L<perlfunc/quotemeta> for details on what gets quoted for non-ASCII
+C<\Q> is used to quote or escape (disable) pattern metacharacters, up to
+the next C<\E> or the end of the pattern. C<\Q> adds a backslash to any
+character that could have special meaning to Perl.  In the ASCII range,
+it quotes every character that isn't a letter, digit, or underscore.
+See L<perlfunc/quotemeta> for details on what gets quoted for non-ASCII
 code points.  Using this ensures that any character between C<\Q> and
 C<\E> will be matched literally, not interpreted as a metacharacter by
 the regex engine.

pod/perlreref.pod

@@ -318,7 +318,7 @@ Captured groups are numbered according to their I<opening> paren.
    fc          Foldcase a string
 
    pos         Return or set current match position
-   quotemeta   Quote metacharacters
+   quotemeta   Quote metacharacters (escape their normal meaning)
    reset       Reset m?pattern? status
    study       Analyze string for optimizing matching
 

pod/perlretut.pod

@@ -187,7 +187,7 @@ C<"["> respectively; other gotchas apply.
 The significance of each of these will be explained
 in the rest of the tutorial, but for now, it is important only to know
 that a metacharacter can be matched as-is by putting a backslash before
-it:
+it.  This is called "escaping" or "quoting" it.  Some examples:
 
     "2+2=4" =~ /2+2/;    # doesn't match, + is a metacharacter
     "2+2=4" =~ /2\+2/;   # matches, \+ is treated like an ordinary +

pp.c

@@ -5082,7 +5082,7 @@ PP(pp_quotemeta)
                 else if (UTF8_IS_NEXT_CHAR_DOWNGRADEABLE(s, s + len)) {
                     if (
 #ifdef USE_LOCALE_CTYPE
-                    /* In locale, we quote all non-ASCII Latin1 chars.
+                    /* In locale, we escape all non-ASCII Latin1 chars.
                      * Otherwise use the quoting rules */
 
                     IN_LC_RUNTIME(LC_CTYPE)
@@ -5116,7 +5116,7 @@ PP(pp_quotemeta)
             }
         }
         else {
-            /* For non UNI_8_BIT (and hence in locale) just quote all \W
+            /* For non UNI_8_BIT (and hence in locale) just escape all \W
              * including everything above ASCII */
             while (len--) {
                 if (!isWORDCHAR_A(*s))