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 (
) 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.