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 _______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
