Pod::Tree::HTML - 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);
HTML::Stream, Text::Template
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.
Pod::Tree::HTML can obtain a POD from any of 5 sources.
new resolves $source by checking these things,
in order:
isa POD::Tree,
then the POD is taken from that tree.
isa IO::File,
then it is taken to be an IO::File object that is already
open on a file containing a POD.
If $source isn't any of these things,
new dies.
Pod::Tree::HTML can write HTML to any of 5 destinations.
new resolves $dest by checking these things,
in order:
isa HTML::Stream,
then Pod::Tree::HTML writes HTML to that stream.
isa IO::File,
then Pod::Tree::HTML writes HTML to that file.
print method,
then Pod::Tree::HTML passes HTML to that method.
Pod::Tree::HTML writes HTML to that scalar.
Pod::Tree::HTML writes HTML to the file with that name.
If $dest isn't any of these things,
new dies.
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.
set_options(%options)
get_options(@keys)
translate
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 dies if there is an error creating or filling in the template.
emit_toc
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.
These methods are provided for implementors who write their own link mapper objects.
escape_2396($section)
Escapes $section according to RFC 2396. For example, the section
some section
is returned as
some%20section
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.
base => $url
bgcolor => #rrggbb
css => $url
depth => $depth
empty => 1
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
text => #rrggbb
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]
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.
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.
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 => $base option,
if any.
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 = new MyMapper;
$html = new Pod::Tree::HTML link_map => $mapper;
Your object should implement one method
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 Pod::Tree::Node/target nodes 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
map($base, $page, $section, $depth);
Where
base option.
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
url method
Pod::Tree::HTML
Pod::Tree::HTML::new: not enough arguments
new called with fewer than 2 arguments.
Pod::Tree::HTML::new: Can't load POD from $source
new couldn't resolve the $source argument.
See /Source resolution for details.
Pod::Tree::HTML::new: Can't write HTML to $dest
new couldn't resolve the $dest argument.
See /Destination resolution for details.
Pod::Tree::HTML::new: Can't open $dest: $!
perl(1), Pod::Tree, Pod::Tree::Node, Text::Template
Steven McDougall, swmcd@world.std.com
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.