Integrate:

[ 24317]
Fix typo, noticed by Randal Schwartz

[ 24345]
Remove confusing punctuation
(spotted by David Rigaudiere)

[ 24354]
Subject: [PATCH] Small patch to perlport.pod
From: Sébastien Aperghis-Tramoni <maddingue@free.fr>
Date: Thu, 28 Apr 2005 02:24:04 +0200
Message-Id: <D38E89F3-B77B-11D9-B91D-000502F3279F@free.fr>

[ 24368]
Clarify the definition of the 'w' pack format, as suggested by
Alexey Toptygin.

[ 24381]
document the internals of exception handling

[ 24383]
Subject: [PATCH] perlvar.pod verbatim paragraph first line does not start with a space
From: Offer Kaye <offer.kaye@gmail.com>
Date: Wed, 4 May 2005 15:10:37 +0300
Message-Id: <56942505050405101bfe678d@mail.gmail.com>

[ 24429]
Update the comment describing arenas.

[ 24430]
Fix typo (bug #35368)

[ 24437]
Subject: [PATCH] perlop.pod nit
From: Steve Peters <steve@fisharerojo.org>
Date: Tue, 10 May 2005 09:41:01 -0500
Message-Id: <20050510144101.GA21362@mccoy.peters.homeunix.org>

[ 24449]
Subject: [perl #33765] [PATCH] perlop: mention why 'print !!0' doesn't 
From: Steve Peters via RT <perlbug-followup@perl.org>
Date: 11 May 2005 16:58:22 -0000
Message-Id: <rt-3.0.11-33765-112475.14.5633321030279@perl.org>

Subject: [perl #33766] [PATCH] perldoc -f split lacks basic null example 
From: Steve Peters via RT <perlbug-followup@perl.org>
Date: 11 May 2005 17:13:29 -0000
Message-Id: <rt-3.0.11-33766-112476.1.84217630998887@perl.org>

[ 24450]
Rework documentation of split(//,...)

[ 24493]
Clarify definition of octal literals
(thanks to Olivier Blin)

[ 24496]
Subject: [PATCH] Eliminate radically out of date CHANGES from perlport
From: Michael G Schwern <schwern@pobox.com>
Date: Mon, 16 May 2005 15:17:05 -0700
Message-ID: <20050516221705.GA212@windhund.schwern.org>

Subject: [PATCH] Eliminate function signatures from perlport
From: Michael G Schwern <schwern@pobox.com>
Date: Mon, 16 May 2005 15:24:18 -0700
Message-ID: <20050516222418.GA422@windhund.schwern.org>

[ 24516]
Fix a typo

[ 24563]
Documentation nit on @-, found by Guillaume Rousse
(plus POD markup simplification, for readability with pod2text)

[ 24564]
Correct the description of pte_arenaroot

[ 24593]
Subject: [PATCH] Re: [perl #35420] localtime corruption
From: Michael G Schwern <schwern@pobox.com>
Date: Thu, 26 May 2005 13:39:38 -0700
Message-ID: <20050526203938.GG11558@windhund.schwern.org>
p4raw-link: @24593 on //depot/perl: 62aa563719d028e176ee9e4eb16701b5a2193e4c
p4raw-link: @24564 on //depot/perl: 590a98e767a2006515bff539a897c2e8f9b73db3
p4raw-link: @24563 on //depot/perl: 5060ef7b6a11b124f0b71afcf7384e13b79a28a6
p4raw-link: @24516 on //depot/perl: 90ce55a189f2bdb2d042b4e4190bf41cd6331190
p4raw-link: @24496 on //depot/perl: 47cd99a476cec03355d01f7362c0175ff9e1c16e
p4raw-link: @24493 on //depot/perl: 802a55ac9fc25e44a7cec31c7f4ed63e323d6f4a
p4raw-link: @24450 on //depot/perl: de5763b09f57cd1553a966128894c602f4a35b8e
p4raw-link: @24449 on //depot/perl: 52ea55c9ee04ef3b03dd13373eda27b47fea1087
p4raw-link: @24437 on //depot/perl: d2a1eec3cd6825dde834f852934b2f286fab1f9f
p4raw-link: @24430 on //depot/perl: a0981a788197c6d427ceaf558d0dc8713c7737b3
p4raw-link: @24429 on //depot/perl: 4977e971c94c012c59e3e99429a0cef3af185c4b
p4raw-link: @24383 on //depot/perl: 304dea91bf747b5b240c3ec3a6a4dfebeab12289
p4raw-link: @24381 on //depot/perl: dfc98234fc15f52c0776048cec291c9d1b2dec2b
p4raw-link: @24368 on //depot/perl: 24436e9a6cbac7c6d5f2e80821bf1e4ed98a4663
p4raw-link: @24354 on //depot/perl: 7ee27b7c84480663d7064ae42f2ae865d6e36170
p4raw-link: @24345 on //depot/perl: 4cb1c523c98f570fe603f3ae31d419bb956906d9
p4raw-link: @24317 on //depot/perl: f464ba52b9670216e4d7f1e806fdbca7fb072215

p4raw-id: //depot/maint-5.8/perl@24597
p4raw-integrated: from //depot/perl@24589 'copy in' pod/perlreftut.pod
	(@21031..) pod/perlsyn.pod (@21435..) 'edit in'
	pod/perlport.pod (@24501..) 'merge in' pod/perldata.pod
	(@24033..) pod/perlhack.pod (@24088..)
p4raw-integrated: from //depot/perl@24564 'edit in' intrpvar.h
	(@24547..)
p4raw-integrated: from //depot/perl@24516 'merge in' hv.h (@24497..)
p4raw-integrated: from //depot/perl@24437 'merge in' pod/perlop.pod
	(@24090..)
p4raw-integrated: from //depot/perl@24429 'merge in' sv.c (@24419..)
p4raw-integrated: from //depot/perl@24383 'edit in' pod/perlvar.pod
	(@24345..)
p4raw-integrated: from //depot/perl@24368 'edit in' pod/perlfunc.pod
	(@24317..)

11 files changed, 290 insertions, 209 deletions

diff --git a/hv.h b/hv.h
index 963317ec5b..c39fbd5dbe 100644
--- a/hv.h
+++ b/hv.h
@@ -64,7 +64,7 @@ struct xpvhv {
  * If USE_HASH_SEED_EXPLICIT is defined, hash randomisation is done
  * only if the environment variable PERL_HASH_SEED is set.
  * For maximal control, one can define PERL_HASH_SEED.
- * (see also erl.c:perl_parse()).
+ * (see also perl.c:perl_parse()).
  */
 #ifndef PERL_HASH_SEED
 #   if defined(USE_HASH_SEED) || defined(USE_HASH_SEED_EXPLICIT)
diff --git a/intrpvar.h b/intrpvar.h
index 7a453ba638..d2650d02bb 100644
--- a/intrpvar.h
+++ b/intrpvar.h
@@ -578,5 +578,5 @@ PERLVARI(Isuidscript, int, -1)	/* fd for suid script */
 
 #if defined(USE_ITHREADS)
 PERLVAR(Ipte_root,	struct ptr_tbl_ent *)	/* free ptr_tbl_ent list */
-PERLVAR(Ipte_arenaroot,	XPV*)		/* list of allocated he areas */
+PERLVAR(Ipte_arenaroot,	XPV*)		/* list of allocated pte areas */
 #endif
diff --git a/pod/perldata.pod b/pod/perldata.pod
index 783da9fce8..61c379abd6 100644
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -278,7 +278,7 @@ integer formats:
     4_294_967_296       # underscore for legibility
     0xff                # hex
     0xdead_beef         # more hex   
-    0377                # octal
+    0377                # octal (only numbers, begins with 0)
     0b011011            # binary
 
 You are allowed to use underscores (underbars) in numeric literals
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d96a23d232..06205d13fd 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2182,6 +2182,8 @@ This scalar value is B<not> locale dependent (see L<perllocale>), but is
 instead a Perl builtin.  To get somewhat similar but locale dependent date
 strings, see the example in L</localtime>.
 
+See L<perlport/gmtime> for portability concerns.
+
 =item goto LABEL
 
 =item goto EXPR
@@ -2574,6 +2576,8 @@ try for example:
 Note that the C<%a> and C<%b>, the short forms of the day of the week
 and the month of the year, may not necessarily be three characters wide.
 
+See L<perlport/localtime> for portability concerns.
+
 =item lock THING
 
 This function places an advisory lock on a shared variable, or referenced
@@ -3353,10 +3357,10 @@ of values, as follows:
     U	A Unicode character number.  Encodes to UTF-8 internally
 	(or UTF-EBCDIC in EBCDIC platforms).
 
-    w	A BER compressed integer.  Its bytes represent an unsigned
-	integer in base 128, most significant digit first, with as
-        few digits as possible.  Bit eight (the high bit) is set
-        on each byte except the last.
+    w	A BER compressed integer (not an ASN.1 BER, see perlpacktut for
+	details).  Its bytes represent an unsigned integer in base 128,
+	most significant digit first, with as few digits as possible.  Bit
+	eight (the high bit) is set on each byte except the last.
 
     x	A null byte.
     X	Back up a byte.
@@ -4182,7 +4186,7 @@ a bareword argument, there is a little extra functionality going on
 behind the scenes.  Before C<require> looks for a "F<.pm>" extension,
 it will first look for a filename with a "F<.pmc>" extension.  A file
 with this extension is assumed to be Perl bytecode generated by
-L<B::Bytecode|B::Bytecode>.  If this file is found, and it's modification
+L<B::Bytecode|B::Bytecode>.  If this file is found, and its modification
 time is newer than a coinciding "F<.pm>" non-compiled file, it will be
 loaded in place of that non-compiled file ending in a "F<.pm>" extension.
 
@@ -4957,14 +4961,19 @@ characters at each point it matches that way.  For example:
 
 produces the output 'h:i:t:h:e:r:e'.
 
-Using the empty pattern C<//> specifically matches the null string, and is
-not be confused with the use of C<//> to mean "the last successful pattern
-match".
+As a special case for C<split>, using the empty pattern C<//> specifically
+matches only the null string, and is not be confused with the regular use
+of C<//> to mean "the last successful pattern match".  So, for C<split>,
+the following:
 
-Empty leading (or trailing) fields are produced when there are positive width
-matches at the beginning (or end) of the string; a zero-width match at the
-beginning (or end) of the string does not produce an empty field.  For
-example:
+    print join(':', split(//, 'hi there'));
+
+produces the output 'h:i: :t:h:e:r:e'.
+
+Empty leading (or trailing) fields are produced when there are positive
+width matches at the beginning (or end) of the string; a zero-width match
+at the beginning (or end) of the string does not produce an empty field.
+For example:
 
    print join(':', split(/(?=\w)/, 'hi there!'));
 
diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 5e188c08a0..01eafdc6fe 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -866,6 +866,157 @@ implement control structures (C<if>, C<while> and the like) and F<pp.c>
 contains everything else. These are, if you like, the C code for Perl's
 built-in functions and operators.
 
+Note that each C<pp_> function is expected to return a pointer to the next
+op. Calls to perl subs (and eval blocks) are handled within the same
+runops loop, and do not consume extra space on the C stack. For example,
+C<pp_entersub> and C<pp_entertry> just push a C<CxSUB> or C<CxEVAL> block
+struct onto the context stack which contain the address of the op
+following the sub call or eval. They then return the first op of that sub
+or eval block, and so execution continues of that sub or block.  Later, a
+C<pp_leavesub> or C<pp_leavetry> op pops the C<CxSUB> or C<CxEVAL>,
+retrieves the return op from it, and returns it.
+
+=item Exception handing
+
+Perl's exception handing (ie C<die> etc) is built on top of the low-level
+C<setjmp()>/C<longjmp()> C-library functions. These basically provide a
+way to capture the current PC and SP registers and later restore them; ie
+a C<longjmp()> continues at the point in code where a previous C<setjmp()>
+was done, with anything further up on the C stack being lost. This is why
+code should always save values using C<SAVE_FOO> rather than in auto
+variables.
+
+The perl core wraps C<setjmp()> etc in the macros C<JMPENV_PUSH> and
+C<JMPENV_JUMP>. The basic rule of perl exceptions is that C<exit>, and
+C<die> (in the absence of C<eval>) perform a C<JMPENV_JUMP(2)>, while
+C<die> within C<eval> does a C<JMPENV_JUMP(3)>.
+
+At entry points to perl, such as C<perl_parse()>, C<perl_run()> and
+C<call_sv(cv, G_EVAL)> each does a C<JMPENV_PUSH>, then enter a runops
+loop or whatever, and handle possible exception returns. For a 2 return,
+final cleanup is performed, such as popping stacks and calling C<CHECK> or
+C<END> blocks. Amongst other things, this is how scope cleanup still
+occurs during an C<exit>.
+
+If a C<die> can find a C<CxEVAL> block on the context stack, then the
+stack is popped to that level and the return op in that block is assigned
+to C<PL_restartop>; then a C<JMPENV_JUMP(3)> is performed.  This normally
+passes control back to the guard. In the case of C<perl_run> and
+C<call_sv>, a non-null C<PL_restartop> triggers re-entry to the runops
+loop. The is the normal way that C<die> or C<croak> is handled within an
+C<eval>.
+
+Sometimes ops are executed within an inner runops loop, such as tie, sort
+or overload code. In this case, something like
+
+    sub FETCH { eval { die } }
+
+would cause a longjmp right back to the guard in C<perl_run>, popping both
+runops loops, which is clearly incorrect. One way to avoid this is for the
+tie code to do a C<JMPENV_PUSH> before executing C<FETCH> in the inner
+runops loop, but for efficiency reasons, perl in fact just sets a flag,
+using C<CATCH_SET(TRUE)>. The C<pp_require>, C<pp_entereval> and
+C<pp_entertry> ops check this flag, and if true, they call C<docatch>,
+which does a C<JMPENV_PUSH> and starts a new runops level to execute the
+code, rather than doing it on the current loop.
+
+As a further optimisation, on exit from the eval block in the C<FETCH>,
+execution of the code following the block is still carried on in the inner
+loop.  When an exception is raised, C<docatch> compares the C<JMPENV>
+level of the C<CxEVAL> with C<PL_top_env> and if they differ, just
+re-throws the exception. In this way any inner loops get popped.
+
+Here's an example.
+
+    1: eval { tie @a, 'A' };
+    2: sub A::TIEARRAY {
+    3:     eval { die };
+    4:     die;
+    5: }
+
+To run this code, C<perl_run> is called, which does a C<JMPENV_PUSH> then
+enters a runops loop. This loop executes the eval and tie ops on line 1,
+with the eval pushing a C<CxEVAL> onto the context stack.
+
+The C<pp_tie> does a C<CATCH_SET(TRUE)>, then starts a second runops loop
+to execute the body of C<TIEARRAY>. When it executes the entertry op on
+line 3, C<CATCH_GET> is true, so C<pp_entertry> calls C<docatch> which
+does a C<JMPENV_PUSH> and starts a third runops loop, which then executes
+the die op. At this point the C call stack looks like this:
+
+    Perl_pp_die
+    Perl_runops      # third loop
+    S_docatch_body
+    S_docatch
+    Perl_pp_entertry
+    Perl_runops      # second loop
+    S_call_body
+    Perl_call_sv
+    Perl_pp_tie
+    Perl_runops      # first loop
+    S_run_body
+    perl_run
+    main
+
+and the context and data stacks, as shown by C<-Dstv>, look like:
+
+    STACK 0: MAIN
+      CX 0: BLOCK  =>
+      CX 1: EVAL   => AV()  PV("A"\0)
+      retop=leave
+    STACK 1: MAGIC
+      CX 0: SUB    =>
+      retop=(null)
+      CX 1: EVAL   => *
+    retop=nextstate
+
+The die pops the first C<CxEVAL> off the context stack, sets
+C<PL_restartop> from it, does a C<JMPENV_JUMP(3)>, and control returns to
+the top C<docatch>. This then starts another third-level runops level,
+which executes the nextstate, pushmark and die ops on line 4. At the point
+that the second C<pp_die> is called, the C call stack looks exactly like
+that above, even though we are no longer within an inner eval; this is
+because of the optimization mentioned earlier. However, the context stack
+now looks like this, ie with the top CxEVAL popped:
+
+    STACK 0: MAIN
+      CX 0: BLOCK  =>
+      CX 1: EVAL   => AV()  PV("A"\0)
+      retop=leave
+    STACK 1: MAGIC
+      CX 0: SUB    =>
+      retop=(null)
+
+The die on line 4 pops the context stack back down to the CxEVAL, leaving
+it as:
+
+    STACK 0: MAIN
+      CX 0: BLOCK  =>
+
+As usual, C<PL_restartop> is extracted from the C<CxEVAL>, and a
+C<JMPENV_JUMP(3)> done, which pops the C stack back to the docatch:
+
+    S_docatch
+    Perl_pp_entertry
+    Perl_runops      # second loop
+    S_call_body
+    Perl_call_sv
+    Perl_pp_tie
+    Perl_runops      # first loop
+    S_run_body
+    perl_run
+    main
+
+In  this case, because the C<JMPENV> level recorded in the C<CxEVAL>
+differs from the current one, C<docatch> just does a C<JMPENV_JUMP(3)>
+and the C stack unwinds to:
+
+    perl_run
+    main
+
+Because C<PL_restartop> is non-null, C<run_body> starts a new runops loop
+and execution continues.
+
 =back
 
 =head2 Internal Variable Types
diff --git a/pod/perlop.pod b/pod/perlop.pod
index c321dc3856..b77b5c35ae 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -191,7 +191,7 @@ the operand is an identifier, a string consisting of a minus sign
 concatenated with the identifier is returned.  Otherwise, if the string
 starts with a plus or minus, a string starting with the opposite sign
 is returned.  One effect of these rules is that -bareword is equivalent
-to "-bareword".
+to the string "-bareword".
 
 Unary "~" performs bitwise negation, i.e., 1's complement.  For
 example, C<0666 & ~027> is 0640.  (See also L<Integer Arithmetic> and
diff --git a/pod/perlport.pod b/pod/perlport.pod
index 2fbead0c8f..ff5e7e679f 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -67,9 +67,9 @@ The important thing is to decide where the code will run and to be
 deliberate in your decision.
 
 The material below is separated into three main sections: main issues of
-portability (L<"ISSUES">, platform-specific issues (L<"PLATFORMS">, and
+portability (L<"ISSUES">), platform-specific issues (L<"PLATFORMS">), and
 built-in perl functions that behave differently on various ports
-(L<"FUNCTION IMPLEMENTATIONS">.
+(L<"FUNCTION IMPLEMENTATIONS">).
 
 This information should not be considered complete; it includes possibly
 transient information about idiosyncrasies of some of the ports, almost
@@ -107,8 +107,8 @@ newlines:
 You can get away with this on Unix and Mac OS (they have a single
 character end-of-line), but the same program will break under DOSish
 perls because you're only chop()ing half the end-of-line.  Instead,
-chomp() should be used to trim newlines.  The Dunce::Files module can
-help audit your code for misuses of chop().
+chomp() should be used to trim newlines.  The L<Dunce::Files> module 
+can help audit your code for misuses of chop().
 
 When dealing with binary files (or text files in binary mode) be sure
 to explicitly set $/ to the appropriate value for your file format
@@ -480,12 +480,14 @@ file name.
 
 To convert $^X to a file pathname, taking account of the requirements
 of the various operating system possibilities, say:
+
   use Config;
   $thisperl = $^X;
   if ($^O ne 'VMS')
      {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
 
 To convert $Config{perlpath} to a file pathname, say:
+
   use Config;
   $thisperl = $Config{perlpath};
   if ($^O ne 'VMS')
@@ -517,7 +519,7 @@ Don't assume that you can ping hosts and get replies.
 
 Don't assume that any particular port (service) will respond.
 
-Don't assume that Sys::Hostname() (or any other API or command)
+Don't assume that Sys::Hostname (or any other API or command)
 returns either a fully qualified hostname or a non-qualified hostname:
 it all depends on how the system had been configured.  Also remember
 things like DHCP and NAT-- the hostname you get back might not be very
@@ -770,11 +772,17 @@ problems in their code that crop up because of lack of testing on other
 platforms; two, to provide users with information about whether
 a given module works on a given platform.
 
+Also see: 
+
 =over 4
 
-=item Mailing list: cpan-testers@perl.org
+=item *
 
-=item Testing results: http://testers.cpan.org/
+Mailing list: cpan-testers@perl.org
+
+=item *
+
+Testing results: http://testers.cpan.org/
 
 =back
 
@@ -897,10 +905,11 @@ DOSish perls are as follows:
      Windows NT    MSWin32    MSWin32-x86       2      4 xx
      Windows NT    MSWin32    MSWin32-ALPHA     2      4 xx
      Windows NT    MSWin32    MSWin32-ppc       2      4 xx
-     Windows 2000  MSWin32    MSWin32-x86       2      5 xx
-     Windows XP    MSWin32    MSWin32-x86       2      ?
+     Windows 2000  MSWin32    MSWin32-x86       2      5 00
+     Windows XP    MSWin32    MSWin32-x86       2      5 01
+     Windows 2003  MSWin32    MSWin32-x86       2      5 02
      Windows CE    MSWin32    ?                 3           
-     Cygwin        cygwin     ?                 
+     Cygwin        cygwin     cygwin
 
 The various MSWin32 Perl's can distinguish the OS they are running on
 via the value of the fifth element of the list returned from 
@@ -1039,6 +1048,10 @@ The MacPerl Pages, http://www.macperl.com/ .
 
 The MacPerl mailing lists, http://lists.perl.org/ .
 
+=item *
+
+MPW, ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/
+
 =back
 
 =head2 VMS
@@ -1308,8 +1321,6 @@ Also see:
 
 =item *
 
-*
-
 L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
 L<perlebcdic>.
 
@@ -1319,7 +1330,7 @@ The perl-mvs@perl.org list is for discussion of porting issues as well as
 general usage issues for all EBCDIC Perls.  Send a message body of
 "subscribe perl-mvs" to majordomo@perl.org.
 
-=item  *
+=item *
 
 AS/400 Perl information at
 http://as400.rochester.ibm.com/
@@ -1507,10 +1518,6 @@ L<Config> for a full description of available variables.
 
 =over 8
 
-=item -X FILEHANDLE
-
-=item -X EXPR
-
 =item -X
 
 C<-r>, C<-w>, and C<-x> have a limited meaning only; directories
@@ -1549,7 +1556,18 @@ suffixes.  C<-S> is meaningless.  (Win32)
 C<-x> (or C<-X>) determine if a file has an executable file type.
 (S<RISC OS>)
 
-=item binmode FILEHANDLE
+=item atan2
+
+Due to issues with various CPUs, math libraries, compilers, and standards,
+results for C<atan2()> may vary depending on any combination of the above.
+Perl attempts to conform to the Open Group/IEEE standards for the results
+returned from C<atan2()>, but cannot force the issue if the system Perl is
+run on does not allow it.  (Tru64, HP-UX 10.20) 
+
+The current version of the standards for C<atan2()> is available at 
+L<http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html>.
+
+=item binmode
 
 Meaningless.  (S<Mac OS>, S<RISC OS>)
 
@@ -1560,7 +1578,7 @@ filehandle may be closed, or pointer may be in a different position.
 The value returned by C<tell> may be affected after the call, and
 the filehandle may be flushed. (Win32)
 
-=item chmod LIST
+=item chmod
 
 Only limited meaning.  Disabling/enabling write permission is mapped to
 locking/unlocking the file. (S<Mac OS>)
@@ -1575,34 +1593,32 @@ Access permissions are mapped onto VOS access-control list changes. (VOS)
 The actual permissions set depend on the value of the C<CYGWIN>
 in the SYSTEM environment settings.  (Cygwin)
 
-=item chown LIST
+=item chown
 
 Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>, VOS)
 
 Does nothing, but won't fail. (Win32)
 
-=item chroot FILENAME
-
 =item chroot
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS, VM/ESA)
 
-=item crypt PLAINTEXT,SALT
+=item crypt
 
 May not be available if library or source was not provided when building
 perl. (Win32)
 
 Not implemented. (VOS)
 
-=item dbmclose HASH
+=item dbmclose
 
 Not implemented. (VMS, S<Plan 9>, VOS)
 
-=item dbmopen HASH,DBNAME,MODE
+=item dbmopen
 
 Not implemented. (VMS, S<Plan 9>, VOS)
 
-=item dump LABEL
+=item dump
 
 Not useful. (S<Mac OS>, S<RISC OS>)
 
@@ -1610,7 +1626,7 @@ Not implemented. (Win32)
 
 Invokes VMS debugger. (VMS)
 
-=item exec LIST
+=item exec
 
 Not implemented. (S<Mac OS>)
 
@@ -1619,8 +1635,6 @@ Implemented via Spawn. (VM/ESA)
 Does not automatically flush output handles on some platforms.
 (SunOS, Solaris, HP-UX)
 
-=item exit EXPR
-
 =item exit
 
 Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
@@ -1630,11 +1644,11 @@ function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
 (C<1>); this mapping cannot be overridden.  Any other argument to exit()
 is used directly as Perl's exit status. (VMS)
 
-=item fcntl FILEHANDLE,FUNCTION,SCALAR
+=item fcntl
 
 Not implemented. (Win32, VMS)
 
-=item flock FILEHANDLE,OPERATION
+=item flock
 
 Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS).
 
@@ -1653,7 +1667,7 @@ Does not automatically flush output handles on some platforms.
 
 Not implemented. (S<Mac OS>, S<RISC OS>)
 
-=item getpgrp PID
+=item getpgrp
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
@@ -1661,43 +1675,43 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
 Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
 
-=item getpriority WHICH,WHO
+=item getpriority
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
 
-=item getpwnam NAME
+=item getpwnam
 
 Not implemented. (S<Mac OS>, Win32)
 
 Not useful. (S<RISC OS>)
 
-=item getgrnam NAME
+=item getgrnam
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
 
-=item getnetbyname NAME
+=item getnetbyname
 
 Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
 
-=item getpwuid UID
+=item getpwuid
 
 Not implemented. (S<Mac OS>, Win32)
 
 Not useful. (S<RISC OS>)
 
-=item getgrgid GID
+=item getgrgid
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
 
-=item getnetbyaddr ADDR,ADDRTYPE
+=item getnetbyaddr
 
 Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
 
-=item getprotobynumber NUMBER
+=item getprotobynumber
 
 Not implemented. (S<Mac OS>)
 
-=item getservbyport PORT,PROTO
+=item getservbyport
 
 Not implemented. (S<Mac OS>)
 
@@ -1730,19 +1744,19 @@ Not implemented. (S<Mac OS>, Win32, S<Plan 9>)
 
 Not implemented. (Win32, S<Plan 9>)
 
-=item sethostent STAYOPEN
+=item sethostent
 
 Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
 
-=item setnetent STAYOPEN
+=item setnetent
 
 Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
 
-=item setprotoent STAYOPEN
+=item setprotoent
 
 Not implemented. (S<Mac OS>, Win32, S<Plan 9>, S<RISC OS>)
 
-=item setservent STAYOPEN
+=item setservent
 
 Not implemented. (S<Plan 9>, Win32, S<RISC OS>)
 
@@ -1774,13 +1788,15 @@ Not implemented. (S<Plan 9>, Win32)
 
 Not implemented. (S<Plan 9>)
 
-=item glob EXPR
-
 =item glob
 
 This operator is implemented via the File::Glob extension on most
 platforms.  See L<File::Glob> for portability information.
 
+=item gmtime
+
+Same portability caveats as L<localtime>.
+
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
 
 Not implemented. (VMS)
@@ -1790,7 +1806,7 @@ in the Winsock API does. (Win32)
 
 Available only for socket handles. (S<RISC OS>)
 
-=item kill SIGNAL, LIST
+=item kill
 
 C<kill(0, LIST)> is implemented for the sake of taint checking;
 use with other signals is unimplemented. (S<Mac OS>)
@@ -1804,7 +1820,7 @@ and makes it exit immediately with exit status $sig.  As in Unix, if
 $sig is 0 and the specified process exists, it returns true without
 actually terminating it. (Win32)
 
-=item link OLDFILE,NEWFILE
+=item link
 
 Not implemented. (S<Mac OS>, MPE/iX, VMS, S<RISC OS>)
 
@@ -1814,9 +1830,12 @@ Link count not updated because hard links are not quite that hard
 Hard links are implemented on Win32 (Windows NT and Windows 2000)
 under NTFS only.
 
-=item lstat FILEHANDLE
+=item localtime
 
-=item lstat EXPR
+Because Perl currently relies on the native standard C localtime()
+function, it is only safe to use times between 0 and (2**31)-1.  Times
+outside this range may result in unexpected behavior depending on your
+operating system's implementation of localtime().
 
 =item lstat
 
@@ -1824,19 +1843,17 @@ Not implemented. (VMS, S<RISC OS>)
 
 Return values (especially for device and inode) may be bogus. (Win32)
 
-=item msgctl ID,CMD,ARG
+=item msgctl
 
-=item msgget KEY,FLAGS
+=item msgget
 
-=item msgsnd ID,MSG,FLAGS
+=item msgsnd
 
-=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
+=item msgrcv
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
 
-=item open FILEHANDLE,EXPR
-
-=item open FILEHANDLE
+=item open
 
 The C<|> variants are supported only if ToolServer is installed.
 (S<Mac OS>)
@@ -1846,21 +1863,19 @@ open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>)
 Opening a process does not automatically flush output handles on some
 platforms.  (SunOS, Solaris, HP-UX)
 
-=item pipe READHANDLE,WRITEHANDLE
+=item pipe
 
 Very limited functionality. (MiNT)
 
-=item readlink EXPR
-
 =item readlink
 
 Not implemented. (Win32, VMS, S<RISC OS>)
 
-=item rename OLDNAME,NEWNAME
+=item rename
 
 Can't move directories between directories on different logical volumes. (Win32)
 
-=item select RBITS,WBITS,EBITS,TIMEOUT
+=item select
 
 Only implemented on sockets. (Win32, VMS)
 
@@ -1868,11 +1883,11 @@ Only reliable on sockets. (S<RISC OS>)
 
 Note that the C<select FILEHANDLE> form is generally portable.
 
-=item semctl ID,SEMNUM,CMD,ARG
+=item semctl
 
-=item semget KEY,NSEMS,FLAGS
+=item semget
 
-=item semop KEY,OPSTRING
+=item semop
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
@@ -1880,11 +1895,11 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
 Not implemented. (S<Mac OS>, MPE/iX, VMS, Win32, S<RISC OS>)
 
-=item setpgrp PID,PGRP
+=item setpgrp
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
-=item setpriority WHICH,WHO,PRIORITY
+=item setpriority
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
@@ -1892,33 +1907,29 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
 Not implemented. (S<Mac OS>, MPE/iX, Win32, S<RISC OS>)
 
-=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+=item setsockopt
 
 Not implemented. (S<Plan 9>)
 
-=item shmctl ID,CMD,ARG
+=item shmctl
 
-=item shmget KEY,SIZE,FLAGS
+=item shmget
 
-=item shmread ID,VAR,POS,SIZE
+=item shmread
 
-=item shmwrite ID,STRING,POS,SIZE
+=item shmwrite
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
-=item sockatmark SOCKET
+=item sockatmark
 
 A relatively recent addition to socket functions, may not
 be implemented even in UNIX platforms.
 
-=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+=item socketpair
 
 Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
 
-=item stat FILEHANDLE
-
-=item stat EXPR
-
 =item stat
 
 Platforms that do not have rdev, blksize, or blocks will return these
@@ -1945,22 +1956,22 @@ meaningful and will differ between stat calls on the same file.  (os2)
 some versions of cygwin when doing a stat("foo") and if not finding it
 may then attempt to stat("foo.exe") (Cygwin)
 
-=item symlink OLDFILE,NEWFILE
+=item symlink
 
 Not implemented. (Win32, VMS, S<RISC OS>)
 
-=item syscall LIST
+=item syscall
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA)
 
-=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
+=item sysopen
 
 The traditional "0", "1", and "2" MODEs are implemented with different
 numeric values on some systems.  The flags exported by C<Fcntl>
 (O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though.  (S<Mac
 OS>, OS/390, VM/ESA)
 
-=item system LIST
+=item system
 
 In general, do not assume the UNIX/POSIX semantics that you can shift
 C<$?> right by eight to get the exit value, or that C<$? & 127>
@@ -2017,9 +2028,7 @@ library. (Win32)
 
 Not useful. (S<RISC OS>)
 
-=item truncate FILEHANDLE,LENGTH
-
-=item truncate EXPR,LENGTH
+=item truncate
 
 Not implemented. (Older versions of VMS)
 
@@ -2030,8 +2039,6 @@ mode (i.e., use C<<< open(FH, '>>filename') >>>
 or C<sysopen(FH,...,O_APPEND|O_RDWR)>.  If a filename is supplied, it
 should not be held open elsewhere. (Win32)
 
-=item umask EXPR
-
 =item umask
 
 Returns undef where unavailable, as of version 5.005.
@@ -2039,7 +2046,7 @@ Returns undef where unavailable, as of version 5.005.
 C<umask> works but the correct permissions are set only when the file
 is finally closed. (AmigaOS)
 
-=item utime LIST
+=item utime
 
 Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
 
@@ -2051,7 +2058,7 @@ two seconds. (Win32)
 
 =item wait
 
-=item waitpid PID,FLAGS
+=item waitpid
 
 Not implemented. (S<Mac OS>, VOS)
 
@@ -2062,94 +2069,6 @@ Not useful. (S<RISC OS>)
 
 =back
 
-=head1 CHANGES
-
-=over 4
-
-=item v1.48, 02 February 2001
-
-Various updates from perl5-porters over the past year, supported
-platforms update from Jarkko Hietaniemi.
-
-=item v1.47, 22 March 2000
-
-Various cleanups from Tom Christiansen, including migration of 
-long platform listings from L<perl>.
-
-=item v1.46, 12 February 2000
-
-Updates for VOS and MPE/iX. (Peter Prymmer)  Other small changes.
-
-=item v1.45, 20 December 1999
-
-Small changes from 5.005_63 distribution, more changes to EBCDIC info.
-
-=item v1.44, 19 July 1999
-
-A bunch of updates from Peter Prymmer for C<$^O> values,
-endianness, File::Spec, VMS, BS2000, OS/400.
-
-=item v1.43, 24 May 1999
-
-Added a lot of cleaning up from Tom Christiansen.
-
-=item v1.42, 22 May 1999
-
-Added notes about tests, sprintf/printf, and epoch offsets.
-
-=item v1.41, 19 May 1999
-
-Lots more little changes to formatting and content.
-
-Added a bunch of C<$^O> and related values
-for various platforms; fixed mail and web addresses, and added
-and changed miscellaneous notes.  (Peter Prymmer)
-
-=item v1.40, 11 April 1999
-
-Miscellaneous changes.
-
-=item v1.39, 11 February 1999
-
-Changes from Jarkko and EMX URL fixes Michael Schwern.  Additional
-note about newlines added.
-
-=item v1.38, 31 December 1998
-
-More changes from Jarkko.
-
-=item v1.37, 19 December 1998
-
-More minor changes.  Merge two separate version 1.35 documents.
-
-=item v1.36, 9 September 1998
-
-Updated for Stratus VOS.  Also known as version 1.35.
-
-=item v1.35, 13 August 1998
-
-Integrate more minor changes, plus addition of new sections under
-L<"ISSUES">: L<"Numbers endianness and Width">,
-L<"Character sets and character encoding">,
-L<"Internationalisation">.
-
-=item v1.33, 06 August 1998
-
-Integrate more minor changes.
-
-=item v1.32, 05 August 1998
-
-Integrate more minor changes.
-
-=item v1.30, 03 August 1998
-
-Major update for RISC OS, other minor changes.
-
-=item v1.23, 10 July 1998
-
-First public release with perl5.005.
-
-=back
 
 =head1 Supported Platforms
 
diff --git a/pod/perlreftut.pod b/pod/perlreftut.pod
index bbcc179cca..e55e4d5308 100644
--- a/pod/perlreftut.pod
+++ b/pod/perlreftut.pod
@@ -1,4 +1,3 @@
-
 =head1 NAME
 
 perlreftut - Mark's very short tutorial about references
@@ -215,7 +214,7 @@ And then replace the hash name with the reference:
 
 =head3 B<Use Rule 2>
 
-B<Use Rule 1> is all you really need, because it tells you how to to
+B<Use Rule 1> is all you really need, because it tells you how to do
 absolutely everything you ever need to do with references.  But the
 most common thing to do with an array or a hash is to extract a single
 element, and the B<Use Rule 1> notation is cumbersome.  So there is an
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index aabd65d212..3d45d55f52 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -105,6 +105,9 @@ as the last item in a statement.
 
 The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
 C<undef> are all false in a boolean context. All other values are true.
+Negation of a true value by C<!> or C<not> returns a special false value.
+When evaluated as a string it is treated as C<''>, but as a number, it
+is treated as 0.
 
 =head2 Statement Modifiers
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 39f0052121..82656a9ca6 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -541,9 +541,9 @@ C<$-[>I<n>C<]> is the offset of the start of the substring matched by
 I<n>-th subpattern, or undef if the subpattern did not match.
 
 Thus after a match against $_, $& coincides with C<substr $_, $-[0],
-$+[0] - $-[0]>.  Similarly, C<$>I<n> coincides with C<substr $_, $-[>I<n>C<],
-$+[>I<n>C<] - $-[>I<n>C<]> if C<$-[>I<n>C<]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-]>.  One can use C<$#-> to find the last
+$+[0] - $-[0]>.  Similarly, $I<n> coincides with C<substr $_, $-[n],
+$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
+C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>.  One can use C<$#-> to find the last
 matched subgroup in the last successful match.  Contrast with
 C<$#+>, the number of subgroups in the regular expression.  Compare
 with C<@+>.
@@ -1224,7 +1224,7 @@ executable files do not require use of the suffix when invoking
 a command.  To convert the value of $^X to a path name, use the
 following statements:
 
-# Build up a set of file names (not command names).
+  # Build up a set of file names (not command names).
   use Config;
   $this_perl = $^X;
   if ($^O ne 'VMS')
@@ -1441,7 +1441,7 @@ C<$@> is set if the string to be C<eval>-ed did not compile (this
 may happen if C<open> or C<close> were imported with bad prototypes),
 or if Perl code executed during evaluation die()d .  In these cases
 the value of $@ is the compile error, or the argument to C<die>
-(which will interpolate C<$!> and C<$?>!).  (See also L<Fatal>,
+(which will interpolate C<$!> and C<$?>).  (See also L<Fatal>,
 though.)
 
 When the eval() expression above is executed, open(), C<< <PIPE> >>,
diff --git a/sv.c b/sv.c
index aaee03ef27..38e7afe115 100644
--- a/sv.c
+++ b/sv.c
@@ -56,14 +56,13 @@ av, hv...) contains type and reference count information, as well as a
 pointer to the body (struct xrv, xpv, xpviv...), which contains fields
 specific to each type.
 
-Normally, this allocation is done using arenas, which are approximately
-1K chunks of memory parcelled up into N heads or bodies. The first slot
-in each arena is reserved, and is used to hold a link to the next arena.
-In the case of heads, the unused first slot also contains some flags and
-a note of the number of slots.  Snaked through each arena chain is a
+Normally, this allocation is done using arenas, which by default are
+approximately 4K chunks of memory parcelled up into N heads or bodies.  The
+first slot in each arena is reserved, and is used to hold a link to the next
+arena.  In the case of heads, the unused first slot also contains some flags
+and a note of the number of slots.  Snaked through each arena chain is a
 linked list of free items; when this becomes empty, an extra arena is
-allocated and divided up into N items which are threaded into the free
-list.
+allocated and divided up into N items which are threaded into the free list.
 
 The following global variables are associated with arenas:
 
@@ -79,7 +78,8 @@ are not allocated using arenas, but are instead just malloc()/free()ed as
 required. Also, if PURIFY is defined, arenas are abandoned altogether,
 with all items individually malloc()ed. In addition, a few SV heads are
 not allocated from an arena, but are instead directly created as static
-or auto variables, eg PL_sv_undef.
+or auto variables, eg PL_sv_undef.  The size of arenas can be changed from
+the default by setting PERL_ARENA_SIZE appropriately at compile time.
 
 The SV arena serves the secondary purpose of allowing still-live SVs
 to be located and destroyed during final cleanup.