Generate html from a pod::tree
use Pod::Tree::HTML;
$source = new Pod::Tree %options;
$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;
$html->translate($template);
$html->emit_toc;
$html->emit_body;
$fragment = $html->escape_2396 ($section);
$url = $html->assemble_url($base, $page, $fragment);
\*(C`HTML::Stream\*(C', \*(C`Text::Template\*(C'
\*(C`Pod::Tree::HTML\*(C' reads a \s-1POD\s0 and translates it to \s-1HTML\s0. The source and destination are fixed when the object is created. Options are provided for controlling details of the translation.
The \*(C`translate\*(C' method does the actual translation.
For convenience, \*(C`Pod::Tree::HTML\*(C' can read PODs from a variety of sources, and write \s-1HTML\s0 to a variety of destinations. The \*(C`new\*(C' method resolves the $source and $dest arguments.
\*(C`Pod::Tree::HTML\*(C' can also use \*(C`Text::Template\*(C' to fill in an \s-1HTML\s0 template file.
\*(C`Pod::Tree::HTML\*(C' can obtain a \s-1POD\s0 from any of 5 sources. \*(C`new\*(C' resolves $source by checking these things, in order:
If $source \*(C`isa\*(C' \*(C`POD::Tree\*(C', then the \s-1POD\s0 is taken from that tree.
If $source is not a reference, then it is taken to be the name of a file containing a \s-1POD\s0.
If $source \*(C`isa\*(C' \*(C`IO::File\*(C', then it is taken to be an \*(C`IO::File\*(C' object that is already open on a file containing a \s-1POD\s0.
If $source is a \s-1SCALAR\s0 reference, then the text of the \s-1POD\s0 is taken from that scalar.
if $source is an \s-1ARRAY\s0 reference, then the paragraphs of the \s-1POD\s0 are taken from that array.
If $source isn't any of these things, \*(C`new\*(C' \*(C`die\*(C's.
\*(C`Pod::Tree::HTML\*(C' can write \s-1HTML\s0 to any of 5 destinations. \*(C`new\*(C' resolves $dest by checking these things, in order:
If $dest \*(C`isa\*(C' \*(C`HTML::Stream\*(C', then \*(C`Pod::Tree::HTML\*(C' writes \s-1HTML\s0 to that stream.
If $dest \*(C`isa\*(C' \*(C`IO::File\*(C', then \*(C`Pod::Tree::HTML\*(C' writes \s-1HTML\s0 to that file.
If $dest has a \*(C`print\*(C' method, then \*(C`Pod::Tree::HTML\*(C' passes \s-1HTML\s0 to that method.
If $dest is a \s-1SCALAR\s0 reference, then \*(C`Pod::Tree::HTML\*(C' writes \s-1HTML\s0 to that scalar.
If $dest is a string, then \*(C`Pod::Tree::HTML\*(C' writes \s-1HTML\s0 to the file with that name.
If $dest isn't any of these things, \*(C`new\*(C' \*(C`die\*(C's.
Creates a new \*(C`Pod::Tree::HTML\*(C' object. $html reads a \s-1POD\s0 from $source, and writes \s-1HTML\s0 to $dest. See \*(L"Source resolution\*(R" and \*(L"Destination resolution\*(R" for details. Options controlling the translation may be passed in the %options hash. See \*(L"\s-1OPTIONS\s0\*(R" for details. Sets options controlling the translation. See \*(L"\s-1OPTIONS\s0\*(R" for details. Returns the current values of the options specified in @keys. See \*(L"\s-1OPTIONS\s0\*(R" for details. Translates the \s-1POD\s0 to \s-1HTML\s0. 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 \*(C`Text::Template\*(C' module. Here is a minimal template, showing example usage of all the variables that are set by \*(C`Pod::Tree::HTML\*(C'. <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 \*(C`Pod::Tree::HTML\*(C' 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 \*(C`HTML::Stream\*(C' object. \*(C`translate\*(C' doesn't return anything. The first form always returns. The second form \*(C`die\*(C's if there is an error creating or filling in the template. Emits the table of contents and body of the \s-1HTML\s0 document. These methods are called automatically by \*(C`translate\*(C'. They are exposed in the \s-1API\s0 for applications that wish to embed the \s-1HTML\s0 inside a larger document.
These methods are provided for implementors who write their own link mapper objects. Escapes $section according to \s-1RFC\s0 2396. For example, the section some section is returned as some%20section Assembles $base, $page, and $fragment into a \s-1URL\s0, of the form $base/$page#$fragment Attempts to construct a valid \s-1URL\s0, even if some of $base, $page, and $fragment are empty.
Specifies a base \s-1URL\s0 for relative \s-1HTML\s0 links. Set the background color to #rrggbb. Default is white. Specifies a Cascading Style Sheet for the generated \s-1HTML\s0 page. Specifies the depth of the generated \s-1HTML\s0 page in a directory tree. See \*(L"\s-1LINK\s0 \s-1MAPPING\s0\*(R" for details. Causes the \*(C`translate\*(C' method to emit an \s-1HTML\s0 file, even if the \s-1POD\s0 is empty. If this option is not provided, then no \s-1HTML\s0 file is created for empty PODs. 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. Sets the link mapper. See \*(L"\s-1LINK\s0 \s-1MAPPING\s0\*(R" for details. Set the text color to #rrggbb. Default is black. Set the page title to title. If no \*(C`title\*(C' option is given, \*(C`Pod::Tree::HTML\*(C' will attempt construct a title from the second paragrah of the \s-1POD\s0. This supports the following style: =head1 NAME
ls - list contents of directory Includes or omits the table of contents. Default is to include the \s-1TOC\s0.
\*(C`Pod::Tree::HTML\*(C' automatically generates \s-1HTML\s0 destination anchors for all =headn command paragraphs, and for text items in =over lists. The text of the paragraph becomes the \*(C`name\*(C' attribute of the anchor. Markups are ignored and the text is escaped according to \s-1RFC\s0 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 \*(C`L<>\*(C' 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 (\*(C`X<>\*(C') 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 \*(C`Pod::Tree::HTML\*(C' has been changed to do that.
The \s-1POD\s0 specification provides the \*(C`L<>\*(C' markup to link from one document to another. \s-1HTML\s0 provides anchors (\*(C`<a href=""></a>\*(C') for the same purpose. Obviously, a \s-1POD2HTML\s0 translator should convert the first to the second.
In general, this is a hard problem. In particular, the \s-1POD\s0 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, \*(C`Pod::Tree::HTML\*(C' uses a link mapper object to translate the target of a \s-1POD\s0 link to a \s-1URL\s0. 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 "\*(C`link_map\*(C' => $link_map" option.
The default link mapper obtains the page and section from the target. It translates \*(C`::\*(C' sequences in the page to \*(C`/\*(C', and returns a \s-1URL\s0 of the form [\*(C`../\*(C'...][page\*(C`.html\*(C'][\*(C`#\*(C'section]
If the "\*(C`depth\*(C' => $depth" option is given, a corresponding number of \*(C`../\*(C' sequences are prepended to page.
This is a relative \s-1URL\s0, so it will be interpreted relative to the "\*(C`base\*(C' => $base" option, if any.
To use your own link mapper, create a link mapper object and provide it to \*(C`Pod::Tree::HTML\*(C' with the \*(C`link_map\*(C' option
sub MyMapper::new { bless {}, shift }
sub MyMapper::url { my($mapper, $html, $target) = @_; ... return $url; }
$mapper = new MyMapper; $html = new Pod::Tree::HTML link_map => $mapper;
Your object should implement one method When $html->\*(C`translate\*(C'() encounters an \*(C`L<>\*(C' markup, it calls $mapper->\*(C`url\*(C'. $html is the \*(C`Pod::Tree::HTML\*(C' object itself. $target is a \*(C`Pod::Tree::Node\*(C' object representing the the target of the link. See \*(L"target nodes\*(R" in Pod::Tree::Node for information on interpreting $target. The \*(C`url\*(C' method must return a string, which will be emitted as the value of the \*(C`href\*(C' attribute of an \s-1HTML\s0 anchor: \*(C`<a href="\*(C'$url\*(C`">\*(C'...\*(C`</a>\*(C' \*(C`Pod:Tree:HTML\*(C' provides the \*(C`escape_2396\*(C' and \*(C`assemble_url\*(C' methods for convenience in implementing link mappers.
If the link mapper does not provide a \*(C`url\*(C' method, \*(C`Pod::Tree::HTML\*(C' will call \*(C`map\*(C' Where
is the \s-1URL\s0 given in the \*(C`base\*(C' option. is the man page named in the L<> markup. is the man page section given in the L<> markup. is the value of the \*(C`depth\*(C' option.
The \*(C`map\*(C' method may perform arbitrary mappings on its arguments. \*(C`Pod::Tree::HTML\*(C' takes the returned values and constructs a \s-1URL\s0 of the form [$base/][$page\*(C`.html\*(C'][\*(C`#\*(C'$fragment]
The \*(C`map\*(C' method is
deprecated
less flexible than the \*(C`url\*(C' method
supported for backwards compatibility with older versions of \*(C`Pod::Tree::HTML\*(C'
(F) \*(C`new\*(C' called with fewer than 2 arguments. (F) \*(C`new\*(C' couldn't resolve the $source argument. See \*(L"Source resolution\*(R" for details. (F) \*(C`new\*(C' couldn't resolve the $dest argument. See \*(L"Destination resolution\*(R" for details. (F) The destination file couldn't be opened.
perl\|(1), \*(C`Pod::Tree\*(C', \*(C`Pod::Tree::Node\*(C', \*(C`Text::Template\*(C'
Steven McDougall, [email protected]
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.