4 use File::Basename qw(&basename &dirname);
7 # List explicitly here the variables you want Configure to
8 # generate. Metaconfig only looks for shell variables, so you
9 # have to mention them as if they were shell variables, not
10 # %Config entries. Thus you write
12 # to ensure Configure will look for $Config{startperl}.
14 # This forces PL files to create target in same directory as PL file.
15 # This is so that make depend always knows where to find PL derivatives.
18 ($file = basename($0)) =~ s/\.PL$//;
19 $file =~ s/\.pl$// if ($^O eq 'os2' or $^O eq 'dos'); # "case-forgiving"
20 $file =~ s/\.pl$/.com/ if ($^O eq 'VMS'); # "case-forgiving"
22 open OUT,">$file" or die "Can't create $file: $!";
24 print "Extracting $file (with variable substitutions)\n";
26 # In this section, perl variables will be expanded during extraction.
27 # You can use $Config{...} to use Configure variables.
29 print OUT <<"!GROK!THIS!";
31 eval 'exec perl -S \$0 "\$@"'
35 # In the following, perl variables are not expanded during extraction.
37 print OUT <<'!NO!SUBS!';
42 # !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
43 # This file is autogenerated by buildtoc.PL.
44 # Edit that file and run it to effect changes.
46 # Builds perltoc.pod and sanity checks the list of pods against all
47 # of the MANIFEST, perl.pod, and ourselves.
54 @PODS = glob("*.pod");
59 die "$0: failed to chdir('pod'): $!\n" unless chdir("pod");
169 for (@ARCHPODS) { s/$/.pod/ }
170 @ARCHPODS{@ARCHPODS} = ();
172 for (@pods) { s/$/.pod/ }
176 open(MANI, "../MANIFEST") || die "$0: opening ../MANIFEST failed: $!";
178 if (m!^pod/([^.]+\.pod)\s+!i) {
183 @MANIPODS{@MANIPODS} = ();
185 open(PERLPOD, "perl.pod") || die "$0: opening perl.pod failed: $!\n";
187 if (/^For ease of access, /../^\(If you're intending /) {
188 if (/^\s+(perl\w*)\s+\w/) {
189 push @PERLPODS, "$1.pod";
194 die "$0: could not find the pod listing of perl.pod\n"
196 @PERLPODS{@PERLPODS} = ();
198 # Cross-check against ourselves
199 # Cross-check against the MANIFEST
200 # Cross-check against the perl.pod
202 foreach my $i (sort keys %PODS) {
203 warn "$0: $i exists but is unknown by buildtoc\n"
204 unless exists $pods{$i};
205 warn "$0: $i exists but is unknown by ../MANIFEST\n"
206 if !exists $MANIPODS{$i} && !exists $ARCHPODS{$i};
207 warn "$0: $i exists but is unknown by perl.pod\n"
208 unless exists $PERLPODS{$i};
210 foreach my $i (sort keys %pods) {
211 warn "$0: $i is known by buildtoc but does not exist\n"
212 unless exists $PODS{$i};
214 foreach my $i (sort keys %MANIPODS) {
215 warn "$0: $i is known by ../MANIFEST but does not exist\n"
216 unless exists $PODS{$i};
218 foreach my $i (sort keys %PERLPODS) {
219 warn "$0: $i is known by perl.pod but does not exist\n"
220 unless exists $PODS{$i};
223 # We are ready to rock.
224 open(OUT, ">perltoc.pod") || die "$0: creating perltoc.pod failed: $!";
229 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
233 perltoc - perl documentation table of contents
237 This page provides a brief table of contents for the rest of the Perl
238 documentation set. It is meant to be scanned quickly or grepped
239 through to locate the proper section you're looking for.
241 =head1 BASIC DOCUMENTATION
248 find \&getpods => qw(../lib ../ext);
252 # Skip .pm files that have corresponding .pod files, and Functions.pm.
253 return if /(.*)\.pm$/ && -f "$1.pod";
254 my $file = $File::Find::name;
255 return if $file eq '../lib/Pod/Functions.pm'; # Used only by pod itself
257 die "tut $name" if $file =~ /TUT/;
258 unless (open (F, "< $_\0")) {
259 warn "bogus <$file>: $!";
260 system "ls", "-l", $file;
264 while ($line = <F>) {
265 if ($line =~ /^=head1\s+NAME\b/) {
266 push @modpods, $file;
267 #warn "GOOD $file\n";
271 warn "$0: $file: cannot find =head1 NAME\n";
276 die "no pods" unless @modpods;
279 #($name) = /(\w+)\.p(m|od)$/;
280 $name = path2modname($_);
281 if ($name =~ /^[a-z]/) {
284 if ($done{$name}++) {
285 # warn "already did $_\n";
289 push @modname, $name;
293 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
297 =head1 PRAGMA DOCUMENTATION
301 podset(sort @pragmata);
303 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
307 =head1 MODULE DOCUMENTATION
311 podset( @modules[ sort { $modname[$a] cmp $modname[$b] } 0 .. $#modules ] );
313 ($_= <<EOPOD2B) =~ s/^\t//gm;
316 =head1 AUXILIARY DOCUMENTATION
318 Here should be listed all the extra programs' documentation, but they
319 don't all have manual pages yet:
345 Larry Wall <F<larry\@wall.org>>, with the help of oodles
351 output "\n"; # flush $LINE
358 if (s/^=head1 (NAME)\s*/=head2 /) {
359 $pod = path2modname($ARGV);
361 output "\n \n\n=head2 ";
363 if ( /^\s*$pod\b/ ) {
364 s/$pod\.pm/$pod/; # '.pm' in NAME !?
372 if (s/^=head1 (.*)/=item $1/) {
374 output "=over\n\n" unless $inhead1;
376 output $_; nl(); next;
378 if (s/^=head2 (.*)/=item $1/) {
380 output "=over\n\n" unless $inhead2;
382 output $_; nl(); next;
384 if (s/^=item ([^=].*)/$1/) {
385 next if $pod eq 'perldiag';
386 s/^\s*\*\s*$// && next;
391 next if $pod eq 'perlmodlib' && /^ftp:/;
392 ##print "=over\n\n" unless $initem;
393 output ", " if $initem;
399 if (s/^=cut\s*\n//) {
418 output "\n\n=back\n\n";
426 output "\n\n=back\n\n";
434 ##print "\n\n=back\n\n";
443 my $NEWLINE; # how many newlines have we seen recently
444 my $LINE; # what remains to be printed
447 for (split /(\n)/, shift) {
450 print OUT wrap('', '', $LINE);
458 elsif (/\S/ && length) {