Item7707: POD formatting fails after a =pod directive

An extra =pod directive, as for example in the plugin module PerlDocPlugin.pm itself, spoils actual POD formatting by said plugin.

Cause: In sub translatePod2TWiki,

1. a plain =pod directive switches the parser into twiki mode (bad), which
2. in turn switches off POD formatting (good).

In my opinion it is quite fine to suppress POD formatting in twiki mode: TWiki isn't POD, and has its own markup syntax. But how come that an explicit =pod switches the parser into twiki mode? Here it becomes dirty.

Many TWiki modules (right now I stumbled over TWiki::Render) start with a =pod directive, followed by TWiki markup. This is just wrong from a POD point of view. The current interpretation of =pod has been introduced in 2007, "in anticipation of it being used by developers for core docs", see Item4093, and TWiki:Codev.DontShipDotPmTopics. So, apparently, a dubious usage of =pod became widely spread as a de-facto-standard for TWiki's module documentation, which in turn motivated a change of PerlDocPlugin to accomodate for that.

I suggest a two-step approach:

1. Immediately delete the =pod line from PerlDocPlugin.pm - and voila, POD processing works as desired. That's just fixing the symptom, but good enough right now.
2. In an extra Item yet to be discussed on a release meeting, fix all TWiki module documentation to be conforming to the POD specs.
3. The third step would be to remove the bad =pod handling from the plugin, but since plugins are intended to be independent of TWiki versions, bad POD will need to be supported until the end of time. Therefore I believe that this third step isn't worth the effort,

Side note: In spite of this bug, PerlDocPlugin usually works quite fine with CPAN modules. The reason is that in traditional POD, the =pod directive is used only in rare edge cases.

-- TWiki:Main/HaraldJoerg - 2015-12-19