=beginna =enda =fortnite

[lizmat]

These are all pod / rakudoc markers that are not allowed in both the old implementation of pod6 as well as in rakudoc.

Why? Because they share the root with =begin, =end and =for.

I was surprised to see this limitation in the legacy grammar as well. And it looks like this limitation has been in there like forever.

So I guess the questions is: should this be fixed (I didn't see an immediate fix), or should this be documented?

[finanalyst]

@lizmat But you managed to fix =formula Other than =formula, which is part of the new specification, all other forms should be caught because the spelling rules only allow lower case block names.

I have implemented a trap in the renderer for all lower case block names not specified (which would include the forms in the title), and create a RakuDoc warning, which is rendered at the end of the output, with some debug information.

The problem I found when =formula was failing is that the compiler does not provide much in the way of debug information, just a failure after the = of =begin rakudoc, which was confusing !!!!

[lizmat]

But you managed to fix =formula

Yes, by adding a specific token for =formula. And if we ever decide to allow =beginna or enda as a specific directive, that can be fixed as well. It's the general case of =begin\w+, =end\w+ and =for\w+ that are a problem.

The problem I found when =formula was failing is that the compiler does not provide much in the way of debug information, just a failure after the = of =begin rakudoc, which was confusing !!!!

Agree. The whole problem really is that from the compiler's point of view, all rakudoc is just whitespace. This also appears to block localizationn, for that matter.

I guess my grammar foo is insufficient to fix this. FWIW, I just tried an approach for =begin\w+, and that resulted in:

===SORRY!===
Invalid to edge 0 in NFA statelist

which is very low level and quite above my current paygrade. So I abandoned this idea, at least for now.

[lizmat]

To illustrate it's all whitespace:

my

=foo bar

$a

=bar baz

=

=zippo

42

=donko

;

=fnoppie

say

=huh

$a

not only compiles, but also runs and says 42

[finanalyst]

The current parser is doing enough for a RakuDoc v2 renderer to work. We already have Rakudo issues about better failure messages when RakuDoc does not compile, and being able to attach # commentary so that we ca get syntax highlighting via DEPARSE.

I think these are related to the above, so I suggest we close this issue here, or move to Rakudo.

[lizmat]

@finanalyst So you're saying the parser should be able to understand =fortnite. And the fact that it doesn't, is a flaw in the implementation.

Since this bug has been in Rakudo like forever, I wonder if @thoughtstream would have any insights as to why this bug (still) exists. If it is something that was found / discussed before, then I'd like to hear the outcome of that discussion! :-)

[finanalyst]

@lizmat oh I misunderstood. I thought that =for\S+, =begin\S+, and =end\S+ caused compile time errors. It does not matter for the Renderer I'm writing whether they are allowed or not. I have

given $ast.type ...
when # a list of named built-ins
when all($_.uniprops) ~~ / Lu / # to match semantic blocks
any($_.uniprops) ~~ / Lu / and any($_.uniprops) ~~ / Ll / # to match custom block
default { # generate an unknown built in block error }

If the compiler allows =fornite through, then it will be caught by the Renderer, and the document writer will get more debugging info than the compiler gives.

So, I suppose that perhaps the compiler should allow these forms through, and that it is for the renderer to deal with them.

Wouldnt that make the parser simpler to manage?

[thoughtstream]

Sorry, @lizmat, I have no insights into that long-standing issue with the Rakudo compiler’s handling of RakuDoc. I was not even aware of it.

[lizmat]

Really odd that nobody has noticed this in what is probably > 15 years :-)

So I guess we can leave it at documenting it as a known issue.

[tbrowder]

My memory is not great, but I do remember contributing to some pod grammar toward NYI items, and one was a sweeping change to the giant parsing block where I moved all the pod-only parsing to the end to help work on pod.

Pod tests then were not very extensive, but did get added slowly. I could easily have made that =fortnite problem when going into a realm I didn't fully understood. One known failed attempt was the =defn construct when I couldn't grok how to handle beginning whitespace after the =defn.

[finanalyst]

@liz Just found another formula problem.

=begin rakudoc

=for formula :caption<Fabulous identity>
e^{i\pi}+1=0

=end rakudoc

generates

$ RAKUDO_RAKUAST=1 raku -c test-e.rakudoc 
===SORRY!=== Error while compiling /home/richard/development/RakuDoc-GAMMA/test-e.rakudoc
=begin may not be followed by directive 'for'
at /home/richard/development/RakuDoc-GAMMA/test-e.rakudoc:3
------> <BOL>⏏=begin formula :caption<Fabulous identit

[finanalyst]

@thoughtstream I am wondering whether we might compromise a bit. =formula is a new addition to RakuDoc. F<> works without a problem.

The problem seems to be related to a deeper parsing problem.

Perhaps we could substitute =formula for =equation?

Perhaps later, we could make =formula an alternative to =equation

[lizmat]

Fortunately, =for formula was easily fixed: https://github.com/rakudo/rakudo/commit/e2fa55b9b1

[thoughtstream]

Outstanding, @lizmat!