create perldelta.pod for 5.12.3

3 files changed, 659 insertions, 264 deletions

diff --git a/pod/.gitignore b/pod/.gitignore
index ec42faf5eb..430154e2c1 100644
--- a/pod/.gitignore
+++ b/pod/.gitignore
@@ -58,7 +58,7 @@
 /podselect.bat
 
 # generated
-/perl5152delta.pod
+/perl5153delta.pod
 /perlapi.pod
 /perlintern.pod
 *.html
diff --git a/pod/perl5152delta.pod b/pod/perl5152delta.pod
new file mode 100644
index 0000000000..1f0850ced5
--- /dev/null
+++ b/pod/perl5152delta.pod
@@ -0,0 +1,477 @@
+=encoding utf8
+
+=for comment
+This has been completed up to perl-5.12.1
+
+=head1 NAME
+
+perldelta - what is new for perl v5.15.2
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.15.1 release and
+the 5.15.2 release.
+
+If you are upgrading from an earlier release such as 5.15.0, first read
+L<perl5151delta>, which describes differences between 5.15.0 and
+5.15.1.
+
+=head1 Core Enhancements
+
+=head2 Subroutines in the CORE namespace
+
+Many Perl keywords are now available as subroutines in the CORE namespace.
+Most of these cannot be called through references or via C<&foo> syntax
+yet, but must be called as barewords.  In other words, you can now do
+this:
+
+    BEGIN { *entangle = \&CORE::tie }
+    entangle $variable, $package, @args;
+
+This currently works for overridable keywords other than C<dump> and the
+infix operators.  Calling through references only works for functions that
+take no arguments (like C<wantarray>).
+
+Work is under way to allow more of these subroutines to be called through
+references.
+
+=head2 C<__FILE__()> Syntax
+
+The C<__FILE__>, C<__LINE__> and C<__PACKAGE__> tokens can now be written
+with an empty pair of parentheses after them.  This makes them parse the
+same way as C<time>, C<fork> and other built-in functions.
+
+=head1 Incompatible Changes
+
+=head2 C<UNIVERSAL::VERSION> now returns $VERSION
+
+C<UNIVERSAL::VERSION> now return whatever is in $VERSION, instead of
+returning $VERSION converted to a version object and then to a string.
+As a result, it no longer parses the version when called without arguments,
+so it no longer dies in that case for malformed versions.  This allows
+custom version number parsers to use C<< ->VERSION >> to retrieve the
+version number, as was the case in Perl 5.8 [perl #95544].
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<B> has been upgraded from version 1.30 to version 1.31
+
+The XS code has changed slightly, as it was too tightly coupled to
+the contents of the header F<embedvar.h>. Documentation in L<B::Terse>
+and L<B::Xref> has been improved, hence their versions have been increased.
+
+=item *
+
+L<CPAN> has been upgraded from version 1.9600 to version 1.9800
+
+=item *
+
+L<CPANPLUS> has been upgraded from version 0.9108 to version 0.9109
+
+Fixed support for v-strings and x.y.z versions with v5.8.4
+
+=item *
+
+L<CPAN::Meta> has been upgraded from version 2.110930_001 to version 2.112150
+
+Stringify any objects encountered during conversion.
+
+Clarified that file paths in the 'provides' section must be in
+Unix-style (i.e. forward slashes)
+
+=item *
+
+L<DB_File> has been upgraded from version 1.822 to version 1.824
+
+Will now croak if attempt to freeze/thaw DB_File object [RT #69985]
+
+=item *
+
+L<diagnostics> has been upgraded from version 1.23 to 1.24.
+
+It now supports the %u formatting code.  Previously it was unable to find
+descriptions for messages whose entries in L<perldiag> included that code
+[perl #94988].
+
+=item *
+
+L<Encode> has been upgraded from version 2.43 to version 2.44
+
+Addressed 'decode_xs n-byte heap-overflow' security bug in Unicode.xs
+
+=item *
+
+L<ExtUtils::Install> has been upgraded from version 1.56 to version 1.57.
+
+There is no change to ExtUtils::Install other than the version number
+increase, but L<ExtUtils::Installed> has been upgraded from version 1.999_001
+to version 1.999002 and a new C<skip_cwd> attribute has been added.
+
+=item *
+
+L<ExtUtils::MakeMaker> has been upgraded from version 6.58 to version 6.59
+
+=item *
+
+L<ExtUtils::Manifest> has been upgraded from version 1.58 to version 1.60
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded from 3.00_01 to 3.00_04.
+
+=item *
+
+L<IPC::Open3> has been upgraded from version 1.11 to 1.12.
+
+C<open3> with "-" for the program name works once more.  This was broken in
+version 1.06 (and hence in Perl 5.14.0) [perl #95748].
+
+=item *
+
+L<Module::Build> has been upgraded from version 0.3800 to version 0.39_01.
+
+Pod to HTML internals changed to support revisions to Pod::Html in core.
+Also fixes some minor bugs. [rt.cpan.org #68585] [rt.cpan.org #67893]
+[rt.cpan.org #67008]
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.54 to version 2.55
+
+=item *
+
+L<Module::Load> has been upgraded from version 0.18 to version 0.20
+
+=item *
+
+L<Module::Metadata> has been upgraded from version 1.000004 to version 1.000005
+
+Added C<new_from_handle()> method.
+
+=item *
+
+L<Params::Check> has been upgraded from version 0.28 to version 0.32
+
+=item *
+
+L<PerlIO::via> has been upgraded from version 0.11 to version 0.12.
+
+The only change is a correction in the documentation.
+
+=item *
+
+L<Term::ANSIColor> has been upgraded from version 3.00 to version 3.01
+
+Only interpret an initial array reference as a list of colors, not any initial
+reference, allowing the colored function to work properly on objects with
+stringification defined.
+
+=item *
+
+L<Unicode::Collate> has been upgraded from version 0.77 to version 0.78
+
+=item *
+
+L<Unicode::Normalize> has been upgraded from version 1.12 to version 1.13
+
+=back
+
+=head1 Documentation
+
+=head2 New Documentation
+
+=head3 L<perlexperiment>
+
+This document is intended to provide a list of experimental features in
+Perl.  It is still a work in progress.
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perlsub>
+
+=over 4
+
+=item *
+
+The ($;) prototype syntax, which has existed for rather a long time, is now
+documented in L<perlsub>.  It allows a unary function to have the same
+precedence as a list operator.
+
+=back
+
+=head1 Diagnostics
+
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see L<perldiag>.
+
+=head2 New Diagnostics
+
+=head3 New Errors
+
+=over 4
+
+=item *
+
+L<&CORE::%s cannot be called directly|perldiag/"&CORE::%s cannot be called directly">
+
+(F) You tried to call a subroutine in the C<CORE::> namespace
+with C<&foo> syntax or through a reference.  The subroutines
+in this package cannot yet be called that way, but must be
+called as barewords.  Something like this will work:
+
+    BEGIN { *shove = \&CORE::push; }
+    shove @array, 1,2,3; # pushes on to @array
+
+=back
+
+=head1 Utility Changes
+
+=head3 L<perlivp>
+
+=over 4
+
+=item *
+
+Fixed a bug whereby other perls under the current directory could cause
+false positive failures.
+
+=item *
+
+Tests for .ph files have been removed, as these test have been optional since
+2005 and .ph files are no longer generated during installation.
+
+=back
+
+=head3 L<splain>
+
+See the entry for C<< diagnostics >> in L</Updated Modules and Pragmata>,
+above.
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item *
+
+F<makedef.pl> has been refactored. This should have no noticeable affect on
+any of the platforms that use it as part of their build (AIX, VMS, Win32).
+
+=item *
+
+C<useperlio> can no longer be disabled.
+
+=back
+
+=head1 Platform Support
+
+=over 4
+
+=item HP-UX PA-RISC/64 now supports gcc-4.x
+
+A fix to correct the socketsize now makes the test suite pass on HP-UX
+PA-RISC for 64bitall builds.
+
+=back
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+F<embedvar.h> has been simplified, and one level of macro indirection for
+PL_* variables has been removed for the default (non-multiplicity)
+configuration. PERLVAR*() macros now directly expand their arguments to
+tokens such as C<PL_defgv>, instead of expanding to C<PL_Idefgv>, with
+F<embedvar.h> defining a macro to map C<PL_Idefgv> to C<PL_defgv>. XS code
+which has unwarranted chumminess with the implementation may need updating.
+
+=item *
+
+A C<coreargs> opcode has been added, to be used by C<&CORE::foo> subs to sort
+out C<@_>.
+
+=item *
+
+An API has been added to explicitly choose whether or not to export XSUB
+symbols.  More detail can be found in the comments for commit e64345f8.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+Locking a subroutine (via C<lock &sub>) is no longer a compile-time error
+for regular subs.  For lvalue subroutines, it no longer tries to return the
+sub as a scalar, resulting in strange side effects like C<ref \$_>
+returning "CODE" in some instances.
+
+C<lock &sub> is now a run-time error if L<threads::shared> is loaded (a
+no-op otherwise), but that may be rectified in a future version.
+
+=item *
+
+The prototypes of several built-in functions--C<getprotobynumber>, C<lock>,
+C<not> and C<select>--have been corrected, or at least are now closer to
+reality than before.
+
+=item *
+
+Most dereferencing operators (C<${}>, etc.) used to call C<FETCH> twice on
+a tied operand when doing a symbolic dereference (looking up a variable by
+name, which is not permitted under C<use strict 'refs'>).  Only C<&{}> did
+not have this problem.  This has been fixed.
+
+=item *
+
+A minor regression introduced in 5.15.0 has been fixed.  Dereferencing a
+magical mortal (e.g., the return value of C<delete> on a tied hash element)
+explicitly returned from a subroutine called recursively was not calling
+C<FETCH>.  This would affect code like C<@{ foo() }> where the C<foo> sub
+contains C<return delete $hash{elem}> and is calling itself.
+
+=item *
+
+A panic involving the combination of the regular expression modifiers
+C</aa> and the C<\b> escape sequence introduced in 5.14.0 has been
+fixed [perl #95964].
+
+=item *
+
+stat() would always return the inode number as an IV, even when the
+original was unsigned, or too large to fit in an IV.  stat() now
+returns the inode number as the type that would best preserve the
+original value. [perl #84590]
+
+=item *
+
+The combination of the regular expression modifiers C</aa> and the C<\b>
+and C<\B> escape sequences did not work properly on UTF-8 encoded
+strings.  All non-ASCII characters under C</aa> should be treated as
+non-word characters, but what was happening was that Unicode rules were
+used to determine wordness/non-wordness for non-ASCII characters.  This
+is now fixed [perl #95968].
+
+=item *
+
+Infinite loops like C<1 while 1> used to stop C<strict 'subs'> mode from
+working for the rest of the block.t
+
+=item *
+
+The C<\h>, C<\H>, C<\v> and C<\V> regular expression metacharacters used to
+cause a panic error message when attempting to match at the end of the
+string [perl #96354].
+
+=item *
+
+For list assignments like C<($a,$b) = ($b,$a)>, Perl has to make a copy of
+the items on the right-hand side before assignment them to the left.  For
+efficiency's sake, it assigns the values on the right straight to the items
+on the left no variable is mentioned on both sides, as in
+C<($a,$b) = ($c,$d)>.  The logic for determining when it can cheat was
+faulty, in that C<&&> and C<||> on the right-hand side could fool it.  So
+C<($a,$b) = $some_true_value && ($b,$a)> would end up assigning the value
+of C<$b> to both scalars.
+
+=item *
+
+Perl no longer tries to apply lvalue context to the string in
+C<("string", $variable) ||= 1> (which used to be an error).  Since the
+left-hand side of C<||=> is evaluated in scalar context, that's a scalar
+comma operator, which gives all but the last item void context.  There is
+no such thing as void lvalue context, so it was a mistake for Perl to try
+to force it [perl #96942].
+
+=item *
+
+Every subroutine has a filename associated with it, that the debugger uses.
+The one associated with constant subroutines used to be misallocated when
+cloned under threads.  Consequently, debugging threaded applications could
+result in memory corruption [perl #96126].
+
+=item *
+
+C<caller> no longer leaks memory when called from the DB package if
+C<@DB::args> was assigned to after the first call to C<caller>.  L<Carp>
+was triggering this bug [perl #97010].
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.15.2 represents approximately 2 months of development since Perl
+5.15.1 and contains approximately 17,000 lines of changes across 330
+files from 35 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.15.2:
+
+Abigail, Andreas König, brian d foy, Brian Greenfield, Chas. Owens,
+Chris 'BinGOs' Williams, Craig A. Berry, David Golden, David Mitchell,
+Eric Brine, Father Chrysostomos, Florian Ragwitz, Gerard Goossen,
+H.Merijn Brand, Jesse Vincent, John Peacock, Karl Williamson, Karthik
+Rajagopalan, Keith Thompson, Kevin Ryde, Matthew Horsfall, Mike
+Sheldrake, Nicholas Clark, Niko Tyni, Reini Urban, Ricardo Signes,
+Salvador Fandiño, Shlomi Fish, Spiros Denaxas, Steffen Müller, Stephen
+Oberholtzer, Steve Hay, Tony Cook, Vincent Pit, Zefram.
+
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core. We're grateful to the entire CPAN
+community for helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors,
+please see the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+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.
+
+If you believe you have an unreported bug, please run the L<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.
+
+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 will 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.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 1f0850ced5..562dca3e95 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1,443 +1,361 @@
 =encoding utf8
 
-=for comment
-This has been completed up to perl-5.12.1
-
 =head1 NAME
 
-perldelta - what is new for perl v5.15.2
+[ this is a template for a new perldelta file. Any text flagged as
+XXX needs to be processed before release. ]
+
+perldelta - what is new for perl v5.XXX.XXX
 
 =head1 DESCRIPTION
 
-This document describes differences between the 5.15.1 release and
-the 5.15.2 release.
+This document describes differences between the 5.XXX.XXX release and
+the 5.XXX.XXX release.
 
-If you are upgrading from an earlier release such as 5.15.0, first read
-L<perl5151delta>, which describes differences between 5.15.0 and
-5.15.1.
+If you are upgrading from an earlier release such as 5.YYY.YYY, first read
+L<perl5YYYdelta>, which describes differences between 5.ZZZ.ZZZ and
+5.YYY.YYY.
 
-=head1 Core Enhancements
+=head1 Notice
 
-=head2 Subroutines in the CORE namespace
+XXX Any important notices here
 
-Many Perl keywords are now available as subroutines in the CORE namespace.
-Most of these cannot be called through references or via C<&foo> syntax
-yet, but must be called as barewords.  In other words, you can now do
-this:
+=head1 Core Enhancements
 
-    BEGIN { *entangle = \&CORE::tie }
-    entangle $variable, $package, @args;
+XXX New core language features go here. Summarise user-visible core language
+enhancements. Particularly prominent performance optimisations could go
+here, but most should go in the L</Performance Enhancements> section.
 
-This currently works for overridable keywords other than C<dump> and the
-infix operators.  Calling through references only works for functions that
-take no arguments (like C<wantarray>).
+[ List each enhancement as a =head2 entry ]
 
-Work is under way to allow more of these subroutines to be called through
-references.
+=head1 Security
 
-=head2 C<__FILE__()> Syntax
+XXX Any security-related notices go here.  In particular, any security
+vulnerabilities closed should be noted here rather than in the
+L</Selected Bug Fixes> section.
 
-The C<__FILE__>, C<__LINE__> and C<__PACKAGE__> tokens can now be written
-with an empty pair of parentheses after them.  This makes them parse the
-same way as C<time>, C<fork> and other built-in functions.
+[ List each security issue as a =head2 entry ]
 
 =head1 Incompatible Changes
 
-=head2 C<UNIVERSAL::VERSION> now returns $VERSION
+XXX For a release on a stable branch, this section aspires to be:
 
-C<UNIVERSAL::VERSION> now return whatever is in $VERSION, instead of
-returning $VERSION converted to a version object and then to a string.
-As a result, it no longer parses the version when called without arguments,
-so it no longer dies in that case for malformed versions.  This allows
-custom version number parsers to use C<< ->VERSION >> to retrieve the
-version number, as was the case in Perl 5.8 [perl #95544].
+    There are no changes intentionally incompatible with 5.XXX.XXX
+    If any exist, they are bugs and reports are welcome.
 
-=head1 Modules and Pragmata
+[ List each incompatible change as a =head2 entry ]
 
-=head2 Updated Modules and Pragmata
+=head1 Deprecations
 
-=over 4
+XXX Any deprecated features, syntax, modules etc. should be listed here.
+In particular, deprecated modules should be listed here even if they are
+listed as an updated module in the L</Modules and Pragmata> section.
 
-=item *
+[ List each deprecation as a =head2 entry ]
 
-L<B> has been upgraded from version 1.30 to version 1.31
+=head1 Performance Enhancements
 
-The XS code has changed slightly, as it was too tightly coupled to
-the contents of the header F<embedvar.h>. Documentation in L<B::Terse>
-and L<B::Xref> has been improved, hence their versions have been increased.
+XXX Changes which enhance performance without changing behaviour go here. There
+may well be none in a stable release.
 
-=item *
+[ List each enhancement as a =item entry ]
 
-L<CPAN> has been upgraded from version 1.9600 to version 1.9800
+=over 4
 
 =item *
 
-L<CPANPLUS> has been upgraded from version 0.9108 to version 0.9109
-
-Fixed support for v-strings and x.y.z versions with v5.8.4
+XXX
 
-=item *
-
-L<CPAN::Meta> has been upgraded from version 2.110930_001 to version 2.112150
+=back
 
-Stringify any objects encountered during conversion.
+=head1 Modules and Pragmata
 
-Clarified that file paths in the 'provides' section must be in
-Unix-style (i.e. forward slashes)
+XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
+go here.  If Module::CoreList is updated, generate an initial draft of the
+following sections using F<Porting/corelist-perldelta.pl>, which prints stub
+entries to STDOUT.  Results can be pasted in place of the '=head2' entries
+below.  A paragraph summary for important changes should then be added by hand.
+In an ideal world, dual-life modules would have a F<Changes> file that could be
+cribbed.
 
-=item *
+[ Within each section, list entries as a =item entry ]
 
-L<DB_File> has been upgraded from version 1.822 to version 1.824
+=head2 New Modules and Pragmata
 
-Will now croak if attempt to freeze/thaw DB_File object [RT #69985]
+=over 4
 
 =item *
 
-L<diagnostics> has been upgraded from version 1.23 to 1.24.
-
-It now supports the %u formatting code.  Previously it was unable to find
-descriptions for messages whose entries in L<perldiag> included that code
-[perl #94988].
+XXX
 
-=item *
+=back
 
-L<Encode> has been upgraded from version 2.43 to version 2.44
+=head2 Updated Modules and Pragmata
 
-Addressed 'decode_xs n-byte heap-overflow' security bug in Unicode.xs
+=over 4
 
 =item *
 
-L<ExtUtils::Install> has been upgraded from version 1.56 to version 1.57.
+L<XXX> has been upgraded from version 0.69 to version 0.70.
 
-There is no change to ExtUtils::Install other than the version number
-increase, but L<ExtUtils::Installed> has been upgraded from version 1.999_001
-to version 1.999002 and a new C<skip_cwd> attribute has been added.
+=back
 
-=item *
+=head2 Removed Modules and Pragmata
 
-L<ExtUtils::MakeMaker> has been upgraded from version 6.58 to version 6.59
+=over 4
 
 =item *
 
-L<ExtUtils::Manifest> has been upgraded from version 1.58 to version 1.60
+XXX
 
-=item *
-
-L<ExtUtils::ParseXS> has been upgraded from 3.00_01 to 3.00_04.
+=back
 
-=item *
+=head1 Documentation
 
-L<IPC::Open3> has been upgraded from version 1.11 to 1.12.
+XXX Changes to files in F<pod/> go here.  Consider grouping entries by
+file and be sure to link to the appropriate page, e.g. L<perlfunc>.
 
-C<open3> with "-" for the program name works once more.  This was broken in
-version 1.06 (and hence in Perl 5.14.0) [perl #95748].
+=head2 New Documentation
 
-=item *
+XXX Changes which create B<new> files in F<pod/> go here.
 
-L<Module::Build> has been upgraded from version 0.3800 to version 0.39_01.
+=head3 L<XXX>
 
-Pod to HTML internals changed to support revisions to Pod::Html in core.
-Also fixes some minor bugs. [rt.cpan.org #68585] [rt.cpan.org #67893]
-[rt.cpan.org #67008]
+XXX Description of the purpose of the new file here
 
-=item *
+=head2 Changes to Existing Documentation
 
-L<Module::CoreList> has been upgraded from version 2.54 to version 2.55
+XXX Changes which significantly change existing files in F<pod/> go here.
+However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
+section.
 
-=item *
+=head3 L<XXX>
 
-L<Module::Load> has been upgraded from version 0.18 to version 0.20
+=over 4
 
 =item *
 
-L<Module::Metadata> has been upgraded from version 1.000004 to version 1.000005
+XXX Description of the change here
 
-Added C<new_from_handle()> method.
+=back
 
-=item *
+=head1 Diagnostics
 
-L<Params::Check> has been upgraded from version 0.28 to version 0.32
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages.  For the complete list of
+diagnostic messages, see L<perldiag>.
 
-=item *
+XXX New or changed warnings emitted by the core's C<C> code go here. Also
+include any changes in L<perldiag> that reconcile it to the C<C> code.
 
-L<PerlIO::via> has been upgraded from version 0.11 to version 0.12.
+[ Within each section, list entries as a =item entry that links to perldiag,
+  e.g.
 
-The only change is a correction in the documentation.
+  =item *
 
-=item *
+  L<Invalid version object|perldiag/"Invalid version object">
+]
 
-L<Term::ANSIColor> has been upgraded from version 3.00 to version 3.01
+=head2 New Diagnostics
 
-Only interpret an initial array reference as a list of colors, not any initial
-reference, allowing the colored function to work properly on objects with
-stringification defined.
+XXX Newly added diagnostic messages go here
 
-=item *
+=head3 New Errors
 
-L<Unicode::Collate> has been upgraded from version 0.77 to version 0.78
+=over 4
 
 =item *
 
-L<Unicode::Normalize> has been upgraded from version 1.12 to version 1.13
+XXX L<message|perldiag/"message">
 
 =back
 
-=head1 Documentation
+=head3 New Warnings
 
-=head2 New Documentation
+=over 4
+
+=item *
 
-=head3 L<perlexperiment>
+XXX L<message|perldiag/"message">
 
-This document is intended to provide a list of experimental features in
-Perl.  It is still a work in progress.
+=back
 
-=head2 Changes to Existing Documentation
+=head2 Changes to Existing Diagnostics
 
-=head3 L<perlsub>
+XXX Changes (i.e. rewording) of diagnostic messages go here
 
 =over 4
 
 =item *
 
-The ($;) prototype syntax, which has existed for rather a long time, is now
-documented in L<perlsub>.  It allows a unary function to have the same
-precedence as a list operator.
+XXX Describe change here
 
 =back
 
-=head1 Diagnostics
+=head1 Utility Changes
 
-The following additions or changes have been made to diagnostic output,
-including warnings and fatal error messages.  For the complete list of
-diagnostic messages, see L<perldiag>.
+XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
+here. Most of these are built within the directories F<utils> and F<x2p>.
 
-=head2 New Diagnostics
+[ List utility changes as a =head3 entry for each utility and =item
+entries for each change
+Use L<XXX> with program names to get proper documentation linking. ]
 
-=head3 New Errors
+=head3 L<XXX>
 
 =over 4
 
 =item *
 
-L<&CORE::%s cannot be called directly|perldiag/"&CORE::%s cannot be called directly">
-
-(F) You tried to call a subroutine in the C<CORE::> namespace
-with C<&foo> syntax or through a reference.  The subroutines
-in this package cannot yet be called that way, but must be
-called as barewords.  Something like this will work:
-
-    BEGIN { *shove = \&CORE::push; }
-    shove @array, 1,2,3; # pushes on to @array
+XXX
 
 =back
 
-=head1 Utility Changes
-
-=head3 L<perlivp>
+=head1 Configuration and Compilation
 
-=over 4
+XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
+go here.  Any other changes to the Perl build process should be listed here.
+However, any platform-specific changes should be listed in the
+L</Platform Support> section, instead.
 
-=item *
+[ List changes as a =item entry ].
 
-Fixed a bug whereby other perls under the current directory could cause
-false positive failures.
+=over 4
 
 =item *
 
-Tests for .ph files have been removed, as these test have been optional since
-2005 and .ph files are no longer generated during installation.
+XXX
 
 =back
 
-=head3 L<splain>
+=head1 Testing
 
-See the entry for C<< diagnostics >> in L</Updated Modules and Pragmata>,
-above.
+XXX Any significant changes to the testing of a freshly built perl should be
+listed here.  Changes which create B<new> files in F<t/> go here as do any
+large changes to the testing harness (e.g. when parallel testing was added).
+Changes to existing files in F<t/> aren't worth summarising, although the bugs
+that they represent may be covered elsewhere.
 
-=head1 Configuration and Compilation
+[ List each test improvement as a =item entry ]
 
 =over 4
 
 =item *
 
-F<makedef.pl> has been refactored. This should have no noticeable affect on
-any of the platforms that use it as part of their build (AIX, VMS, Win32).
-
-=item *
-
-C<useperlio> can no longer be disabled.
+XXX
 
 =back
 
 =head1 Platform Support
 
-=over 4
+XXX Any changes to platform support should be listed in the sections below.
 
-=item HP-UX PA-RISC/64 now supports gcc-4.x
+[ Within the sections, list each platform as a =item entry with specific
+changes as paragraphs below it. ]
 
-A fix to correct the socketsize now makes the test suite pass on HP-UX
-PA-RISC for 64bitall builds.
+=head2 New Platforms
 
-=back
-
-=head1 Internal Changes
+XXX List any platforms that this version of perl compiles on, that previous
+versions did not. These will either be enabled by new files in the F<hints/>
+directories, or new subdirectories and F<README> files at the top level of the
+source tree.
 
 =over 4
 
-=item *
+=item XXX-some-platform
 
-F<embedvar.h> has been simplified, and one level of macro indirection for
-PL_* variables has been removed for the default (non-multiplicity)
-configuration. PERLVAR*() macros now directly expand their arguments to
-tokens such as C<PL_defgv>, instead of expanding to C<PL_Idefgv>, with
-F<embedvar.h> defining a macro to map C<PL_Idefgv> to C<PL_defgv>. XS code
-which has unwarranted chumminess with the implementation may need updating.
+XXX
 
-=item *
+=back
 
-A C<coreargs> opcode has been added, to be used by C<&CORE::foo> subs to sort
-out C<@_>.
+=head2 Discontinued Platforms
 
-=item *
+XXX List any platforms that this version of perl no longer compiles on.
 
-An API has been added to explicitly choose whether or not to export XSUB
-symbols.  More detail can be found in the comments for commit e64345f8.
+=over 4
+
+=item XXX-some-platform
+
+XXX
 
 =back
 
-=head1 Selected Bug Fixes
+=head2 Platform-Specific Notes
+
+XXX List any changes for specific platforms. This could include configuration
+and compilation changes or changes in portability/compatibility.  However,
+changes within modules for platforms should generally be listed in the
+L</Modules and Pragmata> section.
 
 =over 4
 
-=item *
+=item XXX-some-platform
 
-Locking a subroutine (via C<lock &sub>) is no longer a compile-time error
-for regular subs.  For lvalue subroutines, it no longer tries to return the
-sub as a scalar, resulting in strange side effects like C<ref \$_>
-returning "CODE" in some instances.
+XXX
 
-C<lock &sub> is now a run-time error if L<threads::shared> is loaded (a
-no-op otherwise), but that may be rectified in a future version.
+=back
 
-=item *
+=head1 Internal Changes
 
-The prototypes of several built-in functions--C<getprotobynumber>, C<lock>,
-C<not> and C<select>--have been corrected, or at least are now closer to
-reality than before.
+XXX Changes which affect the interface available to C<XS> code go here.
+Other significant internal changes for future core maintainers should
+be noted as well.
 
-=item *
+[ List each change as a =item entry ]
 
-Most dereferencing operators (C<${}>, etc.) used to call C<FETCH> twice on
-a tied operand when doing a symbolic dereference (looking up a variable by
-name, which is not permitted under C<use strict 'refs'>).  Only C<&{}> did
-not have this problem.  This has been fixed.
+=over 4
 
 =item *
 
-A minor regression introduced in 5.15.0 has been fixed.  Dereferencing a
-magical mortal (e.g., the return value of C<delete> on a tied hash element)
-explicitly returned from a subroutine called recursively was not calling
-C<FETCH>.  This would affect code like C<@{ foo() }> where the C<foo> sub
-contains C<return delete $hash{elem}> and is calling itself.
+XXX
 
-=item *
-
-A panic involving the combination of the regular expression modifiers
-C</aa> and the C<\b> escape sequence introduced in 5.14.0 has been
-fixed [perl #95964].
+=back
 
-=item *
+=head1 Selected Bug Fixes
 
-stat() would always return the inode number as an IV, even when the
-original was unsigned, or too large to fit in an IV.  stat() now
-returns the inode number as the type that would best preserve the
-original value. [perl #84590]
+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 *
+[ List each fix as a =item entry ]
 
-The combination of the regular expression modifiers C</aa> and the C<\b>
-and C<\B> escape sequences did not work properly on UTF-8 encoded
-strings.  All non-ASCII characters under C</aa> should be treated as
-non-word characters, but what was happening was that Unicode rules were
-used to determine wordness/non-wordness for non-ASCII characters.  This
-is now fixed [perl #95968].
+=over 4
 
 =item *
 
-Infinite loops like C<1 while 1> used to stop C<strict 'subs'> mode from
-working for the rest of the block.t
+XXX
 
-=item *
+=back
 
-The C<\h>, C<\H>, C<\v> and C<\V> regular expression metacharacters used to
-cause a panic error message when attempting to match at the end of the
-string [perl #96354].
+=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).
 
-For list assignments like C<($a,$b) = ($b,$a)>, Perl has to make a copy of
-the items on the right-hand side before assignment them to the left.  For
-efficiency's sake, it assigns the values on the right straight to the items
-on the left no variable is mentioned on both sides, as in
-C<($a,$b) = ($c,$d)>.  The logic for determining when it can cheat was
-faulty, in that C<&&> and C<||> on the right-hand side could fool it.  So
-C<($a,$b) = $some_true_value && ($b,$a)> would end up assigning the value
-of C<$b> to both scalars.
+This is a list of some significant unfixed bugs, which are regressions
+from either 5.XXX.XXX or 5.XXX.XXX.
 
-=item *
+[ List each fix as a =item entry ]
 
-Perl no longer tries to apply lvalue context to the string in
-C<("string", $variable) ||= 1> (which used to be an error).  Since the
-left-hand side of C<||=> is evaluated in scalar context, that's a scalar
-comma operator, which gives all but the last item void context.  There is
-no such thing as void lvalue context, so it was a mistake for Perl to try
-to force it [perl #96942].
+=over 4
 
 =item *
 
-Every subroutine has a filename associated with it, that the debugger uses.
-The one associated with constant subroutines used to be misallocated when
-cloned under threads.  Consequently, debugging threaded applications could
-result in memory corruption [perl #96126].
+XXX
 
-=item *
+=back
 
-C<caller> no longer leaks memory when called from the DB package if
-C<@DB::args> was assigned to after the first call to C<caller>.  L<Carp>
-was triggering this bug [perl #97010].
+=head1 Obituary
 
-=back
+XXX If any significant core contributor has died, we've added a short obituary
+here.
 
 =head1 Acknowledgements
 
-Perl 5.15.2 represents approximately 2 months of development since Perl
-5.15.1 and contains approximately 17,000 lines of changes across 330
-files from 35 authors.
-
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.15.2:
-
-Abigail, Andreas König, brian d foy, Brian Greenfield, Chas. Owens,
-Chris 'BinGOs' Williams, Craig A. Berry, David Golden, David Mitchell,
-Eric Brine, Father Chrysostomos, Florian Ragwitz, Gerard Goossen,
-H.Merijn Brand, Jesse Vincent, John Peacock, Karl Williamson, Karthik
-Rajagopalan, Keith Thompson, Kevin Ryde, Matthew Horsfall, Mike
-Sheldrake, Nicholas Clark, Niko Tyni, Reini Urban, Ricardo Signes,
-Salvador Fandiño, Shlomi Fish, Spiros Denaxas, Steffen Müller, Stephen
-Oberholtzer, Steve Hay, Tony Cook, Vincent Pit, Zefram.
-
-The list above is almost certainly incomplete as it is automatically
-generated from version control history. In particular, it does not
-include the names of the (very much appreciated) contributors who
-reported issues to the Perl bug tracker.
-
-Many of the changes included in this version originated in the CPAN
-modules included in Perl's core. We're grateful to the entire CPAN
-community for helping Perl to flourish.
-
-For a more complete list of all of Perl's historical contributors,
-please see the F<AUTHORS> file in the Perl source distribution.
+XXX Generate this with:
+
+  perl Porting/acknowledgements.pl v5.15.2..HEAD
 
 =head1 Reporting Bugs