Pod Pitfalls (Programming Perl)

26.4. Pod Pitfalls

Pod is fairly straightforward, but it's still possible to flub a few things:

It's really easy to leave out the trailing angle bracket.
It's really easy to leave out the trailing =back directive.
It's easy to accidentally put a blank line into the middle of a long =forcomment directive. Consider using =begin/=end instead.
If you mistype one of the tags on a =begin/=end pair, it'll eat the rest of your file (podwise). Consider using =for instead.
Pod translators require paragraphs to be separated by completely empty lines; that is, by two or more consecutive newline (\n) characters. If you have a line with spaces or tabs on it, it will not be treated as a blank line. This can cause two or more paragraphs to be treated as one.
The meaning of a "link" is not defined by pod, and it's up to each translator to decide what to do with it. (If you're starting to get the idea that most decisions have been deferred to the translators, not pod, you're right.) Translators will often add wording around a L<> link, so that "L<foo(1)>" becomes "the foo(1) manpage", for example. So you shouldn't write things like "the L<foo> manpage" if you want the translated document to read sensibly: that would end up saying "the the foo(1) manpage manpage".

If you need total control of the text used for a link, use the form L<show this text|foo> instead.

The standard podchecker program checks pod syntax for errors and warnings. For example, it checks for unknown pod sequences and for seemingly blank lines containing whitespace. It is still advisable to pass your document through two or more different pod translators and proofread the results. Some of the problems you find may be idiosyncrasies of the particular translators, which you may or may not wish to work around.

And, as always, Everything is Subject To Change at the Whim of the Random Hacker.