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.

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);

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.

The map method may perform arbitrary mappings on its arguments.

The default link_map translates :: sequences in $page to /.

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.

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

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 (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-2000 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