/ 
Pod-HtmlTree-0.93
River stage zero No dependents
/ Pod::HtmlTree

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.