1 files changed, 153 insertions, 0 deletions
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..bd33cde
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,153 @@
+# Overview
+
+This package emulates [surround.vim by Tim Pope](https://github.com/tpope/vim-surround).
+The functionality is wrapped into a minor mode.
+To enable it globally, add the following lines to ~/.emacs:
+
+    (require 'evil-surround)
+    (global-evil-surround-mode 1)
+
+Alternatively, you can enable surround-mode along a major mode by adding
+`turn-on-surround-mode' to the mode hook.
+
+This package uses [Evil](https://bitbucket.org/lyro/evil/) as its vi layer.
+
+## Add surrounding ##
+You can surround in visual-state with `S<textobject>` or `gS<textobject>`.
+or in normal-state with `ys<textobject>` or `yS<textobject>`.
+
+## Change surrounding ##
+You can change a surrounding with `cs<old-textobject><new-textobject>`.
+
+## Delete surrounding ##
+You can delete a surrounding with `ds<textobject>`.
+
+## Add new surround pairs ##
+A surround pair is this (trigger char with textual left and right strings):
+
+    (?> . ("<" . ">"))
+
+or this (trigger char and calling a function):
+
+    (?< . surround-read-tag)
+
+You can add new by adding them to `evil-surround-pairs-alist`.
+For more information do: `C-h v evil-surround-pairs-alist`.
+
+`evil-surround-pairs-alist` is a buffer local variable, which means that you can have
+different surround pairs in different modes.
+By default `<` is used to insert a tag, in C++ this may not be useful - but
+inserting angle brackets is, so you can add this:
+
+    (add-hook 'c++-mode-hook (lambda ()
+                               (push '(?< . ("< " . " >")) evil-surround-pairs-alist)))
+
+Don't worry about having two entries for `<` surround will take the first.
+
+Or in Emacs Lisp modes using \` to enter \` ' is quite useful, but not adding a
+pair of \` (the default behavior if no entry in `evil-surround-pairs-alist` is
+present), so you can do this:
+
+    (add-hook 'emacs-lisp-mode-hook (lambda ()
+                                      (push '(?` . ("`" . "'")) evil-surround-pairs-alist)))
+
+without affecting your Markdown surround pairs, where the default is useful.
+
+To change the default `evil-surround-pairs-alist` you have to use `setq-default`, for
+example to remove all default pairs:
+
+    (setq-default evil-surround-pairs-alist '())
+
+or to add a pair that surrounds with two ` if you enter ~:
+
+    (setq-default evil-surround-pairs-alist (cons '(?~ . ("``" . "``"))
+                                             evil-surround-pairs-alist))
+
+## Add new supported operators ##
+You can add support for new operators by adding them to `evil-surround-operator-alist`.
+For more information do: `C-h v evil-surround-operator-alist`.
+
+By default, surround works with `evil-change` and `evil-delete`.
+To add support for the evil-paredit package, you need to add `evil-paredit-change`
+and `evil-paredit-delete` to `evil-surround-operator-alist`, like so:
+
+    (add-to-list 'evil-surround-operator-alist
+                 '(evil-paredit-change . change))
+    (add-to-list 'evil-surround-operator-alist
+                 '(evil-paredit-delete . delete))
+
+## Usage examples ##
+
+Here are some usage examples (taken from
+[surround.vim](https://github.com/tpope/vim-surround/blob/master/README.markdown)):
+
+Press `cs"'` inside
+
+    "Hello world!"
+
+to change it to
+
+    'Hello world!'
+
+Now press `cs'<q>` to change it to
+
+    <q>Hello world!</q>
+
+To go full circle, press `cst"` to get
+
+    "Hello world!"
+
+To remove the delimiters entirely, press `ds"`.
+
+    Hello world!
+
+Now with the cursor on "Hello", press `ysiw]` (`iw` is a text object).
+
+    [Hello] world!
+
+Let's make that braces and add some space (use `}` instead of `{` for no
+space): `cs]{`
+
+    { Hello } world!
+
+Now wrap the entire line in parentheses with `yssb` or `yss)`.
+
+    ({ Hello } world!)
+
+Revert to the original text: `ds{ds)`
+
+    Hello world!
+
+Emphasize hello: `ysiw<em>`
+
+    <em>Hello</em> world!
+
+Finally, let's try out visual mode. Press a capital V (for linewise
+visual mode) followed by `S<p class="important">`.
+
+    <p class="important">
+      <em>Hello</em> world!
+    </p>
+
+Suppose you want to call a function on your visual selection or a text
+object. You can simply press `f` instead of the aforementioned keys
+and are then prompted for a functionname in the minibuffer, like with
+the tags. So with:
+
+	"Hello world!"
+
+... after selecting the string, then pressing `Sf`, entering `print`
+and pressing return you would get
+
+    print("Hello world!")
+
+# FAAQ (frequently actually asked questions)
+
+## Why does `vs` no longer surround?
+
+This is due to an upstream change in `vim-surround`. It happened in this commit: https://github.com/tpope/vim-surround/commit/6f0984a. See the discussion in this pull request for more details: https://github.com/timcharper/evil-surround/pull/48.
+
+LICENSE
+---------
+
+[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)