First full draft of the 5.12.1 perldelta

(cherry picked from commit 189604b10ea23a1742e336089a5819d6900287d5)

Signed-off-by: David Golden <dagolden@cpan.org>

1 files changed, 154 insertions, 285 deletions

diff --git a/pod/perl5121delta.pod b/pod/perl5121delta.pod
index f305da952b..8edc4f3e7e 100644
--- a/pod/perl5121delta.pod
+++ b/pod/perl5121delta.pod
@@ -30,442 +30,311 @@ changes to the core langauge in this release.
 
 =head1 Modules and Pragmata
 
-=head2 New Modules and Pragmata
-
 =head2 Pragmata Changes
 
-=head2 Updated Modules
-
-=head2 Removed Modules and Pragmata
+=over 
 
-=head1 Changes to Existing Documentation
+=item *
 
-XXX Changes which significantly change existing files in F<pod/> go here.
-Any changes to F<pod/perldiag.pod> should go in L</New or Changed Diagnostics>.
+We fixed exporting of C<version::is_strict> and C<version::is_lax>
 
+These were being exported with a wrapper that treated them as method
+calls, which causes them to fail.  They are just functions, are
+documented as such, and should never be subclassed, so this patch
+just exports them directly as functions without the wrapper.
 
-=head1 Performance Enhancements
+=back
 
-XXX Changes which enhance performance without changing behaviour go here. There
-may well be none in a stable release.
+=head2 Updated Modules
 
-=over 4
+=over 
 
 =item *
 
-XXX
-
-=back
+We upgraded L<CGI.pm> to version 3.49 to incorporate fixes for regressions
+introduced in the release we shipped with Perl 5.12.0.
 
-=head1 Installation and Configuration Improvements
-
-XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
-go here.
+=item *
 
-=head2 Configuration improvements
+We upgraded L<Pod::Simple> to version 3.14 to get an improvement to \C\<\< \>\>
+parsing.
 
-XXX
+=back
 
-=head2 Compilation improvements
+=head1 Changes to Existing Documentation
 
-XXX
+=over
 
-=head2 Platform Specific Changes
+=item *
 
-=over 4
+We added the new maintenance release policy to L<perlpolicy.pod>
 
-=item XXX-some-platform
+=item *
 
-XXX
+We've clarified the multiple-angle-bracked construct in the spec for POD.
 
-=back
+=item *
 
-=head1 Selected Bug Fixes
+We added a missing explanation for a warning about C<:=> to L<perldiag.pod>
 
-XXX Important bug fixes in the core language are summarised here.
-Bug fixes in files in F<ext/> and F<lib/> are best summarised in
-L</Modules and Pragmata>.
+=item *
 
-=over 4
+We removed a false claim that all text strings are Unicode strings in Perl.
 
 =item *
 
-XXX
+GitHub's mirror is now at mirrors/perl, not github/perl
 
-=back
+=item *
 
-=head1 Changed Internals
+We fixed a a minor error in L<perl5114delta.pod>.
 
-XXX Changes which affect the interface available to C<XS> code go here.
+=item * 
 
-=over 4
+We replaced a mention of the now-obsolete L<Switch.pm> with F<given>/F<when>.
 
 =item *
 
-XXX
-
-=back
+We improved documentation about F<$sitelibexp/sitecustomize.pl>.
 
-=head1 Known Problems
+=item * 
 
-XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
-tests that had to be C<TODO>ed for the release would be noted here, unless
-they were specific to a particular platform (see below).
+We corrected L<perlmodlib.pod> which had unintentionally ommitted a number of modules.
 
-This is a list of some significant unfixed bugs, which are regressions
-from either 5.XXX.XXX or 5.XXX.XXX.
+=item * 
 
-=over 4
+We updated the documentation for 'require' in L<perlfunc.pod> relating to putting Perl code in @INC.
 
 =item *
 
-XXX
+We reinstated some erroneously-removed documentation about quotemeta.
 
-=back
-
-=head1 Platform Specific Notes
-
-XXX Any changes specific to a particular platform. VMS and Win32 are the usual
-stars here. It's probably best to group changes under the same section layout
-as the main perldelta
+=item *
 
-=head1 Acknowledgements
+We fixed an F<a2p> example in L<perlutil.pod>.
 
-XXX The list of people to thank goes here.
+=item  *
 
+We filled in a blank in L<perlport.pod> with the release date of Perl 5.12.
 
-=head1 Reporting Bugs
+=item  *
 
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ .  There may also be
-information at http://www.perl.org/ , the Perl Home Page.
+We fixed broken links in a number of perldelta files.
 
-If you believe you have an unreported bug, please run the B<perlbug>
-program included with your release.  Be sure to trim your bug down
-to a tiny but sufficient test case.  Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug@perl.org to be
-analysed by the Perl porting team.
+=item * 
 
-If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report@perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
-to help assess the impact of issues, figure out a resolution, and help
-co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
+The documentation for L<Carp.pm> incorrectly stated that the $Carp::Verbose
+variable makes cluck generate stack backtraces.
 
-=head1 SEE ALSO
+=item *
 
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
+We fixed a number of typos in L<Pod::Functions>
 
-The F<INSTALL> file for how to build Perl.
+=back
 
-The F<README> file for general stuff.
+=head1 Testing
 
-The F<Artistic> and F<Copying> files for copyright information.
+=head2 Testing Improvements
 
-=cut
+=over
 
+=item *
 
+F<t/op/sselect.t> is now less prone to clock jitter during timing checks
+on Windows.
 
-=HEAD2 BUILD AND INSTALL
+sleep() time on Win32 may be rounded down to multiple of
+the clock tick interval.
 
 =item *
 
-Ignore the /UU directory that exists during ./Configure
-
-=HEAD2 DIAGNOSTICS
+F<lib/blib.t> and F<lib/locale.t>: Fixes for test failures on Darwin/PPC
 
 =item *
 
-Added a missing explanation for a warning about C<:=> to L<perldiag.pod>
+F<perl5db.t>: Fix for test failures when C<Term::ReadLine::Gnu> is installed.
 
-=head2 TEST FIXES
-
-=item *
+=back
 
-Fixes for 5.12.0 test failures in lib/blib.t and lib/locale.t on Darwin/PPC
+=head1 Installation and Configuration Improvements
 
+XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
+go here.
 
-=item *
+=head2 Configuration improvements
 
-    Fix a test failure in perl5db.t when Term::ReadLine::Gnu is installed
+=over 
 
+=item * 
 
-=item *
-    Add fudge to timing checks on Windows
-    
-    sleep() time on Win32 may be rounded down to multiple of
-    the clock tick interval.
-    
-    http://www.nntp.perl.org/group/perl.perl5.porters/2010/03/msg157878.html
+We updated F<INSTALL> with notes aboute how to deal with broken F<dbm.h> on OpenSUSE (and possibly other platforms)
 
+=back
 
+=head1 Selected Bug Fixes
 
-DOC 
+=over 4
 
 =item *
 
-Add the new maint policy to perlpolicy.pod
+A bug in how we process filetest operations could cause a segfault.
+Filetest don't always expect an op on the stack, so we now use
+TOPs only if we're sure that we're not stat'ing the _ filehandle.
+This is indicated by OPf_KIDS (as checked in ck_ftst).
+
+See also http://rt.perl.org/rt3/Public/Bug/Display.html?id=74542
 
 =item *
 
-We've clarified the multiple-angle-bracked construct in the spec for POD
+When deparsing a nextstate op that has both a change of package (relative
+to the previous nextstate) and a label, the package declaration is now
+emitted first, because it is syntactically impermissible for a label to
+prefix a package declaration.
 
 =item * 
 
-    Nits in perlunifaq.pod
+XSUB.h now correctly redefines fgets under PERL_IMPLICIT_SYS
 
-=item *
+See also http://rt.cpan.org/Public/Bug/Display.html?id=55049
 
-    Update title of "Supported Platforms" in perlport to avoid
-    breaking pod links at each perl release (spotted by Karl Williamson)
 
 =item * 
-    [perl #74808] Carp.pm POD error
-    
-    The documentation incorrectly states that the $Carp::Verbose
-    variable makes cluck generate stack backtraces.  cluck
-    already generates stack backtraces.  It should say that
-    the variable makes croak generate stack backtraces.
 
+utf8::is_utf8 now respects respect GMAGIC (e.g. $1)
 
 
-=item *
+=item * 
 
-Fix F<a2p> example in L<perlutil.pod>
+XS code using C<fputc()> or C<fputs()>: on Windows could cause an error due to their arguments being swapped.
 
+See also: http://rt.perl.org/rt3/Public/Bug/Display.html?id=72704
 
-=item  *
+=back
 
-Fill blank with the release date of 5.12 in perlport.pod
+=head1 Changed Internals
 
-=item  *
+XXX Changes which affect the interface available to C<XS> code go here.
 
-Fix broken links in perldelta files
-=item *
+=over 4
 
-Typo fixes in Pod::Functions
 =item *
 
-    Add POD index entries for sitecustomize and sitecustomize.pl
-
+commit bd94fa25a8ae3c7107bd1aec68d4488d21c79b05
+Author: Nicholas Clark <nick@ccl4.org>
+Date:   Mon Apr 19 15:35:59 2010 +0100
 
-=item * 
-    Replace mention of Switch.pm with given/when
-=item *
+    Possible undefined behaviour, spotted by gcc 4.5.0 and HP's updated compiler.
 
-    Improve documentation about sitecustomize.pl.
-    
-=item * 
-    Reintroduce a lot of missing modules into perlmodlib.pod
-    
-    That was due to the great move of dual-life modules into cpan/ and
-    dist/. This fixes the bug: [perl #74332] lots of modules missing from
-    perlmodlib.
+XXX
 
-=item * 
+=back
 
-POD tweak to 'require' in perlfunc relating to putting Perl code in @INC
+=head1 Platform Specific Notes
 
-=item *
-    Reinstate some documentation about quotemeta
-    (that was removed in 8bdbc703cb0af3faf2163ebce618944c51f180a0)
+=head2 HP-UX
 
-=item *
-    [perl #74856] Fix POD syntax in perlapi
+=over 
 
 =item *
 
-    Remove false statement about Unicode strings
-    It is simply not true that all text strings are Unicode strings in Perl.
+Perl now allows -Duse64bitint without promoting to use64bitall on HP-UX
 
-=item *
-    GitHub's mirror is now at mirrors/perl, not github/perl
-=item *
-    Fix a minor perl5114delta error.
+=back
 
-PLATFORM AIX 4.2
+=head2 AIX
 
-=item * 
+=over
 
-    [PATCH] [5.12] Allow build on aix 4.2 (sigaction and IPv6)
-    
-    Based on a patch by AUGUSTE-ETIENNE José <jose.auguste-etienne@cgss-guyane.fr>
-    
-    The attached patches are necessary to work around aix 4.2 lack of support for IPv6,
-    and limited support for POSIX sigaction()
-    
-    The hints/aix_4.sh patch solves the following build failure:
-    
-    "Socket.xs", line 468.16: 1506-007 (S) "struct in6_addr" is undefined.
-    
-    The ext/POSIX/t/sigaction.t patch solves the failing test reported a looong time ago:
-    
-    http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2006-01/msg01124.html
-    
-    After testing a simple C program using POSIX sigaction() with SA_SIGINFO,
-    I found that it worked on aix 4.3 but failed on aix 4.2.
-    
-    I think it's safe to skip the SA_SIGINFO test on the aix 4.2 platform.
-    
-    perl 5.12.0 builds fine on the following platforms / C compiler :
-    
-    aix 4.2.1 / vac 5.0.2.7 (with attached patches)
-    aix 4.3.2 / gcc 2.95.3
-    aix 4.3.3 / vac 4.4.0.3
-    aix 4.3.3 / vac 5.0.28
-    aix 5.2 / GNUpro gcc 2.9.aix51.020209
-    
-    The atatched patches should be applied to blead and maint.
-
-
-
-Platform FreeBSD
 =item * 
-    FreeBSD 7+ no longer contains /usr/bin/objformat, so the following
-    (harmless) following error message is printed when hints are run:
-    
-    ./hints/freebsd.sh: /usr/bin/objformat: not found
-    
-    The reason for this is outlined in this email from Feb 2007
-    http://lists.freebsd.org/pipermail/freebsd-ports/2007-February/038523.html
-    
-    This patch just skips the objformat check for versions 7+ and
-    assumes ELF.  (The end result is unchanged, but the error
-    message will not be printed anymore.)
-
-PLATFORMS VMS
 
-=item *
-    Allow extension building on older (pre 7.3-2) VMS systems.
-    
-    DCL symbol length was limited to 1K up until about seven years or
-    so ago, but there was no particularly deep reason to prevent those
-    older systems from configuring and building Perl.
+Perl now builds on AIX 4.2
 
+The changes required work around AIX 4.2s' lack of support for IPv6,
+and limited support for POSIX C<sigaction()>.
 
-=item *
-
-    Fix broken -Uuseperlio build on VMS.
-    
-    We were checking a variable that doesn't exist in the non-default
-    case of disabling perlio.  Now we only look at it when it exists.
-
-=item *(
-
-    Fix -Uuseperlio command-line option in configure.com.
-    
-    Formerly it only worked if you went through all the questions
-    interactively and explicitly answered no.
-    (cherry picked from commit 839d17582bad556c85fba50bb136d1c1fa878a54)
-commit bd94fa25a8ae3c7107bd1aec68d4488d21c79b05
-Author: Nicholas Clark <nick@ccl4.org>
-Date:   Mon Apr 19 15:35:59 2010 +0100
+=back
 
-    Possible undefined behaviour, spotted by gcc 4.5.0 and HP's updated compiler.
+=head2 FreeBSD 7
 
-PLATFORM SUSE?
+=over
 
 =item * 
 
-    Note how to deal with broken dbm.h on OpenSUSE
-    (cherry picked from commit 1bb125e2afe6197deaf55852a3f8a9c52736bfdc)
+FreeBSD 7 no longer contains F</usr/bin/objformat>. At build time,
+Perl now skips the F<objformat> check for versions 7 and higher and
+assumes ELF.
 
+=back
 
-PLATFORM HPUX
-
-=item *
-    Allow -Duse64bitint without promoting to use64bitall on HP-UX
-    
-    Fix for http://rt.perl.org/rt3/Public/Bug/Display.html?id=17736
-    (cherry picked from commit 064b70ffe2beced36b4693cdd2a8e2cbd2139b47)
-
-
-Module Updates
-
+=head2 VMS
 
+=over
 
 =item *
 
-    fix version::is_strict/is_lax exporting
-    
-    These were being exported with a wrapper that treated them as method
-    calls, which causes them to fail.  They are just functions, are
-    documented as such, and should never be subclassed, so this patch
-    just exports them directly as functions without the wrapper.
-
+It's now possible to build extensions on older (pre 7.3-2) VMS systems.
 
+DCL symbol length was limited to 1K up until about seven years or
+so ago, but there was no particularly deep reason to prevent those
+older systems from configuring and building Perl.
 
 =item *
 
-    Upgrade to CGI.pm 3.49
+We fixed the previously-broken C<-Uuseperlio> build on VMS.
 
-    TODO WHY
+We were checking a variable that doesn't exist in the non-default
+case of disabling perlio.  Now we only look at it when it exists.
 
 =item *
 
-    import Pod-Simple 3.14 for C<< >> fix
-
+We fixed the -Uuseperlio command-line option in configure.com.
 
-=HEAD2 Release Engineering
+Formerly it only worked if you went through all the questions
+interactively and explicitly answered no.
 
-=item *
-
-Teach bump-perl-version about "libperl511.a"
+=back
 
+=head1 Acknowledgements
 
+XXX The list of people to thank goes here.
 
-commit 72c7417ae4c0cbb91b46622e0657f57469f025f8
-Author: Jan Dubois <jand@activestate.com>
-Date:   Fri Mar 5 15:24:17 2010 -0800
 
-    Apply minimal patch for Perl bug 72704.
-    
-    Arguments to fputc() and fputs() are reversed on Windows.
-    
-    http://rt.perl.org/rt3/Public/Bug/Display.html?id=72704
+=head1 Reporting Bugs
 
-=HEAD2 Internals
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ .  There may also be
+information at http://www.perl.org/ , the Perl Home Page.
 
-=item * 
+If you believe you have an unreported bug, please run the B<perlbug>
+program included with your release.  Be sure to trim your bug down
+to a tiny but sufficient test case.  Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug@perl.org to be
+analysed by the Perl porting team.
 
-utf8::is_utf8 now respects respect GMAGIC (e.g. $1)
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report@perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
 
-commit 349476ba0aabe6945fe0b234090937e992e7b95d
+=head1 SEE ALSO
 
-    Fix [perl #74542] 5.12.0 crash on diverse platforms
-    
-    Filetest ops don't always expect an op on the stack, so we should use
-    TOPs only if we're sure that we're not stat'ing the _ filehandle.
-    This is indicated by OPf_KIDS (as checked in ck_ftst).
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
 
-commit 5e8d0adeb52de899a2c0954a747fe56eda402bed
-Author: Zefram <zefram@fysh.org>
-Date:   Fri Apr 30 00:02:06 2010 +0100
+The F<INSTALL> file for how to build Perl.
 
-    put package declaration before label in deparsing
-    
-    When deparsing a nextstate op that has both a change of package (relative
-    to the previous nextstate) and a label, the package declaration must be
-    emitted first, because it is syntactically impermissible for a label to
-    prefix a package declaration.
-    (cherry picked from commit 98a1a1376eb18f3329f6d272d4dc3e9a7780689f)
+The F<README> file for general stuff.
 
+The F<Artistic> and F<Copying> files for copyright information.
 
-commit e560917618a7d70a9f3420f75c62e08872bf97b5
-Author: Jan Dubois <jand@activestate.com>
-Date:   Wed Apr 21 16:49:09 2010 -0700
+=cut
 
-    XSUB.h is supposed to redefine fgets under PERL_IMPLICIT_SYS, but doesn't.
-    
-    See also http://rt.cpan.org/Public/Bug/Display.html?id=55049
-    with workaround in http://code.google.com/p/perl-devel-nytprof/source/detail?r=1168
-    (cherry picked from commit 20c8f8f9118fd23081c818637815bf1aab60b808)