directive, as for example in the plugin module
itself, spoils actual POD formatting by said plugin.
- a plain
=pod directive switches the parser into
twiki mode (bad), which
- in turn switches off POD formatting (good).
In my opinion it is quite fine to suppress POD formatting in
mode: TWiki isn't POD, and has its own markup syntax. But how come that an explicit
switches the parser into
mode? Here it becomes dirty.
Many TWiki modules (right now I stumbled over
) start with a
directive, followed by TWiki markup. This is just wrong
from a POD point of view. The current interpretation of
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
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:
- 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.
- In an extra Item yet to be discussed on a release meeting, fix all TWiki module documentation to be conforming to the POD specs.
- 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
directive is used only in rare edge cases.