my thoughts on P5EE documentation

Hi,

Recently, there was a thread of discussion concerning P5EE
documentation.  Here are my thoughts.

My quick "perldocs" script is a good start, but it's main flaw 
is that it works on a single distribution of perl software.

The following is the roadmap for what I plan to do when I get
around to it (if someone doesn't do it first).

I want a command which analyzes all installed perl code, infers what
distributions
each module is in, and creates sitewide, cross-referenced perl doc.
The syntax might be like the following:

Usage: ./perldocs2 [-option=value] [-verbose]
       -dir=<dir>           Directory to put generated HTML POD
documentation in
       -docroot=<url>       Base of URL tree (corresponding to 'dir' in the
directory tree)
       -pmlibdirs=<dirlist> Directories to scan for .pod and .pm source
files in besides @INC
       -installed=<bool>    Scan all directories in @INC to document the
current installation

By default:
   dir=$HOME/public_html/perl
   docroot=http://localhost/~user/perl
   pmlibdirs=
   installed=1

(No doubt, additional options will present themselves during development.)

This generator itself should be downloadable from CPAN separately from the
P5EE distribution.

So I can download the distribution, run "perldocs2", and then 
visit "http://localhost/~user/perl" to see documentation for all 
of the perl modules the administrator has installed on the system
(presumably using CPAN.pm).  It's that easy!

So fundamentally, "perldocs2" is a wrapper around the Pod2HTML stuff.

Then you start getting creative to parse those source files and discern as
much
of the other information that I display in my documentation

   http://www.officevision.com/pub/p5ee/software/htdocs/api/

http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue/Context.html
   http://www.officevision.com/pub/p5ee/software/htdocs/api/overview-tree.html

from *existing sources* without requiring them to do any special extra
documentation tags.

After a while of studying the idioms used in many people's code, I think
you will be able to get quite far on this.  Invariably, the heuristics you
employ to try to determine valid method signatures (etc.) will come up
short and
sometimes be in error.  This is where you let the specially formatted POD tags
(such as I have used) allow the code author to override the (perhaps
mistakenly) implied metadata with explicit metadata.

Furthermore, I would create a page showing documentation compliance 
metrics for each distribution.  This scoring system could be used to focus 
efforts on which distributions/modules needed more documentation work.

Furthermore, some people seem to want the metadata written to some easily
parsable file (Data::Dumper output to perl?) so that they can examine it
at runtime.  I might do that too.

Once this is done, I would work with the people at "www.perldoc.com" or
perhaps CPAN to run it on all of CPAN.  When the fruits of a perl module
author's documentation efforts are in full view of the world
(particularly in the form of documentation compliance metrics),
it will be easier to work on raising the quality of the documentation 
itself.

So that's what I would do.
Feel free to do this or something else.

Stephen

P.S. Whether you use other people's modules or not, I don't care.
Do what is easiest for you.