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