Make the point a bit clearer after suggestion from Merijin

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

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index ac4ebf8..98bd657 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -663,8 +663,11 @@ Also see L<Error Indicators>.
 
 =item ${^ENCODING}
 
-The encoding used to interpret native eight-bit encodings to Unicode,
-see L<encode>.  An opaque C<Encode::XS> object.
+The I<object reference> to the Encode object that is used to convert
+the source code to Unicode.  Thanks to this variable your perl script
+does not have to be written in UTF-8.  Default is I<undef>.  The direct
+manipulation of this variable is highly discouraged.  See L<encoding>
+for more details.
 
 =item $OS_ERROR
 
@@ -673,9 +676,25 @@ see L<encode>.  An opaque C<Encode::XS> object.
 =item $!
 
 If used numerically, yields the current value of the C C<errno>
-variable, with all the usual caveats.  (This means that you shouldn't
-depend on the value of C<$!> to be anything in particular unless
-you've gotten a specific error return indicating a system error.)
+variable, or in other words, if a system or library call fails, it
+sets this variable.  This means that the value of C<$!> is meaningful
+only I<immediately> after a B<failure>:
+
+    if (open(FH, $filename)) {
+       # Here $! is meaningless.
+       ...
+    } else {
+       # ONLY here is $! meaningful.
+       ...
+       # Already here $! might be meaningless.
+    }
+    # Since here we might have either success or failure,
+    # here $! is meaningless.
+
+In the above I<meaningless> stands for anything: zero, non-zero,
+C<undef>.  A successful system or library call does B<not> set
+the variable to zero.
+
 If used an a string, yields the corresponding system error string.
 You can assign a number to C<$!> to set I<errno> if, for instance,
 you want C<"$!"> to return the string for error I<n>, or you want
@@ -684,6 +703,18 @@ went bang?)
 
 Also see L<Error Indicators>.
 
+=item %!
+
+Each element of C<%!> has a true value only if C<$!> is set to that
+value.  For example, C<$!{ENOENT}> is true if and only if the current
+value of C<$!> is C<ENOENT>; that is, if the most recent error was
+"No such file or directory" (or its moral equivalent: not all operating
+systems give that exact error, and certainly not all languages).
+To check if a particular key is meaningful on your system, use
+C<exists $!{the_key}>; for a list of legal keys, use C<keys %!>.
+See L<Errno> for more information, and also see above for the
+validity of C<$!>.
+
 =item $EXTENDED_OS_ERROR
 
 =item $^E
@@ -1077,6 +1108,11 @@ Control.)  Example:
 
     warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;
 
+To convert C<$^V> into its string representation use sprintf()'s
+C<"%vd"> conversion:
+
+    printf "version is v%vd\n", $^V;  # Perl's version
+
 See the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.
 
@@ -1395,7 +1431,7 @@ expression matches in a program, regardless of whether they occur
 in the scope of C<use English>.  For that reason, saying C<use
 English> in libraries is strongly discouraged.  See the
 Devel::SawAmpersand module documentation from CPAN
-(http://www.cpan.org/modules/by-module/Devel/)
+( http://www.cpan.org/modules/by-module/Devel/ )
 for more information.
 
 Having to even think about the C<$^S> variable in your exception