Write and Check Perl Pod Documentation

Pod is the documentation format Perl agrees to skip right over, which is exactly why it is so easy to get wrong without noticing. You will end up with a small Pod document that Perl ignores safely, that translators can render, and that podchecker validates. The examples use the installed Perl 5.38.2 package, with Pod::Simple 3.43 and Pod::Man 5.01. Allow about fifteen minutes if you already have a Perl source file, or twenty if you are starting fresh.

You need the perl-doc package for the local manual and checking tools. This guide uses an ordinary user account and writes only to a file in your working directory, no root access needed.

1. Confirm the tools you will use

Check the installed interpreter, documentation package and commands before you write anything. These are read-only checks:

$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2)
$ dpkg-query -W -f='${Package} ${Version}\n' perl perl-doc
perl 5.38.2-3.2ubuntu0.6
perl-doc 5.38.2-3.2ubuntu0.6
$ command -v podchecker pod2text pod2man
/usr/bin/podchecker
/usr/bin/pod2text
/usr/bin/pod2man

The exact package revision may differ on another host. What matters is that the commands resolve and perl-doc is installed.

2. Add a Pod block at a valid boundary

Pod is documentation embedded directly in Perl programs and modules. Perl ignores it at runtime, but the Pod parser still needs to see it start at a statement boundary. Open the block on a new paragraph with a command such as =head1, and close it with =cut on its own command paragraph.

Save this as hello.pl:

#!/usr/bin/perl

print "hello\n";

=head1 NAME

hello - a small Perl program with embedded documentation

=head1 DESCRIPTION

This program prints one line and demonstrates a minimal Pod block.

=cut

print "finished\n";

The blank lines are deliberate. Older translators get fussier when a command is jammed against code, or when the paragraph after =cut is not separated cleanly. Do not put a Pod command in the middle of a Perl statement.

$ perl hello.pl
hello
finished

3. Use the three paragraph types deliberately

Pod recognises three kinds of paragraph. An ordinary paragraph is plain text separated by blank lines. A verbatim paragraph starts with a space or tab, so its contents stay as code or other preformatted text. A command paragraph starts with = followed by an identifier.

Extend the DESCRIPTION section with a usage example:

Run the program like this:

    perl hello.pl

The indented line is verbatim text. It is not a shell command executed by
the Pod formatter; it is an example shown to the reader.

Indent every line of a verbatim paragraph consistently. Drop one leading space and the example silently becomes ordinary prose; add stray indentation inside an ordinary paragraph and the formatting can go unexpectedly wide.

4. Add headings, lists and inline formatting

Use =head1 for major sections and =head2 for sections within them. Pod also recognises =head3 through =head6, though a shallow hierarchy stays easier to read. For lists, keep the items inside =over and =back, with consistent markers:

=head2 Options

=over 4

=item *

B<-v> prints the version.

=item *

B<-h> prints help.

=back

The B<...> sequence marks a switch as bold. Other useful sequences: I<...> for emphasis, C<...> for code, F<...> for a filename, and L<...> for a link. Do not use an =item outside an =over/=back region, and do not put a heading inside one.

Angle brackets inside a formatting sequence need care. For a comparison operator, either escape the brackets or use the whitespace-sensitive doubled form:

C<$left E<lt>=E<gt> $right>
C<< $left <=> $right >>

The doubled form needs whitespace right after the opening delimiter and right before the closing one. If that is inconvenient, fall back to E<lt> and E<gt>.

5. Check syntax before rendering

Run podchecker against the Perl file:

$ podchecker hello.pl
hello.pl pod syntax OK.

A clean result means the checker found no Pod syntax errors or warnings. It does not prove the wording is right, or that every target formatter shows it the way you expect. An unknown-command warning usually means a spelling mistake or a missing blank line around that command. An unclosed formatting code means the angle brackets do not match up, so count them.

For a document containing non-ASCII text, declare the encoding once near the start of the Pod block, for example =encoding utf8, using a name your Perl's Encode module supports. Do not add more than one encoding declaration to the same document.

6. Render the same source in two formats

Use the text translator to see what a terminal reader will see:

$ pod2text hello.pl
NAME
    hello - a small Perl program with embedded documentation

DESCRIPTION
    This program prints one line and demonstrates a minimal Pod block.

Use the man-page translator when the documentation will ship as a manual page:

$ pod2man --center="Local Perl Documentation" --release="1.0" hello.pl hello.1
$ man -l hello.1

The output is generated from the same Pod source, so fix the source rather than hand-editing hello.1. If you are only reviewing the result, remove the generated file when you are finished; that deletion is safe only because it is disposable output, do not remove an installed manual page you still need.

7. Keep embedded documentation compatible

When Pod sits at the end of a file, put a blank line before the first command after __END__ or __DATA__. Skip that separator and some translators fail to recognise the Pod block at all. Keep the documentation outside Perl statements and finish it with =cut when code follows.

For formatter-specific material, =for format text handles a single paragraph, while =begin format and =end format wrap a longer region. A formatter that does not understand that named format simply ignores the region. Use this sparingly: plain Pod stays portable across text, HTML, TeX and man-page translators, a target-specific block does not.