Add support for ANSI output format

[tribals]

Currently, there is man output format (-t, --to). It can be viewed using something like

$ cmark -t man < README.md | man -l -

Unfortunately, produced output is absolutely unreadable, unless it follows closely man pages conventions, eg, declares all required sections (NAME, SYNOPSIS, etc). This is very unfortunate situation when most of README's you're reading is from public git repositories.

However, displaying nicely formatted, colored Markdown in terminal is possible, using ANSI "formatting" sequences. Here is example of such representation:

(Colors are a bit weird, but this is just illustration)

So, it would be nice to have ANSI as supported output format. What do you think?

[jgm]

I implemented something like this in the commonmark executable provided by my Haskell commonmark library (jgm/commonmark-hs, see commonmark-cli).

commonmark --highlight

It would certainly be possible to add something like that to cmark, though it's not a priority for me.

[Ericson2314]

Am I reading that right that you all are open to a contribution from this? I would port over https://github.com/kristapsdz/lowdown/blob/master/term.c

This would allow Nix to switch to cmark entirely and drop lowdown, which i would like.

[tribals]

I'm happy with mentioned commonmark executable.

😊

[Ericson2314]

I need a library version, so I am hoping that the commonmark maintainers are happy with that :)

[jgm]

I'd be open to it, but I'd want to be sure that the lighter-weight option of using man output isn't sufficient.

Here's what I see when I generate and view the man output from this project's README.md:

That looks fine to me, except for the ()s at the top. Those could be replaced by something else by using a template that specifies a .TH macro. (And we could build this into the library in principle.)

Small note: commonmark-hs's command line utility does something different from the what is being proposed here, I think. It doesn't render the AST to the terminal, which might introduce semantically insignificant changes in the text, instead, it renders the original file, exactly as it appears, but with highlighting added.

[Ericson2314]

@jgm I actually don't have any issue with the the man output per-se. Our use case includes having a self-contained nix executable directly output some pretty-pretty documentation on the terminal without relying on other programs. It's the self-contained-ness that matters more than what the exact result looks like.

(That said, FWIW our current terminal rendering from lowdown does some colors and whatnot beyond what man does.)

[tribals]

Our use case includes having a self-contained nix executable directly output some pretty-pretty documentation on the terminal without relying on other programs.

Personally I want to state that such style of documentation for CLI tools is worst-case - it is neither man nor help, you're forcing user to pipe output to pager and leaving out man convetions (no one interested in following them because "help files" is written in Markdown, and typical markdown user is rarely even avare of existence of manual pages, and their conventions).

[Ericson2314]

@tribals I didn't event these requirements :). I'm just trying to swap up one markdown library for another one so I can (a) programmatically create docs (b) get windows support, without loosing features.