Personally, I think README.md is pretty readable in a terminal, even more with a pager like less that doesn't wrap lines [i believe] by default. Markdown (at least, without extensions) is meant to be readable as plain text after all.
Maybe it's my eyes but what are the odds that someone reading this file in a terminal has never written markdown before?

The only likely pain in the ass (or to the eyes) would be this line which can simply be split across multiple physical lines and I believe that shouldn't affect the rendered HTML output. It may also do well with a little reformatting overrall.

On another note, README (plain text) contains some extra info about installation. I think this can simply be added to README.md (possibly within a <details> tag to hide it by default in the rendered output), if neccessary.

Finally, as far as MarkDown viewers (terminal-based or not) go, I don't think I've come across any popular Linux distro or DE (I can't speak for other platforms) that comes with one pre-installed, neither do I recall any particular one that's widely used.

Thanks, very happy to have your input.

Unfortunately, less does wrap lines by default, so if you're not invoking it with -S, you'll be looking at impenetrable blobs of HTML. MD supports comments, though, which allows us to have text saying "please skip the following nonsense to get to the actual document". Which is kind of inelegant. Looking at it gives me the same feeling a lot of web pages do, you know the ones where you have to scroll past a lot of dross to get to the actual content.

I'm considering just removing the package installation instructions and revamping the official web pages instead to make them easier to find there. The reason is that if you got the source archive, you're already past that point in your installation decision tree. The other reason is that tables in MD are cluttered. Instead of this:

Arch Linux .... pacman -S chafa
Brew .......... brew install chafa
Debian ........ apt install chafa

...we'd have to do this:

| Distribution | Command to install     |
|--------------|------------------------|
| Arch Linux   | pacman -S chafa        |
| Brew         | brew install chafa     |
| Debian       | apt install chafa      |

Also, you can't have a portable markdown table without headers.

I took a quick look at what people are using to read MD in the terminal, and it wasn't very uplifting. The best option seems to be to convert it to HTML and send it to a web browser:

pandoc README.md | lynx -stdin

The result actually looks pretty good, but I think people mostly won't know or remember to do it. We can put it in the leading comment, though.

Thanks, very happy to have your input.

:)

Unfortunately, less does wrap lines by default, ...

Oh, my bad... I must've been confused by my distro's default config then.

Your concern about using comments is solid. It'll be quite messy.

About the package installation instructions, removal is okay. What should be required at that point are majorly instructions to build which I think INSTALL contains. Someone with the source probably either can't or doesn't want to install using a package manager (or any other means) anyways.

Concerning MD viewers, you might wanna take a look at frogmouth.

Interesting!

Regarding INSTALL, I wonder if we shouldn't just remove that too. It's generic, it's long by today's standards, and I bet nobody reads it. The ones who'd care are packagers, and they generally already know how to deal with autoconf, or where to find the instructions.

Then we can add one or two important configure tips to the README.md, like --help and --prefix. Probably also mention there are tests and that you can run them with make check.

Regarding INSTALL, I wonder if we shouldn't just remove that too. It's generic, it's long by today's standards, and I bet nobody reads it.

To be honest, the first time I read it was when writing my first comment on this issue and I was surprised by the content. I was expecting something way more specific and shorter. At first, when I noticed the length, I assumed it contained (and detailed) all installation options 😆.

Then we can add one or two important configure tips to the README.md, like --help and --prefix. Probably also mention there are tests and that you can run them with make check.

Yeah, will be better.

One possibility is to use Github Actions to keep both files in sync, such as with the help of Pandoc.

Regarding terminal Markdown readers, I recommend glow.