This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Better document setlocale, "use locale" interactions
authorKarl Williamson <public@khwilliamson.com>
Wed, 10 Jul 2013 00:27:45 +0000 (18:27 -0600)
committerKarl Williamson <public@khwilliamson.com>
Wed, 10 Jul 2013 00:57:51 +0000 (18:57 -0600)
The POSIX::setlocale() documentation failed to mention that "use locale"
is also usually necessary.

ext/POSIX/lib/POSIX.pod
pod/perllocale.pod

index d5e93d0..ff201b8 100644 (file)
@@ -727,6 +727,9 @@ for creating hard links into files, see L<perlfunc/link>.
 
 Get numeric formatting information.  Returns a reference to a hash
 containing the current locale formatting values.
+Users of this function should also read L<perllocale>, where there is a
+discussion devoted to this function
+(L<perllocale/The localeconv function>).
 
 Here is how to query the database for the B<de> (Deutsch or German) locale.
 
@@ -1082,7 +1085,14 @@ see L<perlfunc/eval>.
 
 =item setlocale
 
-Modifies and queries program's locale.  The following examples assume
+Modifies and queries the program's underlying locale.  Users of this
+function should also read L<perllocale>, where there is a discussion
+devoted to this function (L<perllocale/The setlocale function>).
+Note that Perl itself is almost entirely unaffected by the locale
+except within the scope of S<C<"use locale">>.  (Exceptions are listed
+in L<perllocale/Not within the scope of any use locale variant>.)
+
+The following examples assume
 
        use POSIX qw(setlocale LC_ALL LC_CTYPE);
 
index 17796ca..d15d4f0 100644 (file)
@@ -319,7 +319,9 @@ C<POSIX::setlocale()> function:
         #                    LC_CTYPE -- explained below
         # (Showing the testing for success/failure of operations is
         # omitted in these examples to avoid distracting from the main
-        # point)
+        # point; also, any real work would almost certainly have to be
+        # done within the scope of "use locale".)
+
         use POSIX qw(locale_h);
 
         # query and save the old locale