Pod::Tree::HTML - Generate HTML from a Pod::Tree

       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.

perl v5.36.0                                       2022-11-19                               Pod::Tree::HTML(3pm)

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

   Sourceresolution
       "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.

   Destinationresolution
       "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.

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

       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 linkmapper 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" => $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"

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

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

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

       Pod::Tree::HTML - Generate HTML from a Pod::Tree

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

       "HTML::Stream", "Text::Template"

perl(1), "Pod::Tree", "Pod::Tree::Node",  "Text::Template"

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