*** empty log message ***
[emacs.git] / lisp / ediff-help.el
blob21fe85c415f017333166c33d1e1a77818297f8ef
1 ;;; ediff-help.el --- Code related to the contents of Ediff help buffers
3 ;; Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
4 ;; 2004, 2005 Free Software Foundation, Inc.
6 ;; Author: Michael Kifer <kifer@cs.stonybrook.edu>
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
13 ;; any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
23 ;; Boston, MA 02110-1301, USA.
25 ;;; Commentary:
27 ;;; Code:
29 (provide 'ediff-help)
31 ;; Compiler pacifier start
32 (defvar ediff-multiframe)
34 (eval-when-compile
35 (let ((load-path (cons (expand-file-name ".") load-path)))
36 (or (featurep 'ediff-init)
37 (load "ediff-init.el" nil nil 'nosuffix))
39 ;; end pacifier
41 (require 'ediff-init)
43 ;; Help messages
45 (defconst ediff-long-help-message-head
46 " Move around | Toggle features | Manipulate
47 =====================|===========================|============================="
48 "The head of the full help message.")
49 (defconst ediff-long-help-message-tail
50 "=====================|===========================|=============================
51 R -show registry | = -compare regions | M -show session group
52 D -diff output | E -browse Ediff manual| G -send bug report
53 i -status info | ? -help off | z/q -suspend/quit
54 -------------------------------------------------------------------------------
55 For help on a specific command: Click Button 2 over it; or
56 Put the cursor over it and type RET."
57 "The tail of the full-help message.")
59 (defconst ediff-long-help-message-compare3
61 p,DEL -previous diff | | -vert/horiz split | xy -copy buf X's region to Y
62 n,SPC -next diff | h -hilighting | rx -restore buf X's old diff
63 j -jump to diff | @ -auto-refinement | * -refine current region
64 gx -goto X's point| | ! -update diff regions
65 C-l -recenter | ## -ignore whitespace |
66 v/V -scroll up/dn | #f/#h -focus/hide regions | wx -save buf X
67 </> -scroll lt/rt | X -read-only in buf X | wd -save diff output
68 ~ -rotate buffers| m -wide display |
70 "Help message usually used for 3-way comparison.
71 Normally, not a user option. See `ediff-help-message' for details.")
73 (defconst ediff-long-help-message-compare2
75 p,DEL -previous diff | | -vert/horiz split |a/b -copy A/B's region to B/A
76 n,SPC -next diff | h -hilighting | rx -restore buf X's old diff
77 j -jump to diff | @ -auto-refinement | * -refine current region
78 gx -goto X's point| | ! -update diff regions
79 C-l -recenter | ## -ignore whitespace |
80 v/V -scroll up/dn | #f/#h -focus/hide regions | wx -save buf X
81 </> -scroll lt/rt | X -read-only in buf X | wd -save diff output
82 ~ -swap variants | m -wide display |
84 "Help message usually used for 2-way comparison.
85 Normally, not a user option. See `ediff-help-message' for details.")
87 (defconst ediff-long-help-message-narrow2
89 p,DEL -previous diff | | -vert/horiz split |a/b -copy A/B's region to B/A
90 n,SPC -next diff | h -hilighting | rx -restore buf X's old diff
91 j -jump to diff | @ -auto-refinement | * -refine current region
92 gx -goto X's point| % -narrow/widen buffs | ! -update diff regions
93 C-l -recenter | ## -ignore whitespace |
94 v/V -scroll up/dn | #f/#h -focus/hide regions | wx -save buf X
95 </> -scroll lt/rt | X -read-only in buf X | wd -save diff output
96 ~ -swap variants | m -wide display |
98 "Help message when comparing windows or regions line-by-line.
99 Normally, not a user option. See `ediff-help-message' for details.")
101 (defconst ediff-long-help-message-word-mode
103 p,DEL -previous diff | | -vert/horiz split | xy -copy buf X's region to Y
104 n,SPC -next diff | h -hilighting | rx -restore buf X's old diff
105 j -jump to diff | |
106 gx -goto X's point| % -narrow/widen buffs | ! -recompute diffs
107 C-l -recenter | |
108 v/V -scroll up/dn | #f/#h -focus/hide regions | wx -save buf X
109 </> -scroll lt/rt | X -read-only in buf X | wd -save diff output
110 ~ -swap variants | m -wide display |
112 "Help message when comparing windows or regions word-by-word.
113 Normally, not a user option. See `ediff-help-message' for details.")
115 (defconst ediff-long-help-message-merge
117 p,DEL -previous diff | | -vert/horiz split | x -copy buf X's region to C
118 n,SPC -next diff | h -hilighting | r -restore buf C's old diff
119 j -jump to diff | @ -auto-refinement | * -refine current region
120 gx -goto X's point| ## -ignore whitespace | ! -update diff regions
121 C-l -recenter | #f/#h -focus/hide regions | + -combine diff regions
122 v/V -scroll up/dn | X -read-only in buf X | wx -save buf X
123 </> -scroll lt/rt | m -wide display | wd -save diff output
124 ~ -swap variants | s -shrink window C | / -show ancestor buff
125 | $$ -show clashes only | & -merge w/new default
126 | $* -skip changed regions |
128 "Help message for merge sessions.
129 Normally, not a user option. See `ediff-help-message' for details.")
131 ;; The actual long help message.
132 (ediff-defvar-local ediff-long-help-message ""
133 "Normally, not a user option. See `ediff-help-message' for details.")
135 (defconst ediff-brief-message-string
136 " Type ? for help"
137 "Contents of the brief help message.")
138 ;; The actual brief help message
139 (ediff-defvar-local ediff-brief-help-message ""
140 "Normally, not a user option. See `ediff-help-message' for details.")
142 (ediff-defvar-local ediff-brief-help-message-function nil
143 "The brief help message that the user can customize.
144 If the user sets this to a parameter-less function, Ediff will use it to
145 produce the brief help message. This function must return a string.")
146 (ediff-defvar-local ediff-long-help-message-function nil
147 "The long help message that the user can customize.
148 See `ediff-brief-help-message-function' for more.")
150 (defcustom ediff-use-long-help-message nil
151 "*If t, Ediff displays a long help message. Short help message otherwise."
152 :type 'boolean
153 :group 'ediff-window)
155 ;; The actual help message.
156 (ediff-defvar-local ediff-help-message ""
157 "The actual help message.
158 Normally, the user shouldn't touch this. However, if you want Ediff to
159 start up with different help messages for different jobs, you can change
160 the value of this variable and the variables `ediff-help-message-*' in
161 `ediff-startup-hook'.")
164 ;; the keymap that defines clicks over the quick help regions
165 (defvar ediff-help-region-map (make-sparse-keymap))
167 (define-key
168 ediff-help-region-map
169 (if ediff-emacs-p [mouse-2] [button2])
170 'ediff-help-for-quick-help)
172 ;; runs in the control buffer
173 (defun ediff-set-help-overlays ()
174 (goto-char (point-min))
175 (let (overl beg end cmd)
176 (while (re-search-forward " *\\([^ \t\n|]+\\||\\) +-[^|\n]+" nil 'noerror)
177 (setq beg (match-beginning 0)
178 end (match-end 0)
179 cmd (buffer-substring (match-beginning 1) (match-end 1)))
180 (setq overl (ediff-make-overlay beg end))
181 (if ediff-emacs-p
182 (ediff-overlay-put overl 'mouse-face 'highlight)
183 (ediff-overlay-put overl 'highlight t))
184 (ediff-overlay-put overl 'ediff-help-info cmd))))
187 (defun ediff-help-for-quick-help ()
188 "Explain Ediff commands in more detail."
189 (interactive)
190 (ediff-barf-if-not-control-buffer)
191 (let ((pos (ediff-event-point last-command-event))
192 overl cmd)
194 (ediff-cond-compile-for-xemacs-or-emacs
195 ;; xemacs
196 (setq overl (extent-at pos (current-buffer) 'ediff-help-info)
197 cmd (ediff-overlay-get overl 'ediff-help-info))
198 ;; emacs
199 (setq cmd (car (mapcar (lambda (elt)
200 (overlay-get elt 'ediff-help-info))
201 (overlays-at pos))))
204 (if (not (stringp cmd))
205 (error "Hmm... I don't see an Ediff command around here..."))
207 (ediff-documentation "Quick Help Commands")
209 (let (case-fold-search)
210 (cond ((string= cmd "?") (re-search-forward "^`\\?'"))
211 ((string= cmd "G") (re-search-forward "^`G'"))
212 ((string= cmd "E") (re-search-forward "^`E'"))
213 ((string= cmd "wd") (re-search-forward "^`wd'"))
214 ((string= cmd "wx") (re-search-forward "^`wa'"))
215 ((string= cmd "a/b") (re-search-forward "^`a'"))
216 ((string= cmd "x") (re-search-forward "^`a'"))
217 ((string= cmd "xy") (re-search-forward "^`ab'"))
218 ((string= cmd "p,DEL") (re-search-forward "^`p'"))
219 ((string= cmd "n,SPC") (re-search-forward "^`n'"))
220 ((string= cmd "j") (re-search-forward "^`j'"))
221 ((string= cmd "gx") (re-search-forward "^`ga'"))
222 ((string= cmd "!") (re-search-forward "^`!'"))
223 ((string= cmd "*") (re-search-forward "^`\\*'"))
224 ((string= cmd "m") (re-search-forward "^`m'"))
225 ((string= cmd "|") (re-search-forward "^`|'"))
226 ((string= cmd "@") (re-search-forward "^`@'"))
227 ((string= cmd "h") (re-search-forward "^`h'"))
228 ((string= cmd "r") (re-search-forward "^`r'"))
229 ((string= cmd "rx") (re-search-forward "^`ra'"))
230 ((string= cmd "##") (re-search-forward "^`##'"))
231 ((string= cmd "#f/#h") (re-search-forward "^`#f'"))
232 ((string= cmd "X") (re-search-forward "^`A'"))
233 ((string= cmd "v/V") (re-search-forward "^`v'"))
234 ((string= cmd "</>") (re-search-forward "^`<'"))
235 ((string= cmd "~") (re-search-forward "^`~'"))
236 ((string= cmd "i") (re-search-forward "^`i'"))
237 ((string= cmd "D") (re-search-forward "^`D'"))
238 ((string= cmd "R") (re-search-forward "^`R'"))
239 ((string= cmd "M") (re-search-forward "^`M'"))
240 ((string= cmd "z/q") (re-search-forward "^`z'"))
241 ((string= cmd "%") (re-search-forward "^`%'"))
242 ((string= cmd "C-l") (re-search-forward "^`C-l'"))
243 ((string= cmd "$$") (re-search-forward "^`\\$\\$'"))
244 ((string= cmd "$*") (re-search-forward "^`\\$\\*'"))
245 ((string= cmd "/") (re-search-forward "^`/'"))
246 ((string= cmd "&") (re-search-forward "^`&'"))
247 ((string= cmd "s") (re-search-forward "^`s'"))
248 ((string= cmd "+") (re-search-forward "^`\\+'"))
249 ((string= cmd "=") (re-search-forward "^`='"))
250 (t (error "Undocumented command! Type `G' in Ediff Control Panel to drop a note to the Ediff maintainer")))
251 ) ; let case-fold-search
255 ;; assuming we are in control window, calculate length of the first line in
256 ;; help message
257 (defun ediff-help-message-line-length ()
258 (save-excursion
259 (goto-char (point-min))
260 (if ediff-use-long-help-message
261 (next-line 1))
262 (end-of-line)
263 (current-column)))
266 (defun ediff-indent-help-message ()
267 (let* ((shift (/ (max 0 (- (window-width (selected-window))
268 (ediff-help-message-line-length)))
270 (str (make-string shift ?\ )))
271 (save-excursion
272 (goto-char (point-min))
273 (while (< (point) (point-max))
274 (insert str)
275 (beginning-of-line)
276 (forward-line 1)))))
279 ;; compose the help message as a string
280 (defun ediff-set-help-message ()
281 (setq ediff-long-help-message
282 (cond ((and ediff-long-help-message-function
283 (or (symbolp ediff-long-help-message-function)
284 (consp ediff-long-help-message-function)))
285 (funcall ediff-long-help-message-function))
286 (ediff-word-mode
287 (concat ediff-long-help-message-head
288 ediff-long-help-message-word-mode
289 ediff-long-help-message-tail))
290 (ediff-narrow-job
291 (concat ediff-long-help-message-head
292 ediff-long-help-message-narrow2
293 ediff-long-help-message-tail))
294 (ediff-merge-job
295 (concat ediff-long-help-message-head
296 ediff-long-help-message-merge
297 ediff-long-help-message-tail))
298 (ediff-diff3-job
299 (concat ediff-long-help-message-head
300 ediff-long-help-message-compare3
301 ediff-long-help-message-tail))
303 (concat ediff-long-help-message-head
304 ediff-long-help-message-compare2
305 ediff-long-help-message-tail))))
306 (setq ediff-brief-help-message
307 (cond ((and ediff-brief-help-message-function
308 (or (symbolp ediff-brief-help-message-function)
309 (consp ediff-brief-help-message-function)))
310 (funcall ediff-brief-help-message-function))
311 ((stringp ediff-brief-help-message-function)
312 ediff-brief-help-message-function)
313 ((ediff-multiframe-setup-p) ediff-brief-message-string)
314 (t ; long brief msg, not multiframe --- put in the middle
315 ediff-brief-message-string)
317 (setq ediff-help-message (if ediff-use-long-help-message
318 ediff-long-help-message
319 ediff-brief-help-message))
320 (run-hooks 'ediff-display-help-hook))
322 ;;;###autoload
323 (defun ediff-customize ()
324 (interactive)
325 (customize-group "ediff"))
328 ;;; arch-tag: 05659813-7fcf-4274-964f-d2f577431a9d
329 ;;; ediff-help.el ends here