view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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.

Embedding HTML in POD
    POD provides the