Fix documentation of 'x-underline-at-descent-line'

* doc/emacs/display.texi (Display Custom):
* src/nsterm.m (syms_of_nsterm):
* src/xterm.c (syms_of_xterm):
* src/w32term.c (syms_of_w32term): Mention the effect of
'line-spacing' on the underline position.  (Bug#30553)

4 files changed, 11 insertions, 2 deletions

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 205ca54728f..64a1d4b5fa0 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1848,8 +1848,11 @@ it may improve the legibility of underlined text for certain fonts.
 area.)  The variable @code{x-underline-at-descent-line} determines how
 to draw underlined text.  The default is @code{nil}, which means to
 draw it at the baseline level of the font; if you change it to
-@code{nil}, Emacs draws the underline at the same height as the font's
-descent line.
+@code{t}, Emacs draws the underline at the same height as the font's
+descent line.  (If non-default line spacing was specified for the
+underlined text, see @ref{Line Height,,, elisp, The Emacs Lisp
+Reference Manual}, Emacs draws the underline below the additional
+spacing.)
 
 @vindex overline-margin
   The variable @code{overline-margin} specifies the vertical position
diff --git a/src/nsterm.m b/src/nsterm.m
index 51a53828b5b..3d58cd5ec64 100644
--- a/src/nsterm.m
+++ b/src/nsterm.m
@@ -9381,6 +9381,8 @@ to 4.1, set this to nil. */);
   DEFVAR_BOOL ("x-underline-at-descent-line",
                x_underline_at_descent_line,
      doc: /* Non-nil means to draw the underline at the same place as the descent line.
+(If `line-spacing' is in effect, that moves the underline lower by
+that many pixels.)
 A value of nil means to draw the underline according to the value of the
 variable `x-use-underline-position-properties', which is usually at the
 baseline level.  The default value is nil.  */);
diff --git a/src/w32term.c b/src/w32term.c
index ac29bbbbd46..611b7c66e7a 100644
--- a/src/w32term.c
+++ b/src/w32term.c
@@ -7401,6 +7401,8 @@ sizes.  */);
   DEFVAR_BOOL ("x-underline-at-descent-line",
                x_underline_at_descent_line,
      doc: /* Non-nil means to draw the underline at the same place as the descent line.
+(If `line-spacing' is in effect, that moves the underline lower by
+that many pixels.)
 A value of nil means to draw the underline according to the value of the
 variable `x-use-underline-position-properties', which is usually at the
 baseline level.  The default value is nil.  */);
diff --git a/src/xterm.c b/src/xterm.c
index b10664dda97..c5163aa990a 100644
--- a/src/xterm.c
+++ b/src/xterm.c
@@ -13260,6 +13260,8 @@ sizes.  */);
   DEFVAR_BOOL ("x-underline-at-descent-line",
                x_underline_at_descent_line,
      doc: /* Non-nil means to draw the underline at the same place as the descent line.
+(If `line-spacing' is in effect, that moves the underline lower by
+that many pixels.)
 A value of nil means to draw the underline according to the value of the
 variable `x-use-underline-position-properties', which is usually at the
 baseline level.  The default value is nil.  */);