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 ('q|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, '<:raw', $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";
280 pod/buildtoc - Generate table of contents
284 This program generates a table of contents for the documentation included in the Perl core distribution. This table of contents takes two forms:
288 =item 1 F<pod/perltoc.pod>
290 A file in Perl's Plain Old Documentation (POD) format found in the F<pod/> directory in the core distribution. Once Perl is installed, this file becomes accessible system-wide via C<perldoc perltoc>.
292 =item 2 F<pod/roffitall>
294 A shell script originally written by Tom Christiansen and Raphael Manfredi, also found in the F<pod/> directory, which can be used to translate Perl documentation into F<man> pages.
300 This program will typically B<not> need to be called directly by a user. Rather, it is one of the last commands invoked during C<make test_prep>:
302 ./perl -Ilib -I. -f pod/buildtoc -q
304 The only command-line switch is C<-q|--quiet>, which quiets some non-critical warnings.
306 =head2 Diagnosing Problems
308 This program C<require>s F<Porting/pod_lib.pl> and makes use of several subroutines found in that file: C<get_pod_metadata()> and C<pods_to_install()> in particular. Consequently, any warnings or exceptions you see when this program is running may be being passed through from those subroutines. You may have to (a) examine those subroutines and/or (b) run that program from the command-line to fully understand what is causing such warnings or exceptions.
310 =head2 AUTHORS and MAINTENANCE
312 This program was introduced into the Perl 5 core distribution by Andy Dougherty, based on earlier work by Tom Christiansen. It is maintained by the Perl 5 Porters.
316 # ex: set ts=8 sts=4 sw=4 et: