RFC: Add annotations to make roast deep-linkable

[awwaiid]

Roast is now the specification for Perl 6, and is the language test-suite for Rakudo. However, currently roast and docs both refer to the synopsis, so the relationship is something like this:

I propose that we reverse the references; we make it so that you can deep-link to specific parts of Roast from the docs, and instead of Roast referring to Synopsis we should have Synopsis refer to Roast (though that is less important than docs).

This PR uses (mis-uses?) the D<> pod6 reference as an example, but really the idea is to have something linkable. I think the filenames aren't fine-grained enough. The other side of this would be adding L<> entries to the docs. These wouldn't have to be visible links in the docs. Maybe like L<roast:operators/++> linking to D<operators/++>.

I'm very open to other syntaxes/notations for anchors & links.

The few things I'm hoping to get out of this in the short term:

• Doc coverage! Look for things in roast that have a D<> but there is no L<> to them from docs
• Make it so you can click and expand directly in the docs (inline) to see corresponding Roast examples. This is analogous to the "click to toggle source" js overlay from ruby-doc.org, but instead of deep linking into Rakudo, we'd deep-link into roast.

If this (or a variation we come up with) looks ok, I'd start annotating every roast file with the important concepts / syntax / etc that those tests define, ideally narrowed down to a specific block of assertions. I'd start with operators so I can get the docs side going as well and get a report of undocumented operators.

[LLFourn]

I am extremely enthusiastic about this feature. The main benefit is that it would allow the test writers to tell the doc writers in a very formal way that something is ready to be documented.

I think the best way to go about this is:

1. for you to do some annotations on your own roast.
2. You build the basic tools into htmlify.p6 in docs (including producing a page that lists all the things that haven't been documented. Pull this from your own roast branch)
3. Once we have the tools and synyax and tooling down we merge your roast into main roast and change htmlify.p6 to pull from the main roast branch.
4. add something to roast README.md that explains HOW and WHY to do doc test annotations

Other thoughts:

• I get where you are going by using #| but I don't think it's a good idea because that's specifically meant for .WHY of declarators which is not what we are doing. If there's a bug in pod declarators it has the potential to goof the entire test suite. I would lose the POD syntax entirely.
  More like:

#doc-roast 'operators','&infix:«+<»'
is( 32 +< 1,            64,     'shift one bit left' );

• The synopsis already refers to roast extensively
  https://design.perl6.org/S04.html#The_Relationship_of_Blocks_and_Declarations (click on the right aligned blue links). But it's fair to say that theirs is more of a dialectical relationship rather than one being a spec of the other. Sometimes the design docs change to reflect the spec sometimes the other way around.

Thanks very much for taking on this useful work! 👍

[awwaiid]

Awesome, thanks for the feedback. I like your suggested approach.

I'm going to go ahead and close this PR (though further comments always welcome) until I get a more full demo on both sides and some coverage. I'll probably work on something like operators first, which would quickly benefit from the coverage metric.