view release on metacpan or  search on metacpan

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

=head3 GZIP

When GZIP is true, the whole HTTP body is compressed. The browser must
accept gzip, and L<Compress::Zlib> must be available. Otherwise, GZIP is
ignored.

An appropriate C<Vary> header is issued to make proxy servers happy.

Also the environment variables C<no-gzip> and C<gzip-only-text/html>
that can be set for example by the C<BrowserMatch> directive are regarded.
See L<the mod_deflate documentation
|http://httpd.apache.org/docs/2.2/mod/mod_deflate.html#recommended> for
more information

  PerlSetVar GZIP 1

By default, this is off.

=head3 PODDIR

This variable is useful only in perldoc mode.

It declares additional directories to look for PODs. This can be given multiple
times. Directories given this way are searched B<before> C<@INC>.

  PerlAddVar PODDIR /path/to/project1
  PerlAddVar PODDIR /path/to/project2

=head3 NOINC

In perldoc mode POD files are normally looked up in C<@INC> plus in the
directories given by C<PODDIR>. If C<NOINC> is set then the C<@INC> search
is skipped. That means only the directories specifed in F<httpd.conf>
are scanned:

  PerlAddVar NOINC 1

For documentation requests for perl functions via
L<http://localhost/perldoc/?functionname> C<@INC> is used nevertheless
to locate C<perlfunc.pod> if it is not found in one of the given directories.

In direct mode this variable is ignored.

=head3 CACHE

When in perldoc mode C<Apache2::PodBrowser> uses
L<Pod::Find::pod_find>
to generate a list of available POD files. This may take quite a while
depending upon the number of directories and files to scan for POD.

To avoid to repeat this for each POD index request one can set up a cache.

  PerlSetVar CACHE /path/to/cache.mmdb

The cache file itself is created on the first access to the index. The POD
index page then contains a link to update the cache. So, if a POD file
is added or removed from the system this link is to be clicked to keep
the POD index page up to date.

The cache file itself is a L<MMapDB> object. If this module is not available
you'll probably get a C<404 - NOT FOUND> response the next time the POD index
page is requested if C<CACHE> is set.

The directory containing the cache file must be writable by the C<httpd>.

=head3 CONTENTTYPE

You'll probably need that only for plain text output with the
L<Pod::Simple::Text> parser. Here one can set the content type
of the output.

  PerlSetVar CONTENTTYPE "text/plain; charset=UTF-8"

=head3 PARSER and LINKBASE

C<PARSER> sets the POD-to-HTML converter class that is used. It should
support at least the interface that L<Pod::Simple::Text> provides.

The L<Pod::Simple::Text> parser gives you plain text.

If L<Pod::Simple::HTML> is used as parser one gets almost usable output
except for the missing C<DOCTYPE> HTML header and the broken linkage
to other modules.

The default C<PARSER> is C<Apache2::PodBrowser::Formatter> and is
suitable for perldoc mode. It derives
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.