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

[Eli Zaretskii]

> Date: Mon, 5 Jun 2017 09:40:18 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 27238@debbugs.gnu.org
> 
> > >   "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.

> 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?

> 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.