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

[Visuwesh <visuweshm@gmail.com>]

[புதன் மே 25, 2022] Eli Zaretskii wrote:

>> Resent-From: Visuwesh <visuweshm@gmail.com>
>> Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
>> Resent-CC: bug-gnu-emacs@gnu.org
>> Resent-Sender: help-debbugs@gnu.org
>> Cc: luangruo@yahoo.com
>> From: Visuwesh <visuweshm@gmail.com>
>> Date: Wed, 25 May 2022 13:23:09 +0530
>> 
>> [புதன் மே 25, 2022] Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:
>> 
>> > Visuwesh <visuweshm@gmail.com> writes:
>> >
>> >> In a tty frame and when using a theme that does not explicitly set the
>> >> default face's :foreground/:background [1], (face-attribute 'default :foreground)
>> >> returns "unspecified-fg".  This value is surprising when the docstring
>> >> of `face-attribute' says,
>> >>
>> >>     To ensure that the return value is always specified and absolute, use a
>> >>     value of ‘default’ for INHERIT; this will resolve any unspecified or
>> >>     relative values by merging with the ‘default’ face (which is always
>> >>     completely specified).              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> >>     ^^^^^^^^^^^^^^^^^^^^^
>> >>
>> >> I opened the Elisp manual and tried to isearch for "unspecified-fg", but
>> >> it got me no matches.  It would be nice if this return value was
>> >> documented somewhere.
>> >
>> > Isn't that a special color which means to use the terminal's default
>> > foreground (and/or background, in the case of unspecified-bg) colors?
>> >
>> > If so, it should be documented as that instead.
>> 
>> Indeed, "unspecified-fg/bg" means to use the terminal's default fg/bg.
>
> Right.  Thus, when the documentation talks about "unspecified values
> for attributes" and about the default face being "always completely
> specified", it excluded the "unspecified-fg" and "unspecified-bg"
> values, because those are considered "specified", except in some rare
> cases.  It is not an accident that they are strings and not symbols.
>
>> But AFAICT, it is not specified in the manual anywhere.
>
> They aren't documented on purpose: documenting them would be messy and
> at best will confuse anyone who isn't familiar with the internals of
> color support on TTY frames.  They are in effect internal
> implementation details which unfortunately leak outside of the
> internals.
>

I agree but I think anyone who is fairly familiar with terminal
emulators can understand that you cannot find the terminal emulator's
colourscheme (for a lack of a better word) in a terminal-agnostic way.
Thus, I believe there won't be too much confusion if we added such a
text.

> What would you like to be documented about these special values, and
> why?

I would like it if some words along the lines of...

    The 'default' face is always fully specified except in special cases
    of TTY frames where :foreground and :background attributes may be
    the strings "unspecified-fg" and "unspecified-bg" respectively.

in the manual somewhere.  You could also add the implementation details,
but I leave the decision to you.

As for the why: In the bug report I alluded to in the OP, ement.el
relied on the completeness of the default-face specification to get the
colour of the face which is then used to calculate a different colour
(similar to the rainbow coloured nicknames you often see in irc
clients).  This special case of the TTY frame would be handled correctly
if it was spelt out somewhere.  (It isn't now since the value returned is
a surprise.)

But since I'm kind of a third party here, maybe Adam can chime in (added
to CCs)?