Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for ANSI output format #362

Open
tribals opened this issue Sep 27, 2020 · 8 comments
Open

Add support for ANSI output format #362

tribals opened this issue Sep 27, 2020 · 8 comments

Comments

@tribals
Copy link

tribals commented Sep 27, 2020

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:

image

(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
Copy link
Member

jgm commented Sep 27, 2020

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
Copy link
Contributor

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
Copy link
Author

tribals commented Jan 19, 2024

I'm happy with mentioned commonmark executable.

😊

@Ericson2314
Copy link
Contributor

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

@jgm
Copy link
Member

jgm commented Jan 19, 2024

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:

image

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
Copy link
Contributor

@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
Copy link
Author

tribals commented Jan 20, 2024

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
Copy link
Contributor

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants