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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 4 Jun 2017 22:44:40 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 27238@debbugs.gnu.org
> 
> > > (face-spec-set-2 TARGET-FACE
> > >                  FRAME
> > >                  (face-spec-choose
> > >                    (get SOURCE-FACE 'face-defface-spec)
> > >                    FRAME))
> > 
> > Why can't you do this by calling a higher-level function?
> 
> What higher-level function would you suggest?

face-spec-recalc and face-spec-set come to mind, for example.

> How would _you_ 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 asked whether the higher-level functions can do the job.  If they
cannot, please explain why, and please provide specific details about
the difficulties.  Answering my question by another question doesn't
help, since I'm sure I don't know enough about the job you wanted to
do.

> But perhaps you have some other higher-level function in
> mind to do this job?  If so, I wonder why `face-set-recalc'
> doesn't use it, instead of `face-spec-set-2.

There are many documented functions that set face attributes in
various forms and for various sets of frames.  My question is
precisely whether any of them can do this job.  If not, perhaps we
could extend one of them to support whatever you need to do.  That'd
be an alternative to renaming face-spec-set-2 and making it public.