Last Updated on April 18, 2024
Plain Old Documentation (known as pod) is a simple, lightweight markup language used for writing documentation for Perl, Perl programs, and Perl modules. This markup language is designed to make it easy for programmers to add documentation to their software and modules.
Pod markup consists of three basic kinds of paragraphs: ordinary, verbatim, command. There’s also a data paragraph.
- Ordinary Paragraph – as the name indicates, this is the standard paragraph text used for documentation. It’s a plain text paragraph that a POD formatter is allowed to reformat to its own specifications. These paragraphs begin with a something other than an equal sign or whitespace.
- Verbatim Paragraph – used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn’t be wrapped. Paragraphs that begin with whitespace characters—tabs or spaces—are considered to be “verbatim paragraphs”.
- Command Paragraph – used for special treatment of whole chunks of text, usually as headings or parts of lists. These paragraph begin with an equal sign. The sequence of alphanumeric characters immediately following the equal sign is treated as a pod directive, and the rest of the paragraph is formatted according to that directive.
- Data Paragraph – a data paragraph is not part of Pod at all (i.e., effectively it’s “out-of-band”), since it’s not subject to most kinds of Pod parsing.
Pod directives start at the beginning of a line at any point where Perl is expecting a new statement.
Perl is a versatile language. It’s often used to write (CGI) scripts, manipulate text, general web programming, networking, system administration, prototyping, database access, and graphical programming. One of the most powerful features of Perl is its extensive library of modules. Many of these modules are available from the Comprehensive Perl Archive Network, which mirrors over 178,000 Perl modules.
Ways to Learn Pod
Plain Old Documentation in 5 minutes
This short guide covers headings, common sections, markup elements, entities, lists, and other POD coolness.
Good and Bad about pod
| Advantages | |
|---|---|
 | Removes obstacles from writing documentation |
| Simple language to learn |
| Friendly and intuitive directives |
| Wide array of POD manipulation tools allow you to parse POD documentation, convert it to different formats, and automatically check it for errors |
| Embed your documentation within your code - intermix Perl code and POD in the same file |
| Disadvantages | |
|---|---|
 | This markup language lacks XML's robust features of well-formedness and unambiguous syntax |
| Audience targeted at Perl developers |
| Supports a small set of markup elements |
| Intended to be nothing more than a simple format for embedding documentation inside software |
Useful Software
Pod::Simple::Wiki – a class for creating Pod to Wiki filters.
Pod::Markdown – converts Pod to Markdown.
Pod::HTML2Pod – translate HTML into POD.
podchecker – checks the syntax of POD format documentation files.