8 require "./Porting/manifest_lib.pl";
12 add-pod-file - Utility to add new F<pod/*.pod> file to core distribution
16 After C<make test_prep> has been run, call from top level of Perl 5 core
19 perl Porting/add-pod-file \
20 --stub=<XXX> --section=<Z> --verbose
24 This is a program which I<may> be helpful when a committer has to add a new
25 F<*.pod> file in the F<pod/> directory.
29 This program assumes that committer has taken the following steps (in the
34 =item 1 You have run F<make test_prep>.
36 This is to guarantee that all files are properly positioned.
38 =item 2 You have placed a well-formatted F<.pod> file into the F<pod/> directory.
40 In the C<NAME> section of this file there is a single non-blank line which
41 consists of a string in the format C<STUB - ABSTRACT>, where C<STUB> is the
42 basename of the file without the C<.pod> suffix and C<ABSTRACT> is the short
43 description of the file. For example, a new file whose path is
44 F<pod/perlphonypod.pod> must have a C<NAME> section like this:
48 perlphonypod - This is phony POD
52 F<pod/*.pod> files need entries in multiple locations to keep F<make
53 test_porting> happy. This program automates the formulation of I<most> of
54 those entries, but will need some assistance from the committer to work
55 properly. The committer will have to make a reasonable choice as to which
56 section of F<pod/perl.pod> the new F<.pod> file should be listed under.
57 The eligible sections are shown in the following table:
59 Command-Line Value Section in pod/perl.pod
63 R => 'Reference Manual',
64 I => 'Internals and C Language Interface',
67 L => 'Language-Specific',
68 P => 'Platform-Specific',
70 For a first pass, we'll put the new entry at the end of the C<^=head2> section
71 specified by the committer with the single-initial provided for command-line
74 =head2 Testing this program
78 =item 1 Run F<configure> and F<make> in the source tree.
80 =item 2 Create a well formatted F<.pod> file somewhere on your system.
82 =item 3 Copy it into the source tree under F<pod>.
84 =item 4 Call the program as in L</USAGE> above.
86 =item 5 Call F<git diff> and examine results.
88 =item 6 Run F<make test_porting>.
94 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.
101 R => 'Reference Manual',
102 I => 'Internals and C Language Interface',
104 M => 'Miscellaneous',
105 L => 'Language-Specific',
106 P => 'Platform-Specific',
109 my @man_section_abbrevs = ();
110 my $man_sections_str = '';
111 for (my $i=0; $i<= $#man_sections; $i+=2) {
113 push @man_section_abbrevs, $man_sections[$i];
114 $man_sections_str .= "\t$man_sections[$i] => $man_sections[$j]\n";
116 my %man_sections_seen = map { $_ => 1 } @man_section_abbrevs;
117 my $man_sections = { @man_sections };
119 my ($stub, $section, $verbose) = ('') x 3;
122 "section=s" => \$section,
123 "verbose" => \$verbose,
124 ) or croak("Error in command line arguments to add-pod-file.pl\n");
125 croak "$0: Must provide value for command-line switch 'stub'"
126 unless length($stub);
127 croak "$0: Must provide value for command-line switch 'section'"
128 unless length($section);
129 my $section_croak = "$0: Value for command-line switch must be one of @man_section_abbrevs\n";
130 $section_croak .= " Select one initial from:\n$man_sections_str";
131 croak $section_croak unless $man_sections_seen{$section};
133 my $newpodfile = "$stub.pod";
134 my $newpodpath = File::Spec->catfile('pod', $newpodfile);
135 croak "Unable to locate new file '$newpodpath'" unless -f $newpodpath;
136 my $thispodchecker = File::Spec->catfile(qw|cpan Pod-Checker podchecker|);
137 croak "Cannot locate 'podchecker' within this checkout; have you called 'make'?"
138 unless -f $thispodchecker;
140 say "Step 1: Basic test of validity of POD in $newpodpath" if $verbose;
142 system(qq|$^X $thispodchecker $newpodpath|)
143 and croak "$newpodpath has POD errors; correct before proceeding further";
144 my $data = Module::Metadata->new_from_file($newpodpath, collect_pod => 1, decode_pod => 1);
146 my $regex = qr/\A\s*(?:\S+\s+)+?-+\s+(.+?)\s*\z/s;
147 my ($abstract) = ($data->pod('NAME') // '') =~ $regex
148 or croak "Could not parse abstract from `=head1 NAME` in $newpodpath";
150 system(qq|git add $newpodpath|) and croak "Unable to 'git add'";
152 # Step 2: Insert entry for $newpodpath into MANIFEST
154 my $manifest = 'MANIFEST';
155 say "Step 2: Insert entry for $newpodpath into $manifest" if $verbose;
157 open(my $IN, '<', $manifest)
158 or croak "Can't open $manifest for reading";
159 my @manifest_orig = <$IN>;
160 close($IN) or croak "Can't close $manifest after reading";
161 chomp(@manifest_orig);
163 my (@before_pod, @pod, @after_pod);
165 while (my $l = shift(@manifest_orig)) {
166 if (! $seen_pod and $l !~ m{^pod\/}) {
167 push @before_pod, $l;
169 elsif ($l =~ m{^pod\/}) {
178 say "Inserting entry for '$newpodpath' into $manifest; text will be '$abstract'" if $verbose;
179 my $new_manifest_entry = "$newpodpath\t\t$abstract";
180 my @new_pod = sort_manifest(@pod, $new_manifest_entry);
182 open(my $OUT, '>', $manifest)
183 or croak "Can't open $manifest for writing";
185 say $OUT join("\n", @before_pod, @new_pod, @after_pod);
186 close($OUT) or croak "Can't close $manifest after writing";
188 my $perlpod = File::Spec->catfile(qw|pod perl.pod|);
190 say "Step 3: Add entry to $perlpod" if $verbose;
192 # Read the existing pod/perl.pod into memory.
193 # Divide it into chunks before the selected section, the head2 of the selected
194 # section, the selected section, and what comes after the selected section.
195 # Add the stub and abstract for the new .pod file to the end of the selected
196 # section. (Manually reposition to taste.)
198 open(my $IN1, '<', $perlpod)
199 or croak "Can't open $perlpod for reading";
203 $perlpod_str = <$IN1>;
205 close($IN1) or croak "Can't close $perlpod after reading";
207 my $section_head = "=head2 $man_sections->{$section}";
208 my @chunks = split $section_head, $perlpod_str;
209 chomp $chunks[0]; # So we can use 'say' consistently later on
211 my @balance = split /\n/, $chunks[1];
212 shift @balance; # $chunks[1] begins with a newline which we won't need to output
213 my (@target_section, @after_section);
215 my $target = \@target_section;
216 for my $l (@balance) {
217 $target = \@after_section if $l =~ m/^=(head2|for)/;
221 push @target_section, " $stub\t\t$abstract";
223 open(my $OUT1, '>', $perlpod)
224 or croak "Can't open $perlpod for writing";
225 say $OUT1 $chunks[0];
226 say $OUT1 $section_head;
227 say $OUT1 join("\n" => @target_section), "\n";
228 say $OUT1 join("\n" => @after_section), "\n";
229 close $OUT1 or croak "Can't close $perlpod after writing";
231 my $podmak_command = './perl -Ilib Porting/pod_rules.pl --build-podmak --verbose';
232 say "Step 4: Running '$podmak_command' to update win32/pod.mak."
235 system($podmak_command) and croak "'$podmak_command' failed";
237 system(qq|git add MANIFEST pod/perl.pod win32/pod.mak|)
238 and croak "Unable to git-add three updated files";
241 say "Call 'git diff --staged' and inspect modified files; correct as needed.";
242 say "Then run 'make test_porting'.";
243 say "Then say 'git commit'.";