NAME
Pod::POM::Web - HTML Perldoc server
DESCRIPTION
Pod::POM::Web is a Web application for browsing the documentation of Perl components installed on your local machine. Since pages are dynamically generated, they are always in sync with code actually installed.
The application offers
a tree view for browsing through installed modules (with dynamic expansion of branches as they are visited)
a tree view for navigating and opening / closing sections while visiting a documentation page
a source code view with syntax coloring (this is an optional feature -- see section "Optional features")
direct access to perlfunc entries (builtin Perl functions)
search through perlfaq headers
fulltext search, including names of Perl variables (this is an optional feature -- see section "Optional features").
parsing and display of version number
display if and when the displayed module entered Perl core.
parsing pod links and translating them into hypertext links
links to CPAN sites
The DHTML code for navigating through documentation trees requires a modern browser. So far it has been tested on Microsoft Internet Explorer 6.0 and Firefox 2.0
USAGE
Usage is described in a separate document Pod::POM::Web::Help.
INSTALLATION
Starting the Web application
Once the code is installed (most probably through CPAN or CPANPLUS), you have to configure the web server :
As a mod_perl service
The recommended way to run this application is within a mod_perl environment. If you have Apache2 with mod_perl 2.0, then edit your perl.conf as follows :
<Location /perldoc>
SetHandler modperl
PerlResponseHandler Pod::POM::Web->handler
</Location>Then navigate to URL http://localhost/perldoc.
As a cgi-bin script
Alternatively, you can run this application as a cgi-script by writing a simple file in your cgi-bin directory, like this :
#!/path/to/perl
use Pod::POM::Web;
Pod::POM::Web->handler;The same can be done for running under mod_perl Registry (write the same script as above and put it in your Apache/perl directory). However, this does not make much sense, because if you have mod_perl Registry then you could as well run it as a basic mod_perl handler.
As a standalone server
A third way to use this application is to start a process invoking the builtin HTTP server :
perl -MPod::POM::Web -e "Pod::POM::Web->server"This is useful if you have no other HTTP server, or if you want to run this module under the perl debugger.
Note about static files
The application needs some static DHTML resources (style sheets, javascript code, images). These are served dynamically by the module, under the lib URL; but of course is it more efficient to tell Apache to serve these files directly, by putting an alias to the perl/site/lib/Pod/POM/Web/lib directory.
Note about security
This application is intented as a power tool for Perl developers, not as an Internet application. It will display the documentation and source code of any module installed under your @INC path or Apache lib/perl directory, so it is probably a bad idea to put it on a public Internet server.
Optional features
Syntax coloring
Syntax coloring improves readability of code excerpts. If your Perl distribution is from ActiveState, then Pod::POM::Web will take advantage of the ActiveState::Scineplex module which is already installed on your system. Otherwise, you need to install PPI::HTML, available from CPAN.
Fulltext indexing
Pod::POM::Web can index the documentation and source code of all your installed modules, including Perl variable names, Names:::Of::Modules, etc. To use this feature you need to
install Search::Indexer from CPAN
build the index as described in Pod::POM::Web::Indexer documentation.
ACKNOWLEDGEMENTS
This web application was deeply inspired by :
the structure of HTML Perl documentation released with ActivePerl (http://www.activeperl.com/ASPN/Perl).
the tree navigation in Microsoft's MSDN Web site.
the standalone HTTP server implemented in Pod::WebServer.
the wide possibilities of Andy Wardley's Pod::POM parser.
Thanks to BooK and CDolan for useful suggestions/patches.
BUGS
Please report any bugs or feature requests to bug-pod-pom-web at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pod-POM-Web. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
AUTHOR
Laurent Dami, <laurent.d...@justice.ge.ch>
COPYRIGHT & LICENSE
Copyright 2007 Laurent Dami, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
TODO
- tests !
- performance, expiry headers, server-side caching
- also serve Programs (c:/perl/bin)Bugs:
- display in perlre (<a...)
- declare bugs
- SQL::Abstract, nonempty line #337
- LWP: item without '*'