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");
173 for (@ARCHPODS) { s/$/.pod/ }
174 @ARCHPODS{@ARCHPODS} = ();
176 for (@pods) { s/$/.pod/ }
180 open(MANI, "../MANIFEST") || die "$0: opening ../MANIFEST failed: $!";
182 if (m!^pod/([^.]+\.pod)\s+!i) {
187 @MANIPODS{@MANIPODS} = ();
189 open(PERLPOD, "perl.pod") || die "$0: opening perl.pod failed: $!\n";
191 if (/^For ease of access, /../^\(If you're intending /) {
192 if (/^\s+(perl\S*)\s+\w/) {
193 push @PERLPODS, "$1.pod";
198 die "$0: could not find the pod listing of perl.pod\n"
200 @PERLPODS{@PERLPODS} = ();
202 # Cross-check against ourselves
203 # Cross-check against the MANIFEST
204 # Cross-check against the perl.pod
206 foreach my $i (sort keys %PODS) {
207 warn "$0: $i exists but is unknown by buildtoc\n"
208 unless exists $pods{$i};
209 warn "$0: $i exists but is unknown by ../MANIFEST\n"
210 if !exists $MANIPODS{$i} && !exists $ARCHPODS{$i};
211 warn "$0: $i exists but is unknown by perl.pod\n"
212 unless exists $PERLPODS{$i};
214 foreach my $i (sort keys %pods) {
215 warn "$0: $i is known by buildtoc but does not exist\n"
216 unless exists $PODS{$i};
218 foreach my $i (sort keys %MANIPODS) {
219 warn "$0: $i is known by ../MANIFEST but does not exist\n"
220 unless exists $PODS{$i};
222 foreach my $i (sort keys %PERLPODS) {
223 warn "$0: $i is known by perl.pod but does not exist\n"
224 unless exists $PODS{$i};
227 # We are ready to rock.
228 open(OUT, ">perltoc.pod") || die "$0: creating perltoc.pod failed: $!";
233 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
237 perltoc - perl documentation table of contents
241 This page provides a brief table of contents for the rest of the Perl
242 documentation set. It is meant to be scanned quickly or grepped
243 through to locate the proper section you're looking for.
245 =head1 BASIC DOCUMENTATION
252 find \&getpods => qw(../lib ../ext);
256 # Skip .pm files that have corresponding .pod files, and Functions.pm.
257 return if /(.*)\.pm$/ && -f "$1.pod";
258 my $file = $File::Find::name;
259 return if $file eq '../lib/Pod/Functions.pm'; # Used only by pod itself
261 die "tut $name" if $file =~ /TUT/;
262 unless (open (F, "< $_\0")) {
263 warn "bogus <$file>: $!";
264 system "ls", "-l", $file;
268 while ($line = <F>) {
269 if ($line =~ /^=head1\s+NAME\b/) {
270 push @modpods, $file;
271 #warn "GOOD $file\n";
275 warn "$0: $file: cannot find =head1 NAME\n";
280 die "no pods" unless @modpods;
283 #($name) = /(\w+)\.p(m|od)$/;
284 $name = path2modname($_);
285 if ($name =~ /^[a-z]/) {
288 if ($done{$name}++) {
289 # warn "already did $_\n";
293 push @modname, $name;
297 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
301 =head1 PRAGMA DOCUMENTATION
305 podset(sort @pragmata);
307 ($_= <<EOPOD2B) =~ s/^\t//gm && output($_);
311 =head1 MODULE DOCUMENTATION
315 podset( @modules[ sort { $modname[$a] cmp $modname[$b] } 0 .. $#modules ] );
317 ($_= <<EOPOD2B) =~ s/^\t//gm;
320 =head1 AUXILIARY DOCUMENTATION
322 Here should be listed all the extra programs' documentation, but they
323 don't all have manual pages yet:
349 Larry Wall <F<larry\@wall.org>>, with the help of oodles
355 output "\n"; # flush $LINE
362 if (s/^=head1 (NAME)\s*/=head2 /) {
363 $pod = path2modname($ARGV);
365 output "\n \n\n=head2 ";
367 if ( /^\s*$pod\b/ ) {
368 s/$pod\.pm/$pod/; # '.pm' in NAME !?
376 if (s/^=head1 (.*)/=item $1/) {
378 output "=over\n\n" unless $inhead1;
380 output $_; nl(); next;
382 if (s/^=head2 (.*)/=item $1/) {
384 output "=over\n\n" unless $inhead2;
386 output $_; nl(); next;
388 if (s/^=item ([^=].*)/$1/) {
389 next if $pod eq 'perldiag';
390 s/^\s*\*\s*$// && next;
395 next if $pod eq 'perlmodlib' && /^ftp:/;
396 ##print "=over\n\n" unless $initem;
397 output ", " if $initem;
403 if (s/^=cut\s*\n//) {
422 output "\n\n=back\n\n";
430 output "\n\n=back\n\n";
438 ##print "\n\n=back\n\n";
447 my $NEWLINE; # how many newlines have we seen recently
448 my $LINE; # what remains to be printed
451 for (split /(\n)/, shift) {
454 print OUT wrap('', '', $LINE);
462 elsif (/\S/ && length) {