Pod::Tree::HTML(3pm)

💖 NAME 💖

Pod::Tree::HTML — it takes a Pod::Tree and turns it into HTML. That's the whole job, bestie, and it does it flawlessly. ✨

---

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

Look at all those ways in and all those ways out. It's giving versatile. 🦋

---

📦 REQUIRES 📦

You're gonna need HTML::Stream and Text::Template installed, or this whole thing is not gonna pop off. Periodt. 💅

---

🌸 DESCRIPTION 🌸

Pod::Tree::HTML reads a POD and translates it to HTML. The source and destination get locked in the moment the object is created — no take-backsies. After that, there's a whole pile of options for controlling the little details of the translation. 🎀

The translate method is the one that actually does the translating. It's the main character here.

For convenience, Pod::Tree::HTML can read PODs from a bunch of different sources and write HTML to a bunch of different destinations. The new method is the one that figures out what your $source and $dest arguments actually mean. iykyk.

It can also use Text::Template to fill in an HTML template file, which is lowkey iconic of it. 🧚

🔍 Source resolution 🔍

Pod::Tree::HTML can get 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's taken to be the name of a file containing a POD.
3. If $source isa IO::File, then it's 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. Like, it's over. 💀

🎯 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 dies. Same energy. 😭

---

🛠️ METHODS 🛠️

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

Creates a brand new Pod::Tree::HTML object. Fresh out the box. ✨

$html reads a POD from $source, and writes HTML to $dest. Peep "Source resolution" and "Destination resolution" above for the deets on how those get figured out.

Options that control the translation can be passed in the %options hash. Scroll down to OPTIONS for the full menu. 📋

$html->set_options(%options)

Sets the options that control the translation. See OPTIONS for details. 💅

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

Hands you back the current values of whatever options you listed in @keys. See OPTIONS for details.

$html->translate

$html->translate($template)

Translates the POD to HTML. 🎉 Heads up: this method should only be called once. Don't be greedy.

In the second form, $template is the name of a file containing a template. That template gets filled in by the Text::Template module. Here's a minimal template that shows you example usage of every variable that Pod::Tree::HTML sets:

<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 get evaluated in the Pod::Tree::HTML package. So any variables you set in that package will be available to your template. Free real estate. 🫶

When a template is used, the destination must not be an HTML::Stream object. Not negotiable, sorry. 🚫

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

$html->emit_toc

$html->emit_body

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

These two get called automatically by translate. They're exposed in the API for applications that wanna embed the HTML inside a bigger document — very "we're all in this together" of them. 🌈

🧰 Utility methods 🧰

These are for implementors who are out here writing their own link mapper objects. Respect. 👑

$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, shaped like this:

$base/$page#$fragment

It attempts to construct a valid URL even if some of $base, $page, and $fragment are empty. It's trying its best and honestly? It's doing great. 💖

---

✨ OPTIONS ✨

• base => $url — Specifies a base URL for relative HTML links. 🔗
• bgcolor => #rrggbb — Sets the background color to #rrggbb. Default is white. 🤍
• css => $url — Specifies a Cascading Style Sheet for the generated HTML page. Serving looks. 💅
• depth => $depth — Specifies the depth of the generated HTML page in a directory tree. See "LINK MAPPING" for details.
• empty => 1 — Makes the translate method emit an HTML file even if the POD is empty. If you don't pass this option, then no HTML file gets created for empty PODs. No POD, no party. 🙈
• hr => $level — Controls the profusion of horizontal lines in the output, like so:

$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 — Sets the text color to #rrggbb. Default is black. 🖤
• title => title — Sets the page title to title. If no title option is given, Pod::Tree::HTML will attempt to construct a title from the second paragraph 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. Automatic. Effortless. Iconic. ✨

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, just give the text of the heading in an L<> markup. The text has to match exactly, but 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. It grew up. 🦋

💖 LINK MAPPING 💖

okay bestie, so 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. no cap.

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. it's giving limitations, fr.

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

🎀 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), "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.

---

This page is from perl v5.36.0, dated 2022-11-19, and it's Pod::Tree::HTML(3pm). stay iconic, bestie 💖✨