From f0531b8e64250414baf1c0d2dde3fbfc55a748a0 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Tue, 27 Nov 2018 10:09:55 +0200
Subject: [PATCH] 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 746c4c829d2..cce8321d9eb 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
-@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 cd2b2c4e628..da7b0f12919 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
--
2.39.5