From 4f33871e476d22c53497f8752b4846aecb7d661a Mon Sep 17 00:00:00 2001
From: Karl Williamson <khw@cpan.org>
Date: Sat, 7 Nov 2020 12:18:26 -0700
Subject: [PATCH] perlop: Clarify parts of tr///

---
 pod/perlop.pod | 45 ++++++++++++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 51303be3a2a2..7778b8222ca2 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -2595,25 +2595,36 @@ C<tr/ACEGIBDFHJ/0246813579/>.
 
 If the I<SEARCHLIST> is delimited by bracketing quotes, the
 I<REPLACEMENTLIST> must have its own pair of quotes, which may or may
-not be bracketing quotes; for example, C<tr[aeiouy][yuoiea]> or
-C<tr(+\-*/)/ABCD/>.
-
-Characters may be literals, or (if the delimiters aren't single quotes)
-any of the escape sequences accepted in double-quoted strings.  But
-there is never any variable interpolation, so C<"$"> and C<"@"> are
-always treated as literals.  A hyphen at the beginning or end, or
-preceded by a backslash is also always considered a literal.  Escape
-sequence details are in L<the table near the beginning of this
+not be bracketing quotes; for example, C<tr(aeiouy)(yuoiea)> or
+C<tr[+\-*/]"ABCD">.  This final example shows a way to visually clarify
+what is going on for people who are more familiar with regular
+expression patterns than with C<tr>, and who may think forward slash
+delimiters imply that C<tr> is more like a regular expression pattern
+than it actually is.  (Another option might be to use C<tr[...][...]>.)
+
+C<tr> isn't fully like bracketed character classes, just
+(significantly) more like them than it is to full patterns.  For
+example, characters appearing more than once in either list behave
+differently here than in patterns, and C<tr> lists do not allow
+backslashed character classes such as C<\d> or C<\pL>, nor variable
+interpolation, so C<"$"> and C<"@"> are always treated as literals.
+
+What is allowed are literals, or (if the delimiters aren't single
+quotes) any of the escape sequences accepted in double-quoted strings.
+Escape sequence details are in L<the table near the beginning of this
 section|/Quote and Quote-like Operators>.
 
-Note that C<tr> does B<not> do regular expression character classes such as
-C<\d> or C<\pL>.  The C<tr> operator is not equivalent to the C<L<tr(1)>>
-utility.  C<tr[a-z][A-Z]> will uppercase the 26 letters "a" through "z",
-but for case changing not confined to ASCII, use
-L<C<lc>|perlfunc/lc>, L<C<uc>|perlfunc/uc>,
-L<C<lcfirst>|perlfunc/lcfirst>, L<C<ucfirst>|perlfunc/ucfirst>
-(all documented in L<perlfunc>), or the
-L<substitution operator C<sE<sol>I<PATTERN>E<sol>I<REPLACEMENT>E<sol>>|/sE<sol>PATTERNE<sol>REPLACEMENTE<sol>msixpodualngcer>
+A hyphen at the beginning or end, or preceded by a backslash is also
+always considered a literal.  Precede a delimiter character with a
+backslash to allow it.
+
+The C<tr> operator is not equivalent to the C<L<tr(1)>> utility.
+C<tr[a-z][A-Z]> will uppercase the 26 letters "a" through "z", but for
+case changing not confined to ASCII, use L<C<lc>|perlfunc/lc>,
+L<C<uc>|perlfunc/uc>, L<C<lcfirst>|perlfunc/lcfirst>,
+L<C<ucfirst>|perlfunc/ucfirst> (all documented in L<perlfunc>), or the
+L<substitution operator
+C<sE<sol>I<PATTERN>E<sol>I<REPLACEMENT>E<sol>>|/sE<sol>PATTERNE<sol>REPLACEMENTE<sol>msixpodualngcer>
 (with C<\U>, C<\u>, C<\L>, and C<\l> string-interpolation escapes in the
 I<REPLACEMENT> portion).