perldocs2 plan

HI Stephen,

	Your perldocs2 implementation plan looks great.

	I'm looking forward to browsing perl modules and method signatures
with hypertext - across a site - I think this will be great for Perl. 
	
	I'm currently working 'part-time' on a Web-based IDE for Perl
which I want to release as open source - I've been lurking a bit and want
to give something back.

	I'm always trying to work out faster ways to code/test/browse/maintain. 

	I realised a lot of my time was spent switching context between 
browser/shells/error_logs/editors - so one solution is a web-based IDE 
where the HTML documentation drives the editing/browsing/testing/cvs 
process.
	
	It also means I can use it next time I'm at the beach and away 
from my office!  :-)

	So I was all set to write a hypertext documentation system ... but 
perldocs2 will save me re-inventing the wheel ... and I can work on the 
other features editing/testing etc and then integrate it with the output 
from perldocs2.

	I'm expecting to finish these other features in about 3 months -
does this fit roughly with your timetable?

NIge


> 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.
> 
> 
> 

-- 
Nigel Hamilton
Turbo10 Metasearch Engine

email:	[email protected]
tel:	+44 (0) 207 987 5460
fax:	+44 (0) 207 987 5468
________________________________________________________________________________
http://turbo10.com		Search Deeper. Browse Faster.