Place repeated hard-coded strings into variables

Call Porting/pod_rules.pl with verbose output.

Simplify syntax per suggestion from rjbs

Note one small bug; clarify how to test program

Improve verbose output

Eliminate command-line switch '--abstract'

Use Module::Metadata to parse new POD file for abstract.

Per suggestions from rjbs, Grinnz and LeonT in ticket.

1 files changed, 36 insertions, 33 deletions

diff --git a/Porting/add-pod-file b/Porting/add-pod-file
index 24b718544b..65060cc1ad 100644
--- a/Porting/add-pod-file
+++ b/Porting/add-pod-file
@@ -4,6 +4,7 @@ use warnings;
 use Carp;
 use File::Spec;
 use Getopt::Long;
+use Module::Metadata;
 require "./Porting/manifest_lib.pl";
 
 =head1 NAME
@@ -16,7 +17,7 @@ After C<make test_prep> has been run, call from top level of Perl 5 core
 distribution:
 
    perl Porting/add-pod-file \
-       --stub=<XXX> --abstract=<YYY> --section=<Z> --verbose
+       --stub=<XXX> --section=<Z> --verbose
 
 =head1 DESCRIPTION
 
@@ -73,18 +74,24 @@ switch C<section>.
 
 =over 4
 
-=item 1 Create a well formatted F<.pod> file somewhere on your system.
+=item 1 Run F<configure> and F<make> in the source tree.
 
-=item 2 Copy it into the source tree under F<pod>.
+=item 2 Create a well formatted F<.pod> file somewhere on your system.
 
-=item 3 Call the program as in L</USAGE> above.
+=item 3 Copy it into the source tree under F<pod>.
 
-=item 4 Call F<git diff> and examine results.
+=item 4 Call the program as in L</USAGE> above.
 
-=item 5 Run F<make test_porting>.
+=item 5 Call F<git diff> and examine results.
+
+=item 6 Run F<make test_porting>.
 
 =back
 
+=head1 BUGS
+
+When the argument provided to the C<--section> command-line switch is C<P> (for platform-specific), F<win32/pod.mak> is not getting updated -- but it's not clear whether it I<ought> to be updated.
+
 =cut
 
 my @man_sections = (
@@ -107,17 +114,14 @@ for (my $i=0; $i<= $#man_sections; $i+=2) {
 my %man_sections_seen = map { $_ => 1 } @man_section_abbrevs;
 my $man_sections = { @man_sections };
 
-my ($stub, $abstract, $section, $verbose) = ('') x 4;
+my ($stub, $section, $verbose) = ('') x 3;
 GetOptions(
     "stub=s"        => \$stub,
-    "abstract=s"    => \$abstract,
     "section=s"     => \$section,
     "verbose"       => \$verbose,
 ) or croak("Error in command line arguments to add-pod-file.pl\n");
 croak "$0: Must provide value for command-line switch 'stub'"
     unless length($stub);
-croak "$0: Must provide value for command-line switch 'abstract'"
-    unless length($abstract);
 croak "$0: Must provide value for command-line switch 'section'"
     unless length($section);
 my $section_croak = "$0: Value for command-line switch must be one of @man_section_abbrevs\n";
@@ -127,19 +131,26 @@ croak $section_croak unless $man_sections_seen{$section};
 my $newpodfile = "$stub.pod";
 my $newpodpath = File::Spec->catfile('pod', $newpodfile);
 croak "Unable to locate new file '$newpodpath'" unless -f $newpodpath;
+my $thispodchecker = File::Spec->catfile(qw|cpan Pod-Checker podchecker|);
+croak "Cannot locate 'podchecker' within this checkout; have you called 'make'?"
+    unless -f $thispodchecker;
 
 say "Step 1: Basic test of validity of POD in $newpodpath" if $verbose;
 
-my $rv;
-system(qq|$^X cpan/Pod-Checker/podchecker $newpodpath|)
-    and croak "$newpodpath has POD errors";
+system(qq|$^X $thispodchecker $newpodpath|)
+    and croak "$newpodpath has POD errors; correct before proceeding further";
+my $data = Module::Metadata->new_from_file($newpodpath, collect_pod => 1, decode_pod => 1);
+
+my ($abstract) = ($data->pod('NAME') // '')  =~ / \A \s+ \S+ \s? - \s? (.+?) \s* \z /x
+    or croak "Could not parse abstract from `=head1 NAME` in $newpodpath";
+
 system(qq|git add $newpodpath|) and croak "Unable to 'git add'";
 
 # Step 2:  Insert entry for $newpodpath into MANIFEST
 
-say "Step 2: Insert entry for $newpodpath into MANIFEST" if $verbose;
-
 my $manifest = 'MANIFEST';
+say "Step 2: Insert entry for $newpodpath into $manifest" if $verbose;
+
 open(my $IN, '<', $manifest)
     or croak "Can't open $manifest for reading";
 my @manifest_orig = <$IN>;
@@ -161,7 +172,7 @@ while (my $l = shift(@manifest_orig)) {
     }
 }
 
-say "Inserting entry for '$newpodpath' into MANIFEST; text will be '$abstract'" if $verbose;
+say "Inserting entry for '$newpodpath' into $manifest; text will be '$abstract'" if $verbose;
 my $new_manifest_entry = "$newpodpath\t\t$abstract";
 my @new_pod = sort_manifest(@pod, $new_manifest_entry);
 
@@ -171,7 +182,9 @@ binmode($OUT);
 say $OUT join("\n", @before_pod, @new_pod, @after_pod);
 close($OUT) or croak "Can't close $manifest after writing";
 
-say "Step 3: Add entry to pod/perl.pod" if $verbose;
+my $perlpod = File::Spec->catfile(qw|pod perl.pod|);
+
+say "Step 3: Add entry to $perlpod" if $verbose;
 
 # Read the existing pod/perl.pod into memory.
 # Divide it into chunks before the selected section, the head2 of the selected
@@ -179,8 +192,6 @@ say "Step 3: Add entry to pod/perl.pod" if $verbose;
 # Add the stub and abstract for the new .pod file to the end of the selected
 # section.  (Manually reposition to taste.)
 
-my $perlpod = "./pod/perl.pod";
-
 open(my $IN1, '<', $perlpod)
     or croak "Can't open $perlpod for reading";
 my $perlpod_str;
@@ -198,18 +209,10 @@ my @balance = split /\n/, $chunks[1];
 shift @balance; # $chunks[1] begins with a newline which we won't need to output
 my (@target_section, @after_section);
 
-my $this = 0;
+my $target = \@target_section;
 for my $l (@balance) {
-    if ($l =~ m/^=(head2|for)/) {
-        push @after_section, $l;
-        $this++;
-    }
-    elsif (! $this) {
-        push @target_section, $l;
-    }
-    else {
-        push @after_section, $l;
-    }
+    $target = \@after_section if $l =~ m/^=(head2|for)/;
+    push @$target, $l;
 }
 
 push @target_section, "    $stub\t\t$abstract";
@@ -222,11 +225,11 @@ say $OUT1 join("\n" => @target_section), "\n";
 say $OUT1 join("\n" => @after_section), "\n";
 close $OUT1 or croak "Can't close $perlpod after writing";
 
-say "Step 4: Running './perl -Ilib Porting/pod_rules.pl --build-podmak' to update win32/pod.mak."
+my $podmak_command = './perl -Ilib Porting/pod_rules.pl --build-podmak --verbose';
+say "Step 4: Running '$podmak_command' to update win32/pod.mak."
     if $verbose;
 
-system(qq|./perl -Ilib Porting/pod_rules.pl --build-podmak|)
-    and croak "Porting/pod_rules.pl --build-podmak failed";
+system($podmak_command) and croak "'$podmak_command' failed";
 
 system(qq|git add MANIFEST pod/perl.pod win32/pod.mak|)
     and croak "Unable to git-add three updated files";