[nongnu] elpa/multiple-cursors 294d574 093/434: Update README

[ELPA Syncer]

branch: elpa/multiple-cursors
commit 294d5748620ce6bd8d612e6b5cf339f2c250fc66
Author: Magnar Sveen <magnars@gmail.com>
Commit: Magnar Sveen <magnars@gmail.com>

    Update README
---
 README.md           |  97 +++++++++++++++++++++++++++++-------------
 multiple-cursors.el | 118 ++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 154 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 0acf396..a129a57 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,94 @@
 # multiple-cursors.el
 
-An experiment in multiple cursors for emacs. Still very much in beta.
+Multiple cursors for Emacs. This is some pretty crazy functionality, so yes,
+there are kinks. Don't be afraid tho, I've been using it since 2011 with
+great success and much merriment.
 
-The basic concept works, but there are definitely some kinks to work out.
+## Basic usage
 
-This extension is dependent on the mark-multiple library.
+Start out with:
 
-    https://github.com/magnars/mark-multiple.el
+    (require 'multiple-cursors)
 
-## Usage
+When you have an active region that spans multiple lines, the following will
+add a cursor to each line:
+
+    (global-set-key (kbd "C-S-c C-S-c") 
'mc/add-multiple-cursors-to-region-lines)
+
+When you want to add multiple cursors not based on continuous lines, but based 
on
+keywords in the buffer, use:
+
+    (global-set-key (kbd "C->") 'mc/mark-next-like-this)
+    (global-set-key (kbd "C-<") 'mc/mark-previous-like-this)
+    (global-set-key (kbd "M-<") 'mc/mark-all-like-this)
+
+First mark the word, then add more cursors.
+
+
+## More commands to play around with
 
 I've set up my key-bindings like so:
 
-    ;; Experimental multiple-cursors
+    ;; From active region to multiple cursors:
     (global-set-key (kbd "C-S-c C-S-c") 
'mc/add-multiple-cursors-to-region-lines)
     (global-set-key (kbd "C-S-c C-e") 'mc/edit-ends-of-lines)
     (global-set-key (kbd "C-S-c C-a") 'mc/edit-beginnings-of-lines)
 
-To get out of multiple-cursors-mode, press `C-g`.
+When you have an active region that spans multiple lines, the preceeding three
+commands will add one cursor to each line.
 
-You can also switch to multiple-cursors-mode by pressing C-g when in
-mark-multiple-mode. This is symmetrical to how pressing C-g with an active
-region deactivates it. Press C-g again to remove extra cursors.
+    ;; Rectangular region mode
+    (global-set-key (kbd "H-SPC") 'set-rectangular-region-anchor)
 
-## Combining with mark-multiple
+Think of this one as `set-mark` except you're marking a rectangular region. It 
is
+an exceedingly quick way of adding multiple cursors to multiple lines.
 
-Right now you can go from multiple marks to multiple cursors with C-g.
+    ;; Mark more like this
+    (global-set-key (kbd "M-æ") 'mc/mark-all-like-this)
+    (global-set-key (kbd "C-å") 'mc/mark-previous-like-this)
+    (global-set-key (kbd "C-æ") 'mc/mark-next-like-this)
+    (global-set-key (kbd "C-Æ") 'mc/mark-more-like-this-extended)
+    (global-set-key (kbd "M-å") 'mc/mark-all-in-region)
 
-The other way around is a bit more tricky:
+Okay, yes, I have a crazy norwegian keyboard. Regardless, these will look at
+whatever you've got selected at the moment, and mark more places like that in
+the buffer.
 
- * What to do about overlapping marks?
- * Expanding the marks should be possible, for instance using `mark-word` or
-   `expand-region`
- * Killing or copying needs to keep a kill-ring for each cursor.
+To get out of multiple-cursors-mode, press `<return>` or `C-g`. The latter will
+first disable multiple regions before disabling multiple cursors. If you want 
to
+insert a newline in multiple-cursors-mode, use `C-j`.
 
-So basically `mark-multiple` isn't ready for prime time as a full blown 
multiple
-marks library. For this to work as expected, I think parts of mark-multiple
-needs to be rewritten, and possibly integrated into multiple-cursors.
+BTW, I highly recommend adding `mc/mark-next-like-this` to a key binding that's
+right next to the key for `er/expand-region`.
 
-For now, mark-multiple is an excellent tool to place your cursors where you 
need
-them to be.
 
-## Contribute
+## Unknown commands
 
-There's plenty wrong with this implementation still. I'm actively trying things
-out, and also working on combining it with
-[mark-multiple.el](https://github.com/magnars/mark-multiple.el) to get a more
-comprehensive tool.
+Multiple-cursors uses two lists of commands to know what to do: the run-once 
list
+and the run-for-all list. It comes with a set of defaults, but it would be 
beyond silly
+to try and include them all.
+
+So that's why multiple-cursors occasionally asks what to do about a command. 
It will
+then remember your choice by saving it in `~/.emacs.d/.mc-lists.el`. You can 
change
+the location with:
+
+    (setq mc/list-file "/my/preferred/file")
+
+
+## Known limitations
+
+* isearch-forward and isearch-backward aren't supported with multiple cursors.
+  You should feel free to add a simplified version that can work with it.
+* Commands run with `M-x` won't be repeated for all cursors.
+* All key bindings that refer to lambdas are always run for all cursors. If you
+  need to limit it, you will have to give it a name.
+* Redo might screw with your cursors. Undo works very well.
+
+
+## Contribute
 
-Still, if you've got something to contribute, please do not hesitate to open
-an issue, and we can take a look together before you dive into the elisp. :-)
+Yes, please do. There's a suite of tests, so remember to add tests for your
+specific feature, or I might break it later.
 
 You'll find the repo at:
 
diff --git a/multiple-cursors.el b/multiple-cursors.el
index ef09102..4714003 100644
--- a/multiple-cursors.el
+++ b/multiple-cursors.el
@@ -20,55 +20,109 @@
 
 ;;; Commentary:
 
-;; An experiment in multiple cursors for emacs. Still very much in beta.
+;; Multiple cursors for Emacs. This is some pretty crazy functionality, so yes,
+;; there are kinks. Don't be afraid tho, I've been using it since 2011 with
+;; great success and much merriment.
+;;
+;; ## Basic usage
+;;
+;; Start out with:
+;;
+;;     (require 'multiple-cursors)
+;;
+;; When you have an active region that spans multiple lines, the following will
+;; add a cursor to each line:
+;;
+;;     (global-set-key (kbd "C-S-c C-S-c") 
'mc/add-multiple-cursors-to-region-lines)
+;;
+;; When you want to add multiple cursors not based on continuous lines, but 
based on
+;; keywords in the buffer, use:
+;;
+;;     (global-set-key (kbd "C->") 'mc/mark-next-like-this)
+;;     (global-set-key (kbd "C-<") 'mc/mark-previous-like-this)
+;;     (global-set-key (kbd "M-<") 'mc/mark-all-like-this)
+;;
+;; First mark the word, then add more cursors.
+;;
+;;
+;; ## More commands to play around with
 ;;
-;; The basic concept works, but there are definitely some kinks to work out.
-
-;; This extension is dependent on the mark-multiple library.
-;;     https://github.com/magnars/mark-multiple.el
-
-;; ** Usage
-
 ;; I've set up my key-bindings like so:
 ;;
-;;     ;; Experimental multiple-cursors
+;;     ;; From active region to multiple cursors:
 ;;     (global-set-key (kbd "C-S-c C-S-c") 
'mc/add-multiple-cursors-to-region-lines)
 ;;     (global-set-key (kbd "C-S-c C-e") 'mc/edit-ends-of-lines)
 ;;     (global-set-key (kbd "C-S-c C-a") 'mc/edit-beginnings-of-lines)
 ;;
-;; To get out of multiple-cursors-mode, press `C-g`.
-
-;; ** Contribute
-
-;; There's plenty wrong with this implementation still. I'm actively trying 
things
-;; out, and also working on combining it with
-;; [mark-multiple.el](https://github.com/magnars/mark-multiple.el) to get a 
more
-;; comprehensive tool.
+;; When you have an active region that spans multiple lines, the preceeding 
three
+;; commands will add one cursor to each line.
+;;
+;;     ;; Rectangular region mode
+;;     (global-set-key (kbd "H-SPC") 'set-rectangular-region-anchor)
 ;;
-;; Still, if you've got something to contribute, please do not hesitate to open
-;; an issue, and we can take a look together before you dive into the elisp. 
:-)
+;; Think of this one as `set-mark` except you're marking a rectangular region. 
It is
+;; an exceedingly quick way of adding multiple cursors to multiple lines.
+;;
+;;     ;; Mark more like this
+;;     (global-set-key (kbd "M-æ") 'mc/mark-all-like-this)
+;;     (global-set-key (kbd "C-å") 'mc/mark-previous-like-this)
+;;     (global-set-key (kbd "C-æ") 'mc/mark-next-like-this)
+;;     (global-set-key (kbd "C-Æ") 'mc/mark-more-like-this-extended)
+;;     (global-set-key (kbd "M-å") 'mc/mark-all-in-region)
+;;
+;; Okay, yes, I have a crazy norwegian keyboard. Regardless, these will look at
+;; whatever you've got selected at the moment, and mark more places like that 
in
+;; the buffer.
+;;
+;; To get out of multiple-cursors-mode, press `<return>` or `C-g`. The latter 
will
+;; first disable multiple regions before disabling multiple cursors. If you 
want to
+;; insert a newline in multiple-cursors-mode, use `C-j`.
+;;
+;; BTW, I highly recommend adding `mc/mark-next-like-this` to a key binding 
that's
+;; right next to the key for `er/expand-region`.
+;;
+;;
+;; ## Unknown commands
+;;
+;; Multiple-cursors uses two lists of commands to know what to do: the 
run-once list
+;; and the run-for-all list. It comes with a set of defaults, but it would be 
beyond silly
+;; to try and include them all.
+;;
+;; So that's why multiple-cursors occasionally asks what to do about a 
command. It will
+;; then remember your choice by saving it in `~/.emacs.d/.mc-lists.el`. You 
can change
+;; the location with:
+;;
+;;     (setq mc/list-file "/my/preferred/file")
+;;
+;;
+;; ## Known limitations
+;;
+;; * isearch-forward and isearch-backward aren't supported with multiple 
cursors.
+;;   You should feel free to add a simplified version that can work with it.
+;; * Commands run with `M-x` won't be repeated for all cursors.
+;; * All key bindings that refer to lambdas are always run for all cursors. If 
you
+;;   need to limit it, you will have to give it a name.
+;; * Redo might screw with your cursors. Undo works very well.
+;;
+;;
+;; ## Contribute
+;;
+;; Yes, please do. There's a suite of tests, so remember to add tests for your
+;; specific feature, or I might break it later.
 ;;
 ;; You'll find the repo at:
 ;;
 ;;     https://github.com/magnars/multiple-cursors.el
-
-;; ## Combining with mark-multiple
 ;;
-;; Right now you can go from multiple marks to multiple cursors with C-g.
+;; To fetch the test dependencies:
 ;;
-;; The other way around is a bit more tricky:
+;;     $ cd /path/to/multiple-cursors
+;;     $ git submodule update --init
 ;;
-;;  * What to do about overlapping marks?
-;;  * Expanding the marks should be possible, for instance using `mark-word` or
-;;    `expand-region`
-;;  * Killing or copying needs to keep a kill-ring for each cursor.
+;; Run the tests with:
 ;;
-;; So basically `mark-multiple` isn't ready for prime time as a full blown 
multiple
-;; marks library. For this to work as expected, I think parts of mark-multiple
-;; needs to be rewritten, and possibly integrated into multiple-cursors.
+;;     $ ./util/ecukes/ecukes --graphical
 ;;
-;; For now, mark-multiple is an excellent tool to place your cursors where you 
need
-;; them to be.
 
 ;;; Code: