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

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

[Drew Adams]

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'

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.