Pod::Tree::HTML3pm

Usage

  use Pod::Tree::HTML;
  $source   =   Pod::Tree->new(%options);
  $source   =  "file.pod";
  $source   =   IO::File->new;
  $source   = \$pod;
  $source   = \@pod;
  $dest     =   HTML::Stream->new;
  $dest     =   IO::File->new;
  $dest     =  "file.html";
  $html     =   Pod::Tree::HTML->new($source, $dest, %options);
              $html->set_options(%options);
  @values   = $html->get_options(@keys);
              $html->translate;
              $html->translate($template);
              $html->emit_toc;
              $html->emit_body;
  $fragment = $html->escape_2396 ($section);
  $url      = $html->assemble_url($base, $page, $fragment);

Requires

"HTML::Stream", "Text::Template"

Overview

"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.

"Pod::Tree::HTML" can also use "Text::Template" to fill in an HTML template file.

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"

$html->"translate"($template)

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

In the second form, $template is the name of a file containing a template. The template will be filled in by the "Text::Template" module. Here is a minimal template, showing example usage of all the variables that are set by "Pod::Tree::HTML".

  <html>
   <head>
    <base href="{$base}">
    <link href="{$css}" rel="stylesheet" type="text/css">
    <title>{$title}</title>
   </head>
   <body bgcolor="{$bgcolor}" text="{$text}">
    {$toc}
    {$body}
   </body>
  </html>

The program fragments in the template are evaulted in the "Pod::Tree::HTML" package. Any variables that you set in this package will be available to your template.

When a template is used, the destination must not be an "HTML::Stream" object.

"translate" doesn't return anything. The first form always returns. The second form "die"s if there is an error creating or filling in the template.

$html->"emit_toc"

$html->"emit_body"

Emits the table of contents and body of the HTML document.

These methods are called automatically by "translate". They are exposed in the API for applications that wish to embed the HTML inside a larger document.

Options

"base" => $url

Specifies a base URL for relative HTML links.

"bgcolor" => #rrggbb

Set the background color to #rrggbb. Default is white.

"css" => $url

Specifies a Cascading Style Sheet for the generated HTML page.

"depth" => $depth

Specifies the depth of the generated HTML page in a directory tree. See "LINK MAPPING" for details.

"empty" => 1

Causes the "translate" method to emit an HTML file, even if the POD is empty. If this option is not provided, then no HTML file is created for empty PODs.

"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 mapper. See "LINK MAPPING" for details.

"text" => #rrggbb

Set the text color to #rrggbb. Default 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 destination anchors for all =headn command paragraphs, and for text items in =over lists. The text of the paragraph becomes the "name" attribute of 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 an "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 destination anchors in other places, use the index ("X<>") markup

    We can link to X<this text> this text.

and link to it as usual

    L</this text> uses the index markup.

Earlier versions of this module also emitted the content of the X<> markup as visible text. However, perlpod now specifies that X<> markups render as an empty string, so "Pod::Tree::HTML" has been changed to do that.

Link mapping

The POD specification provides the "L<>" markup to link from one document to another. HTML provides anchors ("<a href=""></a>") for the same purpose. Obviously, a POD2HTML translator should convert the first to the second.

In general, this is a hard problem. In particular, the POD format is not powerful enough to support the kind of hyper-linking that people want in a complex documentation system.

Rather than try to be all things to all people, "Pod::Tree::HTML" uses a link mapper object to translate the target of a POD link to a URL. The default link mapper does a simple translation, described below. If you don't like the default translation, you can provide your own link mapper with the ""link_map" => $link_map" option.

    sub MyMapper::new { bless {}, shift }
    sub MyMapper::url
    {
        my($mapper, $html, $target) = @_;
        ...
    return $url;
    }
    $mapper = MyMapper->new;
    $html   = Pod::Tree::HTML->new(link_map => $mapper);

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 write HTML to $dest"

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

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

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