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

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

[Visuwesh]

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.



[1] If I use the adwaita theme instead, then `face-foreground' does
    indeed return a colour.

P.S. I'm filing this bug report after this was brought up in
https://github.com/alphapapa/ement.el/issues/34#issuecomment-906893756.

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

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.

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

[Visuwesh]

[புதன் மே 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.
But AFAICT, it is not specified in the manual anywhere.

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?

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

[Visuwesh]

[புதன் மே 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)?

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

[Eli Zaretskii]

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

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

[Visuwesh]

[புதன் மே 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.

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

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: luangruo@yahoo.com,  adam@alphapapa.net,  55623@debbugs.gnu.org
> Date: Wed, 25 May 2022 22:52:00 +0530
> 
> 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.

This is inaccurate and thus misleading.  These special color names are
just like any other color names, they are "special" only when Emacs
needs to actually use them on the screen.  For any other purposes,
they are just color names.  Thus, the default face is "fully
specified" even when these colors are used.  Also, these colors can be
used by other faces, not just by 'default'.

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.

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

[Adam Porter]

On 5/25/22 12:37, Eli Zaretskii wrote:
>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: luangruo@yahoo.com,  adam@alphapapa.net,  55623@debbugs.gnu.org
>> Date: Wed, 25 May 2022 22:52:00 +0530
>>
>> 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.
> 
> This is inaccurate and thus misleading.  These special color names are
> just like any other color names, they are "special" only when Emacs
> needs to actually use them on the screen.  For any other purposes,
> they are just color names.  Thus, the default face is "fully
> specified" even when these colors are used.  Also, these colors can be
> used by other faces, not just by 'default'.

The code in question calls color-gradient on a face's foreground color, 
using the default face as the fallback: 
https://github.com/alphapapa/ement.el/blob/fd96491e82a5335058b72aaff7665f0a2c3d4495/ement-room-list.el#L201

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

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.

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.

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

[Eli Zaretskii]

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

Thanks.

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

[Adam Porter]

On 5/27/22 01:34, Eli Zaretskii wrote:
> 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.

Thanks, Eli.

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

[Stefan Kangas]

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.