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

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

> > > > This is a useful, general function, not just a helper.
> > > 
> > > FWIW, I don't think it's general enough, because it is
> > > tightly couples with face-x-resources.
> > 
> > That's only the _implementation_.
> > 
> > (That reasoning would apply also to `face-spec-recalc', `face-spec-set',
> > `face-set-after-frame-default', `custom-face-set', `custom-face-save',
> > `custom-face-mark-to-save', `custom-face-reset-saved',
> > `custom-face-mark-to-reset-standard', `custom-declare-face',
> > `custom-theme-set-faces', `custom-reset-faces', `woman-default-faces',
> > ...)
> 
> They all call face-spec-recalc.

`face-spec-recalc' calls `face-spec-2', which calls
`face-x-resources'.

Your complaint is that `face-spec-2' should not be treated as
first-class (i.e., given a reasonable name and accurate doc)
because it depends on using `face-x-resources'.  As I said,
that is only its current _implementation_.

As far as _using_ `face-spec-2' is concerned (which is what
this is about), all of the above make use of it.  Given its
current implementation, they depend on that implementation
just as much as it does.  Change the implementation and there
is no coupling with it.  Leave the implementation as is and
they all continue to depend on it.

Your reasoning applies also to all of those functions.  If
your argument is that we should not encourage users to use
this function (by improving its name and doc) because its
implementation is fragile, then that same argument applies
to all current uses of it.

And there are plenty, including uses defining functions,
such as `face-spec-set', that are very widely used, including
by users.

> > Unless you essentially repeat its body, it is the only way
> > to do what it does.  Here's one use case:
> >
> > (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?  That function
does that job - and so it is used in `faces.el' (ultimately
by all of the functions listed above).

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 don't see `face-spec-set' offering that possibility, at
least not directly.  Am I missing something?  I tried it
with each of the allowed SPEC-TYPEs, to see what they'd
do, but none of them did that.  A nil SPEC-TYPE sort of
does the job, but without the ability to limit the setting
to a given frame.

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.