Marek::Pod::HTML 0.49 review

Marek::Pod::HTML is a Perl module to convert Perl POD documents to HTML. SYNOPSIS use Marek::Pod::HTML; pod2html( { -dir =

License: Perl Artistic License File size: 26K Developer: Marek Rouchal

0

Marek::Pod::HTML is a Perl module to convert Perl POD documents to HTML.

SYNOPSIS

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

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 . The heading is reserved for page titles.

=over n, =item, =back

Itemized lists are turned into either (numbered list), (buletted list), or (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) 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.

Requirements:
Perl