GNU bug report logs - #4114
23.1; face doc unclear - no explanation of "underlying" face or attribute value

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4114 in the body.
You can then email your comments to 4114 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Mon, 10 Aug 2009 22:12:01 -0700

emacs -Q
 
In (elisp)Face Attributes, things are explained in terms of
"underlying" face. But this notion is never introduced or
explained. Consequently, the descriptions that refer to this are
incomprehensible. This includes the description of :height and
:inherit:
 
`:height'
     Font height--either an integer in units of 1/10 point, or a
     floating point number specifying the amount by which to scale the
     height of any underlying face, or a function...
 
`:inherit'
     The name of a face from which to inherit attributes, or a list of
     face names.  Attributes from inherited faces are merged into the
     face like an underlying face would be, with higher priority than
     underlying faces....
 
Incomprehensible.
 
Similarly, in (elisp)Attribute Functions, "underlying value" is used
with no definition/explanation, making the explanation of
`merge-face-attribute' incomprehensible:
 
Function: merge-face-attribute attribute value1 value2
     If VALUE1 is a relative value for the face attribute ATTRIBUTE,
     returns it merged with the underlying value VALUE2; otherwise,...
 
Huh? Is "underlying" simply an extra word here (so that it should be
removed), or does it really say something about VALUE2 (what)?
 
I have no idea what was intended in any of these passages.  FWIW, no
such language appears anywhere in the Emacs 20 Elisp manual - is an
underlying face or attribute value something new since Emacs 20? If
so, define it so you can then use it to explain other things. If not,
please clarify what is meant in these passages.
 
Perhaps this use of "underlying" is a translation from some other
language?  In any case, there is no explanation of what is meant.
When you are defining face A, what is its "underlying" face (or
faces)?
 
 
 
In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

Message #10 received at 4114-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 4114-done <at> debbugs.gnu.org
Subject: Re: 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Sat, 15 Aug 2009 17:15:52 -0400

> In (elisp)Face Attributes, things are explained in terms of
> "underlying" face. But this notion is never introduced or explained.

Thanks, I've tweaked the text and added a reference to the node
Displaying Faces, where the concept is explained.

> I have no idea what was intended in any of these passages.

Here's an experiment that should make this clear.  Go to the default
*scratch* buffer and evaluate the following lines, one at a time:

;; Give the comments in this buffer a height of 15.
(set-face-attribute 'font-lock-comment-face nil :height 150)
;; Give characters 5 to 8 a height that's 0.9 times that of the
;; underlying face, in this case font-lock-comment-face.
(setq ov (make-overlay 5 8))
(overlay-put ov 'face (list :height 0.9))

Message #11 received at 4114-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> stupidchicken.com>
Cc: <4114-done <at> debbugs.gnu.org>
Subject: RE: 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Sat, 15 Aug 2009 14:53:20 -0700

> > In (elisp)Face Attributes, things are explained in terms of
> > "underlying" face. But this notion is never introduced or explained.
> 
> Thanks, I've tweaked the text and added a reference to the node
> Displaying Faces, where the concept is explained.

Thanks; that's clearer.

However:

1. "Underlying face" is defined as "a face that has a lower priority in the
list...". That begs the question, "lower than what"? Lower than some other face,
presumably (?), but which one? (This passage is about fonts.) I think we need to
specifically speak of a given face underlying another given face (or perhaps
underlying a faceless set of face attributes?).

2. Related to #1. It's not clear to me whether there is only one underlying face
for a given face/font/attribute-set (?). You say "a face", not "the face", so I
guess there can be more than one that has a lower priority. But then you speak
of "the underlying face".

Probably this text just needs a little more tweaking, but for the moment it is
still not clear to me.

Also, I think the same kind of clarification (e.g. with an xref) is needed in
node Attribute Functions (see `merge-face-attribute'), where it also refers to
"underlying".

> > I have no idea what was intended in any of these passages.
> 
> Here's an experiment that should make this clear.  Go to the default
> *scratch* buffer and evaluate the following lines, one at a time:
> 
> ;; Give the comments in this buffer a height of 15.
> (set-face-attribute 'font-lock-comment-face nil :height 150)
> ;; Give characters 5 to 8 a height that's 0.9 times that of the
> ;; underlying face, in this case font-lock-comment-face.
> (setq ov (make-overlay 5 8))
> (overlay-put ov 'face (list :height 0.9))

OK, that example seems clear; thanks. In this case, the face that's higher
priority is the one set by `overlay-put'. The face that has lower priority is
`font-lock-comment-face'.

The questions mentioned above are still not clear to me, however. Thx.

--

I see that you just now closed this bug. You close bugs too quickly. I don't
know if now this reply will even get added to the bug thread, without my having
to reopen the bug. IIRC, once a bug is closed, no further feedback is possible.

I don't reaslly need the bug reopened in this case, if you will please at least
take this feedback into account - I think a little more clarification would
help.

Message #12 received at 4114-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: <4114-done <at> debbugs.gnu.org>
Subject: Re: 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Sat, 15 Aug 2009 19:00:10 -0400

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 1. "Underlying face" is defined as "a face that has a lower priority
> in the list...". That begs the question, "lower than what"?

Lower than the face to which this attribute applies.  That should be
obvious.

> 2. Related to #1. It's not clear to me whether there is only one
> underlying face for a given face/font/attribute-set (?). You say "a
> face", not "the face", so I guess there can be more than one that has
> a lower priority. But then you speak of "the underlying face".

There's no way to explain this concisely, I'm afraid.  The best thing do
is to read the Displaying Faces node closely (which is why an xref to
that node is probably the best we can do).  Basically, Emacs realizes a
face by the "stacking" procedure described in that node, searching
through the list of applicable faces for each attribute until it finds a
fully-specified value.  The "relative" values for the height are treated
specially.  Thus, in the context of that paragraph in the Face
Attributes node, the "underlying face" refers to that face, X levels
down in the priority list, for which Emacs has found a specified height.

> I see that you just now closed this bug. You close bugs too quickly. I
> don't know if now this reply will even get added to the bug thread,
> without my having to reopen the bug. IIRC, once a bug is closed, no
> further feedback is possible.

It's still possible, IIUC.

Message #17 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: RE: bug#4114; 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Sat, 15 Aug 2009 16:33:11 -0700

And of course I forgot to add back bug-gnu-emacs to the cc list.

It's a pain having to change the #-done back to bug-gnu-emacs and add back the
bug# in the Subject. And we saw what happened when you leave the #-done.

-----Original Message-----
From: Drew Adams Sent: Saturday, August 15, 2009 4:29 PM
To: 'Chong Yidong'

Also, did you see this part of my reply?

> Also, I think the same kind of clarification (e.g. with an xref)
> is needed in node Attribute Functions (see
> `merge-face-attribute'), where it also refers to "underlying".

Message #22 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: RE: bug#4114 - 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Sat, 15 Aug 2009 16:33:09 -0700

And of course I forgot to add back bug-gnu-emacs to the cc list. 

It's a pain having to change the #-done back to bug-gnu-emacs and add back the
bug# in the Subject. And we saw what happened when you leave the #-done.

-----Original Message-----
From: Drew Adams Sent: Saturday, August 15, 2009 4:28 PM
To: 'Chong Yidong'

> > 1. "Underlying face" is defined as "a face that has a lower priority
> > in the list...". That begs the question, "lower than what"?
> 
> Lower than the face to which this attribute applies.  That should be
> obvious.

If you read the doc text in question, I think you'll see that that is what is
missing: the notion that we are talking about applying an attribute to a
particular face (and that there might be other faces (plural) underlying that
face.)

Anyway, I think a little more clarification would help, but do as you like.

> > 2. Related to #1. It's not clear to me whether there is only one
> > underlying face for a given face/font/attribute-set (?). You say "a
> > face", not "the face", so I guess there can be more than 
> > one that has a lower priority. But then you speak of "the
> > underlying face".
> 
> There's no way to explain this concisely, I'm afraid.

I was trying to suggest that the doc is a bit contradictory here. If there can
be more than one face that underlies a given face, then that should be said.
Then it's OK to speak about one of those faces etc. (not "the underlying face").

> The best thing do is to read the Displaying Faces node closely
> (which is why an xref to that node is probably the best we
> can do).  Basically, Emacs realizes a
> face by the "stacking" procedure described in that node, searching
> through the list of applicable faces for each attribute until 
> it finds a fully-specified value.  The "relative" values for
> the height are treated specially.  Thus, in the context of
> that paragraph in the Face Attributes node, the "underlying
> face" refers to that face, X levels down in the priority
> list, for which Emacs has found a specified height.

Perhaps just add what you say in the last sentence to the doc? That is, there is
one of the underlying faces, for which Emacs has found a specified height. Then
you can talk about that face (with the specified height) in the singular. IOW,
identify it first, then it is specific enough to talk about.

> > I see that you just now closed this bug. You close bugs too 
> > quickly. I don't know if now this reply will even get added
> > to the bug thread, without my having to reopen the bug.
> > IIRC, once a bug is closed, no further feedback is possible.
> 
> It's still possible, IIUC.

You're apparently right, but problems have come from simply replying, because of
the #-done in the cc list. I've removed that manually, and reinserted "bug#4114,
but it's easy to forget to do that.

Message #27 received at 4114 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 4114 <at> debbugs.gnu.org
Subject: Re: bug#4114: - 23.1; face doc unclear - no explanation of "underlying" face or attribute value
Date: Mon, 17 Aug 2009 11:08:52 -0400

> And of course I forgot to add back bug-gnu-emacs to the cc list.
> It's a pain having to change the #-done back to bug-gnu-emacs and add
> back the bug# in the Subject.

Don't do that.  Instead, just remove the "-done" part.


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.