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
