Programming Perl, 3rd Edition

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 =for comment 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 ...