This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Code which is both executable and POD.
=head1 VERSION
Maintainer: John Porter <[EMAIL PROTECTED]>
Date: 9 Aug 2000
Version: 1
Mailing List: [EMAIL PROTECTED]
Number: 79
=head1 ABSTRACT
Allow some executable code to be recognized also as POD.
=head1 DESCRIPTION
As of Perl 5, any chunk of source text is either POD, or executable code.
This RFC proposes that a class of source text be allowed which is both
recognized as POD by any POD processor, and as non-POD by the perl parser.
This allows actual running code to be inserted directly into the documentation
for that code.
=head1 IMPLEMENTATION
How this is implemented depends on whether supporting changes can be made
to the perl parser, to POD processors, or both. Changes to the POD specification
can reasonably be assumed to necessitate changes to both the perl parser and
to POD processors.
=head2 1: Leave perl's POD recognition unchanged; modify POD processors
This could be done by adding a variant of the C<=cut> directive, which
is recognized as a normal C<=cut> by perl, but is passed over by POD
processors. This exploits the fact that perl stops ignoring text at
the C<=cut> directive. The POD processors must be modified to NOT stop
accumulating POD when they see the C<=cut include> directive.
The downside of this approach is that overlaps between pod and code can
only occur in this order ( pod, both, code ). Alternatively, the POD
processors could also I<start> accumulating code on a C<=cut include> directive,
but this would look kludgy.
Example:
=pod
This documents the code.
=cut include
sub foo($\%@)
=cut
{
#code for foo
}
=head2 2: The POD spec is changed to include special directives
This is cleaner, but has farther reaching effects in both
the perl parser and POD processors.
This could be done by adding a special variant of the C<=pod> directive,
such as C<=pod code>.
Example:
=pod
Normal documentation.
=pod code
sub foo($\%@)
=cut
{
#code for foo
}
=pod code
$^W = 1; # enable warnings :-)
=pod
Rest of documentation.
=cut
=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.
=cut
