Plain Old Documentation (POD)

[ Perl tips index ]
[ Subscribe to Perl tips ]

In our previous tip we spoke about using perldoc to access documentation about Perl. Most of the help pages perldoc accesses are written in POD (plain old documentation). In this tip we're going to cover the basics of how to write POD.

POD is designed to be a simple, clean documentation language. It's goals are to be:

Almost all Perl modules include their documentation in POD format. Although this is occasionally done as .pod files it's much more common to include the POD directly into the code. This has the advantage that it becomes much harder to accidently separate the code from its documentation.

Paragraphs

POD uses three kinds of paragraphs (text preceded by and followed by a blank line). These are:

Text paragraphs
Plain text paragraphs which the formatter can reformat if required.
Code paragraphs

Text paragraphs which the formatter must not reformat. These paragraphs are typically used for code. For example:

        use strict;
        
        my $test = 1;

You signal to the formatter that some text is a code paragraph by starting each line in the paragraph with at least one space (or tab) character.

Command paragraphs

Unlike the previous two paragraph styles, the content of these paragraphs are not seen by the user. These exist to signal to the formatter which lines are for it to parse, and to provide some indication of how you want your text to appear. POD command start with the equals character (=) in the first column and are listed below.

These are often called command lines however it should be recognised that the specification for these lines is that they appear on a line preceded and followed by blank lines. Thus a paragraph.

=head1, =head2 ...

These denote headings for first level, second level and so on. For example:

        =head1 Plain Old Documentation
=pod
Tells the POD formatter that this is the start of a section of POD and thus to start formatting. This lasts until the =cut command is seen. This will cause the Perl interpreter to skip this section.
=cut
Tells the POD formatter that this is the end of a section of POD and thus to stop. This will cause the Perl interpreter to resume looking for Perl code.
=over n
This moves the indent level over by n spaces. This is used for creating itemized and descriptive lists.
=item string
This creates a list item with the descriptive term set to string. Use an * (asterisk) to represent itemized lists.
=back
Moves the indent level back to the level prior to the last =over. This is used for closing the current list level.
=for format, =begin format, =end format

POD allows you to write different content for different formats. Thus you might have a table created by spaces for text based content, a html table and a LaTeX table each specified where required. These commands provide this functionality. eg:

        =for html
                <table>
                        <tr><td>1</td><td>Rhymes with sun</td></tr>
                        <tr><td>2</td><td>Rhymes with shoe</td></tr>
                </table>

        =begin text

                1       Rhymes with sun

                2       Rhymes with shoe

	=end text

=for format applies only to the next paragraph whereas =begin format will run until the corresponding =end format.

That's almost it to writing POD. There are also few formatting codes to allow you to specify bold text (bold), italicised text (italicised) and code style (code) and similar effects. You can read more about these in perldoc perlpod.

An example

        #!/usr/bin/perl -w
        use strict;

        # ...

        # POD traditionally goes entirely at the top or entirely at the
        # bottom of the file.

        =pod

        =head1 LoremIpsum.pm

        =head2 Synopsis

                use LoremIpsum;

                aenean($dignissim);
                vivamus($accumsan, $semper, $elit, $eget, $odio);
                lacinia($nonummym $congue);

        =head2 Description

        Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Mauris
        nec wisi. Cras vitae justo. Nullam congue auctor libero.
        Suspendisse ut libero et ante condimentum pellentesque. Donec
        tincidunt.
        
        Aenean dignissim. Proin elit nibh, placerat nec, lacinia
        at, malesuada sit amet, nisl. In egestas pulvinar arcu. Praesent in
        neque nec elit gravida dictum. Aenean et pede nec purus convallis
        accumsan. Proin dolor. Donec id orci. Vivamus non augue feugiat
        dolor viverra vehicula. Mauris vel wisi. Fusce in leo. Sed non
        nulla. Fusce orci.

        =over 4
        
        =item C<aenean>

        Aenean ultricies, ligula vel feugiat lobortis, arcu tortor
        fermentum metus, ac rhoncus turpis lectus ac orci. Sed posuere
        tellus in lectus eleifend rhoncus. Nam id massa. 
        
        =item C<vivamus>
        
        Donec aliquam justo ut ante. Morbi tincidunt, sem a auctor
        faucibus, felis leo blandit justo, in vestibulum felis dolor at
        lorem. 
        
        =item C<lacinia>
        
        Suspendisse lacinia sem eu ligula. Donec blandit molestie nulla.
        Fusce a augue.  Vestibulum ante ipsum primis in faucibus orci
        luctus et ultrices posuere cubilia Curae.
        
        =back

        =cut

        1;

Checking your POD

To make sure that your POD is valid, you can use the the podchecker command, which comes standard with perl.

Further references

[ Perl tips index ]
[ Subscribe to Perl tips ]


This Perl tip and associated text is copyright Perl Training Australia. You may freely distribute this text so long as it is distributed in full with this Copyright noticed attached.

If you have any questions please don't hesitate to contact us:

Email: contact@perltraining.com.au
Phone: 03 9354 6001 (Australia)
International: +61 3 9354 6001

Valid XHTML 1.0 Valid CSS