NAME

pod2htmltree.pl - Creates a Perl documentation tree in HTML format.

SYNOPSIS

pod2htmltree.pl options command files package dirs package files

ARGUMENTS

options: Having the form --name=value, the full list of options is available in the documentation for pod2htmlTree.
command files: @filename - file containing other options or package dirs or package files
package dirs: directory names relative to sourcePath
package files: file names relative to sourcePath

REQUIRES

Pod::HtmlTree

DESCRIPTION

This program creates a set of HTML documentation from template files and from POD input contained in Perl files. Just as perldoc is a wrapper around the function pod2html from Pod::Html, pod2htmltree.pl is just a convenience wrapper around the pod2htmlTree function Pod::HtmlTree. perldoc creates an HTML documentation file for a single Perl file; pod2htmltree creates an interconnected HTML documentation tree for multiple Perl files.

The different arguments may be in any order and any quantity. An option has the form --name=value. The value may or may not need to be enclosed in quotation marks. This depends on whether it contains any spaces or other characters special to your shell. Inside a command file, which contains one option or element per line, everything after the equals sign is assigned to the value, except for enclosing (optional) quotation marks.

An element may be either a package directory or an individual package file. Say, for example, you have packages Here::one, Here::two, and There::more, all of these in /perl/lib. From the command line, all of these are equivalent:

        pod2htmltree.pl --sourcePath=/perl/lib Here There
        pod2htmltree.pl --sourcePath=/perl/lib Here There/more.pm
        pod2htmltree.pl --sourcePath=/perl/lib Here/one.pm Here/two.pm There/more.pm
        pod2htmltree.pl @cmd.conf

The last line assumes that you create a command file cmd.conf containing the same arguments (one per line) which might look like:

        --sourcePath=/perl/lib
        Here
        There

You may mix and match options and elements between the command line and command files. Precedence is determined as follows: For options, all command line options are processed first. Then all command file options are processed. If an option appears more than once, the last instance will be effective. For elements, these are processed in the order encountered. That is, you could consider elements within a command file as expanded in place on the command line.

See the documentation for Pod::HtmlTree for further details.

EXIT STATUS

Return Code 0

Normal exit.

Return Code 1

Help requested (-h or -man).

Return Code 2

-Missing file name or spec.

-Template directory does not exist.

-SourcePath and targetPath cannot be the same.

-Cannot create destination directory.

BUGS

[1062791] During generation of each package's index file (i.e. index.html from package.html), a glitch may appear in the finished index.html file. The first sentence of the first paragraph is extracted as the package summary, used in the next higher level description as well as the summary line within index.html. But if this is just one line of a multi-line paragraph, the HTML structure will be compromised by the loss of the opening <p>.

AUTHOR

Michael Sorens

VERSION

$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $

SINCE

CleanCode 0.9

CleanCode Perl Libraries