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

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

[Drew Adams]

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

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

[Drew Adams]

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