podchecker
Verify validity of a Perl POD file
SYNOPSIS
podchecker [options] [file ...]
PARAMETERS
-help
Displays a brief help message and exits.
-man
Prints the full man page for podchecker and exits.
-warnings / -w
Enables the display of warnings in addition to fatal errors. This is the default behavior.
-nowarnings / -W
Disables all warning messages, reporting only fatal errors.
-warnings=category,...
Enables specific categories of warnings. Common categories include 'all', 'none', 'badflag', 'badindent', 'badseq', 'verbatim', 'pod', 'perl', 'syntax'.
-errlvl=level
Sets the minimum error level that will cause podchecker to exit with a non-zero status. Valid levels are 0 (no errors), 1 (warnings), 2 (errors), 3 (fatal errors). Default is 2.
-html
Generates an HTML report of errors and warnings instead of plain text output. This report can be displayed in a web browser.
-quiet
Suppresses all output unless errors or warnings are found. If no problems are detected, it prints nothing.
DESCRIPTION
podchecker is a utility designed to validate the syntax of Perl's Plain Old Documentation (POD) format. It parses POD content, whether from standalone files or embedded within Perl scripts and modules, and reports any deviations from the official POD specification.
The tool identifies common errors such as malformed POD directives (e.g., =head1 with incorrect arguments), unclosed formatting codes (e.g., B>), incorrect heading levels, and other structural issues. By catching these problems early, podchecker ensures that documentation can be correctly processed and rendered by tools like perldoc, pod2man, or pod2html. It's an essential tool for Perl developers maintaining high-quality documentation for their code.
By default, it prints error messages to standard error. It can also produce an HTML error report or exit with a specific status based on the severity of issues found.
CAVEATS
podchecker primarily focuses on the *syntax* of POD. It may not catch all logical or semantic errors, such as documentation that is syntactically correct but factually incorrect or misleading. Its output can be verbose, especially without the -quiet option, and parsing its plain-text output for automation might require careful regular expression matching.
EXIT STATUS
podchecker exits with 0 if no problems are found, 1 if warnings are found (unless -errlvl is set higher than 1), 2 if errors are found, or 3 if fatal errors are found. The exact non-zero exit status can be configured via the -errlvl option, allowing for custom automation logic based on error severity.
BUGS
Despite its utility, podchecker may not catch every conceivable syntax or semantic problem due to the flexible nature of POD. Some complex or ambiguous POD constructs might be misinterpreted or pass unnoticed. Users are encouraged to report any encountered issues to the Perl bug tracking system to contribute to its ongoing improvement.
HISTORY
Plain Old Documentation (POD) was introduced as part of Perl 5.0 (released in 1994) to provide a simple, ubiquitous, and easily parsable format for embedding documentation directly within Perl source code. podchecker, as a component of the standard Perl distribution, has evolved alongside the POD specification, ensuring compliance with new features and refinements. Its development is deeply intertwined with the broader Perl documentation ecosystem, aiming to maintain a consistent and reliable documentation standard for the Perl community.
