Masak's Journal[1] identifies a couple of problems involving the
interaction of POD with block-form classes - one in the article
itself, and another in the comments that follow. The first is that a
mixture of indented block-form classes and non-indented POD is
visually very ugly. The second is that mixing POD and code is in
general problematic. In the latter case, a recommendation is made
that good practice would put all of the POD together at the end of the
file, rather than interspersed throughout.
These two issues seem to operate at cross-purposes: on the one hand,
if all of the POD is consolidated at the end of the file, then you
don't have to worry about how ugly it is to mix POD and indented code.
OTOH, do we really want to punish programmers for trying to mix the
two?
Assuming that we want to make life easier on programmers who like to
intersperse code and POD, one way to do this would be to replace the
"start of line only" rule for POD with an indenting rule not unlike
what is used with block quotes: if there's any leading whitespace on
the opening line of a POD section, then every line in that section
must start with equivalent whitespace. This complicates the POD
extractor, but not by much.
In terms of placing all of the POD at the end: one of the strongest
reasons for mixing POD with code is that you can easily identify what
code to which a given section of POD refers. Putting all of the POD at
the end lacks that ability. One possible solution would be to provide
some means for you to specify a "POD footnote" in the code, not unlike
the URL reference that I've got in this email: in the code itself, you
place an anchor (e.g., '#{{=[1]}}') which can then be referenced later
on by a POD section (e.g., '=[1] start ...'). This would provide an
easy way to switch back and forth between the POD and the related
code. Mind you, I'm not at all enamored with the specific syntax
suggested above. It's a quick-and-dirty hack intended strictly to
illustrate the concept.
--
Jonathan "Dataweaver" Lang
[1] http://use.perl.org/~masak/journal/39334
