Write and Check Perl Pod Documentation

You will finish with a small Pod document that Perl can ignore safely, translators can render, and podchecker can validate. 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 minutes if you are starting a new one.

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 is needed.

1. Confirm the tools you will use

Check the installed interpreter, documentation package and commands before writing. 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. The useful checkpoint is that the commands resolve and that perl-doc is installed.

2. Add a Pod block at a valid boundary

Pod is documentation embedded in Perl programs and modules. Perl ignores the documentation, but the Pod parser still needs to see it at a statement boundary. Start 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 are less forgiving when a command is attached to code or when the paragraph after =cut is not separated. Do not put Pod commands in the middle of a Perl statement.

Checkpoint: run the program before checking its documentation:

$ perl hello.pl
hello
finished

3. Use the three paragraph types deliberately

Pod has ordinary, verbatim and command paragraphs. An ordinary paragraph is plain text separated by blank lines. A verbatim paragraph starts with a space or tab, so its contents are kept as code or other preformatted text. A command paragraph starts with = and 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. A missing leading space turns the example into ordinary prose, while indentation inside an ordinary paragraph can make formatting 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, although a shallow hierarchy is easier to read. For lists, keep the list inside =over and =back, and keep item markers consistent:

=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 include I<...> for emphasis, C<...> for code, F<...> for a filename, and L<...> for a link. Do not use an item outside an =over and =back region, and do not put a heading inside that region.

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 requires whitespace immediately after the opening delimiter and immediately before the closing delimiter. If that rule is not convenient, use 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 that the wording is correct or that every target formatter displays it as you expect. If it reports an unknown command, check the spelling and the blank line before and after that command. If it reports an unclosed formatting code, count the matching angle brackets.

For a document containing non-ASCII text, declare its encoding once near the start of the Pod block, for example =encoding utf8. Use an encoding name supported by Perl's Encode module. Do not add several encoding declarations to the same document.

6. Render the same source in two formats

Use a text translator to inspect the result 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 be installed 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 instead of hand-editing hello.1. If you are only reviewing the result, remove the generated file when finished. This deletion is safe only if it is a disposable output; do not remove an installed manual page you still need.

7. Keep embedded documentation compatible

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

For formatter-specific material, =for format text handles one paragraph, while =begin format and =end format surround a longer region. A formatter that does not understand that format ignores the region. Use this boundary sparingly: normal Pod is more portable across text, HTML, TeX and man-page translators.

Do not confuse a successful translation with a safe program. Pod can contain examples that look executable, and a formatter does not run them. Review copied commands separately, quote shell values, and do not place secrets in documentation that will be committed or installed.