master 0daad76: Improve documentation of line truncation and wrapping

[Eli Zaretskii]

branch: master
commit 0daad767047be33c0189d5e0131b126b49d35e6d
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    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)
---
 doc/emacs/display.texi   | 8 ++++++++
 doc/lispref/display.texi | 3 +++
 lisp/simple.el           | 4 +++-
 src/buffer.c             | 5 ++++-
 src/xdisp.c              | 5 ++++-
 5 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index ae345c1..996c5a6 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 ca438c1..510efaf 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 37952a5..800a927 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 100ebc7..4eb7ab6 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 e853c8c..b2fcc16 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: /*