NAME

Pod::Tree::HTML - Generate HTML from a Pod::Tree

SYNOPSIS

use Pod::Tree::HTML;

$source =   new Pod::Tree %options;
$source =  "file.pod";
$source =   new IO::File;
$source = \$pod;
$source = \@pod;
  
$dest   =   new HTML::Stream;
$dest   =   new IO::File;
$dest   =  "file.html";

$html   =   new Pod:::Tree::HTML $source, $dest, %options;

$html->set_options(%options);
@values = $html->get_options(@keys);

$html->translate;

DESCRIPTION

Pod::Tree::HTML reads a POD and translates it to HTML. The source and destination are fixed when the object is created. Options are provided for controlling details of the translation.

The translate method does the actual translation.

For convenience, Pod::Tree::HTML can read PODs from a variety of sources, and write HTML to a variety of destinations. The new method resolves the $source and $dest arguments.

Source resolution

Pod::Tree::HTML can obtain a POD from any of 5 sources. new resolves $source by checking these things, in order:

1. If $source isa POD::Tree, then the POD is taken from that tree.

2. If $source is not a reference, then it is taken to be the name of a file containing a POD.

3. If $source isa IO::File, then it is taken to be an IO::File object that is already open on a file containing a POD.

4. If $source is a SCALAR reference, then the text of the POD is taken from that scalar.

5. if $source is an ARRAY reference, then the paragraphs of the POD are taken from that array.

If $source isn't any of these things, new dies.

Destination resolution

Pod::Tree::HTML can write HTML to any of 3 destinations. new resolves $dest by checking these things, in order:

1. If $dest isa HTML::Stream, then it writes to that stream.

2. If $dest is a reference, then it is taken to be an IO::File object that is already open on the file where the HTML will be written.

3. If $dest is not a reference, then it is taken to be the name of the file where the HTML will be written.

METHODS

$html = new Pod::Tree::HTML $source, $dest, %options

Creates a new Pod::Tree::HTML object.

$html reads a POD from $source, and writes HTML to $dest. See "Source resolution" and "Destination resolution" for details.

Options controlling the translation may be passed in the %options hash. See "OPTIONS" for details.

$html->set_options(%options)

Sets options controlling the translation. See "OPTIONS" for details.

@values = $html->get_options(@keys)

Returns the current values of the options specified in @keys. See "OPTIONS" for details.

$html->translate

Translates the POD to HTML. This method should only be called once.

OPTIONS

base => $url

Specifies a base URL for relative HTML links.

bgcolor => #rrggbb

Set the background color to #rrggbb. Default is #fffff8, which is an off-white.

depth => $depth

Specifies the depth of the generated HTML page in a directory tree.

hr => $level

Controls the profusion of horizontal lines in the output, as follows:

$level   horizontal lines
0 	     none
1 	     between TOC and body
2 	     after each =head1
3 	     after each =head1 and =head2

Default is level 1.

link_map => $link_map

Sets the link mapping object. Before emitting an L<> markup in HTML, translate calls

($base, $page, $section) = $link_map->map($base, $page, $section, $depth);

Where

$base

is the URL given in the base option.

$page

is the man page named in the L<> markup.

$section

is the man page section given in the L<> markup.

($depth

is the value of the depth option.

The map method may perform arbitrary mappings on its arguments.

The default link_map translates :: sequences in $page to /. If the base option is given, it creates links relative to that URL; if the depth option is given, it creates links relative to the root of the HTML directory tree. If neither the base nor depth options are provided, the default link_map may not generate correct links.

text => #rrggbb

Set the text color to #rrggbb. Default is #fffff, which is black.

title => title

Set the page title to title. If no title option is given, Pod::Tree::HTML will attempt construct a title from the second paragrah of the POD. This supports the following style:

=head1 NAME

ls - list contents of directory

toc => [0|1]

Includes or omits the table of contents. Default is to include the TOC.

LINKS and TARGETS

Pod::Tree::HTML automatically generates HTML name anchors for all =head1 and =head2 command paragraphs, and for text items in =over lists. The text of the paragraph becomes the name entity in the anchor. Markups are ignored and the text is escaped according to RFC 2396.

For example, the paragraph

=head1 C<Foo> Bar

is translated to

<h1><a name="Foo%20Bar"><code>Foo</code> Bar</a></h1>

To link to a heading, simply give the text of the heading in a L<> markup. The text must match exactly; markups may vary. Either of these would link to the heading shown above

L</C<Foo> Bar>
L</Foo Bar>

To generate HTML anchors in other places, use the index () markup

We can link to X<this text>.

and link to it as usual

L</this text> uses the index markup.

DIAGNOSTICS

Pod::Tree::HTML::new: not enough arguments

(F) new called with fewer than 2 arguments.

Pod::Tree::HTML::new: Can't load POD from $source

(F) new couldn't resolve the $source argument. See "Source resolution" for details.

Pod::Tree::HTML::new: Can't open $dest: $!

(F) The destination file couldn't be opened.

SEE ALSO

perl(1), Pod::Tree, Pod::Tree::Node

AUTHOR

Steven McDougall, swmcd@world.std.com

COPYRIGHT

Copyright 1999-2001 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Stream

perl -MCPAN -e shell
install Stream