Ticket #4885, #4896: skins: Move documentation to a separate file

Also slightly reword and update the documentation.

Signed-off-by: Egmont Koblinger <[email protected]>

Author: egmontkob

misc/skins/Makefile.am

@@ -1,6 +1,7 @@
 skindir = $(pkgdatadir)/skins
 
 skin_DATA = \
+	README_SKINS.txt \
 	dark.ini \
 	darkfar.ini \
 	default.ini \

misc/skins/README_SKINS.txt

@@ -0,0 +1,109 @@
+This is an overview of the color capabilities of skin files.
+
+See the FAQ for instructions on setting up 256 color or truecolor support in
+your terminal.
+
+
+Color definitions
+-----------------
+
+Keywords defining the colors and attributes to be used in a certain context
+have the following syntax:
+
+Color definitions have the syntax of
+
+    keyword = foreground_color;background_color;attributes
+
+Omitted values fall back to the section's "_default_", or in turn to the
+"[core]" section's "_default_".
+
+
+Legacy 16 color mode
+--------------------
+
+If you aim for the highest compatibility with terminals, you should restrict
+your skin to the standard 16 colors. These colors each have two names: the
+preferred human-friendly one, and a technical one referring to their color
+index.
+
+        black = color0             gray = color8
+          red = color1        brightred = color9
+        green = color2      brightgreen = color10
+        brown = color3           yellow = color11
+         blue = color4       brightblue = color12
+      magenta = color5    brightmagenta = color13
+         cyan = color6       brightcyan = color14
+    lightgray = color7            white = color15
+
+With 8 color terminal settings (such as TERM=linux or TERM=xterm), bright
+foreground colors (second column) are emulated in mc by enabling the bold
+attribute, and the colors are mapped to their darker counterpart (first
+column). In turn, the terminal may (or may not) interpret the bold flag as
+brighter foreground color, thus reverting to the originally specified bright
+foreground.
+
+Even in terminals that support more colors (such as TERM=xterm-256color), the
+first 8 foreground colors combined with the bold attribute might be converted
+to their brighter counterpart. This depends on choice of the terminal or a
+setting thereof, mc having no control over it.
+
+Plus, the exact color values heavily depend on the user's chosen palette.
+
+For all these reasons, a skin using these colors can look quite different
+across systems.
+
+
+256 color extension
+-------------------
+
+Almost all graphical terminal emulators support the 256 color extension.
+
+By adding "256colors = true" to the "[skin]" section, you get access to 240
+additional colors (a 6x6x6 color cube and a 24 color grayscale ramp) on top of
+the standard 16.
+
+Colors of the 6x6x6 cube are called "rgb000" to "rgb555", all three digits
+ranging from 0 to 5, corresponding to the R, G and B color components.
+Alternatively, you can use their technical color index: "color16" to
+"color231".
+
+Colors of the grayscale ramp are "gray0" to "gray23", or "color232" to
+"color255".
+
+There are scripts available that display these colors in the terminal (e.g.
+"256colors2.pl" shipped in Xterm's source code), as well as web pages showing
+them (e.g. https://www.ditig.com/256-colors-cheat-sheet).
+
+
+Truecolor extension
+-------------------
+
+A wide range of terminals support the truecolor extension.
+
+By adding "truecolors = true" to the "[skin]" section (instead of the
+"256colors" keyword), you get access to 2^24 (about 16 million) direct colors
+on top of the 256 palette ones.
+
+Truecolors are referred to by the standard "#rrggbb" or "#rgb" notation. The
+short form is interpreted by repeating each hex digit, e.g. "#5AF" is a
+shorthand for "#55AAFF".
+
+
+Attributes
+----------
+
+The third value can specify special attributes to apply. Supported attributes
+are:
+
+    bold
+    underline
+    italic
+    reverse
+    blink
+
+Append more with a plus sign, e.g. "bold+italic".
+
+Omitting the field makes it use the fallback value as described above. Use any
+unrecognized word (e.g. "none") to prevent fallback and disable all
+attributes.
+

misc/skins/julia256root.ini

@@ -1,5 +1,5 @@
 # Dark skin with calm colors and good contrast. Mix of the standard & xoria256 skins.
-# Color referance https://www.ditig.com/publications/256-colors-cheat-sheet
+
 [skin]
     description = Dark skin with calm colors and good contrast (root)
     256colors = true

misc/skins/sand256.ini

@@ -1,54 +1,3 @@
-# This skin demonstrates how to use 256 colors in mc.
-#
-# See the FAQ for instructions on setting up 256 colors.
-#
-# Each of the 256 colors has two names, you can use whichever you prefer.
-#
-# One possibility is to use the names "color0" to "color255" to access every
-# color directly based on their number.
-#
-# The first 16 colors ("color0" to "color15") can also be specified by their
-# names (these names are already being used by mc for 8/16 color terminals):
-#   black      gray
-#   red        brightred
-#   green      brightgreen
-#   brown      yellow
-#   blue       brightblue
-#   magenta    brightmagenta
-#   cyan       brightcyan
-#   lightgray  white
-# Note that with 8 color terminal settings (such as TERM=xterm), colors of
-# the second column are emulated using the bold attribute (which many
-# terminals display as bright colors) for the foreground, and mapped to the
-# basic 8 colors for the background. With 16 color terminal settings, the
-# actual implementation of bright colors varies across terminals. Most
-# terminals show true bright colors for foreground and background. However,
-# some terminals show the colors from the first column instead (that is,
-# you only have 8 colors), but make them bold. Yet others make them bold
-# and bright at the same time. So it is safer to use the rest of the colors
-# (color16 to color255).
-#
-# Colors of the 6x6x6 cube ("color16" to "color231") can alternatively be
-# referred to as "rgb000" to "rgb555", all three digits ranging from 0 to 5,
-# corresponding to the R, G and B color components.
-#
-# The 24 grayscale colors ("color232" to "color255") have the aliases "gray0"
-# to "gray23".
-#
-# In addition to the 256 colors, the special word "default" means the
-# default foreground or background color of your terminal, while "base" means
-# mc's main colors. A missing value means falling back to the _default_ of the
-# given section.
-#
-# Following the foreground and background colors, the third (optional) value
-# can specify special attributes to enable. Valid values are bold, underline,
-# italic, reverse and blink. Append more with a plus sign, e.g. "bold+italic".
-# Leaving the field empty makes it fall back to the attributes of _default_.
-# Use any other word (e.g. "none") to prevent fallback and disable all flags.
-#
-# Italic support requires a recent enough ncurses (>= 5.9.20130831) or slang
-# (>= 2.3). All attributes are subject to support by the terminal emulator.
-
 [skin]
     description = Sand skin using 256 colors
     256colors = true

misc/skins/seasons-autumn16M.ini

@@ -1,12 +1,4 @@
 # The Four Seasons skins demonstrate how to use direct RGB true colors.
-#
-# See the FAQ for instructions on setting up true colors.
-#
-# True colors are referred to by the standard #rrggbb or #rgb notation, the
-# short form is interpreted by doubling each hex digit.
-#
-# In addition to these, you can use the basic 8 (non-light) colors and
-# the attributes. However, you can't use the 256 indexed colors.
 
 [skin]
     # Falling leaves, beautiful forests, Halloween pumpkins.

misc/skins/seasons-spring16M.ini

@@ -1,12 +1,4 @@
 # The Four Seasons skins demonstrate how to use direct RGB true colors.
-#
-# See the FAQ for instructions on setting up true colors.
-#
-# True colors are referred to by the standard #rrggbb or #rgb notation, the
-# short form is interpreted by doubling each hex digit.
-#
-# In addition to these the 256 palette colors are still available, and
-# obviously so are the attributes. See the sand256.ini skin file for details.
 
 [skin]
     # Blooming.

misc/skins/seasons-summer16M.ini

@@ -1,12 +1,4 @@
 # The Four Seasons skins demonstrate how to use direct RGB true colors.
-#
-# See the FAQ for instructions on setting up true colors.
-#
-# True colors are referred to by the standard #rrggbb or #rgb notation, the
-# short form is interpreted by doubling each hex digit.
-#
-# In addition to these the 256 palette colors are still available, and
-# obviously so are the attributes. See the sand256.ini skin file for details.
 
 [skin]
     # Sunshine, ocean, beach, beachball, sunshades, ice cream.

misc/skins/seasons-winter16M.ini

@@ -1,12 +1,4 @@
 # The Four Seasons skins demonstrate how to use direct RGB true colors.
-#
-# See the FAQ for instructions on setting up true colors.
-#
-# True colors are referred to by the standard #rrggbb or #rgb notation, the
-# short form is interpreted by doubling each hex digit.
-#
-# In addition to these the 256 palette colors are still available, and
-# obviously so are the attributes. See the sand256.ini skin file for details.
 
 [skin]
     # The sun is shining and the grass is green,