(Attribute Functions): Add examples for face-attribute-relative-p.

[gnu-emacs] / lispref / display.texi

diff --git a/lispref/display.texi b/lispref/display.texi
index bb0518a0e75646a5ec81942523d19793a9ad2b70..9398e0b95fc333b6ab6e7f6fba3cc10612b9ba6c 100644 (file)
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -2116,9 +2116,22 @@ and examine the face attributes which existed in those versions.
 
 @tindex face-attribute-relative-p
 @defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as
-the value of the face attribute @var{attribute}, is relative (that is,
-if it modifies an underlying or inherited value of @var{attribute}).
+This function returns non-@code{nil} if @var{value}, when used as the
+value of the face attribute @var{attribute}, is relative.  This means
+it would modify, rather than completely override, any value that comes
+from a subsequent face in the face list or that is inherited from
+another face.
+
+@code{unspecified} is a relative value for all attributes.
+For @code{:height}, floating point values are also relative.
+
+For example:
+
+@example
+(read-face-name "Describe face" "= `default' face" t)
+@end example
+
+prompts with @samp{Describe face (default = `default' face): }.
 @end defun
 
 @tindex merge-face-attribute