set-face-attribute and floating point :height values

set-face-attribute and floating point :height values

[Giorgos Keramidas]

My ~/.emacs file now includes the following to fine-tune the default
face for X11 frames:

  (when (display-graphic-p)
    (set-face-attribute 'default nil :family "DejaVu Sans Mono" :width 'ultra-condensed :height 102)
    (require 'color-theme))

The documentation of `set-face-attribute' mentions that :height is
supposed to accept floating point values too:

,----[ C-h f set-face-attribute ]---------------------------------------
| set-face-attribute is a compiled Lisp function in `faces.el'.
|
| (set-face-attribute FACE FRAME &rest ARGS)
|
| Set attributes of FACE on FRAME from ARGS.
| [...]
|
| `:height'
|
| VALUE must be either an integer specifying the height of the font to use
| in 1/10 pt, a floating point number specifying the amount by which to
| scale any underlying face, or a function, which is called with the old
| height (from the underlying face), and should return the new height.
| [...]
`-----------------------------------------------------------------------

But trying to use a floating-point number in my ~/.emacs file throws up
an error, e.g. when I evaluate in my *scratch* buffer the expression:

  (set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 1.4)

a debugger pops up with the following backtrace:

    Debugger entered--Lisp error: (error "Invalid default face height" 1.4)
      internal-set-lisp-face-attribute(default :height 1.4 0)
      set-face-attribute(default nil :family "DejaVu Sans Mono" :width
      ultra-condensed :height 1.4)
      eval((set-face-attribute (quote default) nil :family "DejaVu Sans
      Mono" :width (quote ultra-condensed) :height 1.4))
      eval-last-sexp-1(nil)
      eval-last-sexp(nil)
      call-interactively(eval-last-sexp nil nil)

Is the documentation of `set-face-attribute' out of date, or am I using
it incorrectly?

Re: set-face-attribute and floating point :height values

[Glenn Morris]

Giorgos Keramidas wrote:
>   (set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 1.4)
>
> a debugger pops up with the following backtrace:
>
>     Debugger entered--Lisp error: (error "Invalid default face height" 1.4)

You're saying: make the default font height be 1.4 times the default
font height. The default font height must be absolute.

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2659

Re: set-face-attribute and floating point :height values

[Giorgos Keramidas]

On Mon, 31 Jan 2011 15:42:21 -0500, Glenn Morris <rgm@gnu.org> wrote:
>Giorgos Keramidas wrote:
>>   (set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 1.4)
>>
>> a debugger pops up with the following backtrace:
>>
>>     Debugger entered--Lisp error: (error "Invalid default face height" 1.4)
>
> You're saying: make the default font height be 1.4 times the default
> font height. The default font height must be absolute.
>
> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2659

Ah, I see now.  So the underlying face must already have *some* :height
value, so this is not the right way to specify the initial face-height.

I reverted my ~/.emacs file to use:

  (set-face-attribute 'default nil :family "DejaVu Sans Mono" :height 100)

Thanks,
Giorgos

RE: set-face-attribute and floating point :height values

[Drew Adams]

> > You're saying: make the default font height be 1.4 times the default
> > font height. The default font height must be absolute.
> > http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2659
> 
> Ah, I see now.  So the underlying face must already have 
> *some* :height value, so this is not the right way to
> specify the initial face-height.

It might help if the doc either avoided the undefined term "underlying face" or
explained what it means by that.

Does it mean to refer to face-attribute inheritance?  If so, it should say so;
if not, it should say what is really meant by an "underlying" face for the face
whose attribute you are setting.  Can multiple faces underly a given face?  How
to find the underlying faces for a given face?  Etc.

The Elisp manual (node Face Attributes) does a pretty good job here in fact, but
the relation to face inheritance is not so clear.  A distinction is made in the
`:inherit' entry of node Face Attributes, but without any explicit definitions.

There should be a cross-ref to node Face Attributes from any other places (e.g.
node Attribute Functions, `merge-face-attributes') where we mention underlying
faces.

The doc string for `set-face-attribute' explains nothing about "underlying
face", however.  It needs at least a pointer to the corresponding manual page to
become comprehensible.

FWIW, there are additional places in the docs where "underlying" is used with no
real definition/explanation.  It might seem shorter for the person writing the
description to use such a term, but without any explanation it can take longer
for a user to understand what is meant.  Sometimes adding a cross reference
might suffice to clear things up.

If a sentence makes about the same amount of sense with and without the
qualifier "underlying" it's a sign that it should probably just be removed.
E.g., if in some context "the file system" is about as clear as "the underlying
file system", then go with the former.  Put differently, if "the file system" is
not clear enough in some context then just adding "underlying" will not help: If
it has any effect it will only be to confuse (why the qualifier? what does it
mean here?).

Emacs manual:
"underlying text representation" (for images)
"underlying system's text representation" (for international coding)
"underlying details about charsets" (for charsets)
"underlying VC" (for version control)
"underlying method" (for EDE)
"underlying shell" (for shell options)
"underlying face" (for face resources)

Elisp manual:
"underlying OS" (for frame configs)
"underlying OS" (for subprocesses)
"underlying buffer text" (for keymaps)
"underlying platform" (for eol conversion)
"`underlying face'" (for face attributes)

Doc strings:
"underlying file system" (expand-file-name)
"underlying face" (face-remapping-alist)
"underlying face" (set-face-attribute)
"underlying file system" (shell-quote-wildcard-pattern)
"underyling version-control system (vc-rollback)

Re: set-face-attribute and floating point :height values

[Giorgos Keramidas]

On Mon, 31 Jan 2011 14:04:11 -0800, "Drew Adams" <drew.adams@oracle.com> wrote:
>> > You're saying: make the default font height be 1.4 times the default
>> > font height. The default font height must be absolute.
>> > http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2659
>>
>> Ah, I see now.  So the underlying face must already have
>> *some* :height value, so this is not the right way to
>> specify the initial face-height.
>
> It might help if the doc either avoided the undefined term "underlying
> face" or explained what it means by that.

I think the use of the term 'underlying face' is a nice and compact way
of describing that floating point :height values are multipliers for any
:height inherited from another face.  But it's confusing that there is
an exception for the 'default' face that makes this particular format of
:height value invalid for just this *one* exception.

Maybe we should fix the doc string to mention this exception and
explicitly mention 'inheritance' instead of the 'underlying face'.

RE: set-face-attribute and floating point :height values

[Drew Adams]

> > It might help if the doc either avoided the undefined term 
> > "underlying face" or explained what it means by that.
> 
> I think the use of the term 'underlying face' is a nice and 
> compact way of describing that floating point :height values
> are multipliers for any :height inherited from another face.
> But it's confusing that there is an exception for the
> 'default' face that makes this particular format of
> :height value invalid for just this *one* exception.
> 
> Maybe we should fix the doc string to mention this exception and
> explicitly mention 'inheritance' instead of the 'underlying face'.

If you look at the doc I pointed to (node `Face Attributes'),
you will see that "underlying face" is not the same as
inherited face.  According to what is written, underlying is
not about inheritance.  (I don't claim that what is written is
correct.)

An underlying face is "a face that has a lower priority in
the list described in `Displaying Faces'".  In `Displaying
Faces' you will see the ways in which the list of faces that
underly a given face can be constituted.  And you will
notice that there is no mention of inheritance.

In node `Face Attributes', face inheritance is also discussed,
however (see `:inherit').  It is explicitly distinguished from
underlying: "Attributes from inherited faces are merged
into the face like an underlying face would be, with
higher priority than underlying faces (`Displaying Faces')."