[Proposal] New Help subsystem

[KathleenDollard]

Help is the only subsystem we have targeted for a rewrite of Execute behavior. This is a major extensibility point and the core implementation is an opportunity to provide building blocks for extensions. This can be thought of as separating a semantic help from rendering.

Please split this proposal up into actionable issues that we can track here.

Goals:

• Provide primitives so to support renderers
• Provide renderers that can output to different formats, eventually including plain console, rich console, markdown, HTML, JSON, etc.
  • The initial version can just do two - probably plain console and markdown

Non-goals of this proposal:

• Output to alternate streams - let's leave that to the evolved and renamed Console.Hack
• Rich-text - we need to figure out a common format for bold and color, unless we find prior art we like for authors
• Provide the full correct version for terminal - let's keep this scoped to help as a prototype of what we can do with semantic output

Primitives:

• Section
• Table (multi-column - eventually not hard coded to two columns)
• Text

Design (ruminations to be updated as someone spends time on the problem)

My intuition is that usage is a primitive with a collection of "things" that are the different roles text represents and can be displayed by renderers as desired. Lots of detail missing here, such as who puts in the angle brackets.

The question of who puts on the angle bracket may also affect how options and arguments appear as that is repeated there.

If the renderer puts on the angle brackets, should it put on the square brackets as well?

Is that a big decision, or a little one because the angle brackets could be removed, assuming they are always first and last?

That would affect how choices appear. Are choices a sub-primitive?

My intuition is that examples (not needed in V1) is a primitive with a code piece and description.

I have a notion that usage and examples could be one thing.