Skip Menu |
 

This queue is for tickets about the Apache-Pod CPAN distribution.

Report information
The Basics
Id: 7658
Status: open
Priority: 0/
Queue: Apache-Pod

People
Owner: Nobody in particular
Requestors: crome [...] devnetinc.com
Cc:
AdminCc:

Bug Information
Severity: Wishlist
Broken in: (no value)
Fixed in: (no value)



Subject: Insert page headers and footers into generated HTML
Download (untitled) / with headers
text/plain 322b
Thought it might be helpful to allow users to apply a header and footer to Apache::Pod::HTML output so that the resulting markup looks like an integrated part of someone's web site. See the POD for details. Written for Apache::Pod::HTML v 0.10. Tested on ActivePerl build 810/Apache 1.3.31/mod_perl 1.29 on Windows XP.
Download APH_patch
text/plain 10.2k
--- /y/HTML.pm Wed Sep 15 11:03:37 2004 +++ /c/HTML.pm Wed Sep 15 10:52:40 2004 @@ -1,198 +1,240 @@ -package Apache::Pod::HTML; - -=head1 NAME - -Apache::Pod::HTML - base class for converting Pod files to prettier forms - -=head1 VERSION - -Version 0.03 - -$Header: /home/cvs/apache-pod/lib/Apache/Pod/HTML.pm,v 1.12 2004/05/10 20:51:44 andy Exp $ - -=cut - -use strict; -use vars qw( $VERSION ); - -$VERSION = '0.10'; - -use Apache::Pod; -use Apache::Constants; - -=head1 SYNOPSIS - -A simple mod_perl handler to easily convert Pod to HTML or other forms. -You can also emulate F<perldoc>. - -=head1 CONFIGURATION - -=head2 Pod-to-HTML conversion - -Add the following lines to your F<httpd.conf>. - - <Files *.pod> - SetHandler perl-script - PerlHandler Apache::Pod::HTML - </Files> - -All F<*.pod> files will magically be converted to HTML. - -=head2 F<perldoc> emulation - -The following configuration should go in your httpd.conf - - <Location /perldoc> - SetHandler perl-script - PerlHandler Apache::Pod::HTML - PerlSetVar STYLESHEET auto - </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>. - -Specifying 'auto' for the stylesheet will cause the built-in CSS stylesheet -to be used. If you prefer, you can replace the word 'auto' with the URL of -your own custom stylesheet file. - -=cut - -sub handler { - my $r = shift; - - if ( $r->path_info eq '/auto.css' ) { - $r->content_type( 'text/css' ); - $r->send_http_header; - print _css(); - return OK; - } - - my $body; - my $file = Apache::Pod::getpodfile( $r ); - - if ( $file ) { - my $parser = My::Pod::Simple::HTML->new; - $parser->no_errata_section(1); - $parser->complain_stderr(1); - $parser->output_string( \$body ); - $parser->parse_file( $file ); - # TODO: Send the timestamp of the file in the header - - my $stylesheet = $r->dir_config('STYLESHEET') || ''; - $stylesheet = $r->location . '/auto.css' if $stylesheet =~ /^auto/i; - if ( $stylesheet ) { - # Stick in a link to our stylesheet - $stylesheet = qq(<LINK REL="stylesheet" HREF="$stylesheet" TYPE="text/css">); - $body =~ s{(?=</head)}{$stylesheet\n}i; - } - } else { - $body = "<HTML><HEAD><TITLE>Not found</TITLE></HEAD><BODY>That module doesn't exist</BODY></HTML>"; - } - - $r->content_type('text/html'); - $r->send_http_header; - print $body; - - return OK; -} - -sub _css { - return <<'EOF'; -BODY { - background: white; - color: black; - font-family: times,serif; - margin: 0; - padding: 1ex; -} - -TABLE { - border-collapse: collapse; - border-spacing: 0; - border-width: 0; - color: inherit; -} - -A:link, A:visited { - background: transparent; - color: #006699; -} - -PRE { - background: #eeeeee; - border: 1px solid #888888; - color: black; - padding-top: 1em; - padding-bottom: 1em; - white-space: pre; -} - -H1 { - background: transparent; - color: #006699; - font-size: x-large; - font-family: tahoma,sans-serif; -} - -H2 { - background: transparent; - color: #006699; - font-size: large; - font-family: tahoma,sans-serif; -} - -.block { - background: transparent; -} - -TD .block { - color: #006699; - background: #dddddd; - padding: 0.2em; - font-size: large; -} - -HR { - display: none; -} -EOF -} - -package My::Pod::Simple::HTML; - -use Pod::Simple::HTML; - -our @ISA = qw( Pod::Simple::HTML ); - -*VERSION = *Pod::Simple::HTML::VERSION; - -sub resolve_pod_page_link { - my $self = shift; - my $to = shift; - my $section = shift; - - my $link = $to; - - return $link; -} - -=head1 AUTHOR - -Andy Lester C<< <andy@petdance.com> >>, adapted from Apache::Perldoc by -Rich Bowen C<< <rbowen@ApacheAdmin.com> >> - -=head1 LICENSE - -This package is licensed under the same terms as Perl itself. - -=cut - -1; +package Apache::Pod::HTML; + +=head1 NAME + +Apache::Pod::HTML - base class for converting Pod files to prettier forms + +=head1 VERSION + +Version 0.03 + +$Header: /home/cvs/apache-pod/lib/Apache/Pod/HTML.pm,v 1.12 2004/05/10 20:51:44 andy Exp $ + +=cut + +use strict; +use vars qw( $VERSION ); + +$VERSION = '0.10'; + +use Apache::Pod; +use Apache::Constants; + +=head1 SYNOPSIS + +A simple mod_perl handler to easily convert Pod to HTML or other forms. +You can also emulate F<perldoc>. + +=head1 CONFIGURATION + +=head2 Pod-to-HTML conversion + +Add the following lines to your F<httpd.conf>. + + <Files *.pod> + SetHandler perl-script + PerlHandler Apache::Pod::HTML + PerlSetVar HEADER /path/to/your/header.html + PerlSetVar FOOTER /path/to/your/footer.html + </Files> + +All F<*.pod> files will magically be converted to HTML. + +C<HEADER> and C<FOOTER> specifications are entirely optional. When set, +they will allow you to add a standard header and footer to your POD pages. +This is particularly handy if you are writing help pages for an application +and you would like them to appear as an integrated part of your web site. + +If you have a C<HEADER> specification, a corresponding C<FOOTER> +specification is not necessary. Likewise, if you have a C<FOOTER> +specified, you do not need to specify a C<HEADER>. + +C<HEADER> and C<FOOTER> are merely files containing the bits of HTML you +would like to insert into your POD pages. + +=head2 F<perldoc> emulation + +The following configuration should go in your httpd.conf + + <Location /perldoc> + SetHandler perl-script + PerlHandler Apache::Pod::HTML + PerlSetVar STYLESHEET auto + </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>. + +Specifying 'auto' for the stylesheet will cause the built-in CSS stylesheet +to be used. If you prefer, you can replace the word 'auto' with the URL of +your own custom stylesheet file. + +=cut + +sub handler { + my $r = shift; + + if ( $r->path_info eq '/auto.css' ) { + $r->content_type( 'text/css' ); + $r->send_http_header; + print _css(); + return OK; + } + + my $body; + my $file = Apache::Pod::getpodfile( $r ); + + if ( $file ) { + my $header = $r->dir_config('HEADER') || ''; + my $footer = $r->dir_config('FOOTER') || ''; + + my $parser = My::Pod::Simple::HTML->new; + $parser->no_errata_section(1); + $parser->complain_stderr(1); + $parser->bare_output(1) if $header; + $parser->output_string( \$body ); + $parser->parse_file( $file ); + # TODO: Send the timestamp of the file in the header + + $body = _slurp($header) . $body if $header; + + # If we have a header, simply append the footer, else wedge it into the existing HTML. + if($footer) { + $footer = _slurp($footer); + + if($header) { + $body .= $footer; + } + else { + $body =~ s{(?=</body)}{$footer\n}i; + } + } + + my $stylesheet = $r->dir_config('STYLESHEET') || ''; + $stylesheet = $r->location . '/auto.css' if $stylesheet =~ /^auto/i; + if ( $stylesheet ) { + # Stick in a link to our stylesheet + $stylesheet = qq(<LINK REL="stylesheet" HREF="$stylesheet" TYPE="text/css">); + $body =~ s{(?=</head)}{$stylesheet\n}i; + } + } else { + $body = "<HTML><HEAD><TITLE>Not found</TITLE></HEAD><BODY>That module doesn't exist</BODY></HTML>"; + } + + $r->content_type('text/html'); + $r->send_http_header; + print $body; + + return OK; +} + +sub _slurp { + my $file = shift; + + open my $fh, "<", $file or warn "Can't open $file: $!"; + my @content = <$fh> or warn "Can't read $file: $!"; + close $fh; + + return join('', @content); +} + +sub _css { + return <<'EOF'; +BODY { + background: white; + color: black; + font-family: times,serif; + margin: 0; + padding: 1ex; +} + +TABLE { + border-collapse: collapse; + border-spacing: 0; + border-width: 0; + color: inherit; +} + +A:link, A:visited { + background: transparent; + color: #006699; +} + +PRE { + background: #eeeeee; + border: 1px solid #888888; + color: black; + padding-top: 1em; + padding-bottom: 1em; + white-space: pre; +} + +H1 { + background: transparent; + color: #006699; + font-size: x-large; + font-family: tahoma,sans-serif; +} + +H2 { + background: transparent; + color: #006699; + font-size: large; + font-family: tahoma,sans-serif; +} + +.block { + background: transparent; +} + +TD .block { + color: #006699; + background: #dddddd; + padding: 0.2em; + font-size: large; +} + +HR { + display: none; +} +EOF +} + +package My::Pod::Simple::HTML; + +use Pod::Simple::HTML; + +our @ISA = qw( Pod::Simple::HTML ); + +*VERSION = *Pod::Simple::HTML::VERSION; + +sub resolve_pod_page_link { + my $self = shift; + my $to = shift; + my $section = shift; + + my $link = $to; + + return $link; +} + +=head1 AUTHOR + +Andy Lester C<< <andy@petdance.com> >>, adapted from Apache::Perldoc by +Rich Bowen C<< <rbowen@ApacheAdmin.com> >> + +=head1 LICENSE + +This package is licensed under the same terms as Perl itself. + +=cut + +1;
Download (untitled) / with headers
text/plain 451b
[CROMEDOME - Wed Sep 15 12:27:55 2004]: Show quoted text
> Thought it might be helpful to allow users to apply a header and > footer to Apache::Pod::HTML output so that the resulting markup > looks like an integrated part of someone's web site. See the POD > for details.
I'm interested, but the patch you gave me basically replaces the entire source file. Can you please re-diff your stuff against 0.20, which I'll be uploading today? Thanks, xoxo, Andy


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.