cvsuser 02/01/31 12:57:32
Modified: P5EEx/Blue/sbin perldocs
Log:
added POD doc and converted to use Getopt::Long
Revision Changes Path
1.6 +139 -34 p5ee/P5EEx/Blue/sbin/perldocs
Index: perldocs
===================================================================
RCS file: /cvs/public/p5ee/P5EEx/Blue/sbin/perldocs,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -w -r1.5 -r1.6
--- perldocs 28 Jan 2002 21:57:43 -0000 1.5
+++ perldocs 31 Jan 2002 20:57:32 -0000 1.6
@@ -1,18 +1,133 @@
#!/usr/local/bin/perl
#############################################################################
-## $Id: perldocs,v 1.5 2002/01/28 21:57:43 spadkins Exp $
+## $Id: perldocs,v 1.6 2002/01/31 20:57:32 spadkins Exp $
#############################################################################
## (c) 2002 Stephen Adkins <[EMAIL PROTECTED]>
## This is free software, available under the same terms as Perl itself.
#############################################################################
+## TODO
+## o separate documents from classes in lower-left frame
+## o separate implemented from non-implemented classes in inheritance tree
+## o add option not to include non-implemented classes in All Classes lists
+## o add header menu to each of the class doc files
+## o implement "Deprecated" list
+## o implement "Use" list
+## o use Template::Toolkit to generate docs (rather than embedded HTML)
+## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+## o allow programmatic access to source code metadata
+## o add concept of a "Distribution" (and "Installation" and "Site")
+## o rewrite to document uncommented code (i.e. all of /usr/local/lib/perl5)
+## o rewrite as OO code that models the source code (tie in with CPAN objects?)
+#############################################################################
-use Date::Format;
+=head1 NAME
+
+perldocs - Perl documentation for multiple "perldoc" files
+
+=head1 SYNOPSIS
+
+ sbin/perldocs -dir=htdocs -docroot=/pub/p5ee/software/htdocs -pmlibdirs=P5EEx
-distname=P5EEx-Blue -version=0.01
+
+=head1 DESCRIPTION
+
+The "perldocs" program is a documentation generator for Perl code.
+It scans a set of Perl source files, pod files, and output html files
+created by pod2html. It augments the html files created by pod2html
+and creates additional cross-reference documentation showing the
+interrelationships of classes, source files, class groups, distributions,
+and installations within the site.
+
+The "perldocs" program is different than the "perldoc" program distributed
+with Perl. The "perldoc" program returns documentation from a single file.
+The "perldocs" program creates documentation which shows the interrelationships
+between files.
+
+=head1 COMMAND USAGE
+
+=head2 Command Line Options
+
+The program is run as
+
+ perldocs [-opt=value]
+
+where any number of options may be given, and the available options are
+"dir", "docroot", "pmlibdirs", "distname", and "version".
+
+ perldocs -dir=htdocs -docroot=/pub/p5ee/software/htdocs -pmlibdirs=P5EEx
-distname=P5EEx-Blue -version=0.01
+
+=head1 DOCUMENTATION USAGE
+
+=head2 Frames and Navigation
+
+The "perldocs" output is inspired by (and similar to) the output of "javadoc".
+
+The standard view is from a web browser using HTML frames.
+Two frames on the left assist in navigation, while the main frame on the right
+displays the body of the documentation.
+
+The upper left frame is called the "classGroupListFrame". It always contains
+a high level index of groups of classes for which documentation is available.
+Selecting a class group will cause the complete list of classes in that
+class group to be shown in the frame below it.
+
+The lower left frame is called the "classGroupFrame". It always contains a
+list of classes from a particular class group. Selecting a class will
+cause the class documentation to be displayed in the main frame to the
+right.
+
+The main frame on the right is called the "classFrame". It may display
+the "Installation Summary", a "Distribution Summary", a "Class Group Summary",
+or a "Class Document" (the augmented output of pod2html).
+
+ +---------------------+-------------------------------------------+
+ | | |
+ | classGroupListFrame | |
+ | | |
+ +---------------------+ |
+ | | classFrame |
+ | | |
+ | classGroupFrame | |
+ | | |
+ | | |
+ +---------------------+-------------------------------------------+
+
+The top of each document that appears in the "classFrame" will contain a
+navigation menu which allows the user to navigate to a related page of
+documentation.
+
+=head1 INTERNALS
+
+=head2 Generated Files
+
+For the overall distribution, the following files are generated.
+
+ index.html # the outer frameset
+ overview-frame.html # list of class groups [classGroupListFrame]
+ allclasses-frame.html # list of classes and docs [classGroupFrame]
+ overview-summary.html # summary of class groups [classFrame]
+ overview-tree.html # inheritance tree [classFrame]
+
+For each Class Group in the Distribution, the following files are generated.
+
+ ${class_group}-frame.html # list of classes and docs [classGroupFrame]
+ ${class_group}-tree.html # inheritance tree [classFrame]
+
+=cut
use strict;
-my ($docroot, $dir, $pmlibdirs, $distname, $version, $datetime);
-my (%data, %source_file);
+use Date::Format;
+use Getopt::Long;
+
+my $dir = "htdocs";
+my $docroot = "";
+my $pmlibdirs = "lib";
+my $distname = "";
+my $version = "";
+my $verbose = 0;
+
+my (%data, %source_file, $datetime);
my %warning = (
"mfiup", "Module file [%s] includes unexpected package [%s]\n",
"mdnh2", "Module file [%s] contains method [%s] documentation not as
'=head2'\n",
@@ -20,6 +135,7 @@
);
{
+ my ($success, $option);
my %opt_descriptions = (
'dir' => "Directory to correct outputted HTML POD documentation",
'docroot' => "Base of URL tree (corresponding to 'dir' in the directory
tree)",
@@ -28,38 +144,23 @@
'pmlibdirs' => "Directories to scan for .pod and .pm source files",
);
- my %opts = (
- 'dir' => "htdocs",
- 'docroot' => "",
+ $success = GetOptions (
+ "dir=s" => \$dir,
+ "docroot=s" => \$docroot,
+ "pmlibdirs=s" => \$pmlibdirs,
+ "distname=s" => \$distname,
+ "version=s" => \$version,
+ "verbose" => \$verbose,
);
- my ($option);
- if ($#ARGV == -1) {
- print STDERR "Usage: $0 [options]\n";
+ if (!$success) {
+ print STDERR "Usage: $0 [-option=value] [-verbose]\n";
foreach $option (sort keys %opt_descriptions) {
- printf STDERR " %-12s %s\n", "$option:",
$opt_descriptions{$option};
+ printf STDERR " -%-12s %s\n", "$option",
$opt_descriptions{$option};
}
exit (1);
}
- my ($arg, $var, $value);
- foreach $arg (@ARGV) {
- if ($arg =~ /^([^=]+)=(.*)/) {
- $var = $1;
- $value = $2;
- }
- else {
- $var = $arg;
- $value = 1;
- }
- $opts{$var} = $value;
- }
-
- $docroot = $opts{docroot};
- $dir = $opts{dir};
- $pmlibdirs = $opts{pmlibdirs};
- $distname = $opts{distname};
- $version = $opts{version};
$datetime = time2str("%C", time());
mkdir("$dir/api", 0777) if ($dir);
@@ -428,8 +529,8 @@
</HEAD>
<FRAMESET cols="20%,80%">
<FRAMESET rows="30%,70%">
-<FRAME src="overview-frame.html" name="packageListFrame">
-<FRAME src="allclasses-frame.html" name="packageFrame">
+<FRAME src="overview-frame.html" name="classGroupListFrame">
+<FRAME src="allclasses-frame.html" name="classGroupFrame">
</FRAMESET>
<FRAME src="overview-summary.html" name="classFrame">
</FRAMESET>
@@ -472,14 +573,14 @@
<TABLE BORDER="0" WIDTH="100%">
<TR>
<TD NOWRAP>
- <FONT CLASS="FrameItemFont"><A HREF="allclasses-frame.html"
TARGET="packageFrame">All Classes</A></FONT><P>
+ <FONT CLASS="FrameItemFont"><A HREF="allclasses-frame.html"
TARGET="classGroupFrame">All Classes</A></FONT><P>
<FONT size="+1" CLASS="FrameHeadingFont">Class Groups</FONT><BR>
EOF
my ($class_group);
foreach $class_group (sort keys %{$data{classgroup}}) {
$html .= <<EOF;
- <FONT CLASS="FrameItemFont"><A HREF="${class_group}-frame.html"
TARGET="packageFrame">$class_group</A></FONT><BR>
+ <FONT CLASS="FrameItemFont"><A HREF="${class_group}-frame.html"
TARGET="classGroupFrame">$class_group</A></FONT><BR>
EOF
&write_class_frame($class_group);
}
@@ -637,10 +738,13 @@
</CENTER>
This document is the API specification for the $distname-$version.
<P>
+
+<!--
<B>See:</B>
<BR>
<A
HREF="#overview_description"><B>Description</B></A>
<P>
+-->
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
@@ -656,7 +760,8 @@
$url = $data{classgroup}{$class_group}{podclass};
if ($url) {
$url =~ s!::!/!g;
- $url = "../${url}.html" . lc("#Class Group: $class_group");
+ #$url = "../${url}.html" . lc("#Class Group: $class_group");
+ $url = "../${url}.html";
$html .= <<EOF;
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="20%"><B><A HREF="$url">$class_group</A></B></TD>
