Clarify documentation of 'line-spacing' and 'line-height'

* doc/lispref/display.texi (Line Height): Clarify how the line
height is determined via variables and text properties.  (Bug#23806)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 181bff09b55b72d1c46f11e778c53e8ab7121fde..0d0ec671f7cdf1e28dac2d7edd6b59ded381fc11 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1996,15 +1996,17 @@ newline.
 
   If the property value is @code{t}, the newline character has no
 effect on the displayed height of the line---the visible contents
-alone determine the height.  This is useful for tiling small images
-(or image slices) without adding blank areas between the images.
+alone determine the height.  The @code{line-spacing} property,
+described below, is also ignored in this case.  This is useful for
+tiling small images (or image slices) without adding blank areas
+between the images.
 
   If the property value is a list of the form @code{(@var{height}
 @var{total})}, that adds extra space @emph{below} the display line.
 First Emacs uses @var{height} as a height spec to control extra space
 @emph{above} the line; then it adds enough space @emph{below} the line
-to bring the total line height up to @var{total}.  In this case, the
-other ways to specify the line spacing are ignored.
+to bring the total line height up to @var{total}.  In this case, any
+value of @code{line-spacing} property for the newline is ignored.
 
 @cindex height spec
   Any other kind of property value is a height spec, which translates
@@ -2054,9 +2056,10 @@ overrides line spacings specified for the frame.
 
 @kindex line-spacing @r{(text property)}
   Finally, a newline can have a @code{line-spacing} text or overlay
-property that overrides the default frame line spacing and the buffer
-local @code{line-spacing} variable, for the display line ending in
-that newline.
+property that can enlarge the default frame line spacing and the
+buffer local @code{line-spacing} variable: if its value is larger than
+the buffer or frame defaults, that larger value is used instead, for
+the display line ending in that newline.
 
   One way or another, these mechanisms specify a Lisp value for the
 spacing of each line.  The value is a height spec, and it translates