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