Improve documentation of line truncation and wrapping

* doc/emacs/display.texi (Line Truncation, Visual Line Mode):
* doc/lispref/display.texi (Truncation): Document that turning on
line truncation disables wrapping, and vice versa.

* src/buffer.c (syms_of_buffer) <truncate-lines>:
* src/xdisp.c (syms_of_xdisp) <truncate-partial-width-windows>:
Warn against turning on when 'visual-line-mode' is in effect.
* lisp/simple.el (visual-line-mode): Document that this mode
disables line truncation.  (Bug#29664)

5 files changed, 22 insertions, 3 deletions

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index ae345c11df5..996c5a66547 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1767,6 +1767,10 @@ multiple screen lines.  Setting the variable @code{truncate-lines} in
 any way makes it local to the current buffer; until that time, the
 default value, which is normally @code{nil}, is in effect.
 
+  Since line truncation and word wrap (described in the next section)
+are contradictory, @code{toggle-truncate-lines} disables word wrap
+when it turns on line truncation.
+
   If a split window becomes too narrow, Emacs may automatically enable
 line truncation.  @xref{Split Window}, for the variable
 @code{truncate-partial-width-windows} which controls this.
@@ -1797,6 +1801,10 @@ mode is enabled, the mode line shows the string @samp{wrap} in the
 mode display.  The command @kbd{M-x global-visual-line-mode} toggles
 Visual Line mode in all buffers.
 
+  Since word wrap and line truncation (described in the previous
+section) are contradictory, turning on @code{visual-line-mode}
+disables line truncation.
+
 @findex beginning-of-visual-line
 @findex end-of-visual-line
 @findex next-logical-line
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ca438c10ce2..510efaf2719 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -152,6 +152,9 @@ truncation; a @samp{\} on the rightmost column indicates a line that
 wraps.  (The display table can specify alternate characters to use
 for this; @pxref{Display Tables}).
 
+   Since wrapping and truncation of text contradict each other, Emacs
+turns off line truncation when wrapping is requested, and vice versa.
+
 @defopt truncate-lines
 If this buffer-local variable is non-@code{nil}, lines that extend
 beyond the right edge of the window are truncated; otherwise, they are
diff --git a/lisp/simple.el b/lisp/simple.el
index 37952a5bf44..800a9279037 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -7777,7 +7777,9 @@ other purposes."
 When Visual Line mode is enabled, `word-wrap' is turned on in
 this buffer, and simple editing commands are redefined to act on
 visual lines, not logical lines.  See Info node `Visual Line
-Mode' for details."
+Mode' for details.
+Turning on this mode disables line truncation set up by
+variables `truncate-lines' and `truncate-partial-width-windows'."
   :keymap visual-line-mode-map
   :group 'visual-line
   :lighter " Wrap"
diff --git a/src/buffer.c b/src/buffer.c
index 100ebc7e2de..4eb7ab6d6ba 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5805,7 +5805,10 @@ Note that this is overridden by the variable
 `truncate-partial-width-windows' if that variable is non-nil
 and this buffer is not full-frame width.
 
-Minibuffers set this variable to nil.  */);
+Minibuffers set this variable to nil.
+
+Don't set this to a non-nil value when `visual-line-mode' is
+turned on, as it could produce confusing results.   */);
 
   DEFVAR_PER_BUFFER ("word-wrap", &BVAR (current_buffer, word_wrap), Qnil,
                      doc: /* Non-nil means to use word-wrapping for continuation lines.
diff --git a/src/xdisp.c b/src/xdisp.c
index e853c8c2232..b2fcc165a9f 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -35136,7 +35136,10 @@ not span the full frame width.
 
 A value of nil means to respect the value of `truncate-lines'.
 
-If `word-wrap' is enabled, you might want to reduce this.  */);
+If `word-wrap' is enabled, you might want to reduce the value of this.
+
+Don't set this to a non-nil value when `visual-line-mode' is
+turned on, as it could produce confusing results.  */);
   Vtruncate_partial_width_windows = make_fixnum (50);
 
   DEFVAR_BOOL("word-wrap-by-category", word_wrap_by_category, doc: /*