view release on metacpan or  search on metacpan

lib/Apache2/PodBrowser.pm  view on Meta::CPAN

=head2 Differences from Apache2::Pod::HTML as of version 0.01

=over 4

=item * POD index

an index of all PODs found in the given scan directories is
returned if the handler is called in C<perldoc> mode without
a module argument.

=item * NOINC variable

=item * PODDIR variable

=item * PARSER variable

=item * CONTENTTYPE variable

new configuration variables

=item * proper HTTP protocol handling

L<Apache2::Pod::HTML> does not issue a C<Vary> HTTP header in GZIP mode.
It does not support turning off GZIP for certain browsers by C<BrowserMatch>.
And it does not sent C<Content-Length>, C<Last-Modified> or C<ETag> headers.

C<Apache2::PodBrowser> issues correct headers when GZIP is on. It also
sends C<ETag>, C<Last-Modified> and C<Content-Length> headers. And it
checks if a conditional GET request meets its conditions and answers with
HTTP code C<304> (NOT MODIFIED) if so.

=item * using CGI keywords instead of C<PATH_INFO>

how to pass function names to the handler in C<perldoc -f> mode

=item * proper HTTP error codes

L<Apache2::Pod::HTML> returns HTTP code C<200> even if there is no
POD found by a given name

=item * CSS: fancy stylesheet

C<Apache2::PodBrowser> comes with 2 stylesheets, see above

=item * CSS: sent by default handler

C<Apache2::PodBrowser> uses a fixup handler to reconfigure apache
to ship included stylesheets by it's default response handler.

=item * much better test suite

C<Apache2::PodBrowser> uses the L<Apache::Test> framework to test its
work. L<Apache2::Pod::HTML> tests almost only the presence of POD.

=back

=head1 Embedding HTML in POD

=begin html

<div style="width: 80px; height: 104px; background-color: #fff;
            float: right;">
<img align="right"
     alt="Picture of Torsten Foertsch"
     src="Apache2%3A%3APodBrowser/torsten-foertsch.jpg"
     border="0">
</div>

=end html

POD provides the

 =begin html
 ...
 =end html

or

 =for html ...

syntax. This module supports it. If you look at this document via this
module you'll probably see a picture of me on the right side.

Example:

 =begin html

 <img align="right"
      alt="Picture of ..."
      src="http://host.name/image.jpg"
      border="0">

 =end html

You might notice that the image URL is absolute. Wouldn't it be good to
bundle the images with the module, install them somewhere beside it in
C<@INC> and reference them relatively?

It is possible to do that in perldoc mode.
Just strip off the C<.pm> or C<.pod> suffix
from the installed perl module file name and make a directory with that
name. For example assuming that this module is installed as:

 /perl/lib/Apache2/PodBrowser.pm

create the directory

 /perl/lib/Apache2/PodBrowser

and place the images there.

To include them in POD write:

 =begin html

 <img align="right"
      alt="Picture of ..."
      src="./Apache2::PodBrowser/torsten-foertsch.jpg"
      border="0">

 =end html