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

[Eli Zaretskii <eliz@gnu.org>]

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

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

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