bug#27238: 24.5; Rename `face-spec-set-2' and give it a better doc string

[Drew Adams <drew.adams@oracle.com>]

> > (I still suggest fixing the doc string of `face-spec-set-2', as it is
> > misleading about its "SPEC" arg.)
> 
> I'm not sure I understand why it's misleading.  You said:
> 
> > Wrt the doc, the SPEC arg is apparently NOT a face spec, i.e., a spec
> > such as is returned by (get FACE 'face-defface-spec).  Instead, it seems
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > to be an attributes list such as what is returned by `face-spec-choose'
                                             ^^^^^^^^^^^
> > or `face-attr-construct'.
> 
> However, "face spec" is described in '(elisp)Defining Faces' as and
> alist whose elements each have the form
> 
>           (DISPLAY . PLIST)
> 
> and I believe the SPEC argument accepted by face-spec-choose has this
                                  ^^^^^^^^^^^
> form.

Yes.

> The argument received by face-spec-set-2 is just the PLIST
> which matches the frame's display, i.e. a simple list.

Yes.  It is not a face spec.  It is a face-attributes plist.

> So what would you want the doc string to say about this?

The SPEC arg accepted by `face-spec-choose', and by (all of?) the other
face functions whose signatures mention a SPEC arg, is of the same form.

But the "SPEC" accepted by `face-spec-set-2' is not of that form.

Instead, it is of the form that is _returned_ by `face-spec-choose' - it
is a plist of face attributes.  Such a plist is also what is accepted as
the ATTRS argument of `face-attr-match-p'.  It is more properly referred
to as ATTRS or ATTRIBUTES or some such.  It is not a face spec.

This is a face SPEC:

 ((((background dark)) (:background "DarkMagenta"))
  (t (:background "LightGreen" :foreground "Red")))

This is a face-attributes list:

 (:background "LightGreen" :foreground "Red")

I've said the same thing several times now.  HTH.