changeset 98968:155f65cc590b

(High-Level Completion): Document `read-color'.

--- a/doc/lispref/minibuf.texi	Tue Oct 21 10:07:06 2008 +0000
+++ b/doc/lispref/minibuf.texi	Tue Oct 21 11:23:57 2008 +0000
@@ -1267,6 +1267,28 @@
 @end example
 @end defun
 
+@deffn Command read-color &optional prompt convert allow-empty display
+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 #R+G+B+):"})
+and provides completion for color names, but not for hex RGB values.
+In addition to names of standard colors, completion candidates include
+the foreground and background colors at point.
+
+Valid RGB values are described in @ref{Color Names}.
+
+The function's return value is the color name typed by the user in the
+minibuffer.  However, when called interactively or if the optional
+argument @var{convert} is non-@code{nil}, it converts the name into
+the color's RGB value and returns that value as a string.  If an
+invalid color name was specified, this function signals an error,
+except that empty color names are allowed when @code{allow-empty} is
+non-@code{nil} and the user enters null input.
+
+Interactively, or when @var{display} is non-@code{nill}, the return
+value is also displayed in the echo area.
+@end deffn
+
   See also the functions @code{read-coding-system} and
 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
 and @code{read-input-method-name}, in @ref{Input Methods}.