view release on metacpan or  search on metacpan

lib/Apache/Perldoc.pm  view on Meta::CPAN

package Apache::Perldoc;
use vars qw( $VERSION );
$VERSION = qw($Revision: 1.11 $)[1];

sub handler {
    my $r = shift;
    $r->content_type('text/html');
    $r->send_http_header;

    my $pod;

    warn $r->filename;

    if ($r->filename =~ m/\.pod$/i) {
        $pod = $r->filename;
    } else {
        $pod = $r->path_info;
        $pod =~ s|/||;
        $pod =~ s|/|::|g;
        $pod =~ s|\.html$||;  # Intermodule links end with .html
    }

    $pod = 'perl' unless $pod;

    $pod =~
      s/^f::/-f /;    # If we specify /f/ as our "base", it's a function search

    my $tmp      = $r->dir_config('TMP') || "/tmp";
    my $perldoc  = $r->dir_config('PERLDOC');
    my $pod2html = $r->dir_config('POD2HTML');

    if ( $perldoc && $pod2html ) {

        # We want to run tainted
        $ENV{PATH} = "/bin";
      } else {
        $perldoc ||= "perldoc";
        $pod2html ||= "pod2html";
    }

    # Get the path name and throw away errors on stderr
    my $filename = qx( $perldoc -l $pod 2> /dev/null );

    if ($?) {
        print
"No such perldoc. Either you don't have that module installed, or the author neglected to provide documentation.";
      } else {
        chdir $tmp;
        print qx( $perldoc -u $pod | $pod2html --htmlroot=/perldoc --header );
    }
}

1;

# Documentation {{{

=head1 NAME

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

=head1 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 C<Foo::Bar> at the URL
C<http://your.server.com/perldoc/Foo::Bar>

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

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

In addition to Perl modules, you can have C<Apache::Perldoc> convert
C<.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.

=head1 Running under C<PerlTaintCheck>

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

    <Location /perldoc>
      SetHandler	perl-script