`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).
Stop eating spaces that immediately follow @[source], @[evaluate] or @[include] directives on the same line, while unindenting.
Also fix docs.md so its example isn't asking for line-wrapping.
Currently Unison takes doc literals like
[:
example usage:
- note the call to bar
- we pass it 1
foo =
bar 1
baz
:]
and renders them as
[: example usage:
- note the call to bar
- we pass it 1
foo =
bar 1
baz :]
due to the paragraph reflow/wrapping function.
Also, this function only works the first time you use it on a doc: if you `edit` a doc and mess with it, you won't get the wrapping refreshed the next time you view. That's because the pretty-printing works by inserting newlines, which are treated as paragraph breaks by Unison the next time it sees the code.
I'm planning to fix this by
- only doing paragraph reflow/wrapping for lines with zero indent (where zero is the left-most non-whitespace column of the doc)
- normalizing docs during parse, including removing newlines that are within a paragraph.
See unison-src/transcripts/doc-formatting.md in this commit for more details of how this shakes out. Not the .md.output because that's showing the current behavior without this change implemented.
Hopefully this is just a few more lines of code to implement, and then #936/#994 is good to merge.
