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

[Eli Zaretskii]

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

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