code.delx.au - gnu-emacs-elpa/blob - packages/avy/README.md

   1 ## Introduction
   2
   3 `avy` is a GNU Emacs package for jumping to visible text using a char-based decision tree.  See also [ace-jump-mode](https://github.com/winterTTr/ace-jump-mode) and [vim-easymotion](https://github.com/Lokaltog/vim-easymotion) - `avy` uses the same idea.
   4
   5 ![logo](https://raw.githubusercontent.com/wiki/abo-abo/avy/images/avy-avatar-1.png)
   6
   7 ## Command overview
   8
   9 You can bind some of these useful commands in your config.
  10
  11 ### `avy-goto-char`
  12
  13 > Input one char, jump to it with a tree.
  14
  15 ```elisp
  16 (global-set-key (kbd "C-:") 'avy-goto-char)
  17 ```
  18
  19 After <kbd>C-: b</kbd>:
  20
  21 ![avy-goto-char](https://raw.githubusercontent.com/wiki/nloyola/avy/images/avy-goto-char.png)
  22
  23 ### `avy-goto-char-2`
  24
  25 > Input two consecutive chars, jump to the first one with a tree.
  26
  27 The advantage over the previous one is less candidates for the tree search. And it's not too inconvenient to enter two consecutive chars instead of one.
  28
  29 ```elisp
  30 (global-set-key (kbd "C-'") 'avy-goto-char-2)
  31 ```
  32
  33 After <kbd>C-' bu</kbd>:
  34
  35 ![avy-goto-char-2](http://oremacs.com/download/avi-goto-char-2.png)
  36
  37 ### `avy-goto-line`
  38
  39 > Input zero chars, jump to a line start with a tree.
  40
  41 ```elisp
  42 (global-set-key (kbd "M-g f") 'avy-goto-line)
  43 ```
  44
  45 After <kbd>M-g f</kbd>:
  46
  47 ![avy-goto-line](http://oremacs.com/download/avi-goto-line.png)
  48
  49 You can actually replace the <kbd>M-g g</kbd> binding of `goto-line`, since if you enter a digit for `avy-goto-line`, it will switch to `goto-line` with that digit already entered.
  50
  51 ### `avy-goto-word-1`
  52
  53 > Input one char at word start, jump to a word start with a tree.
  54
  55 ```elisp
  56 (global-set-key (kbd "M-g w") 'avy-goto-word-1)
  57 ```
  58
  59 After <kbd>M-g wb</kbd>:
  60
  61 ![avy-goto-word-1](http://oremacs.com/download/avi-goto-word-1.png)
  62
  63 ### `avy-goto-word-0`
  64
  65 > Input zero chars, jump to a word start with a tree.
  66
  67 Compared to `avy-goto-word-1`, there are a lot more candidates. But at a least there's not need to input the initial char.
  68
  69 ```elisp
  70 (global-set-key (kbd "M-g e") 'avy-goto-word-0)
  71 ```
  72
  73 After <kbd>M-g e</kbd>:
  74
  75 ![avy-goto-word-0](http://oremacs.com/download/avi-goto-word-0.png)
  76
  77
  78 ### Other commands
  79
  80 There are some more commands which you can explore yourself by looking at the code.
  81
  82 ### Bindings
  83
  84 You add this to your config to bind some stuff:
  85
  86 ```elisp
  87 (avy-setup-default)
  88 ```
  89
  90 It will bind, for example, `avy-isearch` to <kbd>C-'</kbd> in `isearch-mode-map`, so that you can select one of the currently visible `isearch` candidates using `avy`.
  91
  92 ### Customization
  93
  94 See the comprehensive custom variable list on [the defcustom wiki page](https://github.com/abo-abo/avy/wiki/defcustom).
  95
  96 See how to write your own avy commands on [the custom-commands wiki page](https://github.com/abo-abo/avy/wiki/custom-commands).
  97
  98 ## Contributing
  99
 100 ### Copyright Assignment
 101
 102 Avy is subject to the same [copyright assignment](http://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html) policy as Emacs itself, org-mode, CEDET and other packages in [GNU ELPA](http://elpa.gnu.org/packages/). Any [legally significant](http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant) contributions can only be accepted after the author has completed their paperwork. Please see [the request form](http://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future) if you want to proceed.
 103
 104 The copyright assignment isn't a big deal, it just says that the copyright for your submitted changes to Emacs belongs to the FSF. This assignment works for all projects related to Emacs. To obtain it, you need to send one email, then send one letter (if you live in the US, it's digital), and wait for some time (in my case, I had to wait for one month).
 105
 106 ### Style
 107
 108 The basic code style guide is to use `(setq indent-tabs-mode nil)`. It is provided for you in [.dir-locals.el](https://github.com/abo-abo/avy/blob/master/.dir-locals.el), please obey it.
 109
 110 Before submitting the change, run `make compile` and `make test` to make sure that it doesn't introduce new compile warnings or test failures. Also run <kbd>M-x</kbd> `checkdoc` to see that your changes obey the documentation guidelines.
 111
 112 Use your own judgment for the commit messages, I recommend a verbose style using `magit-commit-add-log`.