questions about =cut

I'm pretty sure that Pod::Eventual has a bug or two related to =cut, but I
haven't written the tests yet because I'm not sure how I want to procede.

This POD:

  This is text.

  =head1 HEADER
  ...and some text.

  =cut
  Text again.

results in something roughly like this:

  { type: text, content: "This is text.\n" }
  { type: command, command: head1, content: "HEADER\n...and some text.\n" }
  { type: command, command: cut,   content: "\n" }
  { type: text, content: "Text again.\n" }

In other words, content that is notionally part of the =cut command (because
there has not yet been a para break) is not made part of the =cut event.
That's because I emulated perl's behavior of going back to Perl on the line
after =cut.

Following perl isn't necessarily the right thing, since when Pod occurs inside
a here-doc it is both part of the Perl document (perl thinks it's in code) and
part of the Pod document (the existing Pod translators pick it up as Pod).

So I think the right thing is to say that content after =cut and before a
paragraph break is part of the =cut commant's content.  (Sure, this is fairly
academic, but it would be nice to reduce the scope of =cut's special casing.)

Also: I know =cut doesn't "take" content or arguments.  That's for a semantic
parser to deal with.  Eventual just finds events.

The other case is this one:


  say "1";

  =cut

  say "2";

  =cut

  say "3";

perl will say 1 and 3.  Does that mean that C<say "2";> is really inside Pod,
or is that a quirk of perl?

If so, is =cut just a misnamed =toggle?

I wonder if perlpod.pod could use some updating.

-- 
rjbs