view release on metacpan or  search on metacpan

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

from L<Pod::Simple::HTML> but overrides the constructor C<new> to
provide a C<DOCTYPE> and C<resolve_pod_page_link> to fix the linkage.

If C<LINKBASE> is not set or empty C<resolve_pod_page_link> creates
relative links to other modules of the type:

  ./Other::Module

If C<LINKBASE> is set it is prepended before C<Other::Module> instead
of C<./>. For example you could set

  PerlSetVar LINKBASE http://search.cpan.org/perldoc?

to generate links to CPAN.

For perldoc mode an empty C<LINKBASE> is best choice.

In direct mode an other parser C<Apache2::PodBrowser::DirectMode> should
be used. It derives from C<Apache2::PodBrowser::Formatter> but overrides
C<resolve_pod_page_link>.

This time the link generator searches for the link destination POD by
the module name with one of the following extensions appended: C<.pod>,
C<.pm> and C<.pl>. If none is found it resorts to its base class. And
now C<LINKBASE> makes sense.

If you know of a C<Apache2::PodBrowser> running in perldoc mode you can
point C<LINKBASE> to that address. This way modules that does not exist
in the local tree would be looked up there or on CPAN if C<LINKBASE>
points there.

If all that is unsuitable for you you can implement your own C<PARSER>
class. Have a look at the source code of this module. It is quite straight
forward regarding the 2 parser classes.

=head2 The Fixup Handler

If you use your own stylesheet or teach apache to find one of the
provided styles in the file system you don't need the fixup handler.

It simply does the file lookup for you.

If you don't like it just find the style sheet in your file system:

  find $(perl -e 'print "@INC"') -type f -name fancy.css

copy it into your C<DocumentRoot> and set C<STYLESHEET> to find it.

=head1 WHISHLIST

=over 4

=item * speed up POD index generation

=back

=head1 HISTORY

As you may know there is already L<Apache2::Pod::HTML>. This module
has borrowed some ideas from it but is implemented anew. In fact, I
had started by editing L<Apache2::Pod::HTML> 0.27 but at a certain moment
I had patched it into something that only vaguely remembered the
original code. When the HTML functionality
was ready I discovered that L<Apache2::Pod::Text> had also to be
taken care of. That was too much to bear.

=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