This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Perl Compiler is Just Another Pod Processor
=head1 VERSION
Number: 79
Version: 2
Date: 9 Aug 2000
Last-Modified: 11 Aug 2000
Maintainer: John Porter <[EMAIL PROTECTED]>
Mailing List: [EMAIL PROTECTED]
=head1 ABSTRACT
With the perl compiler designated as Just Another Pod Processor,
and the POD markup syntax generalized to allow direction to more
than one processor, executable code can be inserted into POD-generated
documentation.
=head1 DESCRIPTION
As of Perl 5, any chunk of source text is either POD, or executable code.
This RFC proposes that, with respect to POD, the perl compiler act as
plain ol' POD processor. Furthermore, the POD markup syntax should be
extended to allow "output" to any combination of processors to be
turned on or off at will.
=head1 CHANGES
Version 1 of this RFC was entitled "Code which is both executable and POD."
Version 1 of this RFC proposed a special "perl" POD processor type.
This version makes the "perl" type non-special.
Version 1 proposed a simple implementation which could theoretically work
with the perl5 front end. This version presumes that the perl6 front end
is game for any implementation details necessary to support the proposal.
=head1 IMPLEMENTATION
The POD specification is modified from its perl5 form, to include
the ability to put any number of POD processor names on the C<=for>, C<=begin>,
and C<=end> lines.
In addition, three POD processor names are reserved: C<"perl">,
C<"all">, and C<"pod">. C<"perl"> is the name for the perl compiler;
C<"all"> is an alias for all POD processors; and C<"pod"> is an alias
for all POD processors except C<perl>.
Furthermore, the standard POD tokens C<=pod> and C<=cut> are defined as
being equivalent to C<=begin pod> and C<=end pod>, respectively.
Alternatively, C<=pod> and C<=cut> could be dropped altogether.
Note that the lists of processors turned on/off by any C<=begin/=end>
directive are additive. Unless you have a better idea... :-)
Example:
=begin pod
This will appear in all pod-generated documentation, but
is ignored by perl.
=begin all
# This is seen by perl AND appears in pod.
=end pod
# this is seen only by perl.
=begin pod
# This is seen by perl too!
=end pod
=head1 REFERENCES
RFC 5: "Multiline Comments for Perl"
RFC 11: "Examples encoded with =also for|begin|end POD commands"
RFC 44: "Bring Documentation Closer To Whatever It Documents"
perlpod manpage for discussion of POD.
