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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 27 May 2022 00:44:38 -0500
> Cc: luangruo@yahoo.com, 55623@debbugs.gnu.org
> From: Adam Porter <adam@alphapapa.net>
> 
>    (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.

These special pseudo-color names _are_ usable as colors, just not in
every situation.  For example, we cannot ask Emacs to produce RGB
values for them, obviously.  (If these pseudo-colors were the same as
'unspecified', you could trust us not to introduce such pseudo-colors
in the first place, right?)

> 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.

These pseudo-colors were already mentioned in the doc string of
color-values, which color-name-to-rgb calls.  I've now mentioned them
in a few more doc strings, including color-name-to-rgb and
face-foreground.  The additional text says something like

  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.

> 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.

This kind of vague description is not appropriate for the manual,
which is supposed to _explain_ stuff, not just mention it.  So I'd
like for now to settle for the additions to the doc strings.  After
all, this issue didn't pop up since these pseudo-colors were
introduced in Emacs 21, so it sounds like it's important only in some
rare cases.

Thanks.