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

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

[Michael Heerdegen]

Hello,

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

The functions defined in the node "Attribute Functions" are not enough
if I want to set face properties e.g for different background-modes,
like here:

(face-spec-set 'stripes-face
     '((((background dark)) (:background "grey7"))
       (t                   (:background "#f0f0f0"))))

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.


Michael



In GNU Emacs 24.0.94.1 (i486-pc-linux-gnu, GTK+ Version 3.2.3)
 of 2012-03-19 on zelenka, modified by Debian
 (emacs-snapshot package, version 2:20120319-1)
Windowing system distributor `The X.Org Foundation', version 11.0.11104000
Configured using:
 `configure '--build' 'i486-linux-gnu' '--host' 'i486-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 '--enable-locallisppath=/etc/emacs-snapshot:/etc/emacs:/usr/local/share/emacs/24.0.94/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.0.94/site-lisp:/usr/share/emacs/site-lisp'
 '--without-compress-info' '--with-crt-dir=/usr/lib/i386-linux-gnu/'
 '--with-x=yes' '--with-x-toolkit=gtk3' '--with-imagemagick=yes'
 'build_alias=i486-linux-gnu' 'host_alias=i486-linux-gnu'
 'CFLAGS=-DDEBIAN -DSITELOAD_PURESIZE_EXTRA=5000 -g -O2''

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.

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

[Michael Heerdegen]

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.

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

[Chong Yidong]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> 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 you want your changes to play nicely with the Custom interface, you
should use `custom-set-faces'.

Obviously, code in .emacs is allowed to do anything.  So for example if
you really don't want to use `custom-set-faces', you could set the
`face-defface-spec' symbol property directly.  But this will cause the
original spec to be lost, and also you have to make sure that the face
has already been defined with defface, i.e. it's listed in
`face-new-frame-defaults' etc.

> If yes, the manual section "Faces" should at least mention it.

I'll see what I can do.

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

[Stefan Monnier]

> If you want your changes to play nicely with the Custom interface, you
> should use `custom-set-faces'.

Indeed, but this has some downsides: Custom may decide to rewrite your
handwritten custom-set-faces.  We should document an Elisp way to
configure faces, and I'd recommend a new function `custom-set-face'
which works just like custom-set-faces except it applies to a single
face and will be left alone by Custom.


        Stefan

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

[Drew Adams]

> > If you want your changes to play nicely with the Custom 
> > interface, you should use `custom-set-faces'.
> 
> Indeed, but this has some downsides: Custom may decide to rewrite your
> handwritten custom-set-faces.  We should document an Elisp way to
> configure faces, and I'd recommend a new function `custom-set-face'
> which works just like custom-set-faces except it applies to a single
> face and will be left alone by Custom.

Haven't thought about it much, but that sounds good to me too.

In addition, a user can try to make sure that s?he evaluates any hand-crafted
`custom-set-faces' sexp outside of the init file and `custom-file', and after
those are loaded.

I also agree that whatever is implemented and recommended in this regard, it be
documented in the Emacs manual.

But I do think it is good to recommend using Customize first and foremost.
There are lots of questions that come up (e.g. on help-gnu-emacs) because users
make mistakes when hand-coding or they do not take into account other Customize
treatments such as :set.

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

[Chong Yidong]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Indeed, but this has some downsides: Custom may decide to rewrite your
> handwritten custom-set-faces.  We should document an Elisp way to
> configure faces, and I'd recommend a new function `custom-set-face'
> which works just like custom-set-faces except it applies to a single
> face and will be left alone by Custom.

We already have a multitude of Elisp ways to configure faces:
set-face-attribute, X resources, various frame parameters,
default-frame-alist, face-new-frame-defaults...  Throwing yet another
function into the current mix is not a pleasing prospect.

The issue is that, as you know, at a fundamental Emacs treats faces in
terms of face attributes; face *specs* are a higher-level construct
recognized only by the Custom system and the related frame creation
code.  So the equivalent of `setq-default' for faces is
`set-face-attribute', which works on attributes not specs.

I'd prefer reforming the system by changing the C code to understand and
store face specs.  Then the equivalent of `setq-default' for faces would
be to change an entry in `face-new-frame-defaults'---which would store
face specs rather than what vectors of attributes (almost all
unspecified) as it currently does.  Probably not difficult, but more
suitable for Emacs 25 than 24.2.

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

[Stefan Monnier]

>> Indeed, but this has some downsides: Custom may decide to rewrite your
>> handwritten custom-set-faces.  We should document an Elisp way to
>> configure faces, and I'd recommend a new function `custom-set-face'
>> which works just like custom-set-faces except it applies to a single
>> face and will be left alone by Custom.
> We already have a multitude of Elisp ways to configure faces:
> set-face-attribute, X resources, various frame parameters,
> default-frame-alist, face-new-frame-defaults...  Throwing yet another
> function into the current mix is not a pleasing prospect.

I find most of those inconvenient, tho.

> The issue is that, as you know, at a fundamental Emacs treats faces in
> terms of face attributes; face *specs* are a higher-level construct
> recognized only by the Custom system and the related frame creation
> code.  So the equivalent of `setq-default' for faces is
> `set-face-attribute', which works on attributes not specs.

I think the problem is not so much the difference between the two, as
the fact that most of the ways you mentioned above deal with the
low-level face attributes, and these are tricky to use in
multi-frame setups.

> I'd prefer reforming the system by changing the C code to understand and
> store face specs.  Then the equivalent of `setq-default' for faces would

That's an option.  But another option is to leave the C code as-is and
simply consider all operations that apply at the level of face
attributes to be "low-level, for internal use only", and the only
advertized operations to be in terms of face specs.  After all, whether
the "interpretation/elaboration" of the face specs is done at
frame-creation time in Elisp, or some other way in C is not
that important.

A good step in that direction is a "setq-default" for faces which takes
a face spec, and we could call it custom-set-face.  Of course, another
name would work fine.


        Stefan

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

[Chong Yidong]

Chong Yidong <cyd@gnu.org> writes:

>> If yes, the manual section "Faces" should at least mention it.
>
> I'll see what I can do.

Done.