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

[Stefan Kangas <stefan@marxist.se>]

Eli Zaretskii <eliz@gnu.org> writes:

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

It seems like this documentation bug was fixed, so I'm closing it.

If this conclusion is incorrect and this is still an issue, please reply
to this email (use "Reply to all" in your email client) and we can
reopen the bug report.