Programming Perl, 4th Edition

Chapter 23. Plain Old Documentation

One of the principles underlying Perl’s design is that simple things should be simple, and hard things should be possible. Documentation should be simple.

Perl supports a simple text markup format called pod that can stand on its own or be freely intermixed with your source code to create embedded documentation. Pod can be converted to many other formats for printing or viewing, or you can just read it directly, because it’s plain.

Pod is not as expressive as languages like XML, , troff(1), or even HTML. This is intentional: we sacrificed that expressiveness for simplicity and convenience. Some text markup languages make authors write more markup than text, which makes writing harder than it has to be and reading next to impossible. A good format, like a good movie score, stays in the background without causing distraction.

Getting programmers to write documentation is almost as hard as getting them to wear ties. Pod was designed to be so easy to write that even a programmer could do it—and would. We don’t claim that pod is sufficient for writing a book, although it was sufficient for writing this one.