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.
46 perltoc - perl documentation table of contents
50 This page provides a brief table of contents for the rest of the Perl
51 documentation set. It is meant to be scanned quickly or grepped
52 through to locate the proper section you're looking for.
54 =head1 BASIC DOCUMENTATION
58 # All the things in the master list that happen to be pod filenames
59 foreach (grep {!$_->[2]{toc_omit}} @{$state->{master}}) {
60 $roffitall .= " \$mandir/$_->[0].1 \\\n";
61 podset($_->[0], $_->[1]);
64 foreach my $type (qw(PRAGMA MODULE)) {
65 ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
69 =head1 $type DOCUMENTATION
73 foreach my $name (sort keys %{$found->{$type}}) {
74 $roffitall .= " \$libdir/$name.3 \\\n";
75 podset($name, $found->{$type}{$name});
82 =head1 AUXILIARY DOCUMENTATION
84 Here should be listed all the extra programs' documentation, but they
85 don't all have manual pages yet:
91 $_ .= join "\n", map {"\t=item $_\n"} @{$state->{aux}};
98 Larry Wall <F<larry\@wall.org>>, with the help of oodles
107 $OUT =~ s/\n\s+\n/\n\n/gs;
108 $OUT =~ s/\n{3,}/\n\n/g;
110 $OUT =~ s/([^\n]+)/wrap('', '', $1)/ge;
112 write_or_die('pod/perltoc.pod', $OUT);
114 write_or_die('pod/roffitall', <<'EOH' . $roffitall . <<'EOT');
117 # Usage: roffitall [-nroff|-psroff|-groff]
119 # Authors: Tom Christiansen, Raphael Manfredi
124 if test -f ../config.sh; then
128 mandir=$installman1dir
129 libdir=$installman3dir
131 test -d $mandir || mandir=/usr/new/man/man1
132 test -d $libdir || libdir=/usr/new/man/man3
135 -nroff) cmd="nroff -man"; ext='txt';;
136 -psroff) cmd="psroff -t"; ext='ps';;
137 -groff) cmd="groff -man"; ext='ps';;
139 echo "Usage: roffitall [-nroff|-psroff|-groff]" >&2
147 | perl -ne 'map { -r && print "$_ " } split'`
149 # Bypass internal shell buffer limit -- can't use case
150 if perl -e '$a = shift; exit($a =~ m|/|)' $toroff; then
151 echo "$me: empty file list -- did you run install?" >&2
155 #psroff -t -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.ps 2>$tmp/PerlTOC.raw
156 #nroff -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.txt 2>$tmp/PerlTOC.nr.raw
158 # First, create the raw data
159 run="$cmd -rC1 -rD1 -rF1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw"
160 echo "$me: running $run"
164 echo "$me: parsing TOC"
165 perl rofftoc $tmp/PerlTOC.$ext.raw > $tmp/PerlTOC.tmp.man
166 run="$cmd $tmp/PerlTOC.tmp.man >$tmp/PerlTOC.$ext"
167 echo "$me: running $run"
170 # Finally, recreate the Doc, without the blank page 0
171 run="$cmd -rC1 -rD1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw"
172 echo "$me: running $run"
174 rm -f $tmp/PerlTOC.tmp.man $tmp/PerlTOC.$ext.raw
175 echo "$me: leaving you with $tmp/PerlDoc.$ext and $tmp/PerlTOC.$ext"
180 # Below are all the auxiliary routines for generating perltoc.pod
182 my ($inhead1, $inhead2, $initem);
185 my ($pod, $file) = @_;
187 open my $fh, '<', $file or my_die "Can't open file '$file' for $pod: $!";
192 if (/^=head1\s+NAME\b/) {
198 unless ($found_pod) {
199 warn "$0: NOTE: cannot find '=head1 NAME' in:\n $file\n" unless $Quiet;
203 seek $fh, 0, 0 or my_die "Can't rewind file '$file': $!";
208 if (s/^=head1 (NAME)\s*/=head2 /) {
210 $OUT .= "\n\n=head2 ";
212 # Remove svn keyword expansions from the Perl FAQ
213 s/ \(\$Revision: \d+ \$\)//g;
214 if ( /^\s*\Q$pod\E\b/ ) {
215 s/$pod\.pm/$pod/; # '.pm' in NAME !?
220 elsif (s/^=head1 (.*)/=item $1/) {
222 $OUT .= "=over 4\n\n" unless $inhead1;
226 elsif (s/^=head2 (.*)/=item $1/) {
228 $OUT .= "=over 4\n\n" unless $inhead2;
232 elsif (s/^=item ([^=].*)/$1/) {
233 next if $pod eq 'perldiag';
234 s/^\s*\*\s*$// && next;
239 next if $pod eq 'perlmodlib' && /^ftp:/;
240 $OUT .= ", " if $initem;
246 unhead1() if /^=cut\s*\n/;
256 $OUT .= "\n\n=back\n\n";
264 $OUT .= "\n\n=back\n\n";
277 # cperl-indent-level: 4
278 # indent-tabs-mode: nil
281 # ex: set ts=8 sts=4 sw=4 et: