Improve interactive prompting for face colors

When displaying the completion candidates, show how the face would
look with the new foreground/background.

* lisp/faces.el (faces--string-with-color): New helper,
factored out from 'defined-colors-with-face-attributes'.
(defined-colors-with-face-attributes): Use it.
(read-color): Add optional argument FACE and pass
it to 'faces--string-with-color.'
(read-face-attribute): Call 'read-color' with more appropriate
foreground and face arguments.

* doc/lispref/minibuf.texi (High-Level Completion): Describe
the intention behind the arguments FOREGROUND and FACE of
'read-color'.  (Bug#64725)

1 files changed, 7 insertions, 1 deletions

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 31b020db57c..4ed36edb8c1 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1537,7 +1537,8 @@ that it uses the predicate @code{custom-variable-p} instead of
 @code{commandp}.
 @end defun
 
-@deffn Command read-color &optional prompt convert allow-empty display
+@deffn Command read-color &optional prompt convert allow-empty @
+  display foreground face
 This function reads a string that is a color specification, either the
 color's name or an RGB hex value such as @code{#RRRGGGBBB}.  It
 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
@@ -1557,6 +1558,11 @@ non-@code{nil} and the user enters null input.
 
 Interactively, or when @var{display} is non-@code{nil}, the return
 value is also displayed in the echo area.
+
+The optional arguments FOREGROUND and FACE control the appearence of
+the completion candidates.  The candidates are displayed like FACE but
+with different colors.  If FOREGROUND is non-@code{nil} the foreground
+varies, otherwise the background.
 @end deffn
 
   See also the functions @code{read-coding-system} and