X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=833e89182579e65ecc26db20897d3843f6617e29;hb=9b5c3821be1f2a9a84772171c8bbadbf9cfc4a53;hp=5fde4b81af9f8eba1d2b94c00c2a49ac47fe00f9;hpb=b17c04f34c21c46addcb48d31ee352efe59be622;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 5fde4b8..833e891 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -614,7 +614,7 @@ false otherwise. See the example under C<die>.
 
 Changes the permissions of a list of files.  The first element of the
 list must be the numerical mode, which should probably be an octal
-number, and which definitely should I<not> a string of octal digits:
+number, and which definitely should I<not> be a string of octal digits:
 C<0644> is okay, C<'0644'> is not.  Returns the number of files
 successfully changed.  See also L</oct>, if all you have is a string.
 
@@ -2519,36 +2519,44 @@ for details, including issues with tied arrays and hashes.
 
 =item localtime EXPR
 
+=item localtime
+
 Converts a time as returned by the time function to a 9-element list
 with the time analyzed for the local time zone.  Typically used as
 follows:
 
     #  0    1    2     3     4    5     6     7     8
     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
-						localtime(time);
+                                                localtime(time);
 
 All list elements are numeric, and come straight out of the C `struct
-tm'.  $sec, $min, and $hour are the seconds, minutes, and hours of the
-specified time.  $mday is the day of the month, and $mon is the month
-itself, in the range C<0..11> with 0 indicating January and 11
-indicating December.  $year is the number of years since 1900.  That
-is, $year is C<123> in year 2023.  $wday is the day of the week, with
-0 indicating Sunday and 3 indicating Wednesday.  $yday is the day of
-the year, in the range C<0..364> (or C<0..365> in leap years.)  $isdst
-is true if the specified time occurs during daylight savings time,
-false otherwise.
+tm'.  C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours
+of the specified time.
 
-Note that the $year element is I<not> simply the last two digits of
-the year.  If you assume it is, then you create non-Y2K-compliant
-programs--and you wouldn't want to do that, would you?
+C<$mday> is the day of the month, and C<$mon> is the month itself, in
+the range C<0..11> with 0 indicating January and 11 indicating December.
+This makes it easy to get a month name from a list:
 
-The proper way to get a complete 4-digit year is simply:
+    my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
+    print "$abbr[$mon] $mday";
+    # $mon=9, $mday=18 gives "Oct 18"
 
-	$year += 1900;
+C<$year> is the number of years since 1900, not just the last two digits
+of the year.  That is, C<$year> is C<123> in year 2023.  The proper way
+to get a complete 4-digit year is simply:
 
-And to get the last two digits of the year (e.g., '01' in 2001) do:
+    $year += 1900;
 
-	$year = sprintf("%02d", $year % 100);
+To get the last two digits of the year (e.g., '01' in 2001) do:
+
+    $year = sprintf("%02d", $year % 100);
+
+C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating
+Wednesday.  C<$yday> is the day of the year, in the range C<0..364>
+(or C<0..365> in leap years.)
+
+C<$isdst> is true if the specified time occurs during Daylight Saving
+Time, false otherwise.
 
 If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
 
@@ -5841,7 +5849,7 @@ will return byte offsets, not character offsets (because implementing
 that would render sysseek() very slow).
 
 sysseek() bypasses normal buffered IO, so mixing this with reads (other
-than C<sysread>, for example &gt;&lt or read()) C<print>, C<write>,
+than C<sysread>, for example C<< <> >> or read()) C<print>, C<write>,
 C<seek>, C<tell>, or C<eof> may cause confusion.
 
 For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>,
@@ -6731,7 +6739,7 @@ and for other examples.
 =item wantarray
 
 Returns true if the context of the currently executing subroutine or
-eval() block is looking for a list value.  Returns false if the context is
+C<eval> is looking for a list value.  Returns false if the context is
 looking for a scalar.  Returns the undefined value if the context is
 looking for no value (void context).
 
@@ -6739,6 +6747,10 @@ looking for no value (void context).
     my @a = complex_calculation();
     return wantarray ? @a : "@a";
 
+C<wantarray()>'s result is unspecified in the top level of a file,
+in a C<BEGIN>, C<CHECK>, C<INIT> or C<END> block, or in a C<DESTROY>
+method.
+
 This function should have been named wantlist() instead.
 
 =item warn LIST