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

[Eli Zaretskii]

> Date: Mon, 5 Jun 2017 10:56:13 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 27238@debbugs.gnu.org
> 
> (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.  The argument received by face-spec-set-2 is just the PLIST
which matches the frame's display, i.e. a simple list.  So what would
you want the doc string to say about this?