---
name: "Pod::Tree::HTML"
section: "3pm"
platform: "linux"
package: "libpod-tree-perl"
version: "1.31-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pod::Tree::HTML"
---

# Pod::Tree::HTML(3pm)

Generate HTML from a Pod::Tree

## NAME

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

## SYNOPSIS

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

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

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

### 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"` `"die"`s.

### Destination resolution

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

- 1\.

  If *$dest* `"isa"` `"HTML::Stream"`, then `"Pod::Tree::HTML"` writes HTML to that stream.

- 2\.

  If *$dest* `"isa"` `"IO::File"`, then `"Pod::Tree::HTML"` writes HTML to that file.

- 3\.

  If *$dest* has a `"print"` method, then `"Pod::Tree::HTML"` passes HTML to that method.

- 4\.

  If *$dest* is a SCALAR reference, then `"Pod::Tree::HTML"` writes HTML to that scalar.

- 5\.

  If *$dest* is a string, then `"Pod::Tree::HTML"` writes HTML to the file with that name.

If *$dest* isn't any of these things, `"new"` `"die"`s.

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

### Utility methods

These methods are provided for implementors who write their own link mapper objects.

- *$fragment* = *$html*-\>"escape\_2396"(*$section*)

  Escapes *$section* according to RFC 2396. For example, the section

  ```
      some section
  ```

  is returned as

  ```
      some%20section
  ```

- *$url* = *$html*-\>"assemble\_url"(*$base*, *$page*, *$fragment*)

  Assembles *$base*, *$page*, and *$fragment* into a URL, of the form

  ```
      $base/$page#$fragment
  ```

  Attempts to construct a valid URL, even if some of *$base*, *$page*, and *$fragment* are empty.

## 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 =head*n* 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.

### Default

The default link mapper obtains the *page* and *section* from the target. It translates `"::"` sequences in the *page* to `"/"`, and returns a URL of the form \[`"../"`...\]\[*page*`".html"`\]\[`"#"`*section*\]

If the "`"depth"` =\> *$depth*" option is given, a corresponding number of `"../"` sequences are prepended to *page*.

This is a relative URL, so it will be interpreted relative to the "`"base"` =\> *$url*" option, if any.

### Custom

To use your own link mapper, create a link mapper object and provide it to `"Pod::Tree::HTML"` with the `"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);
```

Your object should implement one method

- *$url* = *$mapper*-\>"url"(*$html*, *$target*)

  When *$html*-\>`"translate"`() encounters an `"L<>"` markup, it calls *$mapper*-\>`"url"`. *$html* is the `"Pod::Tree::HTML"` object itself. *$target* is a `"Pod::Tree::Node"` object representing the the target of the link. See "target nodes" in Pod::Tree::Node for information on interpreting *$target*.

  The `"url"` method must return a string, which will be emitted as the value of the `"href"` attribute of an HTML anchor: `"<a href=""`*$url*`"">"`...`"</a>"`

  `"Pod:Tree:HTML"` provides the `"escape_2396"` and `"assemble_url"` methods for convenience in implementing link mappers.

If the link mapper does not provide a `"url"` method, `"Pod::Tree::HTML"` will call `"map"`

- (*$base*, *$page*, *$section*) = *$mapper*-\>"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. `"Pod::Tree::HTML"` takes the returned values and constructs a URL of the form \[*$base*/\]\[*$page*`".html"`\]\[`"#"`*$fragment*\]

The `"map"` method is

- •

  deprecated

- •

  less flexible than the `"url"` method

- •

  supported for backwards compatibility with older versions of `"Pod::Tree::HTML"`

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

## SEE ALSO

[**perl**(1)](/perl/1.md), `"Pod::Tree"`, `"Pod::Tree::Node"`,  `"Text::Template"`

## AUTHOR

Steven McDougall, swmcd@world.std.com

## COPYRIGHT

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