Update various instructions about the use of Porting/corelist-perldelta.pl

diff --git a/Porting/how_to_write_a_perldelta.pod b/Porting/how_to_write_a_perldelta.pod
index a7bfc4a..7b9e770 100644 (file)
--- a/Porting/how_to_write_a_perldelta.pod
+++ b/Porting/how_to_write_a_perldelta.pod
@@ -126,28 +126,24 @@ source tree.
 
 =item Modules and Pragmata
 
-All changes to installed files in F<ext/> and F<lib/> go here, in a list
-ordered by distribution name. Minimally it should be the module version,
-but it's more useful to the end user to give a paragraph's summary of the
-module's changes. In an ideal world, dual-life modules would have a
-F<Changes> file that could be cribbed.
+All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/> go
+here, in a list ordered by distribution name. Minimally it should be the
+module version, but it's more useful to the end user to give a paragraph's
+summary of the module's changes. In an ideal world, dual-life modules would
+have a F<Changes> file that could be cribbed.
 
 Whilst this section could be built by incrementally working through change
 descriptions applying to files, this is prone to error. It's better to
-collate changes to F<ext/> and F<lib/> by module, and then summarise all
-changes to a module as a group. This can be done by partitioning directories
-within F<ext/> and F<lib/> to a number of people.
-
-B<FIXME> - this could be automated better
+collate changes by module, and then summarise all changes to a module as a
+group.
 
 If Module::CoreList has been updated, then F<Porting/corelist-perldelta.pl>
-will automatically print out several sections if relevant that can be
-pasted into F<perldelta>:
+will automatically update two sections in F<perldelta>:
 
     * New Modules and Pragmata
-    * Pragmata Changes
-    * Updated Modules
-    * Removed Modules and Pragmata
+    * Updated Modules and Pragmata
+
+(Currently, it does not update the Removed Modules and Pragmata section.)
 
 Each section will have stub entries following a template like this:
 
@@ -162,23 +158,10 @@ added by hand.
 A more adventurous enhancement would be to automate grabbing
 the changelogs for dual lived modules. For each of them, grab the relevant
 changes files from CPAN for the old and new versions, and if the old one is
-a strict subset of the new one, splice the extra lines right into the output,
-as a basis for summarising.
+a strict subset of the new one, use the extra lines as a basis for summarising.
 
 (And if not, experiment with using F<git> to get the relevant part of changelog
-for the particular file in core)
-
-These could also be enhanced further by using a Pod parser module to produce
-a parse tree of F<perl${whatever}delta.pod>, and splicing in the updates
-correctly without throwing existing entries away.
-
-If you think that's nuts, take a look at what F<pod/buildtoc> already does to
-splice into existing Makefiles on various platforms:
-
-http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498
-
-Perl is this really powerful language for text manipulation. And fun to
-play with. We need to get that message out. :-)
+for the particular file in core.)
 
 =item Utility Changes
 

diff --git a/Porting/perl5200delta.pod b/Porting/perl5200delta.pod
index 864a4b6..f4350aa 100644 (file)
--- a/Porting/perl5200delta.pod
+++ b/Porting/perl5200delta.pod
@@ -95,11 +95,9 @@ XXX
 
 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.
+following sections using F<Porting/corelist-perldelta.pl>.  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.
 
 [ Within each section, list entries as a =item entry ]
 

diff --git a/Porting/perldelta_template.pod b/Porting/perldelta_template.pod
index bb48abe..ca762fa 100644 (file)
--- a/Porting/perldelta_template.pod
+++ b/Porting/perldelta_template.pod
@@ -95,11 +95,9 @@ XXX
 
 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.
+following sections using F<Porting/corelist-perldelta.pl>.  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.
 
 [ Within each section, list entries as a =item entry ]
 

diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 37ccf37..c1eeff1 100644 (file)
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -642,7 +642,12 @@ section, which can be generated with something like:
 
   $ perl Porting/acknowledgements.pl v5.15.0..HEAD
 
-Fill in the "Updated Modules" section now that Module::CoreList is updated.
+Fill in the "New/Updated Modules" sections now that Module::CoreList is updated:
+
+  $ ./perl -Ilib Porting/corelist-perldelta.pl --mode=update pod/perldelta.pod
+
+Ideally, also fill in a summary of the major changes to each module for which
+an entry has been added by F<corelist-perldelta.pl>.
 
 Re-read the perldelta to try to find any embarrassing typos and thinkos;
 remove any C<TODO> or C<XXX> flags; update the "Known Problems" section

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 108c6a7..b8f7c5a 100644 (file)
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -117,11 +117,9 @@ XXX
 
 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.
+following sections using F<Porting/corelist-perldelta.pl>.  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.
 
 [ Within each section, list entries as a =item entry ]