lisp/vc/ediff-help.el

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