=head1 TITLE

POD needs a reorder command.

=head1 VERSION

  Maintainer: Kenneth C. Rich <kenrich@mail.rochester.edu>
  Date: 12 Sep 2000
  Last Modified: 13 Sep 2000
  Mailing List: perl6-language@perl.org
  Number: 217
  Version: 2
  Status: Developing

=head1 ABSTRACT

It would be nice to have the order of output be able to
differ from the order in the source.

=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" could be "=for", or "=begin" and "=end" with a
non-text-processor label.

=head2 Motivations:

=over

=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 always a good order for
a man page.

=back

I dislike overloading the "=for" label with "=print" label functionality.

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