Plain Old Documentation format, or POD is Perl's own embedded documentation format.

Advantages

• Embedded documentation cannot be lost
• Can be translated into many different formats
• Can be embedded, as a comment, in other programming languages than Perl.

Disadvantages

• POD is not a complete formatting language and many things cannot easily be expressed, such as embedded images, tables and two-column layout.

Viewers

Command Line

• perldoc

• annopod

Replacement for perldoc that integrates the comments from AnnoCPAN into the documentation.

Local Web Interfaces

• podwebserver

Simple, yet sufficient for many uses.

• Pod::POM::Web

Lots of features.

Formatters

POD can be formatted in many different ways. Here is a list of formats and their translators...

• HTML
• pod2html (aka Pod::Html)

A handy switch to use on the command-line is -css=/path/to/my/css.file, which goes a long way to making the output look much better than default unadorned HTML.

• Pod::Simple::HTML
• RTF
• Pod::Simple::RTF
• PDF
• pod2pdf
• Text
• pod2text (aka Pod::Text)

A couple of handy switches on the command-line are -l -i2 -w72 (loose: blank line after H1's, indent of 2 and wrap at column 72).

• Pod::Simple::Text
• Man page / *roff
• pod2man (aka Pod::Man)
• LaTeX
• pod2latex (aka Pod::Latex)

Verification

Command Line

There are various tools to check the validity of your POD syntax, spelling and other issues.

• podspell
• podchecker

usage: podchecker --warnings [filename]

• Pod::Spell
• Pod::Coverage

Here is a simple shell script that may be used to list possibly misspelled words:

perl {{-MPod::Spell -e}} "Pod::Spell->new->parse_from_file(shift)" $1 \
    | ispell -l -p ~/my.dict -B \
    | sort -u

(where ~/my.dict contains a local dictionary of words)

Automated Testing

• Test::Pod
• Test::Pod::Coverage
• Test::Spelling

Tools

Various tools for working with POD

• search.cpan.org preview

Many people measure the correctness of their POD formatting by what the results look like on search.cpan.org. Unfortunately, if you make a mistake, you have to upload a new distribution. Fortunately, you can test your POD before uploading a distribution to CPAN.

Authors may use the POD previewer on search.cpan.org. You just browse locally for your file and upload it. The POD is then formatted and remdered by the site's custom formatting, which allows you to tweak your POD endlessly before the official release.

Documentation

• perlpod man page
• perlpodspec man page

Alternatives to POD

• Perl6::Perldoc

• Pod::WikiDoc allows one to embed wiki-style documentation in a POD format block, then extract and convert it to ordinary POD for distribution. (See Write More With Less from the YAPC::NA 2006 Lightning Talks.)
• OODoc this module simplifies writing documentation for Object Oriented programs
• Natural Docs an open-source, extensible, multi-language documentation generator. You document your code in a natural syntax that reads like plain English. Natural Docs then scans your code and builds high-quality HTML documentation from it.

Mailing lists

• pod-people - A list for the people who are writing software that either creates or parses Perl POD (plain old documentation) files.
• Archive[s]: http://www.mail-archive.com/pod-people@perl.org/
• Help: send an empty email to mailto:pod-people-help@perl.org
• NNTP Archive: http://nntp.perl.org/group/perl.pod-people
• Name: pod-people
• RSS RDF Feed: http://www.nntp.perl.org/rss/perl.pod-people.rdf
• Subscribe: Send an empty email to mailto:pod-people-subscribe@perl.org
• Unsubscribe: Send an empty email to mailto:pod-people-unsubscribe@perl.org

Useful resources

Web design agency