Better document setlocale, "use locale" interactions

The POSIX::setlocale() documentation failed to mention that "use locale"
is also usually necessary.

diff --git a/ext/POSIX/lib/POSIX.pod b/ext/POSIX/lib/POSIX.pod
index d5e93d0..ff201b8 100644 (file)
--- a/ext/POSIX/lib/POSIX.pod
+++ b/ext/POSIX/lib/POSIX.pod
@@ -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);
 

diff --git a/pod/perllocale.pod b/pod/perllocale.pod
index 17796ca..d15d4f0 100644 (file)
--- a/pod/perllocale.pod
+++ b/pod/perllocale.pod
@@ -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