Check Perl POD Files Before You Publish Them

You will finish with a small, repeatable check for Perl POD documentation: validate one file, pipe a document through standard input, handle a batch, and use the exit status in a script. On this machine, podchecker comes from Perl 5.38.2, package version 5.38.2-3.2ubuntu0.6. Allow about ten minutes for a first check.

You need a shell and readable POD or Perl source files. The command only checks documentation syntax. It does not rewrite files, install modules, publish documentation or change a Perl program. All examples are unprivileged. Do not use sudo to make a documentation check appear to pass: fix the file or its permissions instead.

1. Confirm the installed command

Check which executable your shell will run and record the Perl package version:

$ command -v podchecker
/usr/bin/podchecker
$ dpkg-query -W -f='${Package} ${Version}\n' perl
perl 5.38.2-3.2ubuntu0.6

The installed command accepts -help, -man, -warnings, -nowarnings, and one or more file names. Its underlying Pod::Checker module is version 1.75 here. Exact diagnostic wording can change between Perl releases, so treat the exit status as the automation interface and the message as information for a person.

2. Check one POD file

Run the checker with the path as its only argument:

$ podchecker /path/to/README.pod
/path/to/README.pod pod syntax OK.

A successful check prints a status line and returns zero. The file must contain POD directives such as =head1. POD embedded in a Perl source file can also be checked by passing that source path, provided its documentation is written as normal POD.

Use a temporary copy when testing a document that another process is editing. The checker reads the file but does not lock it, so a concurrent edit can make the result inconsistent with the version eventually committed.

3. Use the exit status in a script

Shell commands can inspect the result without parsing human-readable output:

$ podchecker /path/to/README.pod
$ status=$?
$ printf 'podchecker status: %s\n' "$status"
podchecker status: 0

Status zero means all specified POD files passed. Status one means at least one specified file has POD syntax errors. A file with no POD commands produces status two. Status one takes precedence over status two when several paths are checked. If a pipeline or build needs an unambiguous answer, check one file per invocation and handle each status explicitly.

Do not use echo $? after another command and expect the checker result to remain available: $? always belongs to the most recent command. Save it immediately, as above.

4. Read a failure and fix the source

For a malformed document, podchecker writes errors to standard error and returns one:

$ podchecker /tmp/example-bad.pod
*** ERROR: =over without closing =back at line 5 in file /tmp/example-bad.pod
/tmp/example-bad.pod has 1 pod syntax error.
$ printf 'status: %s\n' "$?"
status: 1

The useful action is to open the named file at the reported area and balance the POD structure. Common checks include matching =over with =back, placing =item inside a list, closing interior sequences such as C<...>, and spelling directives correctly. The line reported can refer to the start of a paragraph rather than the exact character that needs changing.

After editing, run the same command again:

$ podchecker /tmp/example-fixed.pod
/tmp/example-fixed.pod pod syntax OK.

5. Check standard input

With no file argument, the command reads standard input. This is useful when a build step has already selected or generated the text:

$ printf '=head1 NAME\n\nexample - a POD check\n\n=cut\n' | podchecker
<&STDIN pod syntax OK.

Use a quoted here document when the sample spans several lines:

$ podchecker <<'POD'
=head1 NAME

example - a POD check

=cut
POD
<&STDIN pod syntax OK.

The quoted delimiter keeps the shell from expanding variables or command substitutions inside the test document. That matters in a build check: the text reaching podchecker should be the text you intend to validate.

6. Check several files carefully

Pass multiple paths when a single aggregate result is sufficient:

$ podchecker lib/Example.pm script/example.pl docs/README.pod
lib/Example.pm pod syntax OK.
script/example.pl pod syntax OK.
docs/README.pod pod syntax OK.

Directories are ignored and produce a warning, rather than being searched recursively:

$ podchecker /tmp
podchecker: Warning: Ignoring directory '/tmp'

Do not pass a directory expecting a project-wide scan. Build the file list first with a tool that understands your repository, then pass the resulting files. Avoid an unreviewed glob if it might include generated files, backups or paths containing unexpected content.

Warnings are enabled by default. -nowarnings turns their printing off, while repeating -warnings raises the warning level. The installed manual says that warning level two currently flags unescaped angle brackets. Warnings are not the same as syntax errors, but they can identify documentation that translators or readers may misinterpret. Keep the default during normal checks; silence warnings only when you have a recorded reason.

7. Add it to a safe validation step

A simple shell loop gives each file its own unambiguous result:

$ failed=0
$ for file in lib/Example.pm script/example.pl docs/README.pod; do
>     podchecker "$file" || failed=1
> done
$ exit "$failed"

This does not modify the checked files. In a real build, let the surrounding build system report the non-zero exit rather than continuing to publish generated documentation. If your list is produced dynamically, inspect it in a dry run before adding it to an automated job.

There is no undo step because podchecker is read-only. If you edited a source file while fixing an error, recover it through your normal version-control workflow, such as reverting an uncommitted change after checking the diff. Do not delete the original merely because a generated copy failed validation.