view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    *   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

     =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
    @INC and reference them relatively?

    It is possible to do that in perldoc mode. Just strip off the ".pm" or
    ".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

    If the POD file name doesn't contain a dot (".") the last path component
    is stripped off to get the directory name.

    Note that you need to write the package name again. You also need to
    either escape the semicolons as in