Pod::HtmlTree - Create a hierarchy of HTML documents from your module's PMs.
use Pod::HtmlTree qw(pod2htmltree); pod2htmltree($httproot);
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.
Pod::HtmlTree
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).
h2xs
pod2html()
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. So, if you want that, please make sure your documentation contains a SEE ALSO section.
docs/html
SEE ALSO
Also, at the end of the SEE ALSO section, it'll add a link to the source code of the current *.pm file, just in case a user wants to browse it because there's issues which aren't clear from the documentation.
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. What's in httproot is explained below.
httproot
The script pod2htmltree just calls
pod2htmltree
use Pod::HtmlTree; Pod::HtmlTree::pod2htmltree($ARGV[0]);
internally, if you want to call it from within Perl, that's the way to go.
Make sure you've chdir()ed to your module's top directory when calling this function.
chdir()
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.
*.pm
$httproot is the URL (absolute like "http://..." or relative like /mymodule) to the top directory of your module, as seen from your web browser.
$httproot
"http://..."
/mymodule
If you don't like the HTML documents to be created under docs/html, you can specify the relative (!) directory in the additional parameter $htmldocdir:
$htmldocdir
pod2htmltree( $httproot, $htmldocdir );
If not specified, $htmldocdir defaults to docs/html, therefore the one-parameter syntax shown above.
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"
banner()
************************************************** * Make sure * * http://localhost/perldoc/Pod-HtmlTree points * * to /u/mschilli/DEV/Pod-HtmlTree * **************************************************
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:
pod2html
Spiffy.pm
Subspiffy.pm
Subsub.pm
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
and your web server's doc root is /opt/netscape/htdocs, you need to create a symlink like
/opt/netscape/htdocs
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. If you've specified a (probably empty) SEE ALSO section, it will be automatically populated with other modules in your distribution and a link to the current module's source code.
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( ... );
Mike Schilli, <mschilli1@aol.com>
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.
To install Pod::HtmlTree, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::HtmlTree
CPAN shell
perl -MCPAN -e shell install Pod::HtmlTree
For more information on module installation, please visit the detailed CPAN module installation guide.