Perl Cookbook

Documenting Your Module with Pod

Problem

You need to document your module, but don’t know what format to use.

Solution

Embed your documentation in the your module file using pod format.

Discussion

Pod stands for plain old documentation. It’s documentation embedded in your program using a very simple markup format. Programmers are notorious for writing the code first and the documentation never, so pod was designed to make writing documentation so easy that anyone can and will do so. Sometimes this even works.

When Perl is parsing your source code, a line starting with an equal sign (where a new statement is expected) says to ignore all text until it finds a line beginning with =cut, after which it will start parsing code again. This lets you mix code and documentation throughout your Perl program or module file. Since it’s mostly plain text, type in your documentation as literal text, or nearly so. The translators try to be clever and make output-specific decisions so the programmer doesn’t have to specifically format variable names, function calls, etc.

Along with Perl are shipped several translators that filter generic pod format into specific output styles. These include pod2man to change your pods into troff for use with the man program or for phototypesetting and printing; pod2html for creating web pages (which works even on non-Unix systems); and pod2text for plain ASCII. Other translators, like pod2ipf, pod2fm, pod2texi, pod2latex, and pod2ps, may also be available or can be ...