NAME

Marek::Pod::HTML - convert Perl POD documents to HTML

SYNOPSIS

use Marek::Pod::HTML;
pod2html( { -dir => 'html' },
  { '/usr/lib/perl5/Pod/HTML.pm' => 'Pod::HTML' });

DESCRIPTION

THIS IS PRELIMINARY SOFTWARE! The Marek:: namespace is strictly preliminary until a regular place in CPAN is found.

Marek::Pod::HTML converts one or more Pod documents into individual HTML files. This is meant to be a successor of Tom Christiansen's original Pod::HTML. However it is not a plug-in replacement as there are significant differences.

When no document is specified, this script acts as a filter (from STDIN to STDOUT). No index or table of contents is generated. In any other case one or more corresponding .html file(s) is/are created.

Optionally Marek::Pod::HTML can generate a table of contents and an index. As it makes use of the HTML::Element module, it can also generate Postscript output using HTML::FormatPS.

There is a hook for customization of the translation result before writing the actual HTML.

Pod directives and their translation

The following section gives an overview of the translation equivalences.

=headn

A heading is turned into a HTML heading, e.g. =head1 corresponds to <H2>. The <H1> heading is reserved for page titles.

=over n, =item, =back

Itemized lists are turned into either <OL> (numbered list), <UL> (buletted list), or <DL> (definition list), depending on whether the first item in the list starts with a digit, a number or nothing, or anything else, respectively.

=for html, =begin html, =end

Paragraphs starting with =for html or encapsulated in =begin html are parsed as HTML and included into the document. All other =for/=begin paragraphs are ignored.

B<...>

Turned into bold text using <B>...</B>.

I<...>

Turned into italic text using <I>...</I>.

C<...> F<...>

Turned into monospaced (typewriter) text using <CODE>...</CODE>.

E<...>

Pod entities are mapped to the corresponding HTML characters or entities. The most important HTML entities (e.g. E<copy>) are recognized. See also HTML::Entities.

S<...>

All whitespace in this sequence is turned into  , i.e. non-breakable spaces.

X<...>

The text of this sequence is included in the index (along with all non-trivial =item entries), pointing to the place of its ocurrence in the text.

L<...>

Pod hyperlinks are turned into active HTML hyperlinks if the destination has been found in the Pod documents processed in this conversion session. Otherwise the link text is simply underlined.

Note: There is no caching mechanism for deliberate reasons: a) One does not run huge conversion jobs three times a day, so performance is not the most important goal, b) caching is hard to code, and c) although following conversion jobs could make profit of the existing cache of destination nodes in the already converted documents, these will not notice that some of their previously unresolved links may now be ok because the required document has been converted. Conclusion: Run pod2html over all your Pod documents after adding new ones and you will have a consistent state.

As a special unofficial feature HTML hyperlinks are also supported: L<http://www.perl.com>.

Options

mpod2html recognizes the following options. Those passed to the Marek::Pod::HTML class directly are marked with (*).

-converter module

The converter class to use, defaults to Marek::Pod::HTML. This hook allows for simple customization, see also "Customizing".

-suffix string

Use this string for links to other converted Pod documents. The default is .html and also sets the filename suffix unless -filesuffix has been specified. The dot must be included!

-filesuffix string

Use this string as a suffix for the output HTML files. This does not change the suffix used in the hyperlinks to different documents. This feature is meant to be used if some (Makefile based) postprocessing of the generated files has to be performed, but without having to adapt the links.

-dir path

Write the generated HTML files (can be a directory hierarchy) to this path. The default is the current working directory.

-libpods name1,name2,...

This option activates a highly magical feature: The =item nodes of the specified Pod documents (given by Pod name, e.g. Pod::Parser) serve as destinations for highlighted text in all converted Pod documents. Typical usage: When converting your Perl installation's documentation, you may want to say

pod2html -libpods perlfunc,perlvar,perlrun -script -inc

then you will get a hyperlink to perlvar in the text I<$|>.

-localtoc bool

This is by default true, so that at the top of the page a local table of contents with all the =headn lines is generated.

-navigation bool

When using the default customization, this flag enables or disables the navigation in the header of each Pod document.

-toc bool

If true, a table of contents is built from the processed Pod documents.

-idx bool

If true, an index is built from all =items of the processed Pod documents.

-idxopt options

Options for index building. Default is "item,x", which means that item strings as well as text marked up with X<...> generate entries in the index.

-tocname name

Use name as the filename of the table of contents. Default is podtoc. The general file suffix is added to this name.

-idxname name

Use name as the filename of the index. Default is podindex. The general file suffix is added to this name.

-toctitle string

The string that is used as the heading of the table of contents. Default is `Table of Contents'.

-idxtitle string

The string that is used as the heading of the table of contents. Default is `Index'.

-ps bool

In addition to HTML, generate also Postscript output. The suffix is .ps.

-psdir

The root directory where to write Postscript files. Defaults to the same as -dir.

-psfont fontname

Generate Postscript files using the font fontname. Default is `Helvetica'.

-papersize size

Generate Postscript files using the paper size size. Default is `A4'.

-warnings bool

When processing the first pass, print warnings. See Pod::Checker for more information on warnings. Note: This can procude a lot of output if the Pod source does not correspond to strict guidelines.

-stylesheet link

The (optional) link to a style sheet, which is included in the resulting HTML as

<LINK TYPE="text/css" REL="stylesheet" HREF=$link>

-banner bool

If true, a banner is included at the bottom of the generated page. Default is true.

OO Interface

The Marek::Pod::HTML module has an object oriented interface that allows to customize the converter for special requirements or for proprietary conversion tools. This section describes the most important methods.

new()

Create a new converter object. Idiom:

my $converter = new Marek::Pod::HTML;

customize($name)

This method is called after the complete Pod source code has been converted, thus allowing for customizations like title, navigation and footer. $name should contain the page title. This method also reads properties of the current Marek::Pod::HTML object to do the customizations. It is executed for each POD file processed and -- if enabled -- the index and the table of contents.

It is quite simple to build a proprietary customization by writing a new module that inherits from Marek::Pod::HTML:

package POD::HTML::mystyle;
use Marek::Pod::HTML qw(pod2html);
use vars qw(@ISA @EXPORT @EXPORT_OK);
require Exporter;
@ISA = qw(Marek::Pod::HTML);
@EXPORT_OK = qw(&pod2html);
sub customize {
  my ($self,$name) = @_;
  # if you just want to add things, use this line first:
  $self->SUPER::customize($name);
  # do your own things here
  #...
}

For complete customization, it is a good starting point to copy the customize method from Marek::Pod::HTML.

You can access all the converter's methods and properties through the $self-method()> and $self-{-property}> syntax, respectively.

depth()

Returns how "deep" this documents is buried in the directory hierarchy. This value is derived from the -name property and is for instance 1 for Pod::Parser.

description()

Sets or retrieves the short description from the =head1 NAME section of the Pod document. Empty if there is no such section.

indices()

Add a new item or return the list of index entries of this document. Each index is represented by an index text (in HTML) and the unique id (i.e. the anchor name) of the index entry in the HTML document.

name()

Set/retrieve the -name property, i.e. the canonical Pod name (e.g. Marek::Pod::HTML).

See the Pod/HTML.pm file for additional helper functions that you may use in your code, but beware: things may change there without notice!

SEE ALSO

Pod::Checker, Pod::Parser, Pod::Find, HTML::Element, HTML::TreeBuilder, HTML::Entities, HTML::FormatPS, HTML::Tagset, pod2man, pod2text, Pod::Man

AUTHOR

Marek Rouchal <marekr@cpan.org>

HISTORY

A big deal of this code has been recycled from a variety of existing Pod converters, e.g. by Tom Christiansen and Russ Allbery. A lot of ideas came from Nick Ing-Simmons' PodToHtml, e.g. the usage of the HTML::Element module and the HTML::FormatPS module. Without the Pod::Parser module by Brad Appleton and the HTML::Element module by Gisle Aas this module would not exist.