bug#27246: 24.5; doc of `face-spec-set'

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

1. The doc string and (elisp ) `Defining Faces' do not agree about
argument SPEC-TYPE when its value is not one of the special values
documented.

The doc string says:

  Any other value means not to set any spec, but to run the
  function for its other effects.

Huh? What "other effects"?  Not clear, but we can guess (and looking at
the code confirms) that what is hinted at is perhaps this:

  This function also defines FACE as a valid face name if it is not
  already one, and (re)calculates its attributes on existing frames.

But the Elisp manual says instead:

  Any other value of SPEC-TYPE is reserved for internal use.

IOW, the doc string tells us to use another SPEC-TYPE value to get the
effect of defining a face and (re)calculating its attributes on existing
frames.  But the Elisp manual tells us NOT to use any other SPEC-TYPE
value, because other values are reserved for internal use.

2. I also find this part unclear:

Doc string:

  nil or `face-override-spec' means the override spec (which is usually
  what you want if calling this function outside of Custom code);

Manual:

  If [SPEC-TYPE] is nil or `face-override-spec', this function sets
  the "override spec", which overrides over all other face specs on
  FACE.

"if calling this function outside of Custom code"?  What does that
mean for users?  Anyway, both of those descriptions are unclear to me.

("other face specs on FACE"? Does that mean the default (`defface')
spec plus the customized spec plus the saved custom spec?  And it's
not clear here what those are, either.)


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=3D/c/usr --host=3Di686-pc-mingw32'