12 # Assumption is that we're either already being run from the top level (*nix,
13 # VMS), or have absolute paths in @INC (Win32, pod/Makefile)
15 my $Top = File::Spec->catdir($FindBin::Bin, File::Spec->updir);
16 chdir $Top or die "Can't chdir to $Top: $!";
17 require 'Porting/pod_lib.pl';
20 die "$0: Usage: $0 [--quiet]\n"
21 unless GetOptions (quiet => \$Quiet) && !@ARGV;
23 my $state = get_pod_metadata(0, sub { warn @_ if @_ }, 'pod/perltoc.pod');
25 my $found = pods_to_install();
27 my_die "Can't find any pods!\n" unless %$found;
29 # Accumulating everything into a lexical before writing to disk dates from the
30 # time when this script also provided the functionality of regen/pod_rules.pl
31 # and this code was in a subroutine do_toc(). In turn, the use of a file scoped
32 # lexical instead of a parameter or return value is because the code dates back
33 # further still, and used *only* to create pod/perltoc.pod by printing direct
38 ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
40 # !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
41 # This file is autogenerated by buildtoc from all the other pods.
42 # Edit those files and run $0 to effect changes.
48 perltoc - perl documentation table of contents
52 This page provides a brief table of contents for the rest of the Perl
53 documentation set. It is meant to be scanned quickly or grepped
54 through to locate the proper section you're looking for.
56 =head1 BASIC DOCUMENTATION
60 # All the things in the master list that happen to be pod filenames
61 foreach (grep {!$_->[2]{toc_omit}} @{$state->{master}}) {
62 $roffitall .= " \$mandir/$_->[0].1 \\\n";
63 podset($_->[0], $_->[1]);
66 foreach my $type (qw(PRAGMA MODULE)) {
67 ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
71 =head1 $type DOCUMENTATION
75 foreach my $name (sort keys %{$found->{$type}}) {
76 $roffitall .= " \$libdir/$name.3 \\\n";
77 podset($name, $found->{$type}{$name});
84 =head1 AUXILIARY DOCUMENTATION
86 Here should be listed all the extra programs' documentation, but they
87 don't all have manual pages yet:
93 $_ .= join "\n", map {"\t=item $_\n"} @{$state->{aux}};
100 Larry Wall <F<larry\@wall.org>>, with the help of oodles
109 $OUT =~ s/\n\s+\n/\n\n/gs;
110 $OUT =~ s/\n{3,}/\n\n/g;
112 $OUT =~ s/([^\n]+)/wrap('', '', $1)/ge;
114 write_or_die('pod/perltoc.pod', $OUT);
116 write_or_die('pod/roffitall', <<'EOH' . $roffitall . <<'EOT');
119 # Usage: roffitall [-nroff|-psroff|-groff]
121 # Authors: Tom Christiansen, Raphael Manfredi
126 if test -f ../config.sh; then
130 mandir=$installman1dir
131 libdir=$installman3dir
133 test -d $mandir || mandir=/usr/new/man/man1
134 test -d $libdir || libdir=/usr/new/man/man3
137 -nroff) cmd="nroff -man"; ext='txt';;
138 -psroff) cmd="psroff -t"; ext='ps';;
139 -groff) cmd="groff -man"; ext='ps';;
141 echo "Usage: roffitall [-nroff|-psroff|-groff]" >&2
149 | perl -ne 'map { -r && print "$_ " } split'`
151 # Bypass internal shell buffer limit -- can't use case
152 if perl -e '$a = shift; exit($a =~ m|/|)' $toroff; then
153 echo "$me: empty file list -- did you run install?" >&2
157 #psroff -t -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.ps 2>$tmp/PerlTOC.raw
158 #nroff -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.txt 2>$tmp/PerlTOC.nr.raw
160 # First, create the raw data
161 run="$cmd -rC1 -rD1 -rF1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw"
162 echo "$me: running $run"
166 echo "$me: parsing TOC"
167 perl rofftoc $tmp/PerlTOC.$ext.raw > $tmp/PerlTOC.tmp.man
168 run="$cmd $tmp/PerlTOC.tmp.man >$tmp/PerlTOC.$ext"
169 echo "$me: running $run"
172 # Finally, recreate the Doc, without the blank page 0
173 run="$cmd -rC1 -rD1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw"
174 echo "$me: running $run"
176 rm -f $tmp/PerlTOC.tmp.man $tmp/PerlTOC.$ext.raw
177 echo "$me: leaving you with $tmp/PerlDoc.$ext and $tmp/PerlTOC.$ext"
182 # Below are all the auxiliary routines for generating perltoc.pod
184 my ($inhead1, $inhead2, $initem);
187 my ($pod, $file) = @_;
189 open my $fh, '<', $file or my_die "Can't open file '$file' for $pod: $!";
194 if (/^=head1\s+NAME\b/) {
200 unless ($found_pod) {
201 warn "$0: NOTE: cannot find '=head1 NAME' in:\n $file\n" unless $Quiet;
205 seek $fh, 0, 0 or my_die "Can't rewind file '$file': $!";
210 if (s/^=head1 (NAME)\s*/=head2 /) {
212 $OUT .= "\n\n=head2 ";
214 # Remove svn keyword expansions from the Perl FAQ
215 s/ \(\$Revision: \d+ \$\)//g;
216 if ( /^\s*\Q$pod\E\b/ ) {
217 s/$pod\.pm/$pod/; # '.pm' in NAME !?
222 elsif (s/^=head1 (.*)/=item $1/) {
224 $OUT .= "=over 4\n\n" unless $inhead1;
228 elsif (s/^=head2 (.*)/=item $1/) {
230 $OUT .= "=over 4\n\n" unless $inhead2;
234 elsif (s/^=item ([^=].*)/$1/) {
235 next if $pod eq 'perldiag';
236 s/^\s*\*\s*$// && next;
241 next if $pod eq 'perlmodlib' && /^ftp:/;
242 $OUT .= ", " if $initem;
248 unhead1() if /^=cut\s*\n/;
258 $OUT .= "\n\n=back\n\n";
266 $OUT .= "\n\n=back\n\n";
279 # cperl-indent-level: 4
280 # indent-tabs-mode: nil
283 # ex: set ts=8 sts=4 sw=4 et: