######################################################################
Pod::HtmlTree 0.97
######################################################################
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. So, if you want that, please make
sure your documentation contains a "SEE ALSO" section.
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.
The script "pod2htmltree" just calls
use Pod::HtmlTree;
Pod::HtmlTree::pod2htmltree($ARGV[0]);
internally, if you want to call it from within Perl, that's the way to
go.
FUNCTIONS
pod2htmltree( $httproot );
Make sure you've "chdir()"ed to your module's top directory when
calling this function.
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.
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:
pod2htmltree( $httproot, $htmldocdir );
If not specified, $htmldocdir defaults to "docs/html", therefore the
one-parameter syntax shown above.
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. 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.
Or, 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.