A Pod::Simple module or a Subclass of Pod::Simple to process the '=being PIR ... =end PIR' formats in our *.pod files

Alvis Yardley ac.yardley at gmail.com
Sat Apr 28 23:04:18 UTC 2012


All:

Does anyone know of a module which subclasses Pod::Simple to process '=begin
PIR' ... '=end PIR' command paragraphs as pod?

The reason I ask is, as most of you are aware, many of our *.pod docs contain
'=begin PIR' through '=end PIR' command paragraphs, which allow our
auto-generation tools to pick up these formatters, process them, and output
them to our html-ized docs, all of which is, of course, a good-thing.

The problem, however, is perldoc -- as it is designed to do -- ignores these
formatters. One consequence of which is, when someone, say, for example,
someone new to Parrot, goes perldoc-ing through 'docs/', trying to
get a handle on things, whole swaths of example code is left out of the
display. The person, then, is left wondering whether or not our docs are
complete. 

Yes, of course, the html docs do include this example code, but, presently, we
do not *specifically* direct folks to the html docs. (Until today, we even
told folks, in 'docs/gettingstarted.pod', our html-ized docs were still
"experimental.") Instead, we suggest it only as an optional alternative. A
consequence of which is, someone -- again, say, someone new to Parrot -- 
who prefers *.pod to html, reasonably, I think, expects the *.pod docs to
contain the same information as the html docs, but, unfortunately, this is not
the case.

What-is-more, it is only after digging around for a while (perhaps even as
much as a month or two) he or she may discover there is a difference between
the documentation sets. This, imho, is an unnecessary barrier.

So, if any one knows of such a subclass, I'd love to hear about it.

Thanks.
-- 
Alvis


More information about the parrot-dev mailing list