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 a note that quotemeta isn't affected by locale.

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,25 +1350,36 @@ 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:
+To cause a metacharacter to match its literal self, you quote (or
+escape) it by preceding 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 sequences, like C<\w>, which have
+special meaning for Perl.)
+
+But with a non-alphanumeric, it will match literally.  Hence simply
+quoting all non-"word" characters can be used to disable the special
+meanings of regular expression metacharacters in a string that you want
+to use for a pattern. 
 
     $pattern =~ s/(\W)/\\$1/g;
 
-(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>>
+(If C<use locale> is in effect, then this depends on the current locale.)
+
+This template used to be a common paradigm, but these days it is more
+usual to use the C<L<quotemeta()|perlfunc/quotemeta>>
 function or the C<\Q> metaquoting escape sequence to disable all
 metacharacters' special meanings like this:
 
     /$unquoted\Q$quoted\E$unquoted/
 
+(These are not locale-dependent, so won't necessarily give the same
+results as when under S<C<use locale>>.)
+
 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

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))