Re: [PATCH mg.c gv.c and others] ${^TAINT}

[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0761412..6d94459 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -560,11 +560,12 @@ previous time C<caller> was called.
 
 =item chdir EXPR
 
-Changes the working directory to EXPR, if possible.  If EXPR is omitted,
+Changes the working directory to EXPR, if possible. If EXPR is omitted,
 changes to the directory specified by C<$ENV{HOME}>, if set; if not,
-changes to the directory specified by C<$ENV{LOGDIR}>.  If neither is
-set, C<chdir> does nothing.  It returns true upon success, false
-otherwise.  See the example under C<die>.
+changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
+variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
+neither is set, C<chdir> does nothing. It returns true upon success,
+false otherwise. See the example under C<die>.
 
 =item chmod LIST
 
@@ -3755,19 +3756,23 @@ rename(2) manpage or equivalent system documentation for details.
 
 =item require
 
-Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied.
+Demands a version of Perl specified by VERSION, or demands some semantics
+specified by EXPR or by C<$_> if EXPR is not supplied.
 
-If a VERSION is specified as a literal of the form v5.6.1,
-demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
-at least as recent as that version, at run time.  (For compatibility
-with older versions of Perl, a numeric argument will also be interpreted
-as VERSION.)  Compare with L</use>, which can do a similar check at
-compile time.
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION).  A fatal error is produced at run time if
+VERSION is greater than the version of the current Perl interpreter.
+Compare with L</use>, which can do a similar check at compile time.
+
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax.  The equivalent numeric
+version should be used instead.
 
     require v5.6.1;    # run time version check
     require 5.6.1;     # ditto
-    require 5.005_03;  # float version allowed for compatibility
+    require 5.006_001; # ditto; preferred for backwards compatibility
 
 Otherwise, demands that a library file be included if it hasn't already
 been included.  The file is included via the do-FILE mechanism, which is
@@ -3877,6 +3882,9 @@ C<main>.)  Here is a typical code layout:
     # In the main program
     push @INC, new Foo(...);
 
+Note that these hooks are also permitted to set the %INC entry
+corresponding to the files they have loaded. See L<perlvar/%INC>.
+
 For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
@@ -4103,7 +4111,7 @@ calling select() in scalar context just returns $nfound.
 
 Any of the bit masks can also be undef.  The timeout, if specified, is
 in seconds, which may be fractional.  Note: not all implementations are
-capable of returning the$timeleft.  If not, they always return
+capable of returning the $timeleft.  If not, they always return
 $timeleft equal to the supplied $timeout.
 
 You can effect a sleep of 250 milliseconds this way:
@@ -5640,18 +5648,21 @@ package.  It is exactly equivalent to
 
 except that Module I<must> be a bareword.
 
-VERSION, which can be specified as a literal of the form v5.6.1, demands
-that the current version of Perl (C<$^V> or $PERL_VERSION) be at least
-as recent as that version.  (For compatibility with older versions of Perl,
-a numeric literal will also be interpreted as VERSION.)  If the version
-of the running Perl interpreter is less than VERSION, then an error
-message is printed and Perl exits immediately without attempting to
-parse the rest of the file.  Compare with L</require>, which can do a
-similar check at run time.
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION.  A fatal error is produced if VERSION is
+greater than the version of the current Perl interpreter; Perl will not
+attempt to parse the rest of the file.  Compare with L</require>, which can
+do a similar check at run time.
+
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax.  The equivalent numeric
+version should be used instead.
 
     use v5.6.1;                # compile time version check
     use 5.6.1;         # ditto
-    use 5.005_03;      # float version allowed for compatibility
+    use 5.006_001;     # ditto; preferred for backwards compatibility
 
 This is often useful if you need to check the current Perl version before
 C<use>ing library modules that have changed in incompatible ways from