A slight problem with virtual left margins

test.rakupod

=begin pod

This is a normal paragraph.

    This is an implicit =code block

OK so far? In the C<--doc> output of rakudo, code blocks will be indented,
plain blocks will not be.

There's one part of S26 that mentions that the virtual left margin, which
determines if you have an implied code block or not, is set by the
positioning of "the last delimiter". Rakudo follows this, despite the fact that
every other mention in S26 mentions the virtual margin is set by the
positioning of "the opening delimiter" (the directive that starts the block).

The "last delimiter" I believe is a mistake, and here's why: it permanently
breaks implicit code blocks. It's only mentioned in the context of C<=head>
blocks, where it can make some intuitive sense:

=begin code :allow<V>
V<=>begin pod
Some text.

    V<=>head1 Intro

    Having this paragraph text line up with the last header seems right,
    at least in one sense.
V<=>end pod
=end code

But this causes a fundamental issue, which we'll show now:

    =item And now it breaks

    This is a normal paragraph, lining up with the item block.

This is a paragraph indented in-source just like every other paragraph in the
C<=pod> block. And now:

    This is indented like the code block at the very beginning. Notice
    anything?

    The rest of this document is written like an implied code block, but it's
    all rendered like normal text, because of that =item. This is, to put it
    mildly, complete garbage behavior. It's at it's worst when you consider
    people editing different pod documents over time: anyone who happens to
    indent an inner directive at or beyond the column where your implied code
    blocks happen will break every code block coming afterwards.

    Now if you're thinking that a paragraph that starts to the left of the
    current virtual margin should reset the virtual margin for future
    paragraphs, that just causes the same issue in the other direction
    (turning paragraphs at the original margin into code blocks they're not
    meant to be). The proper solution is to honor the virtual margin of the
    opening directive for the block ONLY, and ignore the indentation of
    other directives within that block.

    I truly believe the *one time* "last directive wins" is mentioned in S26
    is a mistake, or if this is Perl 5 POD behavior, a thinko when writing
    Raku's Pod spec. And yes, there is at least one spectest that tests for
    this, so this change would have to be locked behind a future language
    revision. But I do believe this change is for the better, even if you have
    to break compatibility.

=end pod

test_out.txt

This is a normal paragraph.

    This is an implicit =code block

OK so far? In the --doc output of rakudo, code blocks will be indented,
plain blocks will not be.

There's one part of S26 that mentions that the virtual left margin, which
determines if you have an implied code block or not, is set by the
positioning of "the last delimiter". Rakudo follows this, despite the fact
that every other mention in S26 mentions the virtual margin is set by the
positioning of "the opening delimiter" (the directive that starts the
block).

The "last delimiter" I believe is a mistake, and here's why: it permanently
breaks implicit code blocks. It's only mentioned in the context of =head
blocks, where it can make some intuitive sense:

    =begin pod
    Some text.

        =head1 Intro

        Having this paragraph text line up with the last header seems right,
        at least in one sense.
    =end pod


But this causes a fundamental issue, which we'll show now:

  * And now it breaks

This is a normal paragraph, lining up with the item block.

This is a paragraph indented in-source just like every other paragraph in
the =pod block. And now:

This is indented like the code block at the very beginning. Notice
anything?

The rest of this document is written like an implied code block, but it's
all rendered like normal text, because of that =item. This is, to put it
mildly, complete garbage behavior. It's at it's worst when you consider
people editing different pod documents over time: anyone who happens to
indent an inner directive at or beyond the column where your implied code
blocks happen will break every code block coming afterwards.

Now if you're thinking that a paragraph that starts to the left of the
current virtual margin should reset the virtual margin for future
paragraphs, that just causes the same issue in the other direction (turning
paragraphs at the original margin into code blocks they're not meant to
be). The proper solution is to honor the virtual margin of the opening
directive for the block ONLY, and ignore the indentation of other
directives within that block.

I truly believe the *one time* "last directive wins" is mentioned in S26 is
a mistake, or if this is Perl 5 POD behavior, a thinko when writing Raku's
Pod spec. And yes, there is at least one spectest that tests for this, so
this change would have to be locked behind a future language revision. But
I do believe this change is for the better, even if you have to break
compatibility.