4896 skin readme

[egmontkob]

Proposed changes

• Fix frame colors
• Remove some obsolete comments, fix some typos
• Move documentation to a separate file

• Resolves: Wrong comment about 256 colors in truecolor skins #4885
• Resolves: Revise skin instructions, move to separate README #4896

Checklist

👉 Our coding style can be found here: https://midnight-commander.org/coding-style/ 👈

• I have referenced the issue(s) resolved by this PR (if any)
• I have signed-off my contribution with git commit --amend -s
• Lint and unit tests pass locally with my changes (make indent && make check)
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)

[zyv]

Is it a good idea to call it README_SKINS.txt ? In other places, we call those README.txt or README.md.

[ossilator]

yeah, the name is redundant with the path. i wouldn't do that, either.
it would be different if the file got installed into the docdir instead of along with the skins, though then an install-time rename would kind of make sense.

[egmontkob]

Fair enough, I'll rename to README.txt.

Rant:

Despite all my hatred towards Markdown, I started with .md. Then I got stuck at the two-column table listing the 8*2 colors.

Markdown doesn't support headerless tables, tables need to have a header, even if I don't want to. Okay, I made up some header. Then I converted to HTML using a random command I found on the web. The table didn't work. Then I tried another, completely different command I found. Didn't work either. Third command. Nope. Then I read 3 people recommending 3 different extensions to load to that markdown formatter, none of which worked. (They didn't work with tables copy-pasted from Markdown examples either, it's not that I made a stupid typo.)

The idea that the source is already beautifully formatted, and it is also the source of conversion to another format which is even more beautifully formatted, is utterly braindamaged to begin with.

There's no unified specification, everyone has their own extensions. There's not even a bare minimum, including tables, that would work in all reasonable converters. Everyone does their all random things which barely work. (One of my "favorites", deliberately not linking not to have a backlink, is github jamiemcg Remarkable 207: they got the very basics of line / paragraph wrapping wrong and it took them 2 years to fix.)

Another aspect that I hate is that pretty much all characters have a special meaning, and there's no consistent way of escaping, or often there's no way of escaping at all. E.g. inside backticks you get to print some literal text; but what if you want to print a backtick in that way? You're out of luck. What if you want to have a paragraph that begins with "1.", without converting to a bullet point? You're again out of luck. This list goes on and on and on. It's a giant pile of ad-hoc solutions that work together very badly.

If the source file is tied to a particular formatter (e.g. appearing on github's page, or part of mc's make procedure converting it to an html that we install), and you didn't want to do any "unusual" formatting (e.g. as per my previous paragraph), then Markdown, despite being terribly designed, is at least practical.

If the source just sits there without being converted, or left for the user to be converted (and who's going to test and tell the user which converter to use that works properly on that file?) then Markdown is not only terribly designed but is also terribly impractical. If the file just sits there with no one attempting to convert it to html, there's no reason to attempt to be "valid" Markdown (which concept doesn't exist), just go with whatever contents you want to and call it .txt.

My 2 cents on Markdown :)

[ossilator]

yeah, markdown is crap. ReStructuredText is better.

[zyv]

My 2 cents on Markdown :)

Enjoy some roff and the Markdown pain will subside ;-)

[egmontkob]

My recent roff experientes weren't that bad. Mind you, I didn't stress-test its capabilities :)

Actually, now that I started working on merging the manpage and the README here, I might change my mind. Having access to colors, and auto-formatting to the terminal width, are definitely advantages for the user.

Anyway, let me have the contents first. Formatting will follow.

[zyv]

There is some description of skins in the manual page:

https://source.midnight-commander.org/man/mc.html#Skins

This might be quite outdated (after tickets like #4932) and/or incorrect.

Would you have the motivation to glance over it and add obviously missing easy stuff, and maybe a reference to this file?

Also, in this file, you could add a reverse reference to check the manual page for the basic documentation.

I think one could argue for this content to go into the manual page, but it feels way too detailed and annoying to typeset, so probably this README is the best place for it.

[egmontkob]

Indeed, that part of the manual (which I didn't recall existed at all) is super outdated. On the other hand, it talks about the keywords too, which is missing from my README.

We should indeed unify them: keep and update one, and throw away the other.

I would also prefer to further update the README (add the missing keywords), and replace the existing part of the manual with just a brief pointer. Reasons:

• Easier, quicker typesetting (as you said), i.e. less work for us.
• We're more likely to keep it updated as skin capabilities evolve.
• We don't put pressure on translators to translate, should anyone decide to translate the manual to a new language or update one of the outdated translations; in the mean time, keeping the manual short in general might encourage others to translate to new languages.
• It's borderline between user and developer documentation. We already have similar docs outside of the manpage, e.g. in the FAQ.

I'll do it.