Add a README

README.markdown

@@ -0,0 +1,96 @@
+surround.vim
+============
+
+Surround.vim is all about "surroundings": parentheses, brackets, quotes,
+XML tags, and more.  The plugin provides mappings to easily delete,
+change and add such surroundings in pairs.
+
+It's easiest to explain with examples.  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>
+
+This plugin is very powerful for HTML and XML editing, a niche which
+currently seems underfilled in Vim land.  (As opposed to HTML/XML
+*inserting*, for which many plugins are available).  Adding, changing,
+and removing pairs of tags simultaneously is a breeze.
+
+The `.` command will work with `ds`, `cs`, and `yss` if you install
+[repeat.vim](https://github.com/tpope/vim-repeat).
+
+Installation
+------------
+
+If you don't have a preferred installation method, I recommend
+installing [pathogen.vim](https://github.com/tpope/vim-pathogen), and
+then simply copy and paste:
+
+    cd ~/.vim/bundle
+    git clone git://github.com/tpope/vim-surround.git
+
+Once help tags have been generated, you can view the manual with
+`:help surround`.
+
+Contributing
+------------
+
+See the contribution guidelines for
+[pathogen.vim](https://github.com/tpope/vim-pathogen#readme).
+
+Self-Promotion
+--------------
+
+Like surround.vim? Follow the repository on
+[GitHub](https://github.com/tpope/vim-surround) and vote for it on
+[vim.org](http://www.vim.org/scripts/script.php?script_id=1697).  And if
+you're feeling especially charitable, follow [tpope](http://tpo.pe/) on
+[Twitter](http://twitter.com/tpope) and
+[GitHub](https://github.com/tpope).
+
+License
+-------
+
+Distributable under the same terms as Vim itself.  See `:help license`.