bug#55623: 29.0.50; Mention that (face-foreground 'default) can return "unspecified-fg"

[Adam Porter <adam@alphapapa.net>]

On 5/25/22 12:37, Eli Zaretskii wrote:
>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: luangruo@yahoo.com,  adam@alphapapa.net,  55623@debbugs.gnu.org
>> Date: Wed, 25 May 2022 22:52:00 +0530
>>
>> How about the following instead then?
>>
>>      The 'default' face is always fully specified except in special cases
>>      of TTY frames where :foreground and :background attributes may be
>>      the strings "unspecified-bg" and "unspecified-bg" respectively to
>>      mean to use the TTY's color for the foreground and background.
> 
> This is inaccurate and thus misleading.  These special color names are
> just like any other color names, they are "special" only when Emacs
> needs to actually use them on the screen.  For any other purposes,
> they are just color names.  Thus, the default face is "fully
> specified" even when these colors are used.  Also, these colors can be
> used by other faces, not just by 'default'.

The code in question calls color-gradient on a face's foreground color, 
using the default face as the fallback: 
https://github.com/alphapapa/ement.el/blob/fd96491e82a5335058b72aaff7665f0a2c3d4495/ement-room-list.el#L201

   (color-gradient
    (color-name-to-rgb (face-foreground 'ement-room-list-very-recent
                                        nil 'default))
    (color-name-to-rgb (face-foreground 'ement-room-list-recent
                                        nil 'default))
    6)

When running on a TTY, face-foreground returns "unspecified-fg", which 
causes color-name-to-rgb to return nil, which causes color-gradient to 
signal an error.

> Technically, these colors just tell Emacs not to emit a color-changing
> command when it writes text to the screen, or emit a command that
> tells the terminal driver "reset to your default color".  But this is
> an implementation detail, and we cannot talk about it in the manual
> without explaining a lot of details about the inner workings of color
> support on TTY frames.

Since the docstring says that the default face is always fully 
specified, I thought that meant that the default face's foreground would 
always have a defined, usable color name.  Since "unspecified-fg" is not 
in the manual, and apparently isn't usable by, e.g. color-name-to-rgb 
(even on a graphical frame; and by "usable", I mean that it returns an 
expected, useful color name), it seemed like an oversight in the manual 
to not mention that string somewhere.

Theoretically, if "unspecified-fg" were documented somewhere, I could 
have known that my code needs to account for it.  I don't necessarily 
need to know about the inner workings of color support on a TTY--only 
that...

   (face-foreground 'default)

...may return "unspecified-fg" rather than a specific color name, and 
that, therefore...

   (color-name-to-rgb (face-foreground 'default))

...may return nil rather than a color name.

I think a sentence or two in the appropriate place could clear this up 
and prevent users like me from running into this problem.  e.g.

   Note that, on non-graphical frames, the default face's foreground and
   background colors may be unspecified; in this case, those color names
   may be the special values "unspecified-fg" and "unspecified-bg",
   respectively.  While these are in some senses legitimate color names
   in Emacs, not all functions that expect color names as arguments may
   handle these values as expected, so it may be necessary to check for
   these special color names before calling such functions with them.