NAME¶
Pod::Tree::HTML - Generate HTML from a Pod::Tree
SYNOPSIS¶
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);
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" =>
$base" 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 = new MyMapper;
$html = new Pod::Tree::HTML 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.