From 50d950c805921fdae71bd93e65c6ebdfb677886e Mon Sep 17 00:00:00 2001 From: nathan amick Date: Tue, 21 Feb 2012 15:29:22 -0600 Subject: [PATCH 1/2] Update README to clarify some points for Vim beginners. Make surround.vim more approachable to newer or less knowledgeable Vim users while at the same retaining a README that is not too verbose. - Break examples up into a few sections - Add headers to label these sections - Assume less about skill level of the reader --- README.markdown | 78 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 56 insertions(+), 22 deletions(-) diff --git a/README.markdown b/README.markdown index fef61a8..7c7eee6 100644 --- a/README.markdown +++ b/README.markdown @@ -1,57 +1,91 @@ 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. +Surround.vim is a Vim plugin that 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 +How to Use +---------- - "Hello world!" - -to change it to - - 'Hello world!' - -Now press `cs'` to change it to +Surround.vim may be easiest to explain by taking a look at a few examples. - Hello world! +### Single character surroundings -To go full circle, press `cst"` to get +Lets change a set of double quotes to single quotes. Surround.vim makes this +simple with four key strokes. Start with this bit of text: "Hello world!" -To remove the delimiters entirely, press `ds"`. +Move your cursor so that it is within the double quotes. Now type the letter +`c` (change), the letter `s` (surround), the double quote `"`, and then the +single qoute `'`. The double quotes instantly become single quotes. + + 'Hello world!' + +To remove the delimiters entirely, type `d` (delete), `s` (surround), and the +single quote `'`, all together like this: `ds'`. Hello world! -Now with the cursor on "Hello", press `ysiw]` (`iw` is a text object). +#### Surround a text object + +Now with the cursor on the word "Hello", select the word and surround +it brackets by typing: `ysiw]`. (`iw` or "inner word" is one of Vim's +[text objects](http://vimdoc.sourceforge.net/htmldoc/motion.html#object-select), +`y` is copy or "yank", but in this case is being used to select the text object +without changing it.) [Hello] world! + +This works with other text objects like sentences `is` and paragraphs `ip`. + +#### Space or no space -Let's make that braces and add some space (use `}` instead of `{` for no -space): `cs]{` +For pairs of surrounds, use the beginning character `[` to surround +with some space. Use the ending `]` to surround tightly without space. + +Let's change the brackets to braces and add some space. Type: `cs]{`. { Hello } world! -Now wrap the entire line in parentheses with `yssb` or `yss)`. +Now wrap the entire line in parentheses without space. Type: `yss)`. ({ Hello } world!) -Revert to the original text: `ds{ds)` +Revert to the original text with quotes: `ds{ds)yss"` - Hello world! + "Hello world!" + +### Tag surroundings + +HTML and XML tag surroundings are triggered with the `<` character, after +which you can type the whole tag and attributes. + +Lets change the quotes to the html `` tag. Type `cs'Hello world! + +When dealing with existing HTML or XML tags, we don't have to type +out the whole tag, just use the `t` (till). So, to go full circle, +press `cst"` to change the `` tags to quotation marks `"`: + + "Hello world!" -Emphasize hello: `ysiw` +Emphasize hello: `ysiwHello world! Finally, let's try out visual mode. Press a capital V (for linewise -visual mode) followed by `S

`. +visual mode) followed by `S

Hello world!

+ +Notes +----- This plugin is very powerful for HTML and XML editing, a niche which currently seems underfilled in Vim land. (As opposed to HTML/XML From 55653f69b5e26dfbc318735e7ce2643d3d468af5 Mon Sep 17 00:00:00 2001 From: nathan amick Date: Mon, 5 Mar 2012 14:58:00 +0000 Subject: [PATCH 2/2] Implement suggested changes to readme --- README.markdown | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/README.markdown b/README.markdown index 7c7eee6..9ea1f8a 100644 --- a/README.markdown +++ b/README.markdown @@ -30,11 +30,10 @@ single quote `'`, all together like this: `ds'`. #### Surround a text object -Now with the cursor on the word "Hello", select the word and surround -it brackets by typing: `ysiw]`. (`iw` or "inner word" is one of Vim's +Now with the cursor on the word "Hello", you surround it with brackets +by typing: `ysiw]`. (`iw` or "inner word" is one of Vim's [text objects](http://vimdoc.sourceforge.net/htmldoc/motion.html#object-select), -`y` is copy or "yank", but in this case is being used to select the text object -without changing it.) +you might think, "_you surround inner word_".) [Hello] world! @@ -53,7 +52,7 @@ Now wrap the entire line in parentheses without space. Type: `yss)`. ({ Hello } world!) -Revert to the original text with quotes: `ds{ds)yss"` +Revert to the original text with quotes: `ds)` `ds{` `yss"` "Hello world!" @@ -62,23 +61,23 @@ Revert to the original text with quotes: `ds{ds)yss"` HTML and XML tag surroundings are triggered with the `<` character, after which you can type the whole tag and attributes. -Lets change the quotes to the html `` tag. Type `cs'` tag. Type `cs"`, and the +text instantly becomes: Hello world! -When dealing with existing HTML or XML tags, we don't have to type -out the whole tag, just use the `t` (till). So, to go full circle, -press `cst"` to change the `` tags to quotation marks `"`: +When dealing with existing HTML or XML tags, you don't have to type +out the whole tag, just use `t` to refer to the immediately surrounding tag +pair. So, to _delete surrounding tags_ type: `dst` - "Hello world!" + Hello world! -Emphasize hello: `ysiw` Hello world! Finally, let's try out visual mode. Press a capital V (for linewise -visual mode) followed by `S

`.

Hello world!