RFC 217 (v1) POD needs comment command. POD needs a reorder command.

This and other RFCs are available on the web at
  http://dev.perl.org/rfc/

=head1 TITLE

POD needs comment command.  POD needs a reorder command.

=head1 VERSION

 Maintainer: Kenneth C. Rich <[email protected]>
 Date: 12 Sep 2000
 Mailing List: [email protected]
 Number: 217
 Version: 1
 Status: Developing

=head1 ABSTRACT

When you process POD, all POD material prints.
Sometimes that is undesirable.  Podders need to have the
option of not printing their POD.  Also, it would be
nice to have the order of output differ from the order in the
source, sometimes.

=head1 DESCRIPTION

=head2 Syntax suggestions:

C<=clip> I<optional-label>
 
...text...
 
C<=cut>
 
...code...
 
C<=print> I<required-label-from-clip>
 
C<=cut>

The "=clip" would only need a label if an "=print" needs
to refer to it.

I am not suggesting that "=clip" and "=print" are the best strings to
use.  "=say" and "=see", "=in" and "=out", "=cook" and "=serve",
"=think" and "=float", etc.  Someone come up with something
poddishly terse please?  I do not like "=comment" because it's
misleading and it breaks the implicit 5-letter POD command length rule.

=head2 Motivations:

=over

=item Comment out documentation

Sometimes I want a chunk of documentation to stick around but not
be visible to the casual user.  It may be tentative, half-baked, plain
wrong, still in development, a comment about the docs.  

=item Reorder the document

Sometimes I want a chunk of documentation to hang out near a
chunk of code, but the order of the code is not a good order for
a man page.  All right, so maybe this is really 2 proposals.

=item Multiline comment for Perl

I am not formally suggesting this as a multiline comment syntax.  I
already like Perl's current "multiline comment syntax" because it is so
easy to edit-macro-ize.  But I'd probably use it if it were there, cuz I
am a bad, undisciplined programmer.

=back

I'd make "=clip" cover everything to the next "=command".  But that
may be considered un-POD-like, oh well.

I'd probably require that "=print" may only occur after the
matching "=clip."  But I can imagine writing POD processors that deal
with "=print" references preceding "=clip" assertions, so I retract that
sentence.  The "=print" would evaluate into a plain paragraph, so mostly
you'd want to use "=print" after another "=command" like "=head1", and so
on.  For flexibility, an "=print" starting a pod section should
effectively evaluate into an "=pod" paragraph.

=head1 IMPLEMENTATION

...

=head1 REFERENCES

RFC 5: Multiline Comments for Perl