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.

diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi
index 746c4c829d26b7b310dadc4719a6ecfd38821039..cce8321d9ebffbd62df0215db9976ee423b1270b 100644 (file)
--- 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
-@code{ediff-regions-wordwise} are intended for relatively small segments
-of buffers (e.g., up to 100 lines, depending on the speed of your machine),
+@code{ediff-regions-wordwise} 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 cd2b2c4e62888c76982000960127a2710ae929ce..da7b0f12919616ff1626ab8c582e7d7529a2b267 100644 (file)
--- 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