.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pod::Tree::HTML 3pm"
.TH Pod::Tree::HTML 3pm "2019-02-25" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::Tree::HTML \- Generate HTML from a Pod::Tree
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Pod::Tree::HTML;
\&
\&  $source   =   Pod::Tree\->new(%options);
\&  $source   =  "file.pod";
\&  $source   =   IO::File\->new;
\&  $source   = \e$pod;
\&  $source   = \e@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);
.Ve
.SH "REQUIRES"
.IX Header "REQUIRES"
\&\f(CW\*(C`HTML::Stream\*(C'\fR, \f(CW\*(C`Text::Template\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR 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.
.PP
The \f(CW\*(C`translate\*(C'\fR method does the actual translation.
.PP
For convenience,
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR can read PODs from a variety of sources,
and write \s-1HTML\s0 to a variety of destinations.
The \f(CW\*(C`new\*(C'\fR method resolves the \fI\f(CI$source\fI\fR and \fI\f(CI$dest\fI\fR arguments.
.PP
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR can also use \f(CW\*(C`Text::Template\*(C'\fR to fill in an \s-1HTML\s0
template file.
.SS "Source resolution"
.IX Subsection "Source resolution"
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR can obtain a \s-1POD\s0 from any of 5 sources.
\&\f(CW\*(C`new\*(C'\fR resolves \fI\f(CI$source\fI\fR by checking these things,
in order:
.IP "1." 4
If \fI\f(CI$source\fI\fR \f(CW\*(C`isa\*(C'\fR \f(CW\*(C`POD::Tree\*(C'\fR,
then the \s-1POD\s0 is taken from that tree.
.IP "2." 4
If \fI\f(CI$source\fI\fR is not a reference,
then it is taken to be the name of a file containing a \s-1POD.\s0
.IP "3." 4
If \fI\f(CI$source\fI\fR \f(CW\*(C`isa\*(C'\fR \f(CW\*(C`IO::File\*(C'\fR,
then it is taken to be an \f(CW\*(C`IO::File\*(C'\fR object that is already
open on a file containing a \s-1POD.\s0
.IP "4." 4
If \fI\f(CI$source\fI\fR is a \s-1SCALAR\s0 reference,
then the text of the \s-1POD\s0 is taken from that scalar.
.IP "5." 4
if \fI\f(CI$source\fI\fR is an \s-1ARRAY\s0 reference,
then the paragraphs of the \s-1POD\s0 are taken from that array.
.PP
If \fI\f(CI$source\fI\fR isn't any of these things,
\&\f(CW\*(C`new\*(C'\fR \f(CW\*(C`die\*(C'\fRs.
.SS "Destination resolution"
.IX Subsection "Destination resolution"
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR can write \s-1HTML\s0 to any of 5 destinations.
\&\f(CW\*(C`new\*(C'\fR resolves \fI\f(CI$dest\fI\fR by checking these things,
in order:
.IP "1." 4
If \fI\f(CI$dest\fI\fR \f(CW\*(C`isa\*(C'\fR \f(CW\*(C`HTML::Stream\*(C'\fR,
then \f(CW\*(C`Pod::Tree::HTML\*(C'\fR writes \s-1HTML\s0 to that stream.
.IP "2." 4
If \fI\f(CI$dest\fI\fR \f(CW\*(C`isa\*(C'\fR \f(CW\*(C`IO::File\*(C'\fR,
then \f(CW\*(C`Pod::Tree::HTML\*(C'\fR writes \s-1HTML\s0 to that file.
.IP "3." 4
If \fI\f(CI$dest\fI\fR has a \f(CW\*(C`print\*(C'\fR method,
then \f(CW\*(C`Pod::Tree::HTML\*(C'\fR passes \s-1HTML\s0 to that method.
.IP "4." 4
If \fI\f(CI$dest\fI\fR is a \s-1SCALAR\s0 reference,
then \f(CW\*(C`Pod::Tree::HTML\*(C'\fR writes \s-1HTML\s0 to that scalar.
.IP "5." 4
If \fI\f(CI$dest\fI\fR is a string,
then \f(CW\*(C`Pod::Tree::HTML\*(C'\fR writes \s-1HTML\s0 to the file with that name.
.PP
If \fI\f(CI$dest\fI\fR isn't any of these things,
\&\f(CW\*(C`new\*(C'\fR \f(CW\*(C`die\*(C'\fRs.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "\fI\f(CI$html\fI\fR = ""new"" ""Pod::Tree::HTML"" \fI\f(CI$source\fI\fR, \fI\f(CI$dest\fI\fR, \fI\f(CI%options\fI\fR" 4
.el .IP "\fI\f(CI$html\fI\fR = \f(CWnew\fR \f(CWPod::Tree::HTML\fR \fI\f(CI$source\fI\fR, \fI\f(CI$dest\fI\fR, \fI\f(CI%options\fI\fR" 4
.IX Item "$html = new Pod::Tree::HTML $source, $dest, %options"
Creates a new \f(CW\*(C`Pod::Tree::HTML\*(C'\fR object.
.Sp
\&\fI\f(CI$html\fI\fR reads a \s-1POD\s0 from \fI\f(CI$source\fI\fR,
and writes \s-1HTML\s0 to \fI\f(CI$dest\fI\fR.
See \*(L"Source resolution\*(R" and \*(L"Destination resolution\*(R" for details.
.Sp
Options controlling the translation may be passed in the \fI\f(CI%options\fI\fR hash.
See \*(L"\s-1OPTIONS\*(R"\s0 for details.
.ie n .IP "\fI\f(CI$html\fI\fR\->""set_options""(\fI\f(CI%options\fI\fR)" 4
.el .IP "\fI\f(CI$html\fI\fR\->\f(CWset_options\fR(\fI\f(CI%options\fI\fR)" 4
.IX Item "$html->set_options(%options)"
Sets options controlling the translation.
See \*(L"\s-1OPTIONS\*(R"\s0 for details.
.ie n .IP "\fI\f(CI@values\fI\fR = \fI\f(CI$html\fI\fR\->""get_options""(\fI\f(CI@keys\fI\fR)" 4
.el .IP "\fI\f(CI@values\fI\fR = \fI\f(CI$html\fI\fR\->\f(CWget_options\fR(\fI\f(CI@keys\fI\fR)" 4
.IX Item "@values = $html->get_options(@keys)"
Returns the current values of the options specified in \fI\f(CI@keys\fI\fR.
See \*(L"\s-1OPTIONS\*(R"\s0 for details.
.ie n .IP "\fI\f(CI$html\fI\fR\->""translate""" 4
.el .IP "\fI\f(CI$html\fI\fR\->\f(CWtranslate\fR" 4
.IX Item "$html->translate"
.PD 0
.ie n .IP "\fI\f(CI$html\fI\fR\->""translate""(\fI\f(CI$template\fI\fR)" 4
.el .IP "\fI\f(CI$html\fI\fR\->\f(CWtranslate\fR(\fI\f(CI$template\fI\fR)" 4
.IX Item "$html->translate($template)"
.PD
Translates the \s-1POD\s0 to \s-1HTML.\s0
This method should only be called once.
.Sp
In the second form,
\&\fI\f(CI$template\fI\fR is the name of a file containing a template.
The template will be filled in by the \f(CW\*(C`Text::Template\*(C'\fR module.
Here is a minimal template,
showing example usage of all the variables that are set by \f(CW\*(C`Pod::Tree::HTML\*(C'\fR.
.Sp
.Vb 11
\&  <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>
.Ve
.Sp
The program fragments in the template are evaulted in the \f(CW\*(C`Pod::Tree::HTML\*(C'\fR package.
Any variables that you set in this package will be available to your template.
.Sp
When a template is used, the destination must not be an \f(CW\*(C`HTML::Stream\*(C'\fR object.
.Sp
\&\f(CW\*(C`translate\*(C'\fR doesn't return anything.
The first form always returns.
The second form \f(CW\*(C`die\*(C'\fRs if there is an error creating or filling in the template.
.ie n .IP "\fI\f(CI$html\fI\fR\->""emit_toc""" 4
.el .IP "\fI\f(CI$html\fI\fR\->\f(CWemit_toc\fR" 4
.IX Item "$html->emit_toc"
.PD 0
.ie n .IP "\fI\f(CI$html\fI\fR\->""emit_body""" 4
.el .IP "\fI\f(CI$html\fI\fR\->\f(CWemit_body\fR" 4
.IX Item "$html->emit_body"
.PD
Emits the table of contents and body of the \s-1HTML\s0 document.
.Sp
These methods are called automatically by \f(CW\*(C`translate\*(C'\fR.
They are exposed in the \s-1API\s0 for applications that wish to embed the
\&\s-1HTML\s0 inside a larger document.
.SS "Utility methods"
.IX Subsection "Utility methods"
These methods are provided for implementors who write their own link
mapper objects.
.ie n .IP "\fI\f(CI$fragment\fI\fR = \fI\f(CI$html\fI\fR\->""escape_2396""(\fI\f(CI$section\fI\fR)" 4
.el .IP "\fI\f(CI$fragment\fI\fR = \fI\f(CI$html\fI\fR\->\f(CWescape_2396\fR(\fI\f(CI$section\fI\fR)" 4
.IX Item "$fragment = $html->escape_2396($section)"
Escapes \fI\f(CI$section\fI\fR according to \s-1RFC 2396.\s0 For example, the section
.Sp
.Vb 1
\&    some section
.Ve
.Sp
is returned as
.Sp
.Vb 1
\&    some%20section
.Ve
.ie n .IP "\fI\f(CI$url\fI\fR = \fI\f(CI$html\fI\fR\->""assemble_url""(\fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, \fI\f(CI$fragment\fI\fR)" 4
.el .IP "\fI\f(CI$url\fI\fR = \fI\f(CI$html\fI\fR\->\f(CWassemble_url\fR(\fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, \fI\f(CI$fragment\fI\fR)" 4
.IX Item "$url = $html->assemble_url($base, $page, $fragment)"
Assembles \fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, and \fI\f(CI$fragment\fI\fR into a \s-1URL,\s0 of the form
.Sp
.Vb 1
\&    $base/$page#$fragment
.Ve
.Sp
Attempts to construct a valid \s-1URL,\s0 even if some of \fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR,
and \fI\f(CI$fragment\fI\fR are empty.
.SH "OPTIONS"
.IX Header "OPTIONS"
.ie n .IP """base"" => \fI\f(CI$url\fI\fR" 4
.el .IP "\f(CWbase\fR => \fI\f(CI$url\fI\fR" 4
.IX Item "base => $url"
Specifies a base \s-1URL\s0 for relative \s-1HTML\s0 links.
.ie n .IP """bgcolor"" => \fI#rrggbb\fR" 4
.el .IP "\f(CWbgcolor\fR => \fI#rrggbb\fR" 4
.IX Item "bgcolor => #rrggbb"
Set the background color to \fI#rrggbb\fR.
Default is white.
.ie n .IP """css"" => \fI\f(CI$url\fI\fR" 4
.el .IP "\f(CWcss\fR => \fI\f(CI$url\fI\fR" 4
.IX Item "css => $url"
Specifies a Cascading Style Sheet for the generated \s-1HTML\s0 page.
.ie n .IP """depth"" => \fI\f(CI$depth\fI\fR" 4
.el .IP "\f(CWdepth\fR => \fI\f(CI$depth\fI\fR" 4
.IX Item "depth => $depth"
Specifies the depth of the generated \s-1HTML\s0 page in a directory tree.
See \*(L"\s-1LINK MAPPING\*(R"\s0 for details.
.ie n .IP """empty"" => 1" 4
.el .IP "\f(CWempty\fR => \f(CW1\fR" 4
.IX Item "empty => 1"
Causes the \f(CW\*(C`translate\*(C'\fR 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.
.ie n .IP """hr"" => \fI\f(CI$level\fI\fR" 4
.el .IP "\f(CWhr\fR => \fI\f(CI$level\fI\fR" 4
.IX Item "hr => $level"
Controls the profusion of horizontal lines in the output, as follows:
.Sp
.Vb 5
\&    $level   horizontal lines
\&    0          none
\&    1          between TOC and body
\&    2          after each =head1
\&    3          after each =head1 and =head2
.Ve
.Sp
Default is level 1.
.ie n .IP """link_map"" => \fI\f(CI$link_map\fI\fR" 4
.el .IP "\f(CWlink_map\fR => \fI\f(CI$link_map\fI\fR" 4
.IX Item "link_map => $link_map"
Sets the link mapper.
See \*(L"\s-1LINK MAPPING\*(R"\s0 for details.
.ie n .IP """text"" => \fI#rrggbb\fR" 4
.el .IP "\f(CWtext\fR => \fI#rrggbb\fR" 4
.IX Item "text => #rrggbb"
Set the text color to \fI#rrggbb\fR.
Default is black.
.ie n .IP """title"" => \fItitle\fR" 4
.el .IP "\f(CWtitle\fR => \fItitle\fR" 4
.IX Item "title => title"
Set the page title to \fItitle\fR.
If no \f(CW\*(C`title\*(C'\fR option is given,
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR will attempt construct a title from the
second paragrah of the \s-1POD.\s0
This supports the following style:
.Sp
.Vb 1
\&    =head1 NAME
\&
\&    ls \- list contents of directory
.Ve
.ie n .IP """toc"" => [0|1]" 4
.el .IP "\f(CWtoc\fR => [\f(CW0\fR|\f(CW1\fR]" 4
.IX Item "toc => [0|1]"
Includes or omits the table of contents.
Default is to include the \s-1TOC.\s0
.SH "LINKS and TARGETS"
.IX Header "LINKS and TARGETS"
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR automatically generates \s-1HTML\s0 destination anchors for
all =head\fIn\fR command paragraphs,
and for text items in =over lists.
The text of the paragraph becomes the \f(CW\*(C`name\*(C'\fR attribute of the anchor.
Markups are ignored and the text is escaped according to \s-1RFC 2396.\s0
.PP
For example, the paragraph
.PP
.Vb 1
\&    =head1 C<Foo> Bar
.Ve
.PP
is translated to
.PP
.Vb 1
\&    <h1><a name="Foo%20Bar"><code>Foo</code> Bar</a></h1>
.Ve
.PP
To link to a heading,
simply give the text of the heading in an \f(CW\*(C`L<>\*(C'\fR markup.
The text must match exactly;
markups may vary.
Either of these would link to the heading shown above
.PP
.Vb 2
\&    L</C<Foo> Bar>
\&    L</Foo Bar>
.Ve
.PP
To generate destination anchors in other places,
use the index (\f(CW\*(C`X<>\*(C'\fR) markup
.PP
.Vb 1
\&    We can link to X<this text> this text.
.Ve
.PP
and link to it as usual
.PP
.Vb 1
\&    L</this text> uses the index markup.
.Ve
.PP
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 \f(CW\*(C`Pod::Tree::HTML\*(C'\fR has been
changed to do that.
.SH "LINK MAPPING"
.IX Header "LINK MAPPING"
The \s-1POD\s0 specification provides the \f(CW\*(C`L<>\*(C'\fR markup to link from
one document to another. \s-1HTML\s0 provides anchors (\f(CW\*(C`<a href=""></a>\*(C'\fR)
for the same purpose. Obviously, a \s-1POD2HTML\s0 translator should
convert the first to the second.
.PP
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.
.PP
Rather than try to be all things to all people,
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR uses a \fIlink mapper\fR 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 "\f(CW\*(C`link_map\*(C'\fR => \fI\f(CI$link_map\fI\fR" option.
.SS "Default"
.IX Subsection "Default"
The default link mapper obtains the \fIpage\fR and \fIsection\fR from the target.
It translates \f(CW\*(C`::\*(C'\fR sequences in the \fIpage\fR to \f(CW\*(C`/\*(C'\fR,
and returns a \s-1URL\s0 of the form [\f(CW\*(C`../\*(C'\fR...][\fIpage\fR\f(CW\*(C`.html\*(C'\fR][\f(CW\*(C`#\*(C'\fR\fIsection\fR]
.PP
If the "\f(CW\*(C`depth\*(C'\fR => \fI\f(CI$depth\fI\fR" option is given,
a corresponding number of \f(CW\*(C`../\*(C'\fR sequences are prepended to \fIpage\fR.
.PP
This is a relative \s-1URL,\s0
so it will be interpreted relative to the "\f(CW\*(C`base\*(C'\fR => \fI\f(CI$url\fI\fR" option,
if any.
.SS "Custom"
.IX Subsection "Custom"
To use your own link mapper,
create a link mapper object and provide it to \f(CW\*(C`Pod::Tree::HTML\*(C'\fR
with the \f(CW\*(C`link_map\*(C'\fR option
.PP
.Vb 1
\&    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);
.Ve
.PP
Your object should implement one method
.ie n .IP "\fI\f(CI$url\fI\fR = \fI\f(CI$mapper\fI\fR\->""url""(\fI\f(CI$html\fI\fR, \fI\f(CI$target\fI\fR)" 4
.el .IP "\fI\f(CI$url\fI\fR = \fI\f(CI$mapper\fI\fR\->\f(CWurl\fR(\fI\f(CI$html\fI\fR, \fI\f(CI$target\fI\fR)" 4
.IX Item "$url = $mapper->url($html, $target)"
When \fI\f(CI$html\fI\fR\->\f(CW\*(C`translate\*(C'\fR() encounters an \f(CW\*(C`L<>\*(C'\fR markup,
it calls \fI\f(CI$mapper\fI\fR\->\f(CW\*(C`url\*(C'\fR.
\&\fI\f(CI$html\fI\fR is the \f(CW\*(C`Pod::Tree::HTML\*(C'\fR object itself.
\&\fI\f(CI$target\fI\fR is a \f(CW\*(C`Pod::Tree::Node\*(C'\fR object representing the
the target of the link.
See \*(L"target nodes\*(R" in Pod::Tree::Node for information on interpreting \fI\f(CI$target\fI\fR.
.Sp
The \f(CW\*(C`url\*(C'\fR method must return a string,
which will be emitted as the value of the \f(CW\*(C`href\*(C'\fR attribute of an \s-1HTML\s0
anchor: \f(CW\*(C`<a href="\*(C'\fR\fI\f(CI$url\fI\fR\f(CW\*(C`">\*(C'\fR...\f(CW\*(C`</a>\*(C'\fR
.Sp
\&\f(CW\*(C`Pod:Tree:HTML\*(C'\fR provides the \f(CW\*(C`escape_2396\*(C'\fR and \f(CW\*(C`assemble_url\*(C'\fR
methods for convenience in implementing link mappers.
.PP
If the link mapper does not provide a \f(CW\*(C`url\*(C'\fR method,
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR will call \f(CW\*(C`map\*(C'\fR
.ie n .IP "(\fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, \fI\f(CI$section\fI\fR) = \fI\f(CI$mapper\fI\fR\->""map""(\fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, \fI\f(CI$section\fI\fR, \fI\f(CI$depth\fI\fR);" 4
.el .IP "(\fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, \fI\f(CI$section\fI\fR) = \fI\f(CI$mapper\fI\fR\->\f(CWmap\fR(\fI\f(CI$base\fI\fR, \fI\f(CI$page\fI\fR, \fI\f(CI$section\fI\fR, \fI\f(CI$depth\fI\fR);" 4
.IX Item "($base, $page, $section) = $mapper->map($base, $page, $section, $depth);"
Where
.RS 4
.IP "\fI\f(CI$base\fI\fR" 4
.IX Item "$base"
is the \s-1URL\s0 given in the \f(CW\*(C`base\*(C'\fR option.
.IP "\fI\f(CI$page\fI\fR" 4
.IX Item "$page"
is the man page named in the L<> markup.
.IP "\fI\f(CI$section\fI\fR" 4
.IX Item "$section"
is the man page section given in the L<> markup.
.IP "\fI\f(CI$depth\fI\fR" 4
.IX Item "$depth"
is the value of the \f(CW\*(C`depth\*(C'\fR option.
.RE
.RS 4
.Sp
The \f(CW\*(C`map\*(C'\fR method may perform arbitrary mappings on its arguments.
\&\f(CW\*(C`Pod::Tree::HTML\*(C'\fR takes the returned values and constructs a \s-1URL\s0
of the form [\fI\f(CI$base\fI\fR/][\fI\f(CI$page\fI\fR\f(CW\*(C`.html\*(C'\fR][\f(CW\*(C`#\*(C'\fR\fI\f(CI$fragment\fI\fR]
.RE
.PP
The \f(CW\*(C`map\*(C'\fR method is
.IP "\(bu" 4
deprecated
.IP "\(bu" 4
less flexible than the \f(CW\*(C`url\*(C'\fR method
.IP "\(bu" 4
supported for backwards compatibility with
older versions of \f(CW\*(C`Pod::Tree::HTML\*(C'\fR
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """Pod::Tree::HTML::new: not enough arguments""" 4
.el .IP "\f(CWPod::Tree::HTML::new: not enough arguments\fR" 4
.IX Item "Pod::Tree::HTML::new: not enough arguments"
(F) \f(CW\*(C`new\*(C'\fR called with fewer than 2 arguments.
.ie n .IP """Pod::Tree::HTML::new: Can\*(Aqt load POD from $source""" 4
.el .IP "\f(CWPod::Tree::HTML::new: Can\*(Aqt load POD from $source\fR" 4
.IX Item "Pod::Tree::HTML::new: Cant load POD from $source"
(F) \f(CW\*(C`new\*(C'\fR couldn't resolve the \fI\f(CI$source\fI\fR argument.
See \*(L"Source resolution\*(R" for details.
.ie n .IP """Pod::Tree::HTML::new: Can\*(Aqt write HTML to $dest""" 4
.el .IP "\f(CWPod::Tree::HTML::new: Can\*(Aqt write HTML to $dest\fR" 4
.IX Item "Pod::Tree::HTML::new: Cant write HTML to $dest"
(F) \f(CW\*(C`new\*(C'\fR couldn't resolve the \fI\f(CI$dest\fI\fR argument.
See \*(L"Destination resolution\*(R" for details.
.ie n .IP """Pod::Tree::HTML::new: Can\*(Aqt open $dest: $!""" 4
.el .IP "\f(CWPod::Tree::HTML::new: Can\*(Aqt open $dest: $!\fR" 4
.IX Item "Pod::Tree::HTML::new: Cant open $dest: $!"
(F) The destination file couldn't be opened.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \f(CW\*(C`Pod::Tree\*(C'\fR, \f(CW\*(C`Pod::Tree::Node\*(C'\fR,  \f(CW\*(C`Text::Template\*(C'\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Steven McDougall, swmcd@world.std.com
.SH "COPYRIGHT"
.IX Header "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.