[Emacs-diffs] emacs-26 f0531b8: Improve documentation of Ediff wordwise commands

[Eli Zaretskii]

branch: emacs-26
commit f0531b8e64250414baf1c0d2dde3fbfc55a748a0
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of Ediff wordwise commands
    
    * lisp/vc/ediff.el (ediff-windows-wordwise)
    (ediff-windows-linewise, ediff-regions-wordwise): Update and
    clarify the doc strings.
    
    * doc/misc/ediff.texi (Major Entry Points): Update and clarify
    the documentation of 'ediff-windows-wordwise' and
    'ediff-regions-wordwise'.  See the discussion starting at
    https://lists.gnu.org/archive/html/help-gnu-emacs/2018-11/msg00197.html
    for the details.
---
 doc/misc/ediff.texi | 13 ++++++-------
 lisp/vc/ediff.el    |  9 ++++++---
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi
index 746c4c8..cce8321 100644
--- a/doc/misc/ediff.texi
+++ b/doc/misc/ediff.texi
@@ -210,11 +210,11 @@ ancestors.  Ediff selects only the files that are under 
version control.
 
 @item ediff-windows-wordwise
 @findex ediff-windows-wordwise
-Compare windows word-by-word.
+Compare text visible in 2 windows word-by-word.
 
 @item ediff-windows-linewise
 @findex ediff-windows-linewise
-Compare windows line-by-line.
+Compare text visible in 2 windows line-by-line.
 
 @item ediff-regions-wordwise
 @findex ediff-regions-wordwise
@@ -373,13 +373,12 @@ The commands @code{ediff-windows-wordwise},
 @code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
 @code{ediff-regions-linewise} do comparison on parts of existing Emacs
 buffers.  The commands @code{ediff-windows-wordwise} and
address@hidden are intended for relatively small segments
-of buffers (e.g., up to 100 lines, depending on the speed of your machine),
address@hidden could be slow on very large buffers,
 as they perform comparison on the basis of words rather than lines.
-(Word-wise comparison of large chunks of text can be slow.)
+(Word-wise comparison of large chunks of text is relatively expensive.)
 
-To compare large regions, use @code{ediff-regions-linewise}.  This
-command displays differences much like @code{ediff-files} and
+To compare very large regions, use @code{ediff-regions-linewise}.
+This command displays differences much like @code{ediff-files} and
 @code{ediff-buffers}.
 
 The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index cd2b2c4..da7b0f1 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -927,6 +927,7 @@ MERGE-AUTOSTORE-DIR is the directory in which to store 
merged files."
 ;;;###autoload
 (defun ediff-windows-wordwise (dumb-mode &optional wind-A wind-B startup-hooks)
   "Compare WIND-A and WIND-B, which are selected by clicking, wordwise.
+This compares the portions of text visible in each of the two windows.
 With prefix argument, DUMB-MODE, or on a non-windowing display, works as
 follows:
 If WIND-A is nil, use selected window.
@@ -940,6 +941,7 @@ arguments after setting up the Ediff buffers."
 ;;;###autoload
 (defun ediff-windows-linewise (dumb-mode &optional wind-A wind-B startup-hooks)
   "Compare WIND-A and WIND-B, which are selected by clicking, linewise.
+This compares the portions of text visible in each of the two windows.
 With prefix argument, DUMB-MODE, or on a non-windowing display, works as
 follows:
 If WIND-A is nil, use selected window.
@@ -950,7 +952,8 @@ arguments after setting up the Ediff buffers."
   (ediff-windows dumb-mode wind-A wind-B
                 startup-hooks 'ediff-windows-linewise nil))
 
-;; Compare WIND-A and WIND-B, which are selected by clicking.
+;; Compare visible portions of text in WIND-A and WIND-B, which are
+;; selected by clicking.
 ;; With prefix argument, DUMB-MODE, or on a non-windowing display,
 ;; works as follows:
 ;; If WIND-A is nil, use selected window.
@@ -991,8 +994,8 @@ arguments after setting up the Ediff buffers."
   "Run Ediff on a pair of regions in specified buffers.
 BUFFER-A and BUFFER-B are the buffers to be compared.
 Regions (i.e., point and mark) can be set in advance or marked interactively.
-This function is effective only for relatively small regions, up to 200
-lines.  For large regions, use `ediff-regions-linewise'.
+This function might be slow for large regions.  If you find it slow,
+use `ediff-regions-linewise' instead.
 STARTUP-HOOKS is a list of functions that Emacs calls without
 arguments after setting up the Ediff buffers."
   (interactive