`cmark`’s pretty-printer matches our output pretty well, with a few differences:
- it puts a space between the fence and the info string for in code blocks;
- it prefers `-` over `*` for bulleted lists (as do I) and it indents them;
- it `\`-escapes certain chars very conservatively;
- it prefers indented/unfenced code blocks if there is no info string; and
- it prefers `*` over `_` (unlike any sane person).
This also shows how the change fixes a number of issues:
- fix2158-1.output.md also illustrates how this change fixes#1809;
- alias-many.output.md and input-parse-errors.output.md show how fenced
code blocks without an info string would use the beginning of the
content as the info string;
- transcripts-round-trip/main.output.md shows how output blocks for
generated `unison` stanzas (which could contain nested fenced blocks)
might not have long-enough fences; and
- error-messages.output.md and generic-parse-errors.output.md show how
Unison errors were reported on the wrong line number (and thus the
printed error lines were also incorrect).
We don’t need a very rich parser for transcripts, but we _do_ need to
reliably identify fenced code blocks, and that implies a number of
subtle cases. Using a polished CommonMark parser/printer handles those
subtleties for us.
I chose `cmark` for a few reasons:
- it’s a wrapper around `libcmark`, which is the reference
implementation of CommonMark, so it should be correct;
- it provides both a parser and a printer (unlike MMark); and
- it is extremely fast (about 20x faster than MMark), so the fact that
our home-rolled parser got to skip over everything that’s not a block
isn’t an issue.).
This only _partially_ uses the `cmark` printer. I think it should use it
entirely, but for the cases where we do streaming output (processing UCM
commands, etc.) it’s a more involved change. So I think it should be
handled separately.
- remove `warnCallout` and `warn` from individual messages
- make sure no error messages return their `help` content
- add some documentation about how to write failure messages
- don’t add an extra indent level to the entire output
- do add a `warnCallout` to the message
- don’t re-wrap formatted error output
- remove the accidentally-included entire `help <command>` output
to avoid a potential cycle between CommandLine.hs and InputPatterns.hs
that otherwise came up on another branch.
InputPatterns.hs also has formatting helpers that could be used in CommandLine.hs.
Maybe they should be moved too, but I haven't thought about it.
