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

[Michael Heerdegen <michael_heerdegen@web.de>]

Hello Chong,

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

Mmh, ok - then maybe we find a better solution.

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

In my case, face remapping is not an alternative.  What I want is, I
think, a quite common user wish: redefine faces in my .emacs.  For
example:

  (face-spec-set
   'stripes-face
   '((((background dark)) (:background "grey7"))
     (t                   (:background "#f0f0f0"))))
  
  (let ((sat-increment -65)
        (val-increment -35))
    (face-spec-set
     'rainbow-delimiters-depth-1-face
     `((((background dark)) (:foreground ,(icicle-increment-color-saturation "orange red" sat-increment)))
       (t (:foreground ,(icicle-increment-color-value "orange red" val-increment)))))
    (face-spec-set
     'rainbow-delimiters-depth-2-face
     `((((background dark)) (:foreground ,(icicle-increment-color-saturation "blue" sat-increment)))
       (t (:foreground ,(icicle-increment-color-value "blue" val-increment)))))
    ...)

I can't do this with face remapping, because it accepts only
attribute/value pairs as specification, but I want to completely
redefine it for different background modes etc.

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

I don't want to use Custom for this (I don't use it at all), since I
want to be able to calculate the face description in my .emacs.  Like in
the second example, where I want to be able to change the color without
the need to apply the washing of the color again (which is done with
`icicle-increment-color-saturation' and `icicle-increment-color-value').

I know that I _can_ use `custom-set-faces' explicitly in .emacs for this
purpose - that works.  But is this really the right function for users
to use in their .emacs to redefine faces?  If yes, the manual section
"Faces" should at least mention it.


Regards,

Michael.