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

[Visuwesh <visuweshm@gmail.com>]

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

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: luangruo@yahoo.com,  55623@debbugs.gnu.org, adam@alphapapa.net
>> Date: Wed, 25 May 2022 20:27:41 +0530
>> 
>> > 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.
>
> Which "such text" did you have in mind?  The problem here is to come
> up with a useful text, which explains something without raising a lot
> more questions.
>

The text that could be added to describe these strange colour names.

>> > 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.
>
> Without explaining the reason for these strange "color names", how can
> this be useful to anyone?
>

Which is why, I said "You could also add the implementation details, but
I leave the decision to you."  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.

>> 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.)
>
> In such rare cases, it is much easier to explain the issue to a person
> who needs to deal with it (or thinks he/she needs to) than come up
> with a description useful enough to be in the manual.
>
> They are just "special color names", that's all.

I suppose.  But I think it would be for the best if we outlined it in
the manual.  It comes as a "surprise" after all.