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
Copyright © 2001 O'Reilly & Associates. All rights reserved.