projects / p5sagit/p5-mst-13.2.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw (parent: 8a1e91d)
Full documentation generation patch
Raphael Manfredi [Tue, 14 Jan 1997 21:16:28 +0000 (22:16 +0100)]
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.

pod/parsetoc [new file with mode: 0644] patch | blob
pod/roffitall patch | blob | blame | history

diff --git a/pod/parsetoc b/pod/parsetoc
new file mode 100644 (file)
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 (executable)
--- 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"
+
Unnamed repository; edit this file to name it for gitweb.