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");
174 for (@ARCHPODS) { s/$/.pod/ }
175 @ARCHPODS{@ARCHPODS} = ();
177 for (@pods) { s/$/.pod/ }
181 open(MANI, "../MANIFEST") || die "$0: opening ../MANIFEST failed: $!";
183 if (m!^pod/([^.]+\.pod)\s+!i) {
188 @MANIPODS{@MANIPODS} = ();
190 open(PERLPOD, "perl.pod") || die "$0: opening perl.pod failed: $!\n";
192 if (/^For ease of access, /../^\(If you're intending /) {
193 if (/^\s+(perl\S*)\s+\w/) {
194 push @PERLPODS, "$1.pod";
199 die "$0: could not find the pod listing of perl.pod\n"
201 @PERLPODS{@PERLPODS} = ();
203 # Cross-check against ourselves
204 # Cross-check against the MANIFEST
205 # Cross-check against the perl.pod
207 foreach my $i (sort keys %PODS) {
208 warn "$0: $i exists but is unknown by buildtoc\n"
209 unless exists $pods{$i};
210 warn "$0: $i exists but is unknown by ../MANIFEST\n"
211 if !exists $MANIPODS{$i} && !exists $ARCHPODS{$i};
212 warn "$0: $i exists but is unknown by perl.pod\n"
213 unless exists $PERLPODS{$i};
215 foreach my $i (sort keys %pods) {
216 warn "$0: $i is known by buildtoc but does not exist\n"
217 unless exists $PODS{$i};
219 foreach my $i (sort keys %MANIPODS) {
220 warn "$0: $i is known by ../MANIFEST but does not exist\n"
221 unless exists $PODS{$i};
223 foreach my $i (sort keys %PERLPODS) {
224 warn "$0: $i is known by perl.pod but does not exist\n"
225 unless exists $PODS{$i};
228 # We are ready to rock.
229 open(OUT, ">perltoc.pod") || die "$0: creating perltoc.pod failed: $!";
234 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
238 perltoc - perl documentation table of contents
242 This page provides a brief table of contents for the rest of the Perl
243 documentation set. It is meant to be scanned quickly or grepped
244 through to locate the proper section you're looking for.
246 =head1 BASIC DOCUMENTATION
253 find \&getpods => qw(../lib ../ext);
257 # Skip .pm files that have corresponding .pod files, and Functions.pm.
258 return if /(.*)\.pm$/ && -f "$1.pod";
259 my $file = $File::Find::name;
260 return if $file eq '../lib/Pod/Functions.pm'; # Used only by pod itself
262 die "tut $name" if $file =~ /TUT/;
263 unless (open (F, "< $_\0")) {
264 warn "bogus <$file>: $!";
265 system "ls", "-l", $file;
269 while ($line = <F>) {
270 if ($line =~ /^=head1\s+NAME\b/) {
271 push @modpods, $file;
272 #warn "GOOD $file\n";
276 warn "$0: $file: cannot find =head1 NAME\n";
281 die "no pods" unless @modpods;
284 #($name) = /(\w+)\.p(m|od)$/;
285 $name = path2modname($_);
286 if ($name =~ /^[a-z]/) {
289 if ($done{$name}++) {
290 # warn "already did $_\n";
294 push @modname, $name;
298 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
302 =head1 PRAGMA DOCUMENTATION
306 podset(sort @pragmata);
308 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
312 =head1 MODULE DOCUMENTATION
316 podset( @modules[ sort { $modname[$a] cmp $modname[$b] } 0 .. $#modules ] );
318 ($_= <<EOPOD2B) =~ s/^\t//gm;
321 =head1 AUXILIARY DOCUMENTATION
323 Here should be listed all the extra programs' documentation, but they
324 don't all have manual pages yet:
350 Larry Wall <F<larry\@wall.org>>, with the help of oodles
356 output "\n"; # flush $LINE
363 if (s/^=head1 (NAME)\s*/=head2 /) {
364 $pod = path2modname($ARGV);
366 output "\n \n\n=head2 ";
368 if ( /^\s*$pod\b/ ) {
369 s/$pod\.pm/$pod/; # '.pm' in NAME !?
377 if (s/^=head1 (.*)/=item $1/) {
379 output "=over\n\n" unless $inhead1;
381 output $_; nl(); next;
383 if (s/^=head2 (.*)/=item $1/) {
385 output "=over\n\n" unless $inhead2;
387 output $_; nl(); next;
389 if (s/^=item ([^=].*)/$1/) {
390 next if $pod eq 'perldiag';
391 s/^\s*\*\s*$// && next;
396 next if $pod eq 'perlmodlib' && /^ftp:/;
397 ##print "=over\n\n" unless $initem;
398 output ", " if $initem;
404 if (s/^=cut\s*\n//) {
423 output "\n\n=back\n\n";
431 output "\n\n=back\n\n";
439 ##print "\n\n=back\n\n";
448 my $NEWLINE; # how many newlines have we seen recently
449 my $LINE; # what remains to be printed
452 for (split /(\n)/, shift) {
455 print OUT wrap('', '', $LINE);
463 elsif (/\S/ && length) {