* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
@ 2017-07-19 9:20 Philipp Stephani
2017-09-23 18:46 ` Philipp Stephani
0 siblings, 1 reply; 8+ messages in thread
From: Philipp Stephani @ 2017-07-19 9:20 UTC (permalink / raw)
To: 27764
The docstring of `ediff-files' doesn't document the STARTUP-HOOKS
argument. Please amend the docstring.
In GNU Emacs 26.0.50 (build 9, x86_64-pc-linux-gnu, GTK+ Version 3.10.8)
of 2017-07-19 built on localhost
Repository revision: 47429dcb4afd502e5bff9d37a09b030c0b7e0eb0
Windowing system distributor 'The X.Org Foundation', version 11.0.11803000
System Description: 'Ubuntu 14.04 LTS'
Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Configured using:
'configure --enable-gcc-warnings --without-pop --with-mailutils
--enable-checking --enable-check-lisp-object-type --with-modules
'CFLAGS=-O0 -ggdb3''
Configured features:
XPM JPEG TIFF GIF PNG SOUND GSETTINGS NOTIFY GNUTLS FREETYPE XFT ZLIB
TOOLKIT_SCROLL_BARS GTK3 X11 MODULES
Important settings:
value of $LANG: en_US.UTF-8
locale-coding-system: utf-8-unix
Major mode: Lisp Interaction
Minor modes in effect:
tooltip-mode: t
global-eldoc-mode: t
eldoc-mode: t
electric-indent-mode: t
mouse-wheel-mode: t
tool-bar-mode: t
menu-bar-mode: t
file-name-shadow-mode: t
global-font-lock-mode: t
font-lock-mode: t
blink-cursor-mode: t
auto-composition-mode: t
auto-encryption-mode: t
auto-compression-mode: t
line-number-mode: t
transient-mark-mode: t
Load-path shadows:
None found.
Features:
(shadow sort mail-extr emacsbug message subr-x puny seq byte-opt gv
bytecomp byte-compile cconv cl-loaddefs cl-lib dired dired-loaddefs
format-spec rfc822 mml easymenu mml-sec password-cache epa derived epg
epg-config gnus-util rmail rmail-loaddefs mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils time-date mule-util
tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type
mwheel term/x-win x-win term/common-win x-dnd tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode elisp-mode
lisp-mode prog-mode register page menu-bar rfn-eshadow isearch timer
select scroll-bar mouse jit-lock font-lock syntax facemenu font-core
term/tty-colors frame cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite charscript charprop case-table epa-hook jka-cmpr-hook
help simple abbrev obarray minibuffer cl-preloaded nadvice loaddefs
button faces cus-face macroexp files text-properties overlay sha1 md5
base64 format env code-pages mule custom widget hashtable-print-readable
backquote inotify dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty
make-network-process emacs)
Memory information:
((conses 16 94899 7621)
(symbols 48 20234 1)
(miscs 40 39 120)
(strings 32 28620 1543)
(string-bytes 1 766344)
(vectors 16 13972)
(vector-slots 8 492162 8202)
(floats 8 48 68)
(intervals 56 222 0)
(buffers 992 12)
(heap 1024 28062 1067))
--
Google Germany GmbH
Erika-Mann-Straße 33
80636 München
Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg
Geschäftsführer: Matthew Scott Sucherman, Paul Terence Manicle
Diese E-Mail ist vertraulich. Wenn Sie nicht der richtige Adressat sind,
leiten Sie diese bitte nicht weiter, informieren Sie den Absender und löschen
Sie die E-Mail und alle Anhänge. Vielen Dank.
This e-mail is confidential. If you are not the right addressee please do not
forward it, please inform the sender, and please erase this e-mail including
any attachments. Thanks.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-07-19 9:20 bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented Philipp Stephani
@ 2017-09-23 18:46 ` Philipp Stephani
2017-09-23 18:59 ` Eli Zaretskii
0 siblings, 1 reply; 8+ messages in thread
From: Philipp Stephani @ 2017-09-23 18:46 UTC (permalink / raw)
To: 27764
[-- Attachment #1.1: Type: text/plain, Size: 268 bytes --]
Philipp Stephani <p.stephani2@gmail.com> schrieb am Mi., 19. Juli 2017 um
11:20 Uhr:
>
> The docstring of `ediff-files' doesn't document the STARTUP-HOOKS
> argument. Please amend the docstring.
>
>
>
Here's a patch that adds some missing documentation to ediff.el.
[-- Attachment #1.2: Type: text/html, Size: 572 bytes --]
[-- Attachment #2: 0001-Ediff-add-some-missing-documentation.txt --]
[-- Type: text/plain, Size: 16599 bytes --]
From 765fe15c9b2e12daae20a35e01bfc04f37b9e7bf Mon Sep 17 00:00:00 2001
From: Philipp Stephani <phst@google.com>
Date: Sat, 23 Sep 2017 20:43:44 +0200
Subject: [PATCH] Ediff: add some missing documentation
* vc/ediff.el (ediff-files, ediff-files3, ediff-buffers)
(ediff-buffers3, ediff-merge-directories)
(ediff-merge-directories-with-ancestor)
(ediff-merge-directory-revisions)
(ediff-merge-directory-revisions-with-ancestor)
(ediff-windows-wordwise, ediff-windows-linewise)
(ediff-regions-wordwise, ediff-regions-linewise)
(ediff-merge-files, ediff-merge-files-with-ancestor)
(ediff-merge-buffers, ediff-merge-buffers-with-ancestor)
(ediff-merge-revisions, ediff-merge-revisions-with-ancestor)
(ediff-patch-file, ediff-revision): Document missing arguments.
(ediff-patch-buffer, ediff-revision): Add second space after
period.
(ediff-files-command, ediff3-files-command, ediff-merge-command)
(ediff-merge-with-ancestor-command, ediff-directories-command)
(ediff-directories3-command, ediff-merge-directories-command): Add
documentation for the command line functions.
---
lisp/vc/ediff.el | 114 +++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 89 insertions(+), 25 deletions(-)
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index d0f8e63dcb..63faae9b25 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -185,7 +185,9 @@ ediff-get-default-file-name
;;;###autoload
(defun ediff-files (file-A file-B &optional startup-hooks)
- "Run Ediff on a pair of files, FILE-A and FILE-B."
+ "Run Ediff on a pair of files, FILE-A and FILE-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -221,7 +223,9 @@ ediff-files
;;;###autoload
(defun ediff-files3 (file-A file-B file-C &optional startup-hooks)
- "Run Ediff on three files, FILE-A, FILE-B, and FILE-C."
+ "Run Ediff on three files, FILE-A, FILE-B, and FILE-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -419,7 +423,11 @@ ediff-backup
;;;###autoload
(defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
- "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
+ "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers'."
(interactive
(let (bf)
(list (setq bf (read-buffer "Buffer A to compare: "
@@ -441,7 +449,11 @@ 'ebuffers
;;;###autoload
(defun ediff-buffers3 (buffer-A buffer-B buffer-C
&optional startup-hooks job-name)
- "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C."
+ "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers3'."
(interactive
(let (bf bff)
(list (setq bf (read-buffer "Buffer A to compare: "
@@ -637,7 +649,8 @@ 'edirs3
(defun ediff-merge-directories (dir1 dir2 regexp &optional merge-autostore-dir)
"Run Ediff on a pair of directories, DIR1 and DIR2, merging files that have
the same name in both. The third argument, REGEXP, is nil or a regular
-expression; only file names that match the regexp are considered."
+expression; only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -674,7 +687,8 @@ ediff-merge-directories-with-ancestor
Ediff merges files that have identical names in DIR1, DIR2. If a pair of files
in DIR1 and DIR2 doesn't have an ancestor in ANCESTOR-DIR, Ediff will merge
without ancestor. The fourth argument, REGEXP, is nil or a regular expression;
-only file names that match the regexp are considered."
+only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -710,7 +724,8 @@ ediff-merge-directory-revisions
&optional merge-autostore-dir)
"Run Ediff on a directory, DIR1, merging its files with their revisions.
The second argument, REGEXP, is a regular expression that filters the file
-names. Only the files that are under revision control are taken into account."
+names. Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -740,7 +755,8 @@ ediff-merge-directory-revisions-with-ancestor
merge-autostore-dir)
"Run Ediff on a directory, DIR1, merging its files with their revisions and ancestors.
The second argument, REGEXP, is a regular expression that filters the file
-names. Only the files that are under revision control are taken into account."
+names. Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -908,7 +924,9 @@ ediff-windows-wordwise
With prefix argument, DUMB-MODE, or on a non-windowing display, works as
follows:
If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive "P")
(ediff-windows dumb-mode wind-A wind-B
startup-hooks 'ediff-windows-wordwise 'word-mode))
@@ -919,7 +937,9 @@ ediff-windows-linewise
With prefix argument, DUMB-MODE, or on a non-windowing display, works as
follows:
If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive "P")
(ediff-windows dumb-mode wind-A wind-B
startup-hooks 'ediff-windows-linewise nil))
@@ -963,9 +983,12 @@ ediff-windows
;;;###autoload
(defun ediff-regions-wordwise (buffer-A buffer-B &optional startup-hooks)
"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'."
+lines. For large regions, use `ediff-regions-linewise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let (bf)
(list (setq bf (read-buffer "Region's A buffer: "
@@ -1003,10 +1026,13 @@ ediff-regions-wordwise
;;;###autoload
(defun ediff-regions-linewise (buffer-A buffer-B &optional startup-hooks)
"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.
Each region is enlarged to contain full lines.
This function is effective for large regions, over 100-200
-lines. For small regions, use `ediff-regions-wordwise'."
+lines. For small regions, use `ediff-regions-wordwise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let (bf)
(list (setq bf (read-buffer "Region A's buffer: "
@@ -1127,7 +1153,11 @@ ediff-merge-files
;; MERGE-BUFFER-FILE is the file to be
;; associated with the merge buffer
&optional startup-hooks merge-buffer-file)
- "Merge two files without ancestor."
+ "Merge two files without ancestor.
+FILE-A and FILE-B are the names of the files to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. MERGE-BUFFER-FILE
+is the name of the file to be associated with the merge buffer.."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -1171,7 +1201,12 @@ ediff-merge-files-with-ancestor
;; to be associated with the
;; merge buffer
merge-buffer-file)
- "Merge two files with ancestor."
+ "Merge two files with ancestor.
+FILE-A and FILE-B are the names of the files to be merged, and
+FILE-ANCESTOR is the name of the ancestor file. STARTUP-HOOKS is
+a list of functions that Emacs calls without arguments after
+setting up the Ediff buffers. MERGE-BUFFER-FILE is the name of
+the file to be associated with the merge buffer."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -1229,7 +1264,13 @@ ediff-merge-buffers
;; MERGE-BUFFER-FILE is the file to be
;; associated with the merge buffer
startup-hooks job-name merge-buffer-file)
- "Merge buffers without ancestor."
+ "Merge buffers without ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-merge-buffers'. MERGE-BUFFER-FILE is the name of the file
+to be associated with the merge buffer."
(interactive
(let (bf)
(list (setq bf (read-buffer "Buffer A to merge: "
@@ -1256,7 +1297,14 @@ ediff-merge-buffers-with-ancestor
;; file to be associated
;; with the merge buffer
merge-buffer-file)
- "Merge buffers with ancestor."
+ "Merge buffers with ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged, and
+BUFFER-ANCESTOR is their ancestor. STARTUP-HOOKS is a list of
+functions that Emacs calls without arguments after setting up the
+Ediff buffers. JOB-NAME is a symbol describing the Ediff job
+type; it defaults to `ediff-merge-buffers-with-ancestor'.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive
(let (bf bff)
(list (setq bf (read-buffer "Buffer A to merge: "
@@ -1287,8 +1335,11 @@ ediff-merge-buffers-with-ancestor
(defun ediff-merge-revisions (&optional file startup-hooks merge-buffer-file)
;; MERGE-BUFFER-FILE is the file to be associated with the merge buffer
"Run Ediff by merging two revisions of a file.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer. STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive)
(if (stringp file) (find-file file))
(let (rev1 rev2)
@@ -1319,8 +1370,11 @@ ediff-merge-revisions-with-ancestor
;; buffer
merge-buffer-file)
"Run Ediff by merging two revisions of a file with a common ancestor.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer. STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive)
(if (stringp file) (find-file file))
(let (rev1 rev2 ancestor-rev)
@@ -1360,8 +1414,8 @@ ediff-patch-file
"Query for a file name, and then run Ediff by patching that file.
If optional PATCH-BUF is given, use the patch in that buffer
and don't ask the user.
-If prefix argument, then: if even argument, assume that the patch is in a
-buffer. If odd -- assume it is in a file."
+If prefix argument ARG, then: if even argument, assume that the
+patch is in a buffer. If odd -- assume it is in a file."
(interactive "P")
(let (source-dir source-file)
(require 'ediff-ptch)
@@ -1394,7 +1448,7 @@ ediff-patch-buffer
With ARG=1, assumes the patch is in a file and prompts for the file.
With ARG=2, assumes the patch is in a buffer and prompts for the buffer.
PATCH-BUF is an optional argument, which specifies the buffer that contains the
-patch. If not given, the user is prompted according to the prefix argument."
+patch. If not given, the user is prompted according to the prefix argument."
(interactive "P")
(require 'ediff-ptch)
(setq patch-buf
@@ -1421,7 +1475,9 @@ ediff-revision
"Run Ediff by comparing versions of a file.
The file is an optional FILE argument or the file entered at the prompt.
Default: the file visited by the current buffer.
-Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'."
+Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
;; if buffer is non-nil, use that buffer instead of the current buffer
(interactive "P")
(if (not (stringp file))
@@ -1434,7 +1490,7 @@ ediff-revision
'no-dirs)))
(find-file file)
(if (and (buffer-modified-p)
- (y-or-n-p (format "Buffer %s is modified. Save buffer? "
+ (y-or-n-p (format "Buffer %s is modified. Save buffer? "
(buffer-name))))
(save-buffer (current-buffer)))
(let (rev1 rev2)
@@ -1517,6 +1573,7 @@ ediff-documentation
;;;###autoload
(defun ediff-files-command ()
+ "Call `ediff-files' with the next two command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left)))
(setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1524,6 +1581,7 @@ ediff-files-command
;;;###autoload
(defun ediff3-files-command ()
+ "Call `ediff3-files' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(file-c (nth 2 command-line-args-left)))
@@ -1532,6 +1590,7 @@ ediff3-files-command
;;;###autoload
(defun ediff-merge-command ()
+ "Call `ediff-merge-files' with the next two command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left)))
(setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1539,6 +1598,7 @@ ediff-merge-command
;;;###autoload
(defun ediff-merge-with-ancestor-command ()
+ "Call `ediff-merge-files-with-ancestor' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(ancestor (nth 2 command-line-args-left)))
@@ -1547,6 +1607,7 @@ ediff-merge-with-ancestor-command
;;;###autoload
(defun ediff-directories-command ()
+ "Call `ediff-directories' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(regexp (nth 2 command-line-args-left)))
@@ -1555,6 +1616,7 @@ ediff-directories-command
;;;###autoload
(defun ediff-directories3-command ()
+ "Call `ediff-directories3' with the next four command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(file-c (nth 2 command-line-args-left))
@@ -1564,6 +1626,7 @@ ediff-directories3-command
;;;###autoload
(defun ediff-merge-directories-command ()
+ "Call `ediff-merge-directories' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(regexp (nth 2 command-line-args-left)))
@@ -1572,6 +1635,7 @@ ediff-merge-directories-command
;;;###autoload
(defun ediff-merge-directories-with-ancestor-command ()
+ "Call `ediff-merge-directories-with-ancestor' with the next four command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(ancestor (nth 2 command-line-args-left))
--
2.14.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-09-23 18:46 ` Philipp Stephani
@ 2017-09-23 18:59 ` Eli Zaretskii
2017-09-24 8:00 ` Philipp Stephani
0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2017-09-23 18:59 UTC (permalink / raw)
To: Philipp Stephani; +Cc: 27764
> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sat, 23 Sep 2017 18:46:57 +0000
>
> Here's a patch that adds some missing documentation to ediff.el.
Thanks.
> ;;;###autoload
> (defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
> - "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
> + "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
> +STARTUP-HOOKS is a list of functions that Emacs calls without
> +arguments after setting up the Ediff buffers. JOB-NAME is a
> +symbol describing the Ediff job type; it defaults to
> +`ediff-buffers'."
Here and elsewhere where JOB-NAME is mentioned, it would be good to
have a full list of supported symbols, not just the default one.
Otherwise, the patch looks good to me. Thanks for taking good care of
this.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-09-23 18:59 ` Eli Zaretskii
@ 2017-09-24 8:00 ` Philipp Stephani
2017-09-29 7:17 ` Eli Zaretskii
0 siblings, 1 reply; 8+ messages in thread
From: Philipp Stephani @ 2017-09-24 8:00 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 27764
[-- Attachment #1.1: Type: text/plain, Size: 1005 bytes --]
Eli Zaretskii <eliz@gnu.org> schrieb am Sa., 23. Sep. 2017 um 21:00 Uhr:
> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Sat, 23 Sep 2017 18:46:57 +0000
> >
> > Here's a patch that adds some missing documentation to ediff.el.
>
> Thanks.
>
> > ;;;###autoload
> > (defun ediff-buffers (buffer-A buffer-B &optional startup-hooks
> job-name)
> > - "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
> > + "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
> > +STARTUP-HOOKS is a list of functions that Emacs calls without
> > +arguments after setting up the Ediff buffers. JOB-NAME is a
> > +symbol describing the Ediff job type; it defaults to
> > +`ediff-buffers'."
>
> Here and elsewhere where JOB-NAME is mentioned, it would be good to
> have a full list of supported symbols, not just the default one.
>
>
I've added some generic text to the docstrings. I have no idea what the
full list of supported symbols are and what the point of this argument is
in the first place.
[-- Attachment #1.2: Type: text/html, Size: 1470 bytes --]
[-- Attachment #2: 0001-Ediff-add-some-missing-documentation.txt --]
[-- Type: text/plain, Size: 16839 bytes --]
From 098072c1b5959b3458f8859d505a2cf92bbf1d36 Mon Sep 17 00:00:00 2001
From: Philipp Stephani <phst@google.com>
Date: Sat, 23 Sep 2017 20:43:44 +0200
Subject: [PATCH] Ediff: add some missing documentation
* vc/ediff.el (ediff-files, ediff-files3, ediff-buffers)
(ediff-buffers3, ediff-merge-directories)
(ediff-merge-directories-with-ancestor)
(ediff-merge-directory-revisions)
(ediff-merge-directory-revisions-with-ancestor)
(ediff-windows-wordwise, ediff-windows-linewise)
(ediff-regions-wordwise, ediff-regions-linewise)
(ediff-merge-files, ediff-merge-files-with-ancestor)
(ediff-merge-buffers, ediff-merge-buffers-with-ancestor)
(ediff-merge-revisions, ediff-merge-revisions-with-ancestor)
(ediff-patch-file, ediff-revision): Document missing arguments.
(ediff-patch-buffer, ediff-revision): Add second space after
period.
(ediff-files-command, ediff3-files-command, ediff-merge-command)
(ediff-merge-with-ancestor-command, ediff-directories-command)
(ediff-directories3-command, ediff-merge-directories-command): Add
documentation for the command line functions.
---
lisp/vc/ediff.el | 118 +++++++++++++++++++++++++++++++++++++++++++------------
1 file changed, 93 insertions(+), 25 deletions(-)
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index d0f8e63dcb..993ff934df 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -185,7 +185,9 @@ ediff-get-default-file-name
;;;###autoload
(defun ediff-files (file-A file-B &optional startup-hooks)
- "Run Ediff on a pair of files, FILE-A and FILE-B."
+ "Run Ediff on a pair of files, FILE-A and FILE-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -221,7 +223,9 @@ ediff-files
;;;###autoload
(defun ediff-files3 (file-A file-B file-C &optional startup-hooks)
- "Run Ediff on three files, FILE-A, FILE-B, and FILE-C."
+ "Run Ediff on three files, FILE-A, FILE-B, and FILE-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -419,7 +423,12 @@ ediff-backup
;;;###autoload
(defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
- "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
+ "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers', but can also be one of the other `ediff'
+function symbols."
(interactive
(let (bf)
(list (setq bf (read-buffer "Buffer A to compare: "
@@ -441,7 +450,12 @@ 'ebuffers
;;;###autoload
(defun ediff-buffers3 (buffer-A buffer-B buffer-C
&optional startup-hooks job-name)
- "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C."
+ "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers3', but can also be one of the other `ediff'
+function symbols."
(interactive
(let (bf bff)
(list (setq bf (read-buffer "Buffer A to compare: "
@@ -637,7 +651,8 @@ 'edirs3
(defun ediff-merge-directories (dir1 dir2 regexp &optional merge-autostore-dir)
"Run Ediff on a pair of directories, DIR1 and DIR2, merging files that have
the same name in both. The third argument, REGEXP, is nil or a regular
-expression; only file names that match the regexp are considered."
+expression; only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -674,7 +689,8 @@ ediff-merge-directories-with-ancestor
Ediff merges files that have identical names in DIR1, DIR2. If a pair of files
in DIR1 and DIR2 doesn't have an ancestor in ANCESTOR-DIR, Ediff will merge
without ancestor. The fourth argument, REGEXP, is nil or a regular expression;
-only file names that match the regexp are considered."
+only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -710,7 +726,8 @@ ediff-merge-directory-revisions
&optional merge-autostore-dir)
"Run Ediff on a directory, DIR1, merging its files with their revisions.
The second argument, REGEXP, is a regular expression that filters the file
-names. Only the files that are under revision control are taken into account."
+names. Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -740,7 +757,8 @@ ediff-merge-directory-revisions-with-ancestor
merge-autostore-dir)
"Run Ediff on a directory, DIR1, merging its files with their revisions and ancestors.
The second argument, REGEXP, is a regular expression that filters the file
-names. Only the files that are under revision control are taken into account."
+names. Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -908,7 +926,9 @@ ediff-windows-wordwise
With prefix argument, DUMB-MODE, or on a non-windowing display, works as
follows:
If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive "P")
(ediff-windows dumb-mode wind-A wind-B
startup-hooks 'ediff-windows-wordwise 'word-mode))
@@ -919,7 +939,9 @@ ediff-windows-linewise
With prefix argument, DUMB-MODE, or on a non-windowing display, works as
follows:
If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive "P")
(ediff-windows dumb-mode wind-A wind-B
startup-hooks 'ediff-windows-linewise nil))
@@ -963,9 +985,12 @@ ediff-windows
;;;###autoload
(defun ediff-regions-wordwise (buffer-A buffer-B &optional startup-hooks)
"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'."
+lines. For large regions, use `ediff-regions-linewise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let (bf)
(list (setq bf (read-buffer "Region's A buffer: "
@@ -1003,10 +1028,13 @@ ediff-regions-wordwise
;;;###autoload
(defun ediff-regions-linewise (buffer-A buffer-B &optional startup-hooks)
"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.
Each region is enlarged to contain full lines.
This function is effective for large regions, over 100-200
-lines. For small regions, use `ediff-regions-wordwise'."
+lines. For small regions, use `ediff-regions-wordwise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let (bf)
(list (setq bf (read-buffer "Region A's buffer: "
@@ -1127,7 +1155,11 @@ ediff-merge-files
;; MERGE-BUFFER-FILE is the file to be
;; associated with the merge buffer
&optional startup-hooks merge-buffer-file)
- "Merge two files without ancestor."
+ "Merge two files without ancestor.
+FILE-A and FILE-B are the names of the files to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. MERGE-BUFFER-FILE
+is the name of the file to be associated with the merge buffer.."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -1171,7 +1203,12 @@ ediff-merge-files-with-ancestor
;; to be associated with the
;; merge buffer
merge-buffer-file)
- "Merge two files with ancestor."
+ "Merge two files with ancestor.
+FILE-A and FILE-B are the names of the files to be merged, and
+FILE-ANCESTOR is the name of the ancestor file. STARTUP-HOOKS is
+a list of functions that Emacs calls without arguments after
+setting up the Ediff buffers. MERGE-BUFFER-FILE is the name of
+the file to be associated with the merge buffer."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -1229,7 +1266,14 @@ ediff-merge-buffers
;; MERGE-BUFFER-FILE is the file to be
;; associated with the merge buffer
startup-hooks job-name merge-buffer-file)
- "Merge buffers without ancestor."
+ "Merge buffers without ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-merge-buffers', but can also be one of the other `ediff'
+function symbols. MERGE-BUFFER-FILE is the name of the file to
+be associated with the merge buffer."
(interactive
(let (bf)
(list (setq bf (read-buffer "Buffer A to merge: "
@@ -1256,7 +1300,15 @@ ediff-merge-buffers-with-ancestor
;; file to be associated
;; with the merge buffer
merge-buffer-file)
- "Merge buffers with ancestor."
+ "Merge buffers with ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged, and
+BUFFER-ANCESTOR is their ancestor. STARTUP-HOOKS is a list of
+functions that Emacs calls without arguments after setting up the
+Ediff buffers. JOB-NAME is a symbol describing the Ediff job
+type; it defaults to `ediff-merge-buffers-with-ancestor', but can
+also be one of the other `ediff' function symbols.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive
(let (bf bff)
(list (setq bf (read-buffer "Buffer A to merge: "
@@ -1287,8 +1339,11 @@ ediff-merge-buffers-with-ancestor
(defun ediff-merge-revisions (&optional file startup-hooks merge-buffer-file)
;; MERGE-BUFFER-FILE is the file to be associated with the merge buffer
"Run Ediff by merging two revisions of a file.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer. STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive)
(if (stringp file) (find-file file))
(let (rev1 rev2)
@@ -1319,8 +1374,11 @@ ediff-merge-revisions-with-ancestor
;; buffer
merge-buffer-file)
"Run Ediff by merging two revisions of a file with a common ancestor.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer. STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive)
(if (stringp file) (find-file file))
(let (rev1 rev2 ancestor-rev)
@@ -1360,8 +1418,8 @@ ediff-patch-file
"Query for a file name, and then run Ediff by patching that file.
If optional PATCH-BUF is given, use the patch in that buffer
and don't ask the user.
-If prefix argument, then: if even argument, assume that the patch is in a
-buffer. If odd -- assume it is in a file."
+If prefix argument ARG, then: if even argument, assume that the
+patch is in a buffer. If odd -- assume it is in a file."
(interactive "P")
(let (source-dir source-file)
(require 'ediff-ptch)
@@ -1394,7 +1452,7 @@ ediff-patch-buffer
With ARG=1, assumes the patch is in a file and prompts for the file.
With ARG=2, assumes the patch is in a buffer and prompts for the buffer.
PATCH-BUF is an optional argument, which specifies the buffer that contains the
-patch. If not given, the user is prompted according to the prefix argument."
+patch. If not given, the user is prompted according to the prefix argument."
(interactive "P")
(require 'ediff-ptch)
(setq patch-buf
@@ -1421,7 +1479,9 @@ ediff-revision
"Run Ediff by comparing versions of a file.
The file is an optional FILE argument or the file entered at the prompt.
Default: the file visited by the current buffer.
-Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'."
+Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
;; if buffer is non-nil, use that buffer instead of the current buffer
(interactive "P")
(if (not (stringp file))
@@ -1434,7 +1494,7 @@ ediff-revision
'no-dirs)))
(find-file file)
(if (and (buffer-modified-p)
- (y-or-n-p (format "Buffer %s is modified. Save buffer? "
+ (y-or-n-p (format "Buffer %s is modified. Save buffer? "
(buffer-name))))
(save-buffer (current-buffer)))
(let (rev1 rev2)
@@ -1517,6 +1577,7 @@ ediff-documentation
;;;###autoload
(defun ediff-files-command ()
+ "Call `ediff-files' with the next two command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left)))
(setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1524,6 +1585,7 @@ ediff-files-command
;;;###autoload
(defun ediff3-files-command ()
+ "Call `ediff3-files' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(file-c (nth 2 command-line-args-left)))
@@ -1532,6 +1594,7 @@ ediff3-files-command
;;;###autoload
(defun ediff-merge-command ()
+ "Call `ediff-merge-files' with the next two command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left)))
(setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1539,6 +1602,7 @@ ediff-merge-command
;;;###autoload
(defun ediff-merge-with-ancestor-command ()
+ "Call `ediff-merge-files-with-ancestor' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(ancestor (nth 2 command-line-args-left)))
@@ -1547,6 +1611,7 @@ ediff-merge-with-ancestor-command
;;;###autoload
(defun ediff-directories-command ()
+ "Call `ediff-directories' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(regexp (nth 2 command-line-args-left)))
@@ -1555,6 +1620,7 @@ ediff-directories-command
;;;###autoload
(defun ediff-directories3-command ()
+ "Call `ediff-directories3' with the next four command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(file-c (nth 2 command-line-args-left))
@@ -1564,6 +1630,7 @@ ediff-directories3-command
;;;###autoload
(defun ediff-merge-directories-command ()
+ "Call `ediff-merge-directories' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(regexp (nth 2 command-line-args-left)))
@@ -1572,6 +1639,7 @@ ediff-merge-directories-command
;;;###autoload
(defun ediff-merge-directories-with-ancestor-command ()
+ "Call `ediff-merge-directories-with-ancestor' with the next four command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(ancestor (nth 2 command-line-args-left))
--
2.14.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-09-24 8:00 ` Philipp Stephani
@ 2017-09-29 7:17 ` Eli Zaretskii
2017-11-05 16:29 ` Philipp Stephani
0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2017-09-29 7:17 UTC (permalink / raw)
To: Philipp Stephani; +Cc: 27764
> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sun, 24 Sep 2017 08:00:53 +0000
> Cc: 27764@debbugs.gnu.org
>
> > (defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
> > - "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
> > + "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
> > +STARTUP-HOOKS is a list of functions that Emacs calls without
> > +arguments after setting up the Ediff buffers. JOB-NAME is a
> > +symbol describing the Ediff job type; it defaults to
> > +`ediff-buffers'."
>
> Here and elsewhere where JOB-NAME is mentioned, it would be good to
> have a full list of supported symbols, not just the default one.
>
> I've added some generic text to the docstrings. I have no idea what the full list of supported symbols are and
> what the point of this argument is in the first place.
Can we have there at least the list of the symbols that are seen in
the sources: I see these:
ediff-merge-files-with-ancestor, ediff-last-dir-ancestor,
ediff-last-dir-C, ediff-buffers, ediff-buffers3, ediff-merge-buffers,
ediff-merge-buffers-with-ancestor
If this list is too long to be repeated in each doc string, we could
have it once, and reference that place from the other do strings. I
think either way would be much better than using some generic text.
OK?
Thanks.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-09-29 7:17 ` Eli Zaretskii
@ 2017-11-05 16:29 ` Philipp Stephani
2017-11-05 16:51 ` Eli Zaretskii
0 siblings, 1 reply; 8+ messages in thread
From: Philipp Stephani @ 2017-11-05 16:29 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 27764
[-- Attachment #1.1: Type: text/plain, Size: 1494 bytes --]
Eli Zaretskii <eliz@gnu.org> schrieb am Fr., 29. Sep. 2017 um 09:18 Uhr:
> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Sun, 24 Sep 2017 08:00:53 +0000
> > Cc: 27764@debbugs.gnu.org
> >
> > > (defun ediff-buffers (buffer-A buffer-B &optional startup-hooks
> job-name)
> > > - "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
> > > + "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
> > > +STARTUP-HOOKS is a list of functions that Emacs calls without
> > > +arguments after setting up the Ediff buffers. JOB-NAME is a
> > > +symbol describing the Ediff job type; it defaults to
> > > +`ediff-buffers'."
> >
> > Here and elsewhere where JOB-NAME is mentioned, it would be good to
> > have a full list of supported symbols, not just the default one.
> >
> > I've added some generic text to the docstrings. I have no idea what the
> full list of supported symbols are and
> > what the point of this argument is in the first place.
>
> Can we have there at least the list of the symbols that are seen in
> the sources: I see these:
>
> ediff-merge-files-with-ancestor, ediff-last-dir-ancestor,
> ediff-last-dir-C, ediff-buffers, ediff-buffers3, ediff-merge-buffers,
> ediff-merge-buffers-with-ancestor
>
> If this list is too long to be repeated in each doc string, we could
> have it once, and reference that place from the other do strings. I
> think either way would be much better than using some generic text.
>
>
Here's a new version of the patch.
[-- Attachment #1.2: Type: text/html, Size: 2091 bytes --]
[-- Attachment #2: 0001-Ediff-add-some-missing-documentation.txt --]
[-- Type: text/plain, Size: 17329 bytes --]
From e292af4d2ad1b115f01e86e8515664873355712b Mon Sep 17 00:00:00 2001
From: Philipp Stephani <phst@google.com>
Date: Sat, 23 Sep 2017 20:43:44 +0200
Subject: [PATCH] Ediff: add some missing documentation
* vc/ediff.el (ediff-files, ediff-files3, ediff-buffers)
(ediff-buffers3, ediff-merge-directories)
(ediff-merge-directories-with-ancestor)
(ediff-merge-directory-revisions)
(ediff-merge-directory-revisions-with-ancestor)
(ediff-windows-wordwise, ediff-windows-linewise)
(ediff-regions-wordwise, ediff-regions-linewise)
(ediff-merge-files, ediff-merge-files-with-ancestor)
(ediff-merge-buffers, ediff-merge-buffers-with-ancestor)
(ediff-merge-revisions, ediff-merge-revisions-with-ancestor)
(ediff-patch-file, ediff-revision): Document missing arguments.
(ediff-patch-buffer, ediff-revision): Add second space after
period.
(ediff-files-command, ediff3-files-command, ediff-merge-command)
(ediff-merge-with-ancestor-command, ediff-directories-command)
(ediff-directories3-command, ediff-merge-directories-command): Add
documentation for the command line functions.
---
lisp/vc/ediff.el | 125 ++++++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 100 insertions(+), 25 deletions(-)
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index d0f8e63dcb..0adf51328e 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -185,7 +185,9 @@ ediff-get-default-file-name
;;;###autoload
(defun ediff-files (file-A file-B &optional startup-hooks)
- "Run Ediff on a pair of files, FILE-A and FILE-B."
+ "Run Ediff on a pair of files, FILE-A and FILE-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -221,7 +223,9 @@ ediff-files
;;;###autoload
(defun ediff-files3 (file-A file-B file-C &optional startup-hooks)
- "Run Ediff on three files, FILE-A, FILE-B, and FILE-C."
+ "Run Ediff on three files, FILE-A, FILE-B, and FILE-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -419,7 +423,14 @@ ediff-backup
;;;###autoload
(defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
- "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
+ "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers', but can also be one of
+`ediff-merge-files-with-ancestor', `ediff-last-dir-ancestor',
+`ediff-last-dir-C', `ediff-buffers3', `ediff-merge-buffers', or
+`ediff-merge-buffers-with-ancestor'."
(interactive
(let (bf)
(list (setq bf (read-buffer "Buffer A to compare: "
@@ -441,7 +452,14 @@ 'ebuffers
;;;###autoload
(defun ediff-buffers3 (buffer-A buffer-B buffer-C
&optional startup-hooks job-name)
- "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C."
+ "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers3', but can also be one of
+`ediff-merge-files-with-ancestor', `ediff-last-dir-ancestor',
+`ediff-last-dir-C', `ediff-buffers', `ediff-merge-buffers', or
+`ediff-merge-buffers-with-ancestor'."
(interactive
(let (bf bff)
(list (setq bf (read-buffer "Buffer A to compare: "
@@ -637,7 +655,8 @@ 'edirs3
(defun ediff-merge-directories (dir1 dir2 regexp &optional merge-autostore-dir)
"Run Ediff on a pair of directories, DIR1 and DIR2, merging files that have
the same name in both. The third argument, REGEXP, is nil or a regular
-expression; only file names that match the regexp are considered."
+expression; only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -674,7 +693,8 @@ ediff-merge-directories-with-ancestor
Ediff merges files that have identical names in DIR1, DIR2. If a pair of files
in DIR1 and DIR2 doesn't have an ancestor in ANCESTOR-DIR, Ediff will merge
without ancestor. The fourth argument, REGEXP, is nil or a regular expression;
-only file names that match the regexp are considered."
+only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -710,7 +730,8 @@ ediff-merge-directory-revisions
&optional merge-autostore-dir)
"Run Ediff on a directory, DIR1, merging its files with their revisions.
The second argument, REGEXP, is a regular expression that filters the file
-names. Only the files that are under revision control are taken into account."
+names. Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -740,7 +761,8 @@ ediff-merge-directory-revisions-with-ancestor
merge-autostore-dir)
"Run Ediff on a directory, DIR1, merging its files with their revisions and ancestors.
The second argument, REGEXP, is a regular expression that filters the file
-names. Only the files that are under revision control are taken into account."
+names. Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp))
@@ -908,7 +930,9 @@ ediff-windows-wordwise
With prefix argument, DUMB-MODE, or on a non-windowing display, works as
follows:
If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive "P")
(ediff-windows dumb-mode wind-A wind-B
startup-hooks 'ediff-windows-wordwise 'word-mode))
@@ -919,7 +943,9 @@ ediff-windows-linewise
With prefix argument, DUMB-MODE, or on a non-windowing display, works as
follows:
If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive "P")
(ediff-windows dumb-mode wind-A wind-B
startup-hooks 'ediff-windows-linewise nil))
@@ -963,9 +989,12 @@ ediff-windows
;;;###autoload
(defun ediff-regions-wordwise (buffer-A buffer-B &optional startup-hooks)
"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'."
+lines. For large regions, use `ediff-regions-linewise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let (bf)
(list (setq bf (read-buffer "Region's A buffer: "
@@ -1003,10 +1032,13 @@ ediff-regions-wordwise
;;;###autoload
(defun ediff-regions-linewise (buffer-A buffer-B &optional startup-hooks)
"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.
Each region is enlarged to contain full lines.
This function is effective for large regions, over 100-200
-lines. For small regions, use `ediff-regions-wordwise'."
+lines. For small regions, use `ediff-regions-wordwise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
(interactive
(let (bf)
(list (setq bf (read-buffer "Region A's buffer: "
@@ -1127,7 +1159,11 @@ ediff-merge-files
;; MERGE-BUFFER-FILE is the file to be
;; associated with the merge buffer
&optional startup-hooks merge-buffer-file)
- "Merge two files without ancestor."
+ "Merge two files without ancestor.
+FILE-A and FILE-B are the names of the files to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. MERGE-BUFFER-FILE
+is the name of the file to be associated with the merge buffer.."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -1171,7 +1207,12 @@ ediff-merge-files-with-ancestor
;; to be associated with the
;; merge buffer
merge-buffer-file)
- "Merge two files with ancestor."
+ "Merge two files with ancestor.
+FILE-A and FILE-B are the names of the files to be merged, and
+FILE-ANCESTOR is the name of the ancestor file. STARTUP-HOOKS is
+a list of functions that Emacs calls without arguments after
+setting up the Ediff buffers. MERGE-BUFFER-FILE is the name of
+the file to be associated with the merge buffer."
(interactive
(let ((dir-A (if ediff-use-last-dir
ediff-last-dir-A
@@ -1229,7 +1270,16 @@ ediff-merge-buffers
;; MERGE-BUFFER-FILE is the file to be
;; associated with the merge buffer
startup-hooks job-name merge-buffer-file)
- "Merge buffers without ancestor."
+ "Merge buffers without ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers. JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-merge-buffers', but can also be one of
+`ediff-merge-files-with-ancestor', `ediff-last-dir-ancestor',
+`ediff-last-dir-C', `ediff-buffers', `ediff-buffers3', or
+`ediff-merge-buffers-with-ancestor'. MERGE-BUFFER-FILE is the
+name of the file to be associated with the merge buffer."
(interactive
(let (bf)
(list (setq bf (read-buffer "Buffer A to merge: "
@@ -1256,7 +1306,16 @@ ediff-merge-buffers-with-ancestor
;; file to be associated
;; with the merge buffer
merge-buffer-file)
- "Merge buffers with ancestor."
+ "Merge buffers with ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged, and
+BUFFER-ANCESTOR is their ancestor. STARTUP-HOOKS is a list of
+functions that Emacs calls without arguments after setting up the
+Ediff buffers. JOB-NAME is a symbol describing the Ediff job
+type; it defaults to `ediff-merge-buffers-with-ancestor', but can
+also be one of `ediff-merge-files-with-ancestor',
+`ediff-last-dir-ancestor', `ediff-last-dir-C', `ediff-buffers',
+`ediff-buffers3', or `ediff-merge-buffers'. MERGE-BUFFER-FILE is
+the name of the file to be associated with the merge buffer."
(interactive
(let (bf bff)
(list (setq bf (read-buffer "Buffer A to merge: "
@@ -1287,8 +1346,11 @@ ediff-merge-buffers-with-ancestor
(defun ediff-merge-revisions (&optional file startup-hooks merge-buffer-file)
;; MERGE-BUFFER-FILE is the file to be associated with the merge buffer
"Run Ediff by merging two revisions of a file.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer. STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive)
(if (stringp file) (find-file file))
(let (rev1 rev2)
@@ -1319,8 +1381,11 @@ ediff-merge-revisions-with-ancestor
;; buffer
merge-buffer-file)
"Run Ediff by merging two revisions of a file with a common ancestor.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer. STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
(interactive)
(if (stringp file) (find-file file))
(let (rev1 rev2 ancestor-rev)
@@ -1360,8 +1425,8 @@ ediff-patch-file
"Query for a file name, and then run Ediff by patching that file.
If optional PATCH-BUF is given, use the patch in that buffer
and don't ask the user.
-If prefix argument, then: if even argument, assume that the patch is in a
-buffer. If odd -- assume it is in a file."
+If prefix argument ARG, then: if even argument, assume that the
+patch is in a buffer. If odd -- assume it is in a file."
(interactive "P")
(let (source-dir source-file)
(require 'ediff-ptch)
@@ -1394,7 +1459,7 @@ ediff-patch-buffer
With ARG=1, assumes the patch is in a file and prompts for the file.
With ARG=2, assumes the patch is in a buffer and prompts for the buffer.
PATCH-BUF is an optional argument, which specifies the buffer that contains the
-patch. If not given, the user is prompted according to the prefix argument."
+patch. If not given, the user is prompted according to the prefix argument."
(interactive "P")
(require 'ediff-ptch)
(setq patch-buf
@@ -1421,7 +1486,9 @@ ediff-revision
"Run Ediff by comparing versions of a file.
The file is an optional FILE argument or the file entered at the prompt.
Default: the file visited by the current buffer.
-Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'."
+Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
;; if buffer is non-nil, use that buffer instead of the current buffer
(interactive "P")
(if (not (stringp file))
@@ -1434,7 +1501,7 @@ ediff-revision
'no-dirs)))
(find-file file)
(if (and (buffer-modified-p)
- (y-or-n-p (format "Buffer %s is modified. Save buffer? "
+ (y-or-n-p (format "Buffer %s is modified. Save buffer? "
(buffer-name))))
(save-buffer (current-buffer)))
(let (rev1 rev2)
@@ -1517,6 +1584,7 @@ ediff-documentation
;;;###autoload
(defun ediff-files-command ()
+ "Call `ediff-files' with the next two command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left)))
(setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1524,6 +1592,7 @@ ediff-files-command
;;;###autoload
(defun ediff3-files-command ()
+ "Call `ediff3-files' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(file-c (nth 2 command-line-args-left)))
@@ -1532,6 +1601,7 @@ ediff3-files-command
;;;###autoload
(defun ediff-merge-command ()
+ "Call `ediff-merge-files' with the next two command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left)))
(setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1539,6 +1609,7 @@ ediff-merge-command
;;;###autoload
(defun ediff-merge-with-ancestor-command ()
+ "Call `ediff-merge-files-with-ancestor' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(ancestor (nth 2 command-line-args-left)))
@@ -1547,6 +1618,7 @@ ediff-merge-with-ancestor-command
;;;###autoload
(defun ediff-directories-command ()
+ "Call `ediff-directories' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(regexp (nth 2 command-line-args-left)))
@@ -1555,6 +1627,7 @@ ediff-directories-command
;;;###autoload
(defun ediff-directories3-command ()
+ "Call `ediff-directories3' with the next four command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(file-c (nth 2 command-line-args-left))
@@ -1564,6 +1637,7 @@ ediff-directories3-command
;;;###autoload
(defun ediff-merge-directories-command ()
+ "Call `ediff-merge-directories' with the next three command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(regexp (nth 2 command-line-args-left)))
@@ -1572,6 +1646,7 @@ ediff-merge-directories-command
;;;###autoload
(defun ediff-merge-directories-with-ancestor-command ()
+ "Call `ediff-merge-directories-with-ancestor' with the next four command line arguments."
(let ((file-a (nth 0 command-line-args-left))
(file-b (nth 1 command-line-args-left))
(ancestor (nth 2 command-line-args-left))
--
2.14.2
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-11-05 16:29 ` Philipp Stephani
@ 2017-11-05 16:51 ` Eli Zaretskii
2017-11-05 17:54 ` Philipp Stephani
0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2017-11-05 16:51 UTC (permalink / raw)
To: Philipp Stephani; +Cc: 27764
> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sun, 05 Nov 2017 16:29:35 +0000
> Cc: 27764@debbugs.gnu.org
>
> Can we have there at least the list of the symbols that are seen in
> the sources: I see these:
>
> ediff-merge-files-with-ancestor, ediff-last-dir-ancestor,
> ediff-last-dir-C, ediff-buffers, ediff-buffers3, ediff-merge-buffers,
> ediff-merge-buffers-with-ancestor
>
> If this list is too long to be repeated in each doc string, we could
> have it once, and reference that place from the other do strings. I
> think either way would be much better than using some generic text.
>
> Here's a new version of the patch.
Thanks, this is fine.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented
2017-11-05 16:51 ` Eli Zaretskii
@ 2017-11-05 17:54 ` Philipp Stephani
0 siblings, 0 replies; 8+ messages in thread
From: Philipp Stephani @ 2017-11-05 17:54 UTC (permalink / raw)
To: Eli Zaretskii, 27764-done; +Cc: 27764@debbugs.gnu.org
[-- Attachment #1: Type: text/plain, Size: 838 bytes --]
Eli Zaretskii <eliz@gnu.org> schrieb am So., 5. Nov. 2017 um 17:51 Uhr:
> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Sun, 05 Nov 2017 16:29:35 +0000
> > Cc: 27764@debbugs.gnu.org
> >
> > Can we have there at least the list of the symbols that are seen in
> > the sources: I see these:
> >
> > ediff-merge-files-with-ancestor, ediff-last-dir-ancestor,
> > ediff-last-dir-C, ediff-buffers, ediff-buffers3, ediff-merge-buffers,
> > ediff-merge-buffers-with-ancestor
> >
> > If this list is too long to be repeated in each doc string, we could
> > have it once, and reference that place from the other do strings. I
> > think either way would be much better than using some generic text.
> >
> > Here's a new version of the patch.
>
> Thanks, this is fine.
>
Thanks, pushed as 72d07d1950 to the release branch.
[-- Attachment #2: Type: text/html, Size: 1357 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2017-11-05 17:54 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-07-19 9:20 bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented Philipp Stephani
2017-09-23 18:46 ` Philipp Stephani
2017-09-23 18:59 ` Eli Zaretskii
2017-09-24 8:00 ` Philipp Stephani
2017-09-29 7:17 ` Eli Zaretskii
2017-11-05 16:29 ` Philipp Stephani
2017-11-05 16:51 ` Eli Zaretskii
2017-11-05 17:54 ` Philipp Stephani
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).