################################################################################
Pod::HtmlTree 0.93
################################################################################

NAME
    Pod::HtmlTree - Create a hierarchy of HTML documents from your module's
    PMs.

SYNOPSIS
      use Pod::HtmlTree qw(pod2htmltree);
      pod2htmltree($httproot);

DESCRIPTION
    So you've just created a great new Perl module distribution including
    several *.pm files? You've added nice POD documentation to each of them
    and now you'd like to view it nicely formatted in a web browser? And
    you'd also like to navigate between all those manual pages in your
    distribution and even view their source code? Read on, `Pod::HtmlTree'
    is what you need.

    It traverses your module's distribution directory (which you've probably
    created using `h2xs', finds all *.pm files recursivly and calls
    `pod2html()' on them, hereby resolving all POD links (L<...> style).

  Patching SEE ALSO and WHERE'S THE SOURCE?

    It then saves the nicely formatted HTML files under `docs/html' and
    updates each's `SEE ALSO' section to contain links to every other *.pm
    file in you're module's distribution. And it adds a new section `WHERE'S
    THE SOURCE?' to each HTML file with a link which will have the browser
    display the Perl source of the corresponding *.pm file. It also adds a
    stylesheet to `docs/html', which is referenced by every HTML file.

    So, in order to obtain HTML documentation for all your distribution's
    files, just call the script (which comes with the distribution of this
    module)

        pod2htmltree httproot

    while you're located in the top directory of your module's distribution.
    The script `pod2htmltree' just calls

        use Pod::HtmlTree;
        Pod::HtmlTree::pod2htmltree($ARGV[0]);

    internally.

FUNCTIONS
    pod2htmltree( $httproot );
        Recursively finds all `*.pm' files under the current directory,
        transforms them to HTML and places the result files in a tree
        starting at `docs/html' from the current directory.

        `$httproot' is the URL (absolute like `"http://..."' or relative
        like `/mymodule') to the top directory of your module, as seen from
        your web browser.

    banner( $text );
        Prints the passed text string nicely formatted as a screen warning.
        E. g., to notify the user after running `pod2htmltree' to `"Make
        sure http://localhost/perldoc/Pod-HtmlTree points to
        /u/mschilli/DEV/Pod-HtmlTree"', just pass it to `banner()' and print
        the return value:

            **************************************************
            * Make sure                                      *
            * http://localhost/perldoc/Pod-HtmlTree points   *
            * to /u/mschilli/DEV/Pod-HtmlTree                *
            **************************************************

EXAMPLE
    So, if your module is under

        /u/mschilli/MYPROJECTS/Spiffy-Module

    and has the files

        Spiffy-Module
        Spiffy-Module/Changes
        Spiffy-Module/MANIFEST
        Spiffy-Module/Makefile.PL
        Spiffy-Module/README
        Spiffy-Module/lib
        Spiffy-Module/lib/Spiffy.pm
        Spiffy-Module/lib/Spiffy/Subspiffy.pm
        Spiffy-Module/lib/Spiffy/Subspiffy/Subsub.pm
        Spiffy-Module/t
        Spiffy-Module/t/1.t

    a call to

        cd Spiffy-Module
        pod2htmltree http://localhost/Spiffy

    from within the shell or

        use Pod::HtmlTree;
        Pod::HtmlTree::pod2htmltree("http://localhost/Spiffy");

    from within Perl will `pod2html'-transform the files `Spiffy.pm',
    `Subspiffy.pm' and `Subsub.pm' to HTML and put the result there:

        Spiffy-Module/docs/html/Spiffy.html
        Spiffy-Module/docs/html/Spiffy/Subspiffy.html
        Spiffy-Module/docs/html/Spiffy/Subspiffy/Subspiffy.html

    Directories are created on the fly as necessary. To view them on your
    web server via a browser, you need to create a symbolic link from your
    web server's document root.

    If the module's distribution is located under

        /u/mschilli/MYPROJECTS/Spiffy-Module

    and your web server's doc root is `/opt/netscape/htdocs', you need to
    create a symlink like

        ln -s /u/mschilli/MYPROJECTS/Spiffy-Module /opt/netscape/htdocs/Spiffy

    Then, if you point your browser to

        http://localhost/Spiffy/docs/html/Spiffy.html

    you'll see the documentation.

  Call it in Makefile.PL

    If you want to give the user of your distribution the opportunity to
    create their own browsable HTML-documentation of your module, just
    include the following in the Makefil.PL of your distribution:

        use ExtUtils::MakeMaker;

        >>  # Generate documentation?
        >>  if (prompt("Generate HTML documentation?", "n") =~ /^y/) {
        >>      require Pod::HtmlTree;
        >>      Pod::HtmlTree::pod2htmltree("/mymodule");
        >>      print Pod::HtmlTree::banner(
        >>          "Make sure http://localhost/mymodule points to ", `pwd`);
        >>   }

        WriteMakefile(
            ...
        );

SEE ALSO
AUTHOR
    Mike Schilli, <mschilli1@aol.com>

COPYRIGHT AND LICENSE
    Copyright 2002 by Mike Schilli

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.