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

[Eli Zaretskii]

> Date: Sun, 4 Jun 2017 22:43:34 -0700 (PDT)
> From: 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.

I've now clarified what "other effects" means (your guess is correct).

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

I've clarified in the manual that FACE's definition and recalculation
of its attributes are done for any other value of SPEC-TYPE.  As for
the rest, I think it's quite allright for the manual to say
"reserved", while the doc string describes the current behavior (and
will presumably be changed if that behavior ever changes).  I don't
see how this is a request NOT to use other values, just to keep in
mind that their effect might change in the future.  And the sources
are really there to tell the full story.

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

It means nothing for users.  For Lisp programmers, it means what it
says: when this function is called from Lisp outside Custom, use this
value of SPEC-TYPE.  (I've made both places be more consistent.)

> ("other face specs on FACE"? Does that mean the default (`defface')
> spec plus the customized spec plus the saved custom spec?

Yes.  I've made the text more explicit about this.

> And it's not clear here what those are, either.)

They are described right there, so I don't see what could be unclear
about them, if you write code that sets face attributes.

Thanks.