new perldelta

10 files changed, 719 insertions, 320 deletions

diff --git a/MANIFEST b/MANIFEST
index ff1056a4c5..18088ca8e2 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4636,6 +4636,7 @@ pod/perl5142delta.pod		Perl changes in version 5.14.2
 pod/perl5160delta.pod		Perl changes in version 5.16.0
 pod/perl5170delta.pod		Perl changes in version 5.17.0
 pod/perl5171delta.pod		Perl changes in version 5.17.1
+pod/perl5172delta.pod		Perl changes in version 5.17.2
 pod/perl561delta.pod		Perl changes in version 5.6.1
 pod/perl56delta.pod		Perl changes in version 5.6
 pod/perl581delta.pod		Perl changes in version 5.8.1
diff --git a/Makefile.SH b/Makefile.SH
index b7b2970ad4..3b6e1497c0 100755
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -482,7 +482,7 @@ mini_obj = $(minindt_obj) $(MINIDTRACE_O)
 ndt_obj = $(obj0) $(obj1) $(obj2) $(obj3) $(ARCHOBJS)
 obj = $(ndt_obj) $(DTRACE_O)
 
-perltoc_pod_prereqs = extra.pods pod/perl5172delta.pod pod/perlapi.pod pod/perlintern.pod pod/perlmodlib.pod pod/perluniprops.pod
+perltoc_pod_prereqs = extra.pods pod/perl5173delta.pod pod/perlapi.pod pod/perlintern.pod pod/perlmodlib.pod pod/perluniprops.pod
 generated_pods = pod/perltoc.pod $(perltoc_pod_prereqs)
 generated_headers = uudmap.h bitcount.h mg_data.h
 
@@ -1058,8 +1058,8 @@ pod/perlintern.pod: $(MINIPERL_EXE) autodoc.pl embed.fnc
 pod/perlmodlib.pod: $(MINIPERL_EXE) pod/perlmodlib.PL MANIFEST
 	$(MINIPERL) $(Icwd) pod/perlmodlib.PL -q
 
-pod/perl5172delta.pod: pod/perldelta.pod
-	$(LNS) perldelta.pod pod/perl5172delta.pod
+pod/perl5173delta.pod: pod/perldelta.pod
+	$(LNS) perldelta.pod pod/perl5173delta.pod
 
 extra.pods: $(MINIPERL_EXE)
 	-@test ! -f extra.pods || rm -f `cat extra.pods`
diff --git a/pod/.gitignore b/pod/.gitignore
index 7fc4866fed..6e7aaf9fde 100644
--- a/pod/.gitignore
+++ b/pod/.gitignore
@@ -59,7 +59,7 @@
 /roffitall
 
 # generated
-/perl5172delta.pod
+/perl5173delta.pod
 /perlapi.pod
 /perlintern.pod
 *.html
diff --git a/pod/perl.pod b/pod/perl.pod
index 84efb384c3..f5bcf3eb50 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -177,6 +177,7 @@ aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
 
     perlhist		Perl history records
     perldelta		Perl changes since previous version
+    perl5172delta	Perl changes in version 5.17.2
     perl5171delta	Perl changes in version 5.17.1
     perl5170delta	Perl changes in version 5.17.0
     perl5160delta	Perl changes in version 5.16.0
diff --git a/pod/perl5172delta.pod b/pod/perl5172delta.pod
new file mode 100644
index 0000000000..ed2a29c543
--- /dev/null
+++ b/pod/perl5172delta.pod
@@ -0,0 +1,525 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5172delta - what is new for perl v5.17.2
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.17.1 release and
+the 5.17.2 release.
+
+If you are upgrading from an earlier release such as 5.17.0, first read
+L<perl5171delta>, which describes differences between 5.17.0 and
+5.17.1.
+
+=head1 Core Enhancements
+
+=head2 C<kill> with negative signal names
+
+C<kill> has always allowed a negative signal number, which kills the
+process group instead of a single process.  It has also allowed signal
+names.  But it did not behave consistently, because negative signal names
+were treated as 0.  Now negative signals names like C<-INT> are supported
+and treated the same way as -2 [perl #112990].
+
+=head2 C<pack> is now constant folded.
+
+C<pack> with constant arguments is now constant folded in most cases
+[perl #113470].
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<File::stat> has been upgraded from version 1.06 to 1.07.
+
+Previously C<File::stat>'s overloaded C<-x> and C<-X> operators did not give
+the correct results for directories or executable files when running as
+root. They had been treating executable permissions for root just like for
+any other user, performing group membership tests I<etc> for files not owned
+by root. They now follow the correct Unix behaviour - for a directory they
+are always true, and for a file if any of the three execute permission bits
+are set then they report that root can execute the file. Perl's builtin
+C<-x> and C<-X> operators have always been correct.
+
+=item *
+
+L<Tie::StdHandle> has been upgraded from version 4.2 to 4.3.
+
+C<READ> now respects the offset argument to C<read> [perl #112826].
+
+=item *
+
+L<IO> has been upgraded from version 1.25_07 to 1.25_08.
+
+L<IO::Socket> tries harder to cache or otherwise fetch socket
+information.
+
+=item *
+
+L<Storable> has been upgraded from version 2.36 to 2.37.
+
+Restricted hashes were not always thawed correctly [perl #73972].
+
+Storable would croak when freezing a blessed REF object with a
+C<STORABLE_freeze()> method [perl #113880].
+
+=item *
+
+L<Socket> has been upgraded from version 2.001 to 2.002.
+
+=item *
+
+L<autodie> has been upgraded from version 2.11 to 2.12.
+
+C<autodie> now plays nicely with the 'open' pragma.
+
+=item *
+
+L<File::Fetch> has been upgraded from version 0.34 to 0.36.
+
+Added the 'file_default' option for URLs that do not have a file
+component.
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.68 to 2.69.
+
+=back
+
+=head1 Documentation
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perlfunc>
+
+=over 4
+
+=item *
+
+Clarified documentation of C<our>.
+
+=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<Group name must start with a non-digit word character in regex; marked by <-- HERE in mE<sol>%sE<sol>|perldiag/"Group name must start with a non-digit word character in regex; marked by <-- HERE in m/%s/">
+
+This error has been added for C<(?&0)>, which is invalid.  It used to
+produce an incomprehensible error message [perl #101666].
+
+=item *
+
+L<Can't use an undefined value as a subroutine reference|perldiag/"Can't use an undefined value as %s reference">
+
+Calling an undefined value as a subroutine now produces this error message.
+It used to, but was accidentally disabled, first in Perl 5.004 for
+non-magical variables, and then in Perl 5.14 for magical (e.g., tied)
+variables.  It has now been restored.  In the mean time, undef was treated
+as an empty string [perl #113576].
+
+=back
+
+=head3 New Warnings
+
+=over 4
+
+=item *
+
+"L<Invalid negative number (%s) in chr|perldiag/"Invalid negative number (%s) in chr">"
+
+C<chr()> now warns when passed a negative value [perl #83048].
+
+=item *
+
+"L<Integer overflow in srand|perldiag/"Integer overflow in srand">"
+
+C<srand()> now warns when passed a value that doesn't fit in a C<UV> (since the
+value will be truncated rather than overflowing) [perl #40605].
+
+=item *
+
+"L<-i used with no filenames on the command line, reading from STDIN|perldiag/"-i used with no filenames on the command line, reading from STDIN">"
+
+Running perl with the C<-i> flag now warns if no input files are provided on
+the command line [perl #113410].
+
+=back
+
+=head2 Changes to Existing Diagnostics
+
+=over 4
+
+=item *
+
+The 'Can't use "my %s" in sort comparison' error has been downgraded to a
+warning, '"my %s" used in sort comparison' (with 'state' instead of 'my'
+for state variables).  In addition, the heuristics for guessing whether
+lexical $a or $b has been misused have been improved to generate fewer
+false positives.  Lexical $a and $b are no longer disallowed if they are
+outside the sort block.  Also, a named unary or list operator inside the
+sort block no longer causes the $a or $b to be ignored [perl #86136].
+
+=back
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item *
+
+Building perl with some Windows compilers used to fail due to a problem
+with miniperl's C<glob> operator (which uses the C<perlglob> program)
+deleting the PATH environment variable [perl #113798].
+
+=back
+
+=head1 Platform Support
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item VMS
+
+Quotes are now removed from the command verb (but not the parameters) for commands
+spawned via C<system>, backticks, or a piped C<open>.  Previously, quotes on the verb 
+were passed through to DCL, which would fail to recognize the command.  Also, if the
+verb is actually a path to an image or command procedure on an ODS-5 volume, quoting it
+now allows the path to contain spaces.
+
+=item AIX
+
+Configure now always adds C<-qlanglvl=extc99> to the CC flags on AIX when
+using xlC.  This will make it easier to compile a number of XS-based modules
+that assume C99 [perl #113778].
+
+=back
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+Perl used to implement get magic in a way that would sometimes hide bugs in
+code could call mg_get() too many times on magical values.  This hiding of
+errors no longer occurs, so long-standing bugs may become visible now.  If
+you see magic-related errors in XS code, check to make sure it, together
+with the Perl API functions it uses, calls mg_get() only once on SvGMAGICAL()
+values.
+
+=item *
+
+OP allocation for CVs now uses a slab allocator.  This simplifies
+memory management for OPs allocated to a CV, so cleaning up after a
+compilation error is simpler and safer [perl #111462][perl #112312].
+
+=item *
+
+PERL_DEBUG_READONLY_OPS has been rewritten to work with the new slab
+allocator, allowing it to catch more violations than before.
+
+=item *
+
+The old slab allocator for ops, which was only enabled for PERL_IMPLICIT_SYS and PERL_DEBUG_READONLY_OPS, has been retired.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+A regression introduced in v5.14.0 has been fixed, in which some calls
+to the C<re> module would clobber C<$_> [perl #113750].
+
+=item *
+
+C<do FILE> now always either sets or clears C<$@>, even when the file can't be
+read. This ensures that testing C<$@> first (as recommended by the
+documentation) always returns the correct result.
+
+=item *
+
+The array iterator used for the C<each @array> construct is now correctly
+reset when C<@array> is cleared (RT #75596). This happens for example when the
+array is globally assigned to, as in C<@array = (...)>, but not when its
+B<values> are assigned to. In terms of the XS API, it means that C<av_clear()>
+will now reset the iterator.
+
+This mirrors the behaviour of the hash iterator when the hash is cleared.
+
+=item *
+
+C<< $class->can >>, C<< $class->isa >>, and C<< $class->DOES >> now return
+correct results, regardless of whether that package referred to by C<$class>
+exists [perl #47113].
+
+=item *
+
+Arriving signals no longer clear C<$@> [perl #45173].
+
+=item *
+
+Allow C<my ()> declarations with an empty variable list [perl #113554].
+
+=item *
+
+During parsing, subs declared after errors no longer leave stubs
+[perl #113712].
+
+=item *
+
+Closures containing no string evals no longer hang on to their containing
+subroutines, allowing variables closed over by outer subroutines to be
+freed when the outer sub is freed, even if the inner sub still exists
+[perl #89544].
+
+=item *
+
+Duplication of in-memory filehandles by opening with a "<&=" or ">&=" mode
+stopped working properly in 5.16.0.  It was causing the new handle to
+reference a different scalar variable.  This has been fixed [perl #113764].
+
+=item *
+
+C<qr//> expressions no longer crash with custom regular expression engines
+that do not set C<offs> at regular expression compilation time
+[perl #112962].
+
+=item *
+
+C<delete local> no longer crashes with certain magical arrays and hashes
+[perl #112966].
+
+=item *
+
+C<local> on elements of certain magical arrays and hashes used not to
+arrange to have the element deleted on scope exit, even if the element did
+not exist before C<local>.
+
+=item *
+
+C<scalar(write)> no longer returns multiple items [perl #73690].
+
+=item *
+
+String to floating point conversions no longer misparse certain strings under
+C<use locale> [perl #109318].
+
+=item *
+
+C<@INC> filters that die no longer leak memory [perl #92252].
+
+=item *
+
+The implementations of overloaded operations are now called in the correct
+context. This allows, among other things, being able to properly override
+C<< <> >> [perl #47119].
+
+=item *
+
+Specifying only the C<fallback> key when calling C<use overload> now behaves
+properly [perl #113010].
+
+=item *
+
+C<< sub foo { my $a = 0; while ($a) { ... } } >> and
+C<< sub foo { while (0) { ... } } >> now return the same thing [perl #73618].
+
+=item *
+
+Fixed the debugger C<l> and C<M> commands, and other debugger
+functionality which was broken in 5.17.0 [perl #113918].
+
+=item *
+
+String negation now behaves the same under C<use integer;> as it does
+without [perl #113012].
+
+=item *
+
+C<chr> now returns the Unicode replacement character (U+FFFD) for -1,
+regardless of the internal representation.  -1 used to wrap if the argument
+was tied or a string internally.
+
+=item *
+
+Using a C<format> after its enclosing sub was freed could crash as of
+perl 5.12.0, if the format referenced lexical variables from the outer sub.
+
+=item *
+
+Using a C<format> after its enclosing sub was undefined could crash as of
+perl 5.10.0, if the format referenced lexical variables from the outer sub.
+
+=item *
+
+Using a C<format> defined inside a closures, which format references
+lexical variables from outside, never really worked unless the C<write>
+call was directly inside the closure.  In 5.10.0 it even started crashing.
+Now the copy of that closure nearest the top of the call stack is used to
+find those variables.
+
+=item *
+
+Formats that close over variables in special blocks no longer crash if a
+stub exists with the same name as the special block before the special
+block is compiled.
+
+=item *
+
+The parser no longer gets confused, treating C<eval foo ()> as a syntax
+error if preceded by C<print;> [perl #16249].
+
+=item *
+
+The return value of C<syscall> is no longer truncated on 64-bit platforms
+[perl #113980].
+
+=item *
+
+Constant folding no longer causes C<print 1 ? FOO : BAR> to print to the
+FOO handle [perl #78064].
+
+=item *
+
+C<do subname> now calls the named subroutine and uses the file name it
+returns, instead of opening a file named "subname".
+
+=item *
+
+Subroutines looked up by rv2cv check hooks (registered by XS modules) are
+now taken into consideration when determining whether C<foo bar> should be
+the sub call C<foo(bar)> or the method call C<< "bar"->foo >>.
+
+=item *
+
+C<CORE::foo::bar> is no longer treated specially, allowing global overrides
+to be called directly via C<CORE::GLOBAL::uc(...)> [perl #113016].
+
+=item *
+
+Calling an undefined sub whose typeglob has been undefined now produces the
+customary "Undefined subroutine called" error, instead of "Not a CODE
+reference".
+
+=item *
+
+Two bugs involving @ISA have been fixed.  C<*ISA = *glob_without_array> and
+C<undef *ISA; @{*ISA}> would prevent future modifications to @ISA from
+updating the internal caches used to look up methods.  The
+*glob_without_array case was a regression from Perl 5.12.
+
+=item *
+
+Regular expression optimisations sometimes caused C<$> with C</m> to
+produce failed or incorrect matches [perl #114068].
+
+=item *
+
+C<__SUB__> now works in a C<sort> block when the enclosing subroutine is
+predeclared with C<sub foo;> syntax [perl #113710].
+
+=item *
+
+Unicode properties only apply to Unicode code points, which leads to
+some subtleties when regular expressions are matched against
+above-Unicode code points.  There is a warning generated to draw your
+attention to this.  However, this warning was being generated
+inappropriately in some cases, such as when a program was being parsed.
+Non-Unicode matches such as C<\w> and C<[:word;]> should not generate the
+warning, as their definitions don't limit them to apply to only Unicode
+code points.  Now the message is only generated when matching against
+C<\p{}> and C<\P{}>.  There remains a bug, [perl #114148], for the very
+few properties in Unicode that match just a single code point.  The
+warning is not generated if they are matched against an above-Unicode
+code point.
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.17.2 represents approximately 4 weeks of development since Perl 5.17.1
+and contains approximately 15,000 lines of changes across 320 files from 34
+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.17.2:
+
+Aristotle Pagaltzis, Brian Fraser, Chip Salzenberg, Chris 'BinGOs' Williams,
+Colin Kuskie, Craig A. Berry, Daniel Dragan, Daniel Perrett, Darin McBride,
+David Golden, David Mitchell, Dominic Hargreaves, E. Choroba, Eric Brine,
+Father Chrysostomos, François Perrad, H.Merijn Brand, Jan Dubois, Jesse
+Luehrs, Karl Williamson, Lukas Mai, Matthew Horsfall, Nicholas Clark, Oleg
+Nesterov, Reini Urban, Ricardo Signes, Robin Barker, Shirakata Kentaro, Shlomi
+Fish, Steve Hay, Tony Cook, Vincent Pit, Walt Mankowski, Yves Orton.
+
+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 edee4d13f1..6238d2c222 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -2,490 +2,358 @@
 
 =head1 NAME
 
-perldelta - what is new for perl v5.17.2
+[ this is a template for a new perldelta file. Any text flagged as
+XXX needs to be processed before release. ]
 
-=head1 DESCRIPTION
-
-This document describes differences between the 5.17.1 release and
-the 5.17.2 release.
-
-If you are upgrading from an earlier release such as 5.17.0, first read
-L<perl5171delta>, which describes differences between 5.17.0 and
-5.17.1.
-
-=head1 Core Enhancements
+perldelta - what is new for perl v5.17.3
 
-=head2 C<kill> with negative signal names
-
-C<kill> has always allowed a negative signal number, which kills the
-process group instead of a single process.  It has also allowed signal
-names.  But it did not behave consistently, because negative signal names
-were treated as 0.  Now negative signals names like C<-INT> are supported
-and treated the same way as -2 [perl #112990].
-
-=head2 C<pack> is now constant folded.
+=head1 DESCRIPTION
 
-C<pack> with constant arguments is now constant folded in most cases
-[perl #113470].
+This document describes differences between the 5.17.2 release and
+the 5.17.3 release.
 
-=head1 Modules and Pragmata
+If you are upgrading from an earlier release such as 5.17.1, first read
+L<perl5172delta>, which describes differences between 5.17.1 and
+5.17.2.
 
-=head2 Updated Modules and Pragmata
+=head1 Notice
 
-=over 4
+XXX Any important notices here
 
-=item *
+=head1 Core Enhancements
 
-L<File::stat> has been upgraded from version 1.06 to 1.07.
+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.
 
-Previously C<File::stat>'s overloaded C<-x> and C<-X> operators did not give
-the correct results for directories or executable files when running as
-root. They had been treating executable permissions for root just like for
-any other user, performing group membership tests I<etc> for files not owned
-by root. They now follow the correct Unix behaviour - for a directory they
-are always true, and for a file if any of the three execute permission bits
-are set then they report that root can execute the file. Perl's builtin
-C<-x> and C<-X> operators have always been correct.
+[ List each enhancement as a =head2 entry ]
 
-=item *
+=head1 Security
 
-L<Tie::StdHandle> has been upgraded from version 4.2 to 4.3.
+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.
 
-C<READ> now respects the offset argument to C<read> [perl #112826].
+[ List each security issue as a =head2 entry ]
 
-=item *
+=head1 Incompatible Changes
 
-L<IO> has been upgraded from version 1.25_07 to 1.25_08.
+XXX For a release on a stable branch, this section aspires to be:
 
-L<IO::Socket> tries harder to cache or otherwise fetch socket
-information.
+    There are no changes intentionally incompatible with 5.XXX.XXX
+    If any exist, they are bugs, and we request that you submit a
+    report.  See L</Reporting Bugs> below.
 
-=item *
+[ List each incompatible change as a =head2 entry ]
 
-L<Storable> has been upgraded from version 2.36 to 2.37.
+=head1 Deprecations
 
-Restricted hashes were not always thawed correctly [perl #73972].
+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.
 
-Storable would croak when freezing a blessed REF object with a
-C<STORABLE_freeze()> method [perl #113880].
+[ List each deprecation as a =head2 entry ]
 
-=item *
+=head1 Performance Enhancements
 
-L<Socket> has been upgraded from version 2.001 to 2.002.
+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<autodie> has been upgraded from version 2.11 to 2.12.
-
-C<autodie> now plays nicely with the 'open' pragma.
-
-=item *
-
-L<File::Fetch> has been upgraded from version 0.34 to 0.36.
-
-Added the 'file_default' option for URLs that do not have a file
-component.
+=over 4
 
 =item *
 
-L<Module::CoreList> has been upgraded from version 2.68 to 2.69.
+XXX
 
 =back
 
-=head1 Documentation
+=head1 Modules and Pragmata
 
-=head2 Changes to Existing Documentation
+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.
 
-=head3 L<perlfunc>
+[ Within each section, list entries as a =item entry ]
+
+=head2 New Modules and Pragmata
 
 =over 4
 
 =item *
 
-Clarified documentation of C<our>.
+XXX
 
 =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
+=head2 Updated Modules and Pragmata
 
 =over 4
 
 =item *
 
-L<Group name must start with a non-digit word character in regex; marked by <-- HERE in mE<sol>%sE<sol>|perldiag/"Group name must start with a non-digit word character in regex; marked by <-- HERE in m/%s/">
-
-This error has been added for C<(?&0)>, which is invalid.  It used to
-produce an incomprehensible error message [perl #101666].
-
-=item *
-
-L<Can't use an undefined value as a subroutine reference|perldiag/"Can't use an undefined value as %s reference">
-
-Calling an undefined value as a subroutine now produces this error message.
-It used to, but was accidentally disabled, first in Perl 5.004 for
-non-magical variables, and then in Perl 5.14 for magical (e.g., tied)
-variables.  It has now been restored.  In the mean time, undef was treated
-as an empty string [perl #113576].
+L<XXX> has been upgraded from version 0.69 to version 0.70.
 
 =back
 
-=head3 New Warnings
+=head2 Removed Modules and Pragmata
 
 =over 4
 
 =item *
 
-"L<Invalid negative number (%s) in chr|perldiag/"Invalid negative number (%s) in chr">"
+XXX
 
-C<chr()> now warns when passed a negative value [perl #83048].
+=back
 
-=item *
+=head1 Documentation
 
-"L<Integer overflow in srand|perldiag/"Integer overflow in srand">"
+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<srand()> now warns when passed a value that doesn't fit in a C<UV> (since the
-value will be truncated rather than overflowing) [perl #40605].
+=head2 New Documentation
 
-=item *
+XXX Changes which create B<new> files in F<pod/> go here.
 
-"L<-i used with no filenames on the command line, reading from STDIN|perldiag/"-i used with no filenames on the command line, reading from STDIN">"
+=head3 L<XXX>
 
-Running perl with the C<-i> flag now warns if no input files are provided on
-the command line [perl #113410].
+XXX Description of the purpose of the new file here
 
-=back
-
-=head2 Changes to Existing Diagnostics
-
-=over 4
+=head2 Changes to Existing Documentation
 
-=item *
+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.
 
-The 'Can't use "my %s" in sort comparison' error has been downgraded to a
-warning, '"my %s" used in sort comparison' (with 'state' instead of 'my'
-for state variables).  In addition, the heuristics for guessing whether
-lexical $a or $b has been misused have been improved to generate fewer
-false positives.  Lexical $a and $b are no longer disallowed if they are
-outside the sort block.  Also, a named unary or list operator inside the
-sort block no longer causes the $a or $b to be ignored [perl #86136].
-
-=back
-
-=head1 Configuration and Compilation
+=head3 L<XXX>
 
 =over 4
 
 =item *
 
-Building perl with some Windows compilers used to fail due to a problem
-with miniperl's C<glob> operator (which uses the C<perlglob> program)
-deleting the PATH environment variable [perl #113798].
+XXX Description of the change here
 
 =back
 
-=head1 Platform Support
+=head1 Diagnostics
 
-=head2 Platform-Specific Notes
+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>.
 
-=over 4
+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.
 
-=item VMS
+[ Within each section, list entries as a =item entry that links to perldiag,
+  e.g.
 
-Quotes are now removed from the command verb (but not the parameters) for commands
-spawned via C<system>, backticks, or a piped C<open>.  Previously, quotes on the verb 
-were passed through to DCL, which would fail to recognize the command.  Also, if the
-verb is actually a path to an image or command procedure on an ODS-5 volume, quoting it
-now allows the path to contain spaces.
+  =item *
 
-=item AIX
+  L<Invalid version object|perldiag/"Invalid version object">
+]
 
-Configure now always adds C<-qlanglvl=extc99> to the CC flags on AIX when
-using xlC.  This will make it easier to compile a number of XS-based modules
-that assume C99 [perl #113778].
+=head2 New Diagnostics
 
-=back
+XXX Newly added diagnostic messages go here
 
-=head1 Internal Changes
+=head3 New Errors
 
 =over 4
 
 =item *
 
-Perl used to implement get magic in a way that would sometimes hide bugs in
-code could call mg_get() too many times on magical values.  This hiding of
-errors no longer occurs, so long-standing bugs may become visible now.  If
-you see magic-related errors in XS code, check to make sure it, together
-with the Perl API functions it uses, calls mg_get() only once on SvGMAGICAL()
-values.
+XXX L<message|perldiag/"message">
 
-=item *
-
-OP allocation for CVs now uses a slab allocator.  This simplifies
-memory management for OPs allocated to a CV, so cleaning up after a
-compilation error is simpler and safer [perl #111462][perl #112312].
+=back
 
-=item *
+=head3 New Warnings
 
-PERL_DEBUG_READONLY_OPS has been rewritten to work with the new slab
-allocator, allowing it to catch more violations than before.
+=over 4
 
 =item *
 
-The old slab allocator for ops, which was only enabled for PERL_IMPLICIT_SYS and PERL_DEBUG_READONLY_OPS, has been retired.
+XXX L<message|perldiag/"message">
 
 =back
 
-=head1 Selected Bug Fixes
+=head2 Changes to Existing Diagnostics
+
+XXX Changes (i.e. rewording) of diagnostic messages go here
 
 =over 4
 
 =item *
 
-A regression introduced in v5.14.0 has been fixed, in which some calls
-to the C<re> module would clobber C<$_> [perl #113750].
+XXX Describe change here
 
-=item *
+=back
 
-C<do FILE> now always either sets or clears C<$@>, even when the file can't be
-read. This ensures that testing C<$@> first (as recommended by the
-documentation) always returns the correct result.
+=head1 Utility Changes
 
-=item *
+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>.
 
-The array iterator used for the C<each @array> construct is now correctly
-reset when C<@array> is cleared (RT #75596). This happens for example when the
-array is globally assigned to, as in C<@array = (...)>, but not when its
-B<values> are assigned to. In terms of the XS API, it means that C<av_clear()>
-will now reset the iterator.
+[ 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. ]
 
-This mirrors the behaviour of the hash iterator when the hash is cleared.
-
-=item *
+=head3 L<XXX>
 
-C<< $class->can >>, C<< $class->isa >>, and C<< $class->DOES >> now return
-correct results, regardless of whether that package referred to by C<$class>
-exists [perl #47113].
+=over 4
 
 =item *
 
-Arriving signals no longer clear C<$@> [perl #45173].
-
-=item *
+XXX
 
-Allow C<my ()> declarations with an empty variable list [perl #113554].
+=back
 
-=item *
+=head1 Configuration and Compilation
 
-During parsing, subs declared after errors no longer leave stubs
-[perl #113712].
+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 ].
 
-Closures containing no string evals no longer hang on to their containing
-subroutines, allowing variables closed over by outer subroutines to be
-freed when the outer sub is freed, even if the inner sub still exists
-[perl #89544].
+=over 4
 
 =item *
 
-Duplication of in-memory filehandles by opening with a "<&=" or ">&=" mode
-stopped working properly in 5.16.0.  It was causing the new handle to
-reference a different scalar variable.  This has been fixed [perl #113764].
+XXX
 
-=item *
-
-C<qr//> expressions no longer crash with custom regular expression engines
-that do not set C<offs> at regular expression compilation time
-[perl #112962].
+=back
 
-=item *
+=head1 Testing
 
-C<delete local> no longer crashes with certain magical arrays and hashes
-[perl #112966].
+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.
 
-=item *
+[ List each test improvement as a =item entry ]
 
-C<local> on elements of certain magical arrays and hashes used not to
-arrange to have the element deleted on scope exit, even if the element did
-not exist before C<local>.
+=over 4
 
 =item *
 
-C<scalar(write)> no longer returns multiple items [perl #73690].
+XXX
 
-=item *
+=back
 
-String to floating point conversions no longer misparse certain strings under
-C<use locale> [perl #109318].
+=head1 Platform Support
 
-=item *
+XXX Any changes to platform support should be listed in the sections below.
 
-C<@INC> filters that die no longer leak memory [perl #92252].
+[ Within the sections, list each platform as a =item entry with specific
+changes as paragraphs below it. ]
 
-=item *
+=head2 New Platforms
 
-The implementations of overloaded operations are now called in the correct
-context. This allows, among other things, being able to properly override
-C<< <> >> [perl #47119].
+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.
 
-=item *
+=over 4
 
-Specifying only the C<fallback> key when calling C<use overload> now behaves
-properly [perl #113010].
+=item XXX-some-platform
 
-=item *
+XXX
 
-C<< sub foo { my $a = 0; while ($a) { ... } } >> and
-C<< sub foo { while (0) { ... } } >> now return the same thing [perl #73618].
+=back
 
-=item *
+=head2 Discontinued Platforms
 
-Fixed the debugger C<l> and C<M> commands, and other debugger
-functionality which was broken in 5.17.0 [perl #113918].
+XXX List any platforms that this version of perl no longer compiles on.
 
-=item *
+=over 4
 
-String negation now behaves the same under C<use integer;> as it does
-without [perl #113012].
+=item XXX-some-platform
 
-=item *
+XXX
 
-C<chr> now returns the Unicode replacement character (U+FFFD) for -1,
-regardless of the internal representation.  -1 used to wrap if the argument
-was tied or a string internally.
+=back
 
-=item *
+=head2 Platform-Specific Notes
 
-Using a C<format> after its enclosing sub was freed could crash as of
-perl 5.12.0, if the format referenced lexical variables from the outer sub.
+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.
 
-=item *
+=over 4
 
-Using a C<format> after its enclosing sub was undefined could crash as of
-perl 5.10.0, if the format referenced lexical variables from the outer sub.
+=item XXX-some-platform
 
-=item *
+XXX
 
-Using a C<format> defined inside a closures, which format references
-lexical variables from outside, never really worked unless the C<write>
-call was directly inside the closure.  In 5.10.0 it even started crashing.
-Now the copy of that closure nearest the top of the call stack is used to
-find those variables.
+=back
 
-=item *
+=head1 Internal Changes
 
-Formats that close over variables in special blocks no longer crash if a
-stub exists with the same name as the special block before the special
-block is compiled.
+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 ]
 
-The parser no longer gets confused, treating C<eval foo ()> as a syntax
-error if preceded by C<print;> [perl #16249].
+=over 4
 
 =item *
 
-The return value of C<syscall> is no longer truncated on 64-bit platforms
-[perl #113980].
+XXX
 
-=item *
+=back
 
-Constant folding no longer causes C<print 1 ? FOO : BAR> to print to the
-FOO handle [perl #78064].
+=head1 Selected Bug Fixes
 
-=item *
+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>.
 
-C<do subname> now calls the named subroutine and uses the file name it
-returns, instead of opening a file named "subname".
+[ List each fix as a =item entry ]
 
-=item *
-
-Subroutines looked up by rv2cv check hooks (registered by XS modules) are
-now taken into consideration when determining whether C<foo bar> should be
-the sub call C<foo(bar)> or the method call C<< "bar"->foo >>.
+=over 4
 
 =item *
 
-C<CORE::foo::bar> is no longer treated specially, allowing global overrides
-to be called directly via C<CORE::GLOBAL::uc(...)> [perl #113016].
-
-=item *
+XXX
 
-Calling an undefined sub whose typeglob has been undefined now produces the
-customary "Undefined subroutine called" error, instead of "Not a CODE
-reference".
+=back
 
-=item *
+=head1 Known Problems
 
-Two bugs involving @ISA have been fixed.  C<*ISA = *glob_without_array> and
-C<undef *ISA; @{*ISA}> would prevent future modifications to @ISA from
-updating the internal caches used to look up methods.  The
-*glob_without_array case was a regression from Perl 5.12.
+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. Unfixed
+platform specific bugs also go here.
 
-=item *
+[ List each fix as a =item entry ]
 
-Regular expression optimisations sometimes caused C<$> with C</m> to
-produce failed or incorrect matches [perl #114068].
+=over 4
 
 =item *
 
-C<__SUB__> now works in a C<sort> block when the enclosing subroutine is
-predeclared with C<sub foo;> syntax [perl #113710].
+XXX
 
-=item *
+=back
 
-Unicode properties only apply to Unicode code points, which leads to
-some subtleties when regular expressions are matched against
-above-Unicode code points.  There is a warning generated to draw your
-attention to this.  However, this warning was being generated
-inappropriately in some cases, such as when a program was being parsed.
-Non-Unicode matches such as C<\w> and C<[:word;]> should not generate the
-warning, as their definitions don't limit them to apply to only Unicode
-code points.  Now the message is only generated when matching against
-C<\p{}> and C<\P{}>.  There remains a bug, [perl #114148], for the very
-few properties in Unicode that match just a single code point.  The
-warning is not generated if they are matched against an above-Unicode
-code point.
+=head1 Obituary
 
-=back
+XXX If any significant core contributor has died, we've added a short obituary
+here.
 
 =head1 Acknowledgements
 
-Perl 5.17.2 represents approximately 4 weeks of development since Perl 5.17.1
-and contains approximately 15,000 lines of changes across 320 files from 34
-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.17.2:
-
-Aristotle Pagaltzis, Brian Fraser, Chip Salzenberg, Chris 'BinGOs' Williams,
-Colin Kuskie, Craig A. Berry, Daniel Dragan, Daniel Perrett, Darin McBride,
-David Golden, David Mitchell, Dominic Hargreaves, E. Choroba, Eric Brine,
-Father Chrysostomos, François Perrad, H.Merijn Brand, Jan Dubois, Jesse
-Luehrs, Karl Williamson, Lukas Mai, Matthew Horsfall, Nicholas Clark, Oleg
-Nesterov, Reini Urban, Ricardo Signes, Robin Barker, Shirakata Kentaro, Shlomi
-Fish, Steve Hay, Tony Cook, Vincent Pit, Walt Mankowski, Yves Orton.
-
-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.17.2..HEAD
 
 =head1 Reporting Bugs
 
diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template
index 0d09ec5d8c..40671756a8 100644
--- a/vms/descrip_mms.template
+++ b/vms/descrip_mms.template
@@ -326,7 +326,7 @@ x2p : [.x2p]$(DBG)a2p$(E) [.x2p]s2p.com [.x2p]find2perl.com
 extra.pods : miniperl
 	@ @extra_pods.com
 
-PERLDELTA_CURRENT = [.pod]perl5172delta.pod
+PERLDELTA_CURRENT = [.pod]perl5173delta.pod
 
 $(PERLDELTA_CURRENT) : [.pod]perldelta.pod
 	Copy/NoConfirm/Log $(MMS$SOURCE) $(MMS$TARGET)
diff --git a/win32/Makefile b/win32/Makefile
index b8748118bd..765441825e 100644
--- a/win32/Makefile
+++ b/win32/Makefile
@@ -1072,7 +1072,7 @@ utils: $(PERLEXE) $(X2P)
 	copy ..\README.vmesa    ..\pod\perlvmesa.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5172delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5173delta.pod
 	cd ..\win32
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(PERLEXE) $(ICWD) ..\autodoc.pl ..
@@ -1165,7 +1165,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-cd $(PODDIR) && del /f *.html *.bat roffitall \
-	    perl5172delta.pod perlaix.pod perlamiga.pod perlapi.pod \
+	    perl5173delta.pod perlaix.pod perlamiga.pod perlapi.pod \
 	    perlbeos.pod perlbs2000.pod perlce.pod perlcn.pod \
 	    perlcygwin.pod perldgux.pod perldos.pod perlepoc.pod \
 	    perlfreebsd.pod perlhaiku.pod perlhpux.pod perlhurd.pod \
diff --git a/win32/makefile.mk b/win32/makefile.mk
index 077cde26e8..10ca3d31d8 100644
--- a/win32/makefile.mk
+++ b/win32/makefile.mk
@@ -1256,7 +1256,7 @@ utils: $(PERLEXE) $(X2P)
 	copy ..\README.vmesa    ..\pod\perlvmesa.pod
 	copy ..\README.vos      ..\pod\perlvos.pod
 	copy ..\README.win32    ..\pod\perlwin32.pod
-	copy ..\pod\perldelta.pod ..\pod\perl5172delta.pod
+	copy ..\pod\perldelta.pod ..\pod\perl5173delta.pod
 	$(PERLEXE) $(PL2BAT) $(UTILS)
 	$(PERLEXE) $(ICWD) ..\autodoc.pl ..
 	$(PERLEXE) $(ICWD) ..\pod\perlmodlib.pl -q
@@ -1348,7 +1348,7 @@ distclean: realclean
 	-if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
 	-if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
 	-cd $(PODDIR) && del /f *.html *.bat roffitall \
-	    perl5172delta.pod perlaix.pod perlamiga.pod perlapi.pod \
+	    perl5173delta.pod perlaix.pod perlamiga.pod perlapi.pod \
 	    perlbeos.pod perlbs2000.pod perlce.pod perlcn.pod \
 	    perlcygwin.pod perldgux.pod perldos.pod perlepoc.pod \
 	    perlfreebsd.pod perlhaiku.pod perlhpux.pod perlhurd.pod \
diff --git a/win32/pod.mak b/win32/pod.mak
index c6f87d4657..c7a2b1e5ab 100644
--- a/win32/pod.mak
+++ b/win32/pod.mak
@@ -30,6 +30,7 @@ POD = perl.pod	\
 	perl5170delta.pod	\
 	perl5171delta.pod	\
 	perl5172delta.pod	\
+	perl5173delta.pod	\
 	perl561delta.pod	\
 	perl56delta.pod	\
 	perl581delta.pod	\
@@ -151,6 +152,7 @@ MAN = perl.man	\
 	perl5170delta.man	\
 	perl5171delta.man	\
 	perl5172delta.man	\
+	perl5173delta.man	\
 	perl561delta.man	\
 	perl56delta.man	\
 	perl581delta.man	\
@@ -272,6 +274,7 @@ HTML = perl.html	\
 	perl5170delta.html	\
 	perl5171delta.html	\
 	perl5172delta.html	\
+	perl5173delta.html	\
 	perl561delta.html	\
 	perl56delta.html	\
 	perl581delta.html	\
@@ -393,6 +396,7 @@ TEX = perl.tex	\
 	perl5170delta.tex	\
 	perl5171delta.tex	\
 	perl5172delta.tex	\
+	perl5173delta.tex	\
 	perl561delta.tex	\
 	perl56delta.tex	\
 	perl581delta.tex	\