Status of the POD6 implementation

[JJ]

I am not sure what's the status of the Pod6 implementation. @tbrowder has been doing a great job so far, but I'm not sure who else is taking care of that. A lot of what needs to be done is included in this document by @tbrowder, but there are also other parts of the stack (pod-to-text, test) that are not included there. I'll mix and match below.

Anyway, as far as I can tell

• P<> is not implemented. There's a block type P, but then it does not actually act on that, by including the content of P at the AST level or at the rendering level. This PR which does the latter rakudo/rakudo#313 is in fact the first one not yet merged.
• :margin is not tested. Not clear if it's implemented or not. `=headx :numbered" is not tested, and there are other versions of numbered whose tests are skipped.
• I'm not too sure about :allow. It's parsed and tested, but I'm not sure about support in the pod-to-text level.
• Lists are tested up to =item2 level; lists with skipped levels are not tested
• Named blocks (=begin Html) are not tested, although they are used in the documentation, so I guess they work...
• =finish block is not tested. It's apparently in the code since 2015.06
• Data blocks are not implemented
• Semantic blocks are ignored, as far as I can tell. Synopsis tells us to format them using =head1, but I don't see them in the source.
• U, K, T, R and D<>formatting codes are not tested. Not clear if they are parsed.
• Links to docs are not implemented: L<doc> Other types of links, like the ones to definitions, are not present either.
• Indexes C are handled at the rendering level. We do have lots of trouble with this in the documentation (/cc @antoniogamiz ) since we get the raw content of the X and what we do with it is ambiguous
• Module-defined formatting codes will probably never be implemented
• =alias is not even heard of

All in all, I would say

• There are parts that are implemented and tested, but not documented. I'll raise an issue about that.
• There are parts that are implemented, but not tested. We can raise an issue in roast.
• There are parts whose implementation status is not clear. We need to clarify that.
• There are parts that are clearly identified as NYI. We need to have a roadmap to implement them.
• There are parts that are neither implemented nor NYI. I would say we have to provide a new specification to clarify what's going to happen to them.

[jnthn]

I am not sure what's the status of the Pod6 implementation.

Depends what you mean by status, but if you mean "who is working on it", then its status is like just about everything else going on around Perl 6: it's dependent on either volunteers making it happen - as you note, @tbrowder has been doing a great job there for Pod6 - or, on the occasion when we're really lucky, on some organization deciding to throw employee time at it because they need it (or are feeling generous).

In terms of its status in terms of "is the implementation in good shape": certainly I find the Pod6 part of the grammar a bit trickier than the rest of it, but I don't know to what degree that's accidental complexity or a result of Pod6 being quite some effort to parse. I do know that for Comma's parser I mostly followed the grammar in Rakudo (with lots of derivations for handling incomplete constructs), but when I came to Pod6 I decided to work off the spec instead; if I remember correctly, there's quite a lot of imperative elements to the way Pod6 is parsed in Rakudo. That said, I didn't actually get into many of the details yet, and maybe when I do, I'll realize why it's so involved in Rakudo. If I come up with a simpler approach that seems to work, I'll certainly share that.

In terms of the list of things you have: it'd help to prioritize. There's a lot of work there, but probably some bits are more valuable to the Perl 6 documentation effort that others. That doesn't magically make volunteers appear, but at least it's a bit easier to get motivated on things are known to be valuable.

I guess it might help to make Pod6 a "squashathon" topic, which might at least help with some aspects that don't require internals knowledge (such as increasing roast coverage and documenting things that aren't yet documented).

[JJ]

OK, let's try and prioritize.

• Testing what's already implemented would be first.
• Inclusion via P would actually make the life of the doccers (my own made-up name for people working in the documentation) easier. We could overhaul the whole system in a more principled way.
• The rest in no particular order.

The squashathon would be a good idea, but just looking at the NQP code @tbrowder has written tells me we have soooo much to learn... If there's someone participating that could help there it would be great, because I have the impression that a big chunk of it will be NQP coding.

[AlexDaniel]

You can't just throw a difficult problem at squashathon participants and expect a lot of work to get done. Practice shows that squashathons only work when you have many (like ≈100 at least) of small actionable tasks. There's no such thing for pod6 (… yet?), so forget it.

[JJ]

OK, so I just closed that PR trying to include P as too difficult to add, but we still need it in the documentation. Something along the lines of that patch would be nice, but we have not agreed on the difference between the doc: and the file: URIs in this context, or how they would be treated. Any feedback on this?