Merge topic 'ccmake-custom-colors'

671fe28313 ccmake: Improve coloring, allow customization
f56a695440 ccmake: Rename cmCursesColor::{Options => Choice}

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4629

3 files changed, 47 insertions, 0 deletions

diff --git a/Help/envvar/CCMAKE_COLORS.rst b/Help/envvar/CCMAKE_COLORS.rst
new file mode 100644
index 0000000..d4750c3
--- /dev/null
+++ b/Help/envvar/CCMAKE_COLORS.rst
@@ -0,0 +1,34 @@
+CCMAKE_COLORS
+-------------
+
+Determines what colors are used by the CMake curses interface,
+when run on a terminal that supports colors.
+The syntax follows the same conventions as ``LS_COLORS``;
+that is, a list of key/value pairs separated by ``:``.
+
+Keys are a single letter corresponding to a CMake cache variable type:
+
+- ``s``: A ``STRING``.
+- ``p``: A ``FILEPATH``.
+- ``c``: A value which has an associated list of choices.
+- ``y``: A ``BOOL`` which has a true-like value (e.g. ``ON``, ``YES``).
+- ``n``: A ``BOOL`` which has a false-like value (e.g. ``OFF``, ``NO``).
+
+Values are an integer number that specifies what color to use.
+``0`` is black (you probably don't want to use that).
+Others are determined by your terminal's color support.
+Most (color) terminals will support at least 8 or 16 colors.
+Some will support up to 256 colors. The colors will likely match
+`this chart <https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg>`_,
+although the first 16 colors may match the original
+`CGA color palette <https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette>`_.
+(Many modern terminal emulators also allow their color palette,
+at least for the first 16 colors, to be configured by the user.)
+
+Note that fairly minimal checking is done for bad colors
+(although a value higher than what curses believes your terminal supports
+will be silently ignored) or bad syntax.
+
+For example::
+
+  CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index dfdf415..ee83799 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -80,3 +80,11 @@ Environment Variables for CTest
    /envvar/CTEST_PROGRESS_OUTPUT
    /envvar/CTEST_USE_LAUNCHERS_DEFAULT
    /envvar/DASHBOARD_TEST_FROM_CTEST
+
+Environment Variables for the CMake curses interface
+====================================================
+
+.. toctree::
+   :maxdepth: 1
+
+   /envvar/CCMAKE_COLORS
diff --git a/Help/release/dev/ccmake-custom-colors.rst b/Help/release/dev/ccmake-custom-colors.rst
new file mode 100644
index 0000000..fcabe56
--- /dev/null
+++ b/Help/release/dev/ccmake-custom-colors.rst
@@ -0,0 +1,5 @@
+ccmake-custom-colors
+--------------------
+
+* :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
+  environment variable to customize colors.