From 818defb9eb745d8ae4b08e9f313bde316f68aced Mon Sep 17 00:00:00 2001
From: Scott Baker <scott@perturb.org>
Date: Wed, 2 Jun 2021 13:31:28 -0700
Subject: Simply the uc() and lc() documentation for novices

---
 pod/perlfunc.pod | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

(limited to 'pod')

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 08e1ce1d0d..baf17b3f4f 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3896,10 +3896,10 @@ X<lc> X<lowercase>
 
 =for Pod::Functions return lower-case version of a string
 
-Returns a lowercased version of EXPR.  This is the internal function
-implementing the C<\L> escape in double-quoted strings.
+Returns a lowercased version of EXPR.  If EXPR is omitted, uses
+L<C<$_>|perlvar/$_>.
 
-If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
+    my $str = lc("Perl is GREAT"); # "perl is great"
 
 What gets returned depends on several factors:
 
@@ -3946,6 +3946,12 @@ outside the ASCII range is the character itself.
 
 =back
 
+B<Note:> This is the internal function implementing the
+L<C<\L>|perlop/"Quote and Quote-like Operators"> escape in double-quoted
+strings.
+
+    my $str = "Perl is \LGREAT\E"; # "Perl is great"
+
 =item lcfirst EXPR
 X<lcfirst> X<lowercase>
 
@@ -9335,16 +9341,23 @@ X<uc> X<uppercase> X<toupper>
 
 =for Pod::Functions return upper-case version of a string
 
-Returns an uppercased version of EXPR.  This is the internal function
-implementing the C<\U> escape in double-quoted strings.
-It does not attempt to do titlecase mapping on initial letters.  See
-L<C<ucfirst>|/ucfirst EXPR> for that.
+Returns an uppercased version of EXPR.  If EXPR is omitted, uses
+L<C<$_>|perlvar/$_>.
 
-If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
+    my $str = uc("Perl is GREAT"); # "PERL IS GREAT"
 
 This function behaves the same way under various pragmas, such as in a locale,
 as L<C<lc>|/lc EXPR> does.
 
+If you want titlecase mapping on initial letters see
+L<C<ucfirst>|/ucfirst EXPR> instead.
+
+B<Note:> This is the internal function implementing the
+L<C<\U>|perlop/"Quote and Quote-like Operators"> escape in double-quoted
+strings.
+
+    my $str = "Perl is \Ugreat\E"; # "Perl is GREAT"
+
 =item ucfirst EXPR
 X<ucfirst> X<uppercase>
 
-- 
cgit v1.2.1