Update FLTK colormap (src/fl_cmap.h) w/o changing colors

- update comments, including filenames
- update build instructions for developers in util/cmap.cxx
- update CMakeLists.txt (comments only)

1 files changed, 43 insertions, 14 deletions

diff --git a/util/cmap.cxx b/util/cmap.cxx
index e413c4534..3f821fd5b 100644
--- a/util/cmap.cxx
+++ b/util/cmap.cxx
@@ -1,7 +1,7 @@
 //
 // Colormap generation program for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-2026 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -15,23 +15,51 @@
 //
 
 //
-// This program produces the contents of "fl_cmap.h" on stdout
+// This program produces the contents of "fl_cmap.h" on stdout. If you
+// need to change the built-in FLTK colormap, change this source file
+// accordingly and proceed as follows:
 //
-// Compile, link, run and delete the program 'cmap' (for instance on a
-// Linux system) to generate fl_cmap.h:
+// (1) Build the program `bin/cmap`
+//
+//   $ `MAKE` cmap   # see below for details
+//
+// or
+//
+//   $ cmake --build . --target cmap
+//
+// in your CMake build directory (replace `MAKE` with your build tool,
+// for instance `make` or `ninja` or whatever you chose to build FLTK).
+//
+// (2) Run the program from the build folder:
+//
+//   $ bin/cmap > output.h
+//
+// (3) Compare `output.h` with the existing file in the source folder
+// `[fltk-source-dir]/src/fl_cmap.h`. Take care that the result (diff)
+// is plausible.
+//
+// (4) Replace `[fltk-source-dir]/src/fl_cmap.h` in the FLTK source tree
+// with the created file `output.h`.
+//
+// (5) Build and test FLTK, check if the new color map is as intended.
+//
+// (6) Finally check in *both* modified file with `git commit` and push
+// your changes to the main repository with `git push`.
+//
+// Note: the created executable `bin/cmap` is temporary and may be deleted
+// at any time. It is not intended to be `installed` with the FLTK library.
 //
-// gcc -o cmap cmap.cxx -lm && ./cmap > ../src/fl_cmap.h && rm -f ./cmap
 
 #include <stdio.h>
 #include <math.h>
 #include <time.h>
 
-// This table is initialized with color values I got by reading the
-// colormap on an IRIX 4.3 machine:
+// This table is initialized with color values taken from the colormap
+// on an IRIX 4.3 machine:
 
 // "full intensity colors" have been turned down some to make white
 // background less intense by default.  The hope is that this will make
-// fltk programs more friendly on color-adjusted screens.  If you want
+// FLTK programs more friendly on color-adjusted screens. If you want
 // pure colors you should get them out of the colormap.
 
 // #define III 244 // maximum intensity of the basic colors
@@ -63,15 +91,15 @@ static short cmap[256][3] = {
   {142, 56,142},        // purple, orchid, pale magenta
   { 56,142,142},        // cadet blue, aquamarine, pale cyan
 
-  // The next location (15) is used for FL_SELECTION_COLOR. It formerly was
-  // 2/3 gray but this is changed to be the Windows blue color. This allows
-  // the default behavior on both X and Windows to match:
+  // The next location (index 15) is used for FL_SELECTION_COLOR. It formerly
+  // was 2/3 gray but this is changed to be the Windows blue color. This
+  // allows the default behavior on both X and Windows to match:
   // {170,170,170},     // old 2/3 gray color
 
   {  0,  0,128},        // 15 = FL_SELECTION_COLOR
 
   // These next 16 (index 16 - 31) are the FL_FREE_COLOR area. In some
-  // versions of fltk these were filled with random colors that a Irix 5.3
+  // versions of FLTK these were filled with random colors that a Irix 5.3
   // machine placed in these locations.
 
   // This version uses colors that NewTek has assigned for their GUI
@@ -101,7 +129,8 @@ static short cmap[256][3] = {
 
 #define FL_GRAY_RAMP 32
 #define FL_NUM_GRAY  24
-#define FL_GRAY 49 // old value is 47
+#define FL_GRAY      49 // old value is 47
+
 typedef unsigned char uchar;
 
 void background(uchar r, uchar g, uchar b) {
@@ -191,7 +220,7 @@ int main() {
   // write final comment
 
   printf("//\n");
-  printf("// End of fl_cmap.h - generated by cmap.cxx\n");
+  printf("// End of src/fl_cmap.h - generated by util/cmap.cxx\n");
   printf("//\n");
 
   return 0;