* display.texi (Face Attributes): Add xref to Displaying Faces for

explanation of "underlying face".

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 9ab5b15b4bc8124667be273a87fe196d3302c2c4..f6ed748fdd0b4c68b4ca1bf3e2cd69e065f1f07b 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,8 @@
 2009-08-15  Chong Yidong  <cyd@stupidchicken.com>
 
+       * display.texi (Face Attributes): Add xref to Displaying Faces for
+       explanation of "underlying face".
+
        * customize.texi (Common Keywords): Add xref to Loading.
 
        * loading.texi (How Programs Do Loading): Add xref to Lisp

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 14e6a79c5f0c1d3b78178ad8c815cc47a88bf3e1..a2990858c8ca7d527e9ca262542516f3155fd36e 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2020,12 +2020,18 @@ set width.  This should be one of the symbols @code{ultra-condensed},
 @code{extra-expanded}, or @code{ultra-expanded}.
 
 @item :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 that is called with one argument (the
-height of the underlying face) and returns the height of the new face.
-If the function is passed an integer argument, it must return an
-integer.
+The height of the font.  In the simplest case, this is an integer in
+units of 1/10 point.
+
+The value can also be a floating point number or a function, which
+specifies the height relative to an @dfn{underlying face} (i.e., a
+face that has a lower priority in the list described in
+@ref{Displaying Faces}).  If the value is a floating point number,
+that specifies the amount by which to scale the height of the
+underlying face.  If the value is a function, that function is called
+with one argument, the height of the underlying face, and returns the
+height of the new face.  If the function is passed an integer
+argument, it must return an integer.
 
 The height of the default face must be specified using an integer;
 floating point and function values are not allowed.
@@ -2143,8 +2149,9 @@ this attribute also changes the values of the @code{:family},
 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.  If a list of faces is used, attributes from faces earlier in
-the list override those from later faces.
+faces (@pxref{Displaying Faces}).  If a list of faces is used,
+attributes from faces earlier in the list override those from later
+faces.
 @end table
 
 For compatibility with Emacs 20, you can also specify values for two