bug#45264: 26.3; `face-remap-set-base' seems to be bugged

[Drew Adams]

> > Is there a doc bug (both manual and doc string)?  Or is there a code
> > bug?  Or am I missing something?
> 
> I don't see anything wrong with the documentation yet.  One needs to
> know and understand what is a "face spec", and then everything falls
> into its place.  The &rest part is also a big hint.
> 
> Can I turn the table and ask you why you thought the argument could be
> a list of one or more faces?  The doc string says "should FORM a list
> of faces", it doesn't say it should BE a list of faces.  And since
> when does &rest specify a single argument that is a list?

The confusion is not from not understanding what a
face spec is.  I think I know what a face spec is.

The confusion is from the doc not saying explicitly
that each element of SPECS is a face spec, and NOT a
face.  Please consider making that explicit (clear).

1. I didn't suggest (at all) that &rest specifies a
single arg that is a list.  Quite the contrary - the
answer I gave to that SE question explicitly made
that exact point.

2. "why you thought the argument could be a list of
one or more faces?"

The doc string explicitly says that elements of
SPECS can be face names:

  Each list element should be either a face name or...

3. The predicate that tests for a face is `facep',
and it doesn't return non-nil for a face spec.  Its
doc explicitly says that it tests whether its arg
is a "face name", which can be a string or a symbol.

Putting #2 and #3 together, the doc for SPECS does
indeed say that elements of SPECS can be faces.

4. I strongly suggest that you change the language.
"FORM" as a verb here is not clear, and this is
apparently not about faces as arguments; it's about
face specs.  Face specs can be said to define (or
"form") faces, but they are not faces - they don't
satisfy `facep'.
___

Another possibility is perhaps to fix the behavior,
so that it does what its doc says: allow elements
of SPECS to "be either a face name or a property
list of...".  Allow faces, not just face specs.