Mention "unspecified-fg" and "unspecified-bg" in some doc strings

* lisp/faces.el (face-foreground, face-background)
(foreground-color-at-point, background-color-at-point):
* lisp/color.el (color-name-to-rgb): Mention "unspecified-fg" and
"unspecified-bg" pseudo-colors on TTY frames.  (Bug#55623)

diff --git a/lisp/color.el b/lisp/color.el
index 0fe663d97a790f96f2419597bfd4171825544bb0..ef3a2f58362563c1d8a0dc8804850b24dc413b63 100644 (file)
--- a/lisp/color.el
+++ b/lisp/color.el
@@ -39,6 +39,10 @@
 COLOR should be a color name (e.g. \"white\") or an RGB triplet
 string (e.g. \"#ffff1122eecc\").
 
+COLOR can also be the symbol `unspecified' or one of the strings
+\"unspecified-fg\" or \"unspecified-bg\", in which case the
+return value is nil.
+
 Normally the return value is a list of three floating-point
 numbers, (RED GREEN BLUE), each between 0.0 and 1.0 inclusive.
 

diff --git a/lisp/faces.el b/lisp/faces.el
index 3bd1e5db6f8b52e3b861e00c3461e3edbbdbc7a9..e93d8c7af85aa7b45f59928bcc07e111843ce715 100644 (file)
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -515,6 +515,9 @@ FACES may be either a single face or a list of faces.
 
 (defun face-foreground (face &optional frame inherit)
   "Return the foreground color name of FACE, or nil if unspecified.
+On TTY frames, the returned color name can be \"unspecified-fg\",
+which stands for the unknown default foreground color of the display
+where the frame is displayed.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
 If FRAME is omitted or nil, use the selected frame.
@@ -536,6 +539,9 @@ merging with the `default' face (which is always completely specified)."
 
 (defun face-background (face &optional frame inherit)
   "Return the background color name of FACE, or nil if unspecified.
+On TTY frames, the returned color name can be \"unspecified-bg\",
+which stands for the unknown default background color of the display
+where the frame is displayed.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
 If FRAME is omitted or nil, use the selected frame.
@@ -2061,11 +2067,17 @@ unnamed faces (e.g, `foreground-color')."
         (face-attribute 'default attribute))))
 
 (defun foreground-color-at-point ()
-  "Return the foreground color of the character after point."
+  "Return the foreground color of the character after point.
+On TTY frames, the returned color name can be \"unspecified-fg\",
+which stands for the unknown default foreground color of the
+display where the frame is displayed."
   (faces--attribute-at-point :foreground 'foreground-color))
 
 (defun background-color-at-point ()
-  "Return the background color of the character after point."
+  "Return the background color of the character after point.
+On TTY frames, the returned color name can be \"unspecified-bg\",
+which stands for the unknown default background color of the
+display where the frame is displayed."
   (faces--attribute-at-point :background 'background-color))
 
 \f