bug#54115: [External] : Re: bug#54115: 27.2; `face-remap-set-base' bug with only two args

[Drew Adams]

> > > How is this different from bug#46973?
> >
> > 1. I'd forgotten about that bug filing.  Thx.
> > 2. That's a doc bug.  This is a behavior bug.
> 
> Then how is it different from bug#45264?
> 
> > So far, there's been no improvement of the doc
> > or correction of the behavior.
> 
> So which is it -- a doc bug or a behavior bug?

I won't argue.  It seems to me that following the
doc/description, the behavior observed is not what
is described.  Is there a doc bug, a behavior bug,
or both?

> > And please let us know how to pass a single
> > face for SPECS.
> 
> You can't.  A face spec doesn't allow single faces.  See defface.

For defface we say one thing about what a face
spec is.  But here we say something different.
We say here:

 "SPECS, should form either a list of face names,
  or a property list of attribute/value pairs."

(And note that that doesn't allow for a mix of
the two: some face names and some attribute/value
pairs.)

Maybe there's some unspoken, special meaning of
"forms" intended here, other than meaning only
that SPECS, which is (by &rest) the list of
evaluated args after the first, should _be_ a
list of face names or a property list...

IOW, AFAICT we say that elements of list SPECS
can be face names.  And in particular SPECS can
be a list with just one element, which is a face
name.

Do you see the doc/behavior problem now?  If this
is a misunderstanding of what the doc _wants_ to
say, then please correct it to say what's needed.
If you need help with the wording, please speak up.

Further adding to the confusion is the fact that
when introducing "the following functions" (such
as `face-remap-set-base') we talk about
`face-remapping-alist' entries of the form:

(FACE RELATIVE-SPEC-1 RELATIVE-SPEC-2 ... BASE-SPEC)

and we say that each of those elements except FACE
can be "either a face name, or a property list of
attribute/value pairs".  (The comma is better
removed, BTW.)

A careful reading reminds us that this is about the
_alist_ entries, and not about the SPECS we see in
the descriptions of those "following functions".
Nevertheless, we've introduced things with "SPEC" in
their name (RELATIVE-SPEC-N) which can be face names.

So in some places (e.g. defface) we say that a face
SPEC can't be a face name.  In other places we say
it can.

And again, in this particular place we pretty clearly
suggest that SPECS elements can be face names.

Again, I don't claim to correctly understand what the
behavior is or should be.  I'm just reading the doc
and then trying to use the function as it seems to
say it can be used, and getting an error.

Please clarify.  If you do that here (bug thread) and
you would like help rewording, to make the doc more
clear, let me know.  One way or another, I think you
should be able to see what the misunderstanding is
and clarify things.  Thank you.