Fractals

Plain Old Documentation (pod) – write documentation for Perl, Perl software, and Perl modules

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.


Project page

Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments