Developer

How do I... Convert Perl's POD to HTML?

This article will show you how to use some of CPAN's tools to prepare your POD data for online publication in HTML format. Try it out -- you'll be surprised at how easy it is to complete the conversion process.

One of the nicer things about Perl is its Plain Old Documentation (POD) format for code documentation. This format provides a framework for code explanation and formatting, using friendly and intuitive directives to make code documentation a relatively painless process.

CPAN's wide array of POD manipulation tools allow you to parse POD documentation, convert it to different formats, and automatically check it for errors. This article will show you how to use some of CPAN's tools to prepare your POD data for online publication in HTML format. I use three CPAN modules: POD::Checker, Test::Spelling, and Pod::2::html.

Create a sample Perl module

First, download and install POD::Checker, Test::Spelling, and Pod::2::html by running the following commands at your Perl prompt:

perl> perl -MCPAN -e "install POD::Checker"

perl> perl -MCPAN -e "install Test::Spelling"

perl> perl -MCPAN -e "install Pod::2::html"

You can also manually download and install these modules from CPAN: POD::Checker, Test::Spelling, and Pod::2::html.

Next, type the following code to create a dummy Perl module (named Module.pm), which will serve as an example for the steps that follow. Note: This module contains deliberate errors to start with for illustrative purposes.
package My::Module;

use strict; use warnings;

1;

=pod

=head1 NAME

My::Module - an eample module on POD

=head1 VERSION

This documentation refers to My::Module version 0.1

=head1 SYNOPSIS"

    use My::Module;

    # create the object

    my $module = My::Module->new();

    # login to the service

    $module->login({

        email => 'email@domain.com',

        password => 'password',

    });

    # lets turn debugging on

    $module->debug(1);

    # get credit balance

    my $balance = $module->get_balance();

    print "Balance is $balancen";

=head1 DESCRIPTION

This module does absolutely nothing, and is just an example of how to write POD documentation!

=head1 METHODS

=head2 new()

=over 4

The constructor for this module

=back

=head2 login()

=over 4

Log in to the service

=back

=head2 debug()

=over 4

Set this to 1 to show debug output

=back

=head2 get_balance()

=over 4

Get the current account balance

=back

=head1 LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or

modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Now that the module is created, let's take the first step to publishing it as HTML.

Step 1: Check your POD syntax

A critical step before converting your POD data to HTML is to ensure that the data contains no structural or syntax errors. The easiest way to verify this is with CPAN's POD::Checker module, which looks for syntax errors in a supplied POD file. Here's the code:

#!/usr/bin/perl

use strict; use warnings;

use Pod::Checker;

# The POD file path is sent as a command line argument

my $pod_file = shift or die "Specify POD file as command line argumentn";

# Create checker object

my $checker = Pod::Checker->new();

# Parse the POD file, with errors sent to STDERR

$checker->parse_from_file($pod_file, *STDERR);

The script is quite self-explanatory: It creates a new Pod::Checker object and then calls the parse_from_file() method. This sends all errors (including warnings) to STDERR, usually the console.

When you run this script on the (deliberately broken) module created earlier, POD::Checker will find a number of syntax errors in the file. Here's a sample of the output:

shell> ./checker.pl Module.pm

*** WARNING: No items in =over (at line 48) / =back list at line 52 in file Module_errors.pm

*** WARNING: No items in =over (at line 56) / =back list at line 60 in file Module_errors.pm

*** WARNING: No items in =over (at line 64) / =back list at line 68 in file Module_errors.pm

*** WARNING: No items in =over (at line 72) / =back list at line 76 in file Module_errors.pm

This message indicates that, as per POD's syntax rules, any =over block should contain one or more =item commands. Make the correction and proceed to the next step.

Step 2: Check your POD content for spelling errors

Once you ensure your POD grammar is correct, it's time to look for spelling errors. CPAN's Test::Spelling module is the best tool for this task, as it can call the external spell program to identify misspelled words in a POD file. Here's the code:

#!/usr/bin/perl

use strict; use warnings;

use Test::Spelling;

use Test::More tests => 1;

my $pod_file = shift or die "Specify POD file as srgumentn";

pod_file_spelling_ok($pod_file, 'POD spelling');

This code imports the required modules, specifies the number of tests, and calls pod_file_spelling_ok() with the name of the file to be tested and the name of the test.

A close look at the POD created earlier reveals that it contains two spelling errors: eample and LICENCE. When you run the above script, Test::Spelling will find and flag both of these errors, which the resulting output illustrates:

shell> ./spellchecker.pl Module.pm
1..1

not ok 1 - POD spelling

#   Failed test 'POD spelling'

#   in ./spellchecker.pl at line 9.

# Errors:

#     LICENCE

#     eample

# Looks like you failed 1 test of 1.

Make the corrections and move on to the third and final step.

Step 3: Convert your POD to HTML

Assuming you corrected the errors discovered in the preceding two steps, your revised POD file should look something like this:

package My::Module;

use strict; use warnings;

1;

=pod

=head1 NAME

My::Module - an example module on POD

=head1 VERSION

This documentation refers to My::Module version 0.1

=head1 SYNOPSIS

    use My::Module;

    # create the object

    my $module = My::Module->new();

    # login to the service

    $module->login({

        email => 'email@domain.com',

        password => 'password',

    });

    # lets turn debugging on

    $module->debug(1);

    # get credit balance

    my $balance = $module->get_balance();

    print "Balance is $balancen";

=head1 DESCRIPTION

This module does absolutely nothing, and is just an example of how to write POD documentation!

=head1 METHODS

=over 4

=item B<new()> - The constructor for this module

=item B<login()> - Log in to the service

=item B<debug()> - Set this to 1 to show debug output

=item B<get_balance()> - Get the current account balance

=back

=head1 LICENSE AND COPYRIGHT

This module is free software; you can redistribute it and/or

modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

All that's left now is to convert this data to HTML, which the Pod::2::html module is well-equipped to do. The module accepts both an HTML template and a POD file and then "maps" various POD sections into corresponding sections of the HTML file to create an HTML-ized version of the POD data.

Normally, you would need to manually create the HTML template file that Pod::2::html uses; however, since an example file is included with the module's source code, it's often easier to modify and use this instead. Here's an example template:

<html>

<head>

<title>Documentation for My::Module</title>

<style type="text/css">

h1 {

    color: white;

    background-color: blue;

}

li {

    font-size: 14pt;

}

</style>

</head>

<body>

<main>

<hr>

All done!

</body>

</html>

The <main> tag in this HTML template is completely replaced by the contents of the POD. Additionally, =headn tags are replaced by the corresponding <hn> HTML element. (For example, =head2 is replaced by <h2>, and the =over and =item commands in the POD are replaced by <ul> and <li> HTML elements.) You can style these elements using a custom CSS stylesheet.

The template is only half the puzzle — it still needs to be integrated with the POD data. The following code combines the POD data with the template to generate a new HTML document:

#!/usr/bin/perl

use strict; use warnings;

use Pod::2::html;

my $pod_file = shift or die "Specify POD file as argumentn";

# Create pod2html object

my $pod = Pod::2::html->new($pod_file);

# The path to the HTML template

$pod->template("pod2html.tmpl");

# The formatted HTML will go to STDOUT

$pod->readpod();

This is how you would use it:

shell> ./convert.pl Module.pm > Module.html

The output file will now contain the POD documentation in HTML format.

In three simple steps, your POD data is converted to HTML and is suitable for online publication, indexing, or archival purposes. Try it out — you'll be surprised at how easy it is to complete the conversion process.

Editor's Picks

Free Newsletters, In your Inbox