Add support for "literate specs"

[shonfeder]

We'll want an easy and convenient way for specification authors to be able to author specs meant as protocol and algorithm design documents while taking advantage of all our tooling. The best UX for this is probably thru extending our compiler and plugin tooling. Likely features to include:

• Generate markdown that preserves the body of operators
• Support annotations for hiding some sections by default
  • This would probably produce details/summary tags
• Support markdown syntax highlighting for documentation comments in VSCode pluging
• Support multiline documentation comments
• Preserve comments in AST so they can be included, as they are often important for literate code

[konnov]

I have introduced its own milestone for this issue, as it will definitely generate more issues.

[konnov]

I am closing this issue. lmt solves this problem in a simple yet powerful way. I have written 3 markdown documents with it and it works much better than my initial idea of having markdown in comments. If we run into issues with lmt, we should design a new approach to literate specs, but not earlier than that.

[shonfeder]

Nice that we don't need to implement this 💃

Let's document the process tho, and set up an example with a makefile! :D

[shonfeder]

Just a note as I'm looking at lmt and giving it a spin:

• unreleased, unversioned, not available on any package managers
• no tests I can see
• the macro system seems unnecessary for our needs IMO
• the CLI has no help or documentation

That said, the tool works as documented. I'll write up a note on a workflow for this to integrate with our tool for the time being. Still, we may want to consider finding or creating a more robust solution at some point.