Re: PATCH: true colour support

[Oliver Kiddle <okiddle@xxxxxxxxxxx>]

The following patch adds documentation for the nearcolor module and
true color support.

By the way, the code is rather generous in terms of allowing missing
closing braces or extra characters before the closing brace in %F{…}
prompt expansions. So %F{123crap} just gives you colour 123. This is
in parsecolorchar() in prompt.c. Should this be considered a bug and
changed. This behaviour is old and has nothing todo with the patches.

Oliver

diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index 71ca52195..5a6a705ff 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -63,7 +63,8 @@ Zsh/mod_compctl.yo Zsh/mod_complete.yo Zsh/mod_complist.yo \
 Zsh/mod_computil.yo Zsh/mod_curses.yo \
 Zsh/mod_datetime.yo Zsh/mod_db_gdbm.yo Zsh/mod_deltochar.yo \
 Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_langinfo.yo \
-Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo Zsh/mod_newuser.yo \
+Zsh/mod_mapfile.yo Zsh/mod_mathfunc.yo \
+Zsh/mod_nearcolor.yo Zsh/mod_newuser.yo \
 Zsh/mod_parameter.yo Zsh/mod_pcre.yo Zsh/mod_private.yo \
 Zsh/mod_regex.yo Zsh/mod_sched.yo Zsh/mod_socket.yo \
 Zsh/mod_stat.yo  Zsh/mod_system.yo Zsh/mod_tcp.yo \
diff --git a/Doc/Zsh/mod_nearcolor.yo b/Doc/Zsh/mod_nearcolor.yo
new file mode 100644
index 000000000..9694bc105
--- /dev/null
+++ b/Doc/Zsh/mod_nearcolor.yo
@@ -0,0 +1,36 @@
+COMMENT(!MOD!zsh/nearcolor
+Map colours to the nearest colour in the available palette.
+!MOD!)
+The tt(zsh/nearcolor) module replaces colours specified as hex triplets
+with the nearest colour in the 88 or 256 colour palettes that are widely
+used by terminal emulators.  By default, 24-bit true colour escape codes
+are generated when colours are specified using hex triplets.  These are
+not supported by all terminals.  The purpose of this module is to make
+it easier to define colour preferences in a form that can work across a
+range of terminal emulators.
+
+Aside from the default colour, the ANSI standard for terminal escape
+codes provides for eight colours. The bright attribute brings this to
+sixteen. These basic colours are commonly used in terminal applications
+due to being widely supported. Expanded 88 and 256 colour palettes are
+also common and, while the first sixteen colours vary somewhat between
+terminals and configurations, these add a generally consistent and
+predictable set of colours.
+
+In order to use the tt(zsh/nearcolor) module, it only needs to be
+loaded. Thereafter, whenever a colour is specified using a hex triplet,
+it will be compared against each of the available colours and the
+closest will be selected. The first sixteen colours are never matched in
+this process due to being unpredictable.
+
+It isn't possible to reliably detect support for true colour in the
+terminal emulator. It is therefore recommended to be selective in
+loading the tt(zsh/nearcolor) module. For example, the following
+checks the tt(COLORTERM) environment variable:
+
+example([[ $COLORTERM = *LPAR()24bit|truecolor+RPAR()* ]] || \
+    zmodload zsh/nearcolor)
+
+Note that some terminals accept the true color escape codes but map
+them internally to a more limited palette in a similar manner to the
+tt(zsh/nearcolor) module.
diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index 895c5c570..fe4e5bd04 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -2703,8 +2703,9 @@ this to appear with other types of highlighting; it is used to override
 a default.
 )
 item(tt(fg=)var(colour))(
-The foreground colour should be set to var(colour), a decimal integer
-or the name of one of the eight most widely-supported colours.
+The foreground colour should be set to var(colour), a decimal integer,
+the name of one of the eight most widely-supported colours or as a
+`tt(#)' followed by an RGB triplet in hexadecimal format.
 
 Not all terminals support this and, of those that do, not all provide
 facilities to test the support, hence the user should decide based on the
@@ -2721,6 +2722,15 @@ Co)'; if this succeeds, it indicates a limit on the number of colours which
 will be enforced by the line editor.  The number of colours is in any case
 limited to 256 (i.e. the range 0 to 255).
 
+Some modern terminal emulators have support for 24-bit true colour (16
+million colours). In this case, the hex triplet format can be used. This
+consists of either a three or six digit hexadecimal number describing
+the red, green and blue components of the colour. Hex triplets can also
+be used with 88 and 256 colour terminals via the tt(zsh/nearcolor)
+module (see ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zsh/nearcolor Module))\
+).
+
 Colour is also known as color.
 )
 item(tt(bg=)var(colour))(
diff --git a/NEWS b/NEWS
index f3e617b9c..0b0c0e84c 100644
--- a/NEWS
+++ b/NEWS
@@ -4,6 +4,15 @@ CHANGES FROM PREVIOUS VERSIONS OF ZSH
 
 Note also the list of incompatibilities in the README file.
 
+Changes since 5.6.2
+-------------------
+
+Support for 24-bit true color terminals has been added. Hex triplets
+can be used when specifying colours for prompts and line editor
+highlighting. On 88 and 256 colour terminals, a new zsh/nearcolor module
+allows colours specified with hex triplets to be matched against the
+nearest available colour.
+
 Changes from 5.6.1 to 5.6.2
 ---------------------------