NAME

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

SYNOPSIS

  use Pod::Tree::HTML;

  $source =   new Pod::Tree;
  $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

Translate L<> sequences into HTML links relative to $url.

toc => [0|1]

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

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.

bgcolor => #rrggbb

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

text => #rrggbb

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

LINKS and TARGETS

Pod::Tree::HTML automatically generates HTML name anchors for all =head1 and =head2 command paragraphs. Markups are ignored and non-word (\W) characters are translated to hex.

For example, the paragraph

        =head1 C<Foo> Bar

is translated to

        <h1><a name="Foo20Bar"><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 (X<>) 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 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Pod::Tree

perl -MCPAN -e shell
install Pod::Tree