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

Jonathan "Duke" Leto jonathan at leto.net
Wed May 2 16:27:24 UTC 2012


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 <ac.yardley at gmail.com> 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 <jonathan at leto.net>
Leto Labs LLC http://labs.leto.net
209.691.DUKE http://dukeleto.pl


More information about the parrot-dev mailing list