Howdy, I agree, Alvis. The current state of things leaves much to be desired.
I am +1 to creating a subclass of Pod::Simple that we include with Parrot to render our POD more correctly. Duke On Sat, Apr 28, 2012 at 4:04 PM, Alvis Yardley <[email protected]> wrote: > 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 -- Jonathan "Duke" Leto <[email protected]> Leto Labs LLC http://labs.leto.net 209.691.DUKE http://dukeleto.pl _______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
