diff options
Diffstat (limited to 'lisp/vc/emerge.el')
| -rw-r--r-- | lisp/vc/emerge.el | 133 |
1 files changed, 71 insertions, 62 deletions
diff --git a/lisp/vc/emerge.el b/lisp/vc/emerge.el index 8f7affeea4e..b2fdb07d5fb 100644 --- a/lisp/vc/emerge.el +++ b/lisp/vc/emerge.el @@ -26,15 +26,18 @@ ;;; Macros -(defmacro emerge-defvar-local (var value doc) +(defmacro emerge-defvar-local (symbol value &optional doc) "Define SYMBOL as an advertised buffer-local variable. -Performs a defvar, then executes `make-variable-buffer-local' on -the variable. Also sets the `permanent-local' property, so that -`kill-all-local-variables' (called by major-mode setting commands) -won't destroy Emerge control variables." +Run `defvar-local', setting the value of the variable to VALUE +and its docstring to DOC. + +Then set the `permanent-local' property, so that +`kill-all-local-variables' (called by major-mode setting +commands) won't destroy Emerge control variables." + (declare (indent defun) (doc-string 3)) `(progn - (defvar-local ,var ,value ,doc) - (put ',var 'permanent-local t))) + (defvar-local ,symbol ,value ,doc) + (put ',symbol 'permanent-local t))) ;; We need to define this function so describe-mode can describe Emerge mode. (define-minor-mode emerge-mode @@ -217,8 +220,7 @@ depend on the flags." (emerge-new-flags) (defcustom emerge-min-visible-lines 3 - "Number of lines that we want to show above and below the flags when we are -displaying a difference." + "Number of lines to show above and below the flags when displaying a difference." :type 'integer) (defcustom emerge-temp-file-prefix @@ -434,8 +436,7 @@ or nil if there is none.") '((buffer-modified-p set-buffer-modified-p) buffer-read-only buffer-auto-save-file-name) - "Variables and properties of a buffer which are saved, modified and restored -during a merge.") + "Variables and properties of a buffer to save, modify and restore during a merge.") (defconst emerge-merging-values '(nil t nil) "Values to be assigned to emerge-saved-variables during a merge.") @@ -481,10 +482,10 @@ replaced by emerge-fast-keymap.") (emerge-defvar-local emerge-old-keymap nil "The original local keymap for the merge buffer.") (emerge-defvar-local emerge-auto-advance nil - "If non-nil, emerge-select-A and emerge-select-B automatically advance to + "If non-nil, emerge-select-A and emerge-select-B automatically advance to the next difference.") (emerge-defvar-local emerge-skip-prefers nil - "If non-nil, differences for which there is a preference are automatically + "If non-nil, differences for which there is a preference are automatically skipped.") (emerge-defvar-local emerge-quit-hook nil "Hooks to run in the merge buffer after the merge has been finished. @@ -825,7 +826,7 @@ This is *not* a user option, since Emerge uses it for its own processing.") ;;;###autoload (defun emerge-files (_arg file-A file-B file-out &optional startup-hooks quit-hooks) - "Run Emerge on two files." + "Run Emerge on two files FILE-A and FILE-B." (interactive (let (f) (list current-prefix-arg @@ -874,7 +875,7 @@ This is *not* a user option, since Emerge uses it for its own processing.") ;;;###autoload (defun emerge-buffers (buffer-A buffer-B &optional startup-hooks quit-hooks) - "Run Emerge on two buffers." + "Run Emerge on two buffers BUFFER-A and BUFFER-B." (interactive "bBuffer A to merge: \nbBuffer B to merge: ") (let ((emerge-file-A (emerge-make-temp-file "A")) (emerge-file-B (emerge-make-temp-file "B"))) @@ -1773,15 +1774,15 @@ BEG must be at the beginning of a line." (emerge-unselect-and-select-difference n))) (error "At beginning"))) -(defun emerge-jump-to-difference (difference-number) - "Go to the N-th difference." +(defun emerge-jump-to-difference (n) + "Go to difference number N." (interactive "p") (let ((inhibit-read-only t)) - (setq difference-number (1- difference-number)) - (if (and (>= difference-number -1) - (< difference-number (1+ emerge-number-of-differences))) - (emerge-unselect-and-select-difference difference-number) - (error "Bad difference number")))) + (setq n (1- n)) + (if (and (>= n -1) + (< n (1+ emerge-number-of-differences))) + (emerge-unselect-and-select-difference n) + (error "Bad difference number: %s" n)))) (defun emerge-abort () "Abort the Emerge session." @@ -1790,7 +1791,7 @@ BEG must be at the beginning of a line." (defun emerge-quit (arg) "Finish the Emerge session and exit Emerge. -Prefix argument means to abort rather than successfully finish. +Prefix argument ARG means to abort rather than successfully finish. The difference depends on how the merge was started, but usually means to not write over one of the original files, or to signal to some process which invoked Emerge a failure code. @@ -1849,7 +1850,7 @@ buffer after this will cause serious problems." "Select the A variant of this difference. Refuses to function if this difference has been edited, i.e., if it is neither the A nor the B variant. -A prefix argument forces the variant to be selected +With prefix argument FORCE, force the variant to be selected even if the difference has been edited." (interactive "P") (let ((operate #'emerge-select-A-edit) @@ -1876,7 +1877,7 @@ even if the difference has been edited." "Select the B variant of this difference. Refuses to function if this difference has been edited, i.e., if it is neither the A nor the B variant. -A prefix argument forces the variant to be selected +With prefix argument FORCE, force the variant to be selected even if the difference has been edited." (interactive "P") (let ((operate #'emerge-select-B-edit) @@ -1973,8 +1974,8 @@ must be prefixed with \\<emerge-fast-keymap>\\[emerge-basic-keymap]." "Toggle Auto-Advance mode, for Emerge. This mode causes `emerge-select-A' and `emerge-select-B' to automatically advance to the next difference. -With a positive argument, turn on Auto-Advance mode. -With a negative argument, turn off Auto-Advance mode." +With a positive argument ARG, turn on Auto-Advance mode. +With a negative argument ARG, turn off Auto-Advance mode." (interactive "P") (setq emerge-auto-advance (if (null arg) (not emerge-auto-advance) @@ -1988,8 +1989,8 @@ With a negative argument, turn off Auto-Advance mode." "Toggle Skip-Prefers mode, for Emerge. This mode causes `emerge-next-difference' and `emerge-previous-difference' to automatically skip over differences for which there is a preference. -With a positive argument, turn on Skip-Prefers mode. -With a negative argument, turn off Skip-Prefers mode." +With a positive argument ARG, turn on Skip-Prefers mode. +With a negative argument ARG, turn off Skip-Prefers mode." (interactive "P") (setq emerge-skip-prefers (if (null arg) (not emerge-skip-prefers) @@ -2028,7 +2029,7 @@ With a negative argument, turn off Skip-Prefers mode." (defun emerge-insert-A (arg) "Insert the A variant of this difference at the point. Leaves point after text, mark before. -With prefix argument, puts point before, mark after." +With prefix argument ARG, puts point before, mark after." (interactive "P") (emerge-validate-difference) (let* ((diff-vector @@ -2046,7 +2047,7 @@ With prefix argument, puts point before, mark after." (defun emerge-insert-B (arg) "Insert the B variant of this difference at the point. Leaves point after text, mark before. -With prefix argument, puts point before, mark after." +With prefix argument ARG, puts point before, mark after." (interactive "P") (emerge-validate-difference) (let* ((diff-vector @@ -2062,8 +2063,8 @@ With prefix argument, puts point before, mark after." (goto-char opoint)))) (defun emerge-mark-difference (arg) - "Leaves the point before this difference and the mark after it. -With prefix argument, puts mark before, point after." + "Leave the point before this difference and the mark after it. +With prefix argument ARG, put mark before, point after." (interactive "P") (emerge-validate-difference) (let* ((diff-vector @@ -2079,7 +2080,7 @@ With prefix argument, puts mark before, point after." (defun emerge-file-names () "Show the names of the buffers or files being operated on by Emerge. -Use C-u l to reset the windows afterward." +Use \\[universal-argument] l to reset the windows afterward." (interactive) (delete-other-windows) (let ((temp-buffer-show-function @@ -2122,7 +2123,7 @@ Use C-u l to reset the windows afterward." (defun emerge-join-differences (arg) "Join the selected difference with the following one. -With a prefix argument, join with the preceding one." +With a prefix argument ARG, join with the preceding one." (interactive "P") (let ((n emerge-current-difference)) ;; adjust n to be first difference to join @@ -2332,9 +2333,9 @@ ancestor version does not share.)" ;; to have it ask for a buffer. (defun emerge-find-difference (arg) "Find the difference containing the current position of the point. -If there is no containing difference and the prefix argument is positive, -it finds the nearest following difference. A negative prefix argument finds -the nearest previous difference." +If there is no containing difference and the prefix argument ARG +is positive, find the nearest following difference. With +negative prefix argument, find the nearest previous difference." (interactive "P") (cond ((eq (current-buffer) emerge-A-buffer) (emerge-find-difference-A arg)) @@ -2344,9 +2345,9 @@ the nearest previous difference." (defun emerge-find-difference-merge (arg) "Find the difference containing point, in the merge buffer. -If there is no containing difference and the prefix argument is positive, -it finds the nearest following difference. A negative prefix argument finds -the nearest previous difference." +If there is no containing difference and the prefix argument ARG +is positive, find the nearest following difference. With +negative prefix argument, find the nearest previous difference." (interactive "P") ;; search for the point in the merge buffer, using the markers ;; for the beginning and end of the differences in the merge buffer @@ -2355,9 +2356,9 @@ the nearest previous difference." (defun emerge-find-difference-A (arg) "Find the difference containing point, in the A buffer. This command must be executed in the merge buffer. -If there is no containing difference and the prefix argument is positive, -it finds the nearest following difference. A negative prefix argument finds -the nearest previous difference." +If there is no containing difference and the prefix argument ARG +is positive, find the nearest following difference. With +negative prefix argument, find the nearest previous difference." (interactive "P") ;; search for the point in the A buffer, using the markers ;; for the beginning and end of the differences in the A buffer @@ -2368,9 +2369,9 @@ the nearest previous difference." (defun emerge-find-difference-B (arg) "Find the difference containing point, in the B buffer. This command must be executed in the merge buffer. -If there is no containing difference and the prefix argument is positive, -it finds the nearest following difference. A negative prefix argument finds -the nearest previous difference." +If there is no containing difference and the prefix argument ARG +is positive, find the nearest following difference. With +negative prefix argument, find the nearest previous difference." (interactive "P") ;; search for the point in the B buffer, using the markers ;; for the beginning and end of the differences in the B buffer @@ -2450,8 +2451,10 @@ merge buffers." (defun emerge-set-combine-template (string &optional localize) "Set `emerge-combine-versions-template' to STRING. This value controls how `emerge-combine-versions' combines the two versions. -With prefix argument, `emerge-combine-versions-template' is made local to this -merge buffer. Localization is permanent for any particular merge buffer." + +With prefix argument LOCALIZE, `emerge-combine-versions-template' +is made local to this merge buffer. Localization is permanent +for any particular merge buffer." (interactive "s\nP") (if localize (make-local-variable 'emerge-combine-versions-template)) @@ -2464,8 +2467,10 @@ merge buffer. Localization is permanent for any particular merge buffer." (defun emerge-set-combine-versions-template (start end &optional localize) "Copy region into `emerge-combine-versions-template'. This controls how `emerge-combine-versions' will combine the two versions. -With prefix argument, `emerge-combine-versions-template' is made local to this -merge buffer. Localization is permanent for any particular merge buffer." + +With prefix argument LOCALIZE, `emerge-combine-versions-template' +is made local to this merge buffer. Localization is permanent +for any particular merge buffer." (interactive "r\nP") (if localize (make-local-variable 'emerge-combine-versions-template)) @@ -2479,8 +2484,9 @@ merge buffer. Localization is permanent for any particular merge buffer." "Combine versions using the template in `emerge-combine-versions-template'. Refuses to function if this difference has been edited, i.e., if it is neither the A nor the B variant. -An argument forces the variant to be selected even if the difference has -been edited." + +With prefix argument FORCE, force the variant to be selected even +if the difference has been edited." (interactive "P") (emerge-combine-versions-internal emerge-combine-versions-template force)) @@ -2490,8 +2496,9 @@ See documentation of the variable `emerge-combine-versions-template' for how the template is interpreted. Refuses to function if this difference has been edited, i.e., if it is neither the A nor the B variant. -An argument forces the variant to be selected even if the difference has -been edited. + +With prefix argument CHAR, force the variant to be selected even +if the difference has been edited. Interactively, reads the register using `register-read-with-preview'." (interactive (list @@ -2539,9 +2546,9 @@ Interactively, reads the register using `register-read-with-preview'." (if emerge-auto-advance (emerge-next-difference)))) (defun emerge-set-merge-mode (mode) - "Set the major mode in a merge buffer. -Overrides any change that the mode might make to the mode line or local -keymap. Leaves merge in fast mode." + "Set the major mode to MODE in a merge buffer. +Override any change that the mode might make to the mode line or +local keymap. Leave merge in fast mode." (interactive (list (intern (completing-read "New major mode for merge buffer: " obarray 'commandp t nil)))) @@ -2678,8 +2685,8 @@ keymap. Leaves merge in fast mode." (emerge-refresh-mode-line)))) (defun emerge-select-version (force a-version b-version neither-version) - "Perform tests to see whether user should be allowed to select a version -of this difference: + "Test if user should be allowed to select a version of this difference. +This is the case if: a valid difference has been selected; and the difference text in the merge buffer is: the A version (execute a-version), or @@ -2847,7 +2854,9 @@ Otherwise, signal an error." ;; When the pointless option emerge-temp-file-prefix goes, ;; make this function obsolete too, and just use make-temp-file. (defun emerge-make-temp-file (prefix) - "Make a private temporary file based on `emerge-temp-file-prefix'." + "Make a private temporary file based on PREFIX. +This is named by concatenating `emerge-temp-file-prefix' with +PREFIX." (make-temp-file (concat emerge-temp-file-prefix prefix))) ;;; Functions that query the user before he can write out the current buffer. @@ -2921,7 +2930,7 @@ around the current difference are removed." ;; Define a key, even if a prefix of it is defined (defun emerge-force-define-key (keymap key definition) - "Like `define-key', but forcibly creates prefix characters as needed. + "Like `define-key', but forcibly create prefix characters as needed. If some prefix of KEY has a non-prefix definition, it is redefined." ;; Find out if a prefix of key is defined (let ((v (lookup-key keymap key))) |