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

[Drew Adams]

> > > >   "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:
> 
> No, it also consults face-x-resources, which is not necessarily what
> the caller wants.

That's not the point. The point is code to "set the attributes of the
target face to the values of the same attributes of the source face".

Do you see another function that does that?

> > 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'?
> 
> Are you suggesting that for every loop someone might possibly need at
> some point we should have a documented and public function in Emacs?

Do you think I am?  Why?

> > Or are you hinting that there is some other "higher-level
> > function" that already does exactly that?
> 
> Well, there's defface with :inherit, and there's copy-face, to name
> just two.  You didn't describe enough context of what you want to do,
> so I cannot be sure they are not relevant.

Should I explicitly have mentioned that I don't want to inherit another
face?

But I did forget that `copy-face', where the NEW-FACE arg is an
existing face, does what I was looking for.  Thanks for the reminder
about it.  That works for my use case.

(Why doesn't `face-spec-recalc' use `copy-face' instead of
`face-spec-set-2'?  I guess it's to check the return value of
`face-spec-choose', which it goes to the trouble of calling
for each face that it iterates over.)

BTW, while looking to see if Emacs 22 would support my code, since it
will not use `face-spec-set-2', I (re)discovered that prior to Emacs
24.3 `frame-set-spec' DID let you specify the FRAME.  The signature of
`frame-spec-set' was changed incompatibly after Emacs 24.3.

(I still suggest fixing the doc string of `face-spec-set-2', as it is
misleading about its "SPEC" arg.)