NAME

Apache::Perldoc - mod_perl handler to spooge out HTML perldocs

DESCRIPTION

A simple mod_perl handler to give you Perl documentation on installed modules.

The following configuration should go in your httpd.conf

    <Location /perldoc>
      SetHandler perl-script
      PerlHandler Apache::Perldoc
    </Location>

You can then get documentation for a module Foo::Bar at the URL http://your.server.com/perldoc/Foo::Bar

Note that you can also get the standard Perl documentation with URLs like http://your.server.com/perldoc/perlfunc or just http://your.server.com/perldoc for the main Perl docs.

Finally, you can search for a particular Perl keyword with http://your.server.com/perldoc/f::keyword The 'f' is used by analogy with the -f flag to perldoc.

In addition to Perl modules, you can have Apache::Perldoc convert .pod files to HTML with the following configiration:

    <FilesMatch \.pod$>
      SetHandler perl-script
      PerlHandler Apache::Perldoc
    </FilesMatch>

This has not been extensively tested, but appears to mostly work.

Running under PerlTaintCheck

If you have PerlTaintCheck turned on, then we can't rely on $ENV{PATH} to find perldoc and pod2html. You'll have to specify the full paths to perldoc and pod2html like so:

    <Location /perldoc>
      SetHandler        perl-script
      PerlHandler Apache::Perldoc
      PerlSetVar        PERLDOC  /usr/local/bin/perldoc
      PerlSetVar        POD2HTML /usr/local/bin/pod2html
    </Location>

Specifying your own TMP directory

Apache::Perldoc assumes that it can use /tmp as the temp directory to run from, since pod2html requires a place to put its work files. You can override this with a

    PerlSetVar TMP /my/temp/directory

Author

Rich Bowen <rbowen@ApacheAdmin.com>

http://www.ApacheAdmin.com/

Patches from Andy Lester to make it a little bit more secure.

Caveat

Note that this is EXCEEDINGLY insecure. Run this at your own risk, and only on internal web sites, if you know what's good for you.

If someone would like to make this a little more secure, I would be delighted to apply any patches you would like to provide. This module was written for my own benefit, and put back on CPAN because some folks asked me to.

You have been warned.

Other neat trick - Bookmarklet

If you create a browser bookmark to the following URL, you can highlight the name of a module on web page, then select the bookmark, and go directly to the documentation for that module. Selecting the bookmark without having anything highlighted will result in a pop-up dialog in which you can type a module name.

 javascript:Qr=document.getSelection();if(!Qr){void(Qr=prompt('Module
 name',''))};if(Qr)location.href='http://localhost/perldoc/'+escape(Qr)

Note that that's all one line, split here for display purposes. I know this works in Netscape and Mozilla. Can't vouch for IE.

LICENSE

This code is released under the HJTI license ("Here, Just Take It"), or, if you really want a real license, take your pick of the GPL and the Artistic License. Which is to say, this is release under the same terms as Perl itself.

The author makes no particular claims to ownership, as this is a really obvious idea, and a lot of other people have been doing this for ages. I just appear to be the first to put it on CPAN.

cpanm Apache::Perldoc

perl -MCPAN -e shell
install Apache::Perldoc