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

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

> > The job to do is shown in the code I gave above.  And it is
> > described in the description I gave:
> >
> >   "set one face (`fringe' or whatever), in only a given frame,
> >                                         ^^^^^^^^^^^^^^^^^^^^^
> >   to the spec of another face (or to a spec that isn't yet used
> >   for any face)"
> >
> > I don't see a "higher-level function" that does that.  I don't
> > see any function that does, apart from `face-spec-2'.
> 
> Doesn't this boil down to setting the attributes of the target face to
> the values of the same attributes of the source face?

Yes, of course, which is why `face-spec-set-2' does that:

(defun face-spec-set-2 (face frame spec)
  "Set the face attributes of FACE on FRAME according to SPEC."
  (let (attrs)
    (while spec
      (when (assq (car spec) face-x-resources)
	(push (car spec) attrs)
	(push (cadr spec) attrs))
      (setq spec (cddr spec)))
    (apply 'set-face-attribute face frame (nreverse attrs))))

Which is also why I said, in my first reply to you:

  Unless you essentially repeat its body, it is the only way
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  to do what it does.

Are suggesting that everyone who needs to "set the attributes
of the target face to the values of the same attributes of the
source face" should just write such an explicit loop (repeat
the body of `face-spec-set-2') instead of just calling
`face-spec-set-2'?

Or are you hinting that there is some other "higher-level
function" that already does exactly that?  And if there is,
why wouldn't `face-spec-set-recalc' use that instead of
`face-spec-set-2'?