bug#11059: 24.0.94; Please add `face-spec-set' to the elisp manual

[Chong Yidong]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Please add `face-spec-set' to the elisp manual.  It's the preferred
> way for users/developers to redefine face specs (Or is there a better
> way?  Then please describe it instead in the manual).

Promoting the use of face-spec-set in third party code is probably not a
good idea.  That function is pretty internal; its role is actually to
apply the face spec, and it assumes that the caller has done some of the
relevant bookkeeping in symbol properties like `face-defface-spec' and
`saved-face', so that the Custom interface doesn't get confused.

Could you give an example of why your code wants to redefine face specs?
In most cases, I suspect face remapping is the better solution.

> And `custom-set-faces' is deprecated - at least, the custom file
> warns to use it:
>
> ;; custom-set-faces was added by Custom.
> ;; If you edit it by hand, you could mess it up, so be careful.
> ;; Your init file should contain only one such instance.
> ;; If there is more than one, they won't work right.

This does not say that it is deprecated, only that it is meant to store
the result of the user's use of the Custom interface.