From: Raphael Manfredi Date: Tue, 14 Jan 1997 21:16:28 +0000 (+0100) Subject: Full documentation generation patch X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a3270a1d7469cab9221ab0050a0e6695bd0047d8;p=p5sagit%2Fp5-mst-13.2.git Full documentation generation patch I propose the following patch for perl5.004. It automates the generation of the documentation and is derived from the pioneer work of Tom Christiansen, which was sub-documented, unfortunately. It allows one to run 'roffitall' to generate the full manual and table of contents, based on existing installed files only. Next step: automate the maintainance of the roffitall file list, or generate it automatically... Well, the current version should be OK for 5.004. --- diff --git a/pod/parsetoc b/pod/parsetoc new file mode 100644 index 0000000..cbb80ee --- /dev/null +++ b/pod/parsetoc @@ -0,0 +1,66 @@ +# feed this into perl + eval 'exec perl -S $0 ${1+"$@"}' + if $running_under_some_shell; + +# Usage: parsetoc PerlTOC.xxx.raw +# +# Post-processes roffitall output. Called from roffitall to produce +# a formatted table of contents. +# +# Author: Tom Christiansen + +print <<'EOF'; +.de NP +'.sp 0.8i +.tl ''- % -'' +'bp +'sp 0.5i +.tl ''\fB\s+2Perl Table of Contents\s0\fR'' +'sp 0.3i +.. +.wh -1i NP +.af % i +.sp 0.5i +.tl ''\fB\s+5Perl Table of Contents\s0\fR'' +.sp 0.5i +.nf +.na +EOF +while (<>) { + #chomp; + s/Index://; + ($type, $page, $desc) = split ' ', $_, 3; + $desc =~ s/^"(.*)"$/$1/; + if ($type eq 'Title') { + ($name = $desc) =~ s/ .*//; + next; + } elsif ($type eq 'Name') { + #print STDERR $page, "\t", $desc; + print ".ne 5\n"; + print ".in 0\n"; + print ".sp\n"; + print ".ft B\n"; + print "$desc\n"; + print ".ft P\n"; + print ".in 5n\n"; + } elsif ($type eq 'Header') { + print ".br\n", $page, "\t", $desc; + } elsif ($type eq 'Subsection') { + print ".br\n", $page, "\t\t", $desc; + } elsif ($type eq 'Item') { + next if $desc =~ /\\bu/; + next unless $name =~ /POSIX|func/i; + print ".br\n", $page, "\t\t\t", $desc; + } +} +__END__ +Index:Title 1 "PERL 1" +Index:Name 1 "perl - Practical Extraction and Report Language" +Index:Header 1 "NAME" +Index:Header 1 "SYNOPSIS" +Index:Header 2 "DESCRIPTION" +Index:Item 2 "\(bu Many usability enhancements" +Index:Item 2 "\(bu Simplified grammar" +Index:Item 2 "\(bu Lexical scoping" +Index:Item 2 "\(bu Arbitrarily nested data structures" +Index:Item 2 "\(bu Modularity and reusability" diff --git a/pod/roffitall b/pod/roffitall index 3df9386..abc71a6 100755 --- a/pod/roffitall +++ b/pod/roffitall @@ -1,86 +1,171 @@ #!/bin/sh -#psroff -t -man -rC1 -rD1 -rF1 > /tmp/PerlDoc.ps 2>/tmp/PerlTOC.raw \ -nroff -man -rC1 -rD1 -rF1 > /tmp/PerlDoc.txt 2>/tmp/PerlTOC.nr.raw \ - /usr/local/man/man1/perl.1 \ - /usr/local/man/man1/perlnews.1 \ - /usr/local/man/man1/perldata.1 \ - /usr/local/man/man1/perlsyn.1 \ - /usr/local/man/man1/perlop.1 \ - /usr/local/man/man1/perlre.1 \ - /usr/local/man/man1/perlrun.1 \ - /usr/local/man/man1/perllocale.1 \ - /usr/local/man/man1/perlfunc.1 \ - /usr/local/man/man1/perlvar.1 \ - /usr/local/man/man1/perlsub.1 \ - /usr/local/man/man1/perlmod.1 \ - /usr/local/man/man1/perlref.1 \ - /usr/local/man/man1/perldsc.1 \ - /usr/local/man/man1/perllol.1 \ - /usr/local/man/man1/perlobj.1 \ - /usr/local/man/man1/perltie.1 \ - /usr/local/man/man1/perlbot.1 \ - /usr/local/man/man1/perldebug.1 \ - /usr/local/man/man1/perldiag.1 \ - /usr/local/man/man1/perlform.1 \ - /usr/local/man/man1/perlipc.1 \ - /usr/local/man/man1/perlsec.1 \ - /usr/local/man/man1/perltrap.1 \ - /usr/local/man/man1/perlstyle.1 \ - /usr/local/man/man1/perlxs.1 \ - /usr/local/man/man1/perlxstut.1 \ - /usr/local/man/man1/perlguts.1 \ - /usr/local/man/man1/perlcall.1 \ - /usr/local/man/man1/perlembed.1 \ - /usr/local/man/man1/perlpod.1 \ - /usr/local/man/man1/perlbook.1 \ +# +# Usage: roffitall [-nroff|-psroff|-groff] +# +# Authors: Tom Christiansen, Raphael Manfredi + +me=roffitall +tmp=. + +#manroot=/usr/local +#libroot=/usr/local + +manroot=$HOME/usr +libroot=$HOME/usr/lib/perl5 + +case "$1" in +-nroff) cmd="nroff -man"; ext='txt';; +-psroff) cmd="psroff -t"; ext='ps';; +-groff) cmd="groff -man"; ext='ps';; +*) + echo "Usage: roffitall [-nroff|-psroff|-groff]" >&2 + exit 1 + ;; +esac + +toroff=` + echo \ + $manroot/man/man1/perl.1 \ + $manroot/man/man1/perlnews.1 \ + $manroot/man/man1/perldata.1 \ + $manroot/man/man1/perlsyn.1 \ + $manroot/man/man1/perlop.1 \ + $manroot/man/man1/perlre.1 \ + $manroot/man/man1/perlrun.1 \ + $manroot/man/man1/perllocale.1 \ + $manroot/man/man1/perlfunc.1 \ + $manroot/man/man1/perlvar.1 \ + $manroot/man/man1/perlsub.1 \ + $manroot/man/man1/perlmod.1 \ + $manroot/man/man1/perlref.1 \ + $manroot/man/man1/perldsc.1 \ + $manroot/man/man1/perllol.1 \ + $manroot/man/man1/perlobj.1 \ + $manroot/man/man1/perltie.1 \ + $manroot/man/man1/perlbot.1 \ + $manroot/man/man1/perldebug.1 \ + $manroot/man/man1/perldiag.1 \ + $manroot/man/man1/perlform.1 \ + $manroot/man/man1/perlipc.1 \ + $manroot/man/man1/perlsec.1 \ + $manroot/man/man1/perltrap.1 \ + $manroot/man/man1/perlstyle.1 \ + $manroot/man/man1/perlapio.1 \ + $manroot/man/man1/perlxs.1 \ + $manroot/man/man1/perlxstut.1 \ + $manroot/man/man1/perlguts.1 \ + $manroot/man/man1/perlcall.1 \ + $manroot/man/man1/perlembed.1 \ + $manroot/man/man1/perlpod.1 \ + $manroot/man/man1/perlbook.1 \ \ - /usr/local/man/man3/diagnostics.3 \ - /usr/local/man/man3/integer.3 \ - /usr/local/man/man3/less.3 \ - /usr/local/man/man3/lib.3 \ - /usr/local/man/man3/overload.3 \ - /usr/local/man/man3/sigtrap.3 \ - /usr/local/man/man3/strict.3 \ - /usr/local/man/man3/subs.3 \ + $libroot/man/man3/blib.3 \ + $libroot/man/man3/diagnostics.3 \ + $libroot/man/man3/integer.3 \ + $libroot/man/man3/less.3 \ + $libroot/man/man3/lib.3 \ + $libroot/man/man3/localle.3 \ + $libroot/man/man3/overload.3 \ + $libroot/man/man3/sigtrap.3 \ + $libroot/man/man3/strict.3 \ + $libroot/man/man3/subs.3 \ + $libroot/man/man3/vars.3 \ \ - /usr/local/man/man3/AnyDBM_File.3 \ - /usr/local/man/man3/AutoLoader.3 \ - /usr/local/man/man3/AutoSplit.3 \ - /usr/local/man/man3/Benchmark.3 \ - /usr/local/man/man3/Carp.3 \ - /usr/local/man/man3/Config.3 \ - /usr/local/man/man3/Cwd.3 \ - /usr/local/man/man3/DB_File.3 \ - /usr/local/man/man3/Devel::SelfStubber.3 \ - /usr/local/man/man3/DynaLoader.3 \ - /usr/local/man/man3/English.3 \ - /usr/local/man/man3/Env.3 \ - /usr/local/man/man3/Exporter.3 \ - /usr/local/man/man3/ExtUtils::Liblist.3 \ - /usr/local/man/man3/ExtUtils::MakeMaker.3 \ - /usr/local/man/man3/ExtUtils::Manifest.3 \ - /usr/local/man/man3/ExtUtils::Mkbootstrap.3 \ - /usr/local/man/man3/Fcntl.3 \ - /usr/local/man/man3/File::Basename.3 \ - /usr/local/man/man3/File::CheckTree.3 \ - /usr/local/man/man3/File::Find.3 \ - /usr/local/man/man3/FileHandle.3 \ - /usr/local/man/man3/File::Path.3 \ - /usr/local/man/man3/Getopt::Long.3 \ - /usr/local/man/man3/Getopt::Std.3 \ - /usr/local/man/man3/I18N::Collate.3 \ - /usr/local/man/man3/IPC::Open2.3 \ - /usr/local/man/man3/IPC::Open3.3 \ - /usr/local/man/man3/Net::Ping.3 \ - /usr/local/man/man3/POSIX.3 \ - /usr/local/man/man3/Safe.3 \ - /usr/local/man/man3/SelfLoader.3 \ - /usr/local/man/man3/Socket.3 \ - /usr/local/man/man3/Sys::Hostname.3 \ - /usr/local/man/man3/Term::Cap.3 \ - /usr/local/man/man3/Term::Complete.3 \ - /usr/local/man/man3/Test::Harness.3 \ - /usr/local/man/man3/Text::Abbrev.3 \ - /usr/local/man/man3/Text::Soundex.3 \ - /usr/local/man/man3/TieHash.3 \ - /usr/local/man/man3/Time::Local.3 + $libroot/man/man3/AnyDBM_File.3 \ + $libroot/man/man3/AutoLoader.3 \ + $libroot/man/man3/AutoSplit.3 \ + $libroot/man/man3/Benchmark.3 \ + $libroot/man/man3/Carp.3 \ + $libroot/man/man3/Config.3 \ + $libroot/man/man3/Cwd.3 \ + $libroot/man/man3/DB_File.3 \ + $libroot/man/man3/Devel::SelfStubber.3 \ + $libroot/man/man3/DynaLoader.3 \ + $libroot/man/man3/English.3 \ + $libroot/man/man3/Env.3 \ + $libroot/man/man3/Exporter.3 \ + $libroot/man/man3/ExtUtils::Embed.3 \ + $libroot/man/man3/ExtUtils::Install.3 \ + $libroot/man/man3/ExtUtils::Liblist.3 \ + $libroot/man/man3/ExtUtils::MakeMaker.3 \ + $libroot/man/man3/ExtUtils::Manifest.3 \ + $libroot/man/man3/ExtUtils::Mkbootstrap.3 \ + $libroot/man/man3/ExtUtils::Mksymlists.3 \ + $libroot/man/man3/Fatal.3 \ + $libroot/man/man3/Fcntl.3 \ + $libroot/man/man3/File::Basename.3 \ + $libroot/man/man3/File::CheckTree.3 \ + $libroot/man/man3/File::Copy.3 \ + $libroot/man/man3/File::Compare.3 \ + $libroot/man/man3/File::Find.3 \ + $libroot/man/man3/File::Path.3 \ + $libroot/man/man3/File::stat.3 \ + $libroot/man/man3/FileCache.3 \ + $libroot/man/man3/FileHandle.3 \ + $libroot/man/man3/FindBin.3 \ + $libroot/man/man3/Getopt::Long.3 \ + $libroot/man/man3/Getopt::Std.3 \ + $libroot/man/man3/I18N::Collate.3 \ + $libroot/man/man3/IO.3 \ + $libroot/man/man3/IO::File.3 \ + $libroot/man/man3/IO::Handle.3 \ + $libroot/man/man3/IO::Pipe.3 \ + $libroot/man/man3/IO::Seekable.3 \ + $libroot/man/man3/IO::Select.3 \ + $libroot/man/man3/IO::Socket.3 \ + $libroot/man/man3/IPC::Open2.3 \ + $libroot/man/man3/IPC::Open3.3 \ + $libroot/man/man3/Math::BigFloat.3 \ + $libroot/man/man3/Math::BigInt.3 \ + $libroot/man/man3/Math::Complex.3 \ + $libroot/man/man3/Net::Ping.3 \ + $libroot/man/man3/Net::hostent.3 \ + $libroot/man/man3/Net::netent.3 \ + $libroot/man/man3/Net::protoent.3 \ + $libroot/man/man3/Net::servent.3 \ + $libroot/man/man3/Opcode.3 \ + $libroot/man/man3/POSIX.3 \ + $libroot/man/man3/Pod::Text.3 \ + $libroot/man/man3/Safe.3 \ + $libroot/man/man3/Search::Dict.3 \ + $libroot/man/man3/SelectSaver.3 \ + $libroot/man/man3/SelfLoader.3 \ + $libroot/man/man3/Shell.3 \ + $libroot/man/man3/Socket.3 \ + $libroot/man/man3/Symbol.3 \ + $libroot/man/man3/Sys::Hostname.3 \ + $libroot/man/man3/Sys::Syslog.3 \ + $libroot/man/man3/Term::Cap.3 \ + $libroot/man/man3/Term::Complete.3 \ + $libroot/man/man3/Test::Harness.3 \ + $libroot/man/man3/Text::Abbrev.3 \ + $libroot/man/man3/Text::ParseWords.3 \ + $libroot/man/man3/Text::Soundex.3 \ + $libroot/man/man3/Text::Tabs.3 \ + $libroot/man/man3/Tie::Hash.3 \ + $libroot/man/man3/Tie::RefHash.3 \ + $libroot/man/man3/Tie::Scalar.3 \ + $libroot/man/man3/Tie::SubstrHash.3 \ + $libroot/man/man3/Time::Local.3 \ + $libroot/man/man3/Time::gmtime.3 \ + $libroot/man/man3/Time::localtime.3 \ + $libroot/man/man3/Time::tm.3 \ + $libroot/man/man3/UNIVERSAL.3 \ + $libroot/man/man3/User::grent.3 \ + $libroot/man/man3/User::pwent.3 | \ +perl -ne 'map { -r && print "$_ " } split'` + +#psroff -t -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.ps 2>$tmp/PerlTOC.raw +#nroff -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.txt 2>$tmp/PerlTOC.nr.raw + +run="$cmd -rC1 -rD1 -rF1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw" +echo "$me: running $run" +eval $run $toroff +echo "$me: parsing TOC" +./parsetoc $tmp/PerlTOC.$ext.raw > $tmp/PerlTOC.tmp.man +run="$cmd $tmp/PerlTOC.tmp.man >$tmp/PerlTOC.$ext" +echo "$me: running $run" +eval $run +rm -f $tmp/PerlTOC.tmp.man $tmp/PerlTOC.$ext.raw +echo "$me: leaving you with $tmp/PerlDoc.$ext and $tmp/PerlTOC.$ext" +