Apache2::Pod - base class for converting Pod files to prettier forms

Apache2-Pod documentation Contained in the Apache2-Pod distribution.

Index

Code Index:

NAME

Top

Apache2::Pod - base class for converting Pod files to prettier forms

VERSION

Top

Version 0.27

SYNOPSIS

Top

The Apache2::Pod::* are mod_perl handlers to easily convert Pod to HTML or other forms. You can also emulate perldoc.

CONFIGURATION

Top

All configuration is done in one of the subclasses.

TODO

Top

I could envision a day when the user can specify which output format he'd like from the URL, such as

    http://your.server/perldoc/f/printf?rtf

FUNCTIONS

Top

No functions are exported. I don't want to dink around with Exporter in mod_perl if I don't need to.

getpodfile( $r )

Returns the filename requested off of the $r request object, or what Perldoc would find, based on Pod::Find.

resolve_modname( $r )

Returns a module name based on $r->path_info.

getpodfuncdoc( $file, $function_name )

Given the full filepath of the perlfunc pod file and a function name, returns the section of that pod document pertaining to the function. If the function is not found, returns a pod document phrase stating so.

SEE ALSO

Top

Apache2::Pod::HTML, Apache2::Pod::Text,

AUTHOR

Top

Theron Lewis <theron at theronlewis dot com>

HISTORY

Top

Adapteded from Andy Lester's <andy at petdance dot com> Apache::Pod package which was adapted from Apache2::Perldoc by Rich Bowen <rbowen@ApacheAdmin.com>

ACKNOWLEDGEMENTS

Top

Thanks also to Pete Krawczyk, Kjetil Skotheim, Kate Yoak and Chris Eade for contributions.

LICENSE

Top

This package is licensed under the same terms as Perl itself.

Apache2-Pod documentation Contained in the Apache2-Pod distribution. 
package Apache2::Pod;


use vars qw( $VERSION );
use strict;

$VERSION = '0.27';


use Pod::Find;
use Carp ();

sub getpodfile {
	my $r = shift;

	my $filename;

	if ($r->filename =~ m/\.pod$/i) {
		$filename = $r->filename;
	} 
	else {
		my $module = resolve_modname( $r );
		if ( $module =~ /^f::/ ) {
			$module =~ s/^f:://;
			$filename = "-f<$module>::" . Pod::Find::pod_where( {-inc=>1}, "perlfunc" );
		}
		else {
			$filename = Pod::Find::pod_where( {-inc=>1}, $module );
		}
	}

	return $filename;
}

sub resolve_modname {
	my ( $r ) = @_;
	my $module = $r->path_info;
	$module =~ s|/||;
	$module =~ s|/|::|g;
	$module =~ s|\.html?$||;  # Intermodule links end with .html
	return $module;
}

sub getpodfuncdoc {
	my ( $file, $fun ) = @_;
	# Functions like -r, -e, etc. are listed under `-X'.
	my $search_re = ($fun =~ /^-[rwxoRWXOeszfdlpSbctugkTBMAC]$/)
		? '(?:I<)?-X' : quotemeta($fun) ;
	my $document = '';
	# TODO:  Handle error on open gracefully.
	open(PFUNC, "<$file") || Carp::croak "Can't open $file: $!";
	# Skip introduction
	local $_;
	while ( <PFUNC> ) {
		last if /^=head2 Alphabetical Listing of Perl Functions/;
	}
	
	# Look for our function
	my $found = 0;
	my $inlist = 0;
	while ( <PFUNC> ) {  # "The Mothership Connection is here!"
		if ( m/^=item\s+$search_re\b/ )  {
			$found = 1;
		}
		elsif (/^=item/) {
			last if $found > 1 and not $inlist;
		}
		next unless $found;
		if (/^=over/) {
			++$inlist;
		}
		elsif (/^=back/) {
			--$inlist;
		}
		$document .= "$_";
		++$found if /^\w/;        # found descriptive text
	}
	# TODO:  Handle error on open/close gracefully.
	close PFUNC or Carp::croak "Can't open $file: $!";
	if ( ! $document ) {
		$document = sprintf "=item %s\n\nNo documentation for perl function '%s' found\n", $fun, $fun; # no $fun
	}
	return $document;
}
1;