[% setvar title Add a "emit pod" runtime option to Perl %]

This file is part of the Perl 6 Archive

Note: these documents may be out of date. Do not use as reference!

To see what is currently happening visit http://www.perl6.org/


Add a "emit pod" runtime option to Perl


  Maintainer: Adam Turoff <ziggy@panix.com>
  Date: 24 Sep 2000
  Last Modified: 26 Sep 2000
  Mailing List: perl6-stdlib@perl.org
  Number: 286
  Version: 2
  Status: Frozen


It would be really handy if there were a core mechanism to emit the documentation embedded in a Perl program/module.


Not much discussion came out of this proposal. John Porter mentioned that this would be trivial to implement, if RFC 79 is implemented.


Tom Christiansen proposed this in his perl6storm message:

	=item perl6storm #0004

	Need perl to spit out pod/non-pod, like cc -E.  Pod is too hard to parse.
	This would make catpod trivially implemented as a compiler filter.

This feature would be quite useful, aside from just Tom's example of 'catpod'.

While RFC 79 proposes a much broader mechanism, this RFC proposes that Perl simply have three modes - one where POD is ignored and Perl code is analyzed and interpreted, one mode where Perl code is ignored and POD is emitted, and one mode where POD is ignored and Perl code is emitted without any parsing or interpretation.

This RFC does not require RFC 79-style interleaved POD streams to be implemented.


Many options exist, including mucking around with the core to have a simple commandline flag (e.g. perl -E)

The most sensible implementation would be to write a standard module that was a compiler backend, and invoked easliy, as in:

	perl -MPOD -e "emit()" *.pl *.pm t/*.t

Another option would be to tweak the parser to ignore Perl code and simply emit any POD it would otherwise ignore, as well as emit the Perl code it would otherwise process after ignoring POD as usual.


RFC 79: