NAME
    Apache2::PodBrowser - show your POD in a browser

INSTALLATION
     perl Makefile.PL
     make
     make test
     make install

DESCRIPTION
    Yet another mod_perl2 handler to view POD in a HTML browser. See
    "HISTORY" for more information.

  Direct Mode
    "Apache2::PodBrowser" can run in *direct* and *perldoc* modes. In direct
    mode apache takes care of the URI to filename translation. So,
    "$r->filename" points to a regular file when the request hits
    "Apache2::PodBrowser"'s handler. Use this mode if your POD files are
    installed in one directory tree which is accessible through the WEB
    server. You'll perhaps need an additional directory index handler.

  Perldoc Mode
    In *perldoc* mode you specify a "Location" where the handler resides. If
    you append a module name to the location URL as in

      http://localhost/location/Apache2::PodBrowser

    you'll get its documentation.

    Further, in perldoc mode you can ask for documentation for a given perl
    function similar to "perldoc -f open" at the command line. Simply call
    the location and give the wanted function as CGI keyword:

      http://localhost/location/?open

    The same works also for special variables. Try

      http://localhost/location/?$_

    and you'll see the documentation for $_.

    Usually you want to use perldoc mode. It allows you to access PODs at
    their natural locations. On the downside, it is of course a bit slower.

  Indexes
    Also in perldoc mode, there are 2 indexes available, one of all
    installed modules and scripts that come with POD and one of built-in
    functions and variables.

    The the handler location itself shows the module index:

      http://localhost/location/

    If a single question mark "?" is given as CGI keyword the function and
    variable index is shown:

      http://localhost/location/??

    Don't worry you don't have to remember all these URLs. The pages are
    properly linked together.

CONFIGURATION
  Direct Mode
    Direct mode's basic configuration look like this:

      <Directory /...>
          Options +Indexes
          <Files ~ "\.p(od|m|l)">
              SetHandler modperl
              PerlResponseHandler Apache2::PodBrowser
              PerlSetVar  STYLESHEET /path/to/style.css
              PerlSetVar  PARSER Apache2::PodBrowser::DirectMode
          </Files>
      </Directory>

    All *.pod, *.pm and *.pl files will magically be converted to HTML.

  Perldoc Mode
    For perldoc mode add the following lines to your httpd.conf:

      <Location /perldoc>
          SetHandler  modperl
          PerlHandler Apache2::PodBrowser
          PerlFixupHandler Apache2::PodBrowser::Fixup
          PerlSetVar  STYLESHEET fancy
      </Location>

    You can then get documentation for module "Apache2::PodBrowser" at
    <http://localhost/perldoc/Apache2::PodBrowser>.

    Finally, a particular Perl built-in function's or variable's
    documentation is at
    <http://localhost/perldoc/?function_or_variable_name>. For example
    <http://localhost/perldoc/?open> or <http://localhost/perldoc/?$_>.

    At <http://localhost/perldoc/> you'll see a module index and at
    <http://localhost/perldoc/??> an index over all built-in functions and
    variables.

  Configuration Variables
    The following variables affect the work of "Apache2::PodBrowser". They
    are all set by "PerlSetVar" or "PerlAddVar". See t/conf/extra.conf.in
    for example configurations.

   STYLESHEET
    Specifies the stylesheet to use with the output HTML file.

      PerlSetVar  STYLESHEET /path/to/style.css

    There are 2 stylesheets *auto* and *fancy* that come with this module.
    They are installed alongside in @INC. To use them either teach your
    Apache to look for them or use the provided fixup handler:

      PerlFixupHandler Apache2::PodBrowser::Fixup
      PerlSetVar STYLESHEET fancy    # or auto

    If you want to use your own stylesheet simply specify its URL.

    To use one of the built in styles in direct mode you have to teach
    apache where it is located. One way is to use an "Alias" and make the
    file accessible. Another is to use the provided fixup handler. For
    example

      <Directory /some/directory>
          Options +Indexes
          <Files ~ "\.p(od|m)">
              SetHandler modperl
              PerlResponseHandler Apache2::PodBrowser
              PerlSetVar STYLESHEET /auto.css
              PerlSetVar PARSER Apache2::PodBrowser::DirectMode
          </Files>
          <Files *.css>
              PerlFixupHandler Apache2::PodBrowser::Fixup
          </Files>
      </Directory>

    In direct mode the stylesheet must be given as a complete URL not just
    "auto" or "fancy".

   INDEX
    When INDEX is true, a table of contents is added at the top of the HTML
    document.

      PerlSetVar INDEX 1

    By default, this is off.

    The "fancy" stylesheet places the index into a sort of drop-down menu
    that is placed fixed at the right top corner of the page. So, it is
    always at hand if you want to jump to another part of the document. This
    works in most browsers with the necessary CSS support. Notably, the
    Internet Explorer is not among them.

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

    An appropriate "Vary" header is issued to make proxy servers happy.

    Also the environment variables "no-gzip" and "gzip-only-text/html" that
    can be set for example by the "BrowserMatch" directive are regarded. See
    <the mod_deflate documentation > for more information

      PerlSetVar GZIP 1

    By default, this is off.

   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 before @INC.

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

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

      PerlAddVar NOINC 1

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

    In direct mode this variable is ignored.

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

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

   PARSER and LINKBASE
    "PARSER" sets the POD-to-HTML converter class that is used. It should
    support at least the interface that Pod::Simple::Text provides.

    The Pod::Simple::Text parser gives you plain text.

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

    The default "PARSER" is "Apache2::PodBrowser::Formatter" and is suitable
    for perldoc mode. It derives from Pod::Simple::HTML but overrides the
    constructor "new" to provide a "DOCTYPE" and "resolve_pod_page_link" to
    fix the linkage.

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

      ./Other::Module

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

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

    to generate links to CPAN.

    For perldoc mode an empty "LINKBASE" is best choice.

    In direct mode an other parser "Apache2::PodBrowser::DirectMode" should
    be used. It derives from "Apache2::PodBrowser::Formatter" but overrides
    "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: ".pod",
    ".pm" and ".pl". If none is found it resorts to its base class. And now
    "LINKBASE" makes sense.

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

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

  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 "DocumentRoot" and set "STYLESHEET" to find it.

WHISHLIST
    *   speed up POD index generation

HISTORY
    As you may know there is already Apache2::Pod::HTML. This module has
    borrowed some ideas from it but is implemented anew. In fact, I had
    started by editing 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
    Apache2::Pod::Text had also to be taken care of. That was too much to
    bear.

  Differences from Apache2::Pod::HTML as of version 0.01
    *   POD index

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

    *   NOINC variable

    *   PODDIR variable

    *   PARSER variable

    *   CONTENTTYPE variable

        new configuration variables

    *   proper HTTP protocol handling

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

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

    *   using CGI keywords instead of "PATH_INFO"

        how to pass function names to the handler in "perldoc -f" mode

    *   proper HTTP error codes

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

    *   CSS: fancy stylesheet

        "Apache2::PodBrowser" comes with 2 stylesheets, see above

    *   CSS: sent by default handler

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

    *   much better test suite

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

SEE ALSO
    Apache2::Pod::HTML
    Pod::Simple
    Pod::Simple::HTML
    Pod::Simple::Text

AUTHOR
    Torsten Förtsch "<torsten.foertsch@gmx.net>"

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