lisp/ediff-help.el

   1 ;;; ediff-help.el --- Code related to the contents of Ediff help buffers
   2
   3 ;; Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
   4 ;;   2004, 2005, 2006 Free Software Foundation, Inc.
   5
   6 ;; Author: Michael Kifer <kifer@cs.stonybrook.edu>
   7
   8 ;; This file is part of GNU Emacs.
   9
  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.
  14
  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.
  19
  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.
  24
  25 ;;; Commentary:
  26
  27 ;;; Code:
  28
  29 (provide 'ediff-help)
  30
  31 ;; Compiler pacifier start
  32 (defvar ediff-multiframe)
  33
  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))
  38     ))
  39 ;; end pacifier
  40
  41 (require 'ediff-init)
  42
  43 ;; Help messages
  44
  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.")
  58
  59 (defconst ediff-long-help-message-compare3
  60   "
  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       |
  69 "
  70   "Help message usually used for 3-way comparison.
  71 Normally, not a user option.  See `ediff-help-message' for details.")
  72
  73 (defconst ediff-long-help-message-compare2
  74   "
  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       |
  83 "
  84   "Help message usually used for 2-way comparison.
  85 Normally, not a user option.  See `ediff-help-message' for details.")
  86
  87 (defconst ediff-long-help-message-narrow2
  88   "
  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       |
  97 "
  98   "Help message when comparing windows or regions line-by-line.
  99 Normally, not a user option.  See `ediff-help-message' for details.")
 100
 101 (defconst ediff-long-help-message-word-mode
 102   "
 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       |
 111 "
 112   "Help message when comparing windows or regions word-by-word.
 113 Normally, not a user option.  See `ediff-help-message' for details.")
 114
 115 (defconst ediff-long-help-message-merge
 116   "
 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 |
 127 "
 128   "Help message for merge sessions.
 129 Normally, not a user option.  See `ediff-help-message' for details.")
 130
 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.")
 134
 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.")
 141
 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.")
 149
 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)
 154
 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'.")
 162
 163
 164 ;; the keymap that defines clicks over the quick help regions
 165 (defvar ediff-help-region-map (make-sparse-keymap))
 166
 167 (define-key
 168   ediff-help-region-map
 169   (if ediff-emacs-p [mouse-2] [button2])
 170   'ediff-help-for-quick-help)
 171
 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))))
 185
 186
 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)
 193
 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))))
 202      )
 203
 204     (if (not (stringp cmd))
 205         (error "Hmm...  I don't see an Ediff command around here..."))
 206
 207     (ediff-documentation "Quick Help Commands")
 208
 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
 252     ))
 253
 254
 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)))
 264
 265
 266 (defun ediff-indent-help-message ()
 267   (let* ((shift (/ (max 0 (- (window-width (selected-window))
 268                              (ediff-help-message-line-length)))
 269                    2))
 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)))))
 277
 278
 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))
 302               (t
 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)
 316               ))
 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))
 321
 322 ;;;###autoload
 323 (defun ediff-customize ()
 324   (interactive)
 325   (customize-group "ediff"))
 326
 327
 328 ;;; arch-tag: 05659813-7fcf-4274-964f-d2f577431a9d
 329 ;;; ediff-help.el ends here