Skip to content

Update README to clarify some points for Vim beginners. #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
namick wants to merge 2 commits into from
Closed

Update README to clarify some points for Vim beginners. #50

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
50d950c
Update README to clarify some points for Vim beginners.
namick Feb 21, 2012
55653f6
Implement suggested changes to readme
namick Mar 5, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 56 additions & 22 deletions README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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'<q>` to change it to
Surround.vim may be easiest to explain by taking a look at a few examples.

<q>Hello world!</q>
### 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

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be better to avoid saying “select” here since that might make the user think of Vim’s visual or select modes.

Maybe just delete the phrase “select the word and”.

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed.

it brackets by typing: `ysiw]`. (`iw` or "inner word" is one of Vim's

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this needs a “with” between “it” and “brackets” so that it reads

… surround it with brackets by typing …

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right you are, sir. :-)

[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

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

y does not refer to “yank” here. The vim-surround maps ys to one of its commands. It will only ever mean “yank” if you wait too long (more than one second) before typing the following s (depending on the settings of timeout, ttimeout, timeoutlen, and ttimeoutlen).

The documentation suggests “you surround” as a mnemonic for ys.

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. Yes, actually that one second timeout was tripping me up for a while before I figured out what was happening. Thanks for the clarification here.

I also changed the wording in a few places to read more like that mnemonic.

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"`

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may want to use ds)ds{yss" here instead (delete the parentheses before the curly braces) because if the user does not move the cursor after the previous yss), it will be on the opening parenthesis and ds{ will not work.

Or, advise the user to first move the cursor back onto (or inside) the curly braces before doing the sequence starting with ds{.

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, it makes sense to do the brackets before the parentheses. I also separated the three commands so it looks less like gibberish to a beginner.


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 `<q>` tag. Type `cs'<q`, hit enter,

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Lets” should have an apostrophe.

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

Also, I just realized I had cs'<q instead of cs"<q, also fixed.

and the text instantly becomes:

<q>Hello world!</q>

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,

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The t used in the cst" on the next line does not refer Vim’s built-in “till” command, it refers to vim-surround’s tag surround target (see :help surround-targets).

Maybe something like this:

just use t to refer to the immediately surrounding tag pair. So, to go full circle,

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, yes, that is better. Updated.

press `cst"` to change the `<q>` tags to quotation marks `"`:

"Hello world!"

Emphasize hello: `ysiw<em>`
Emphasize hello: `ysiw<em`

@ChrisJohnsen ChrisJohnsen Mar 4, 2012

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After the previous cst", the cursor will be on the opening double quote. The user will need to move the cursor to the word “Hello” to surround it with an EM tag (otherwise the “inner word” will be just the opening double quote).

Also, the double quotes have disappeared in the following examples. Did you intend to keep them in there, or do you want to add a ds" before doing the EM tag surround?

@namick namick Mar 5, 2012

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right. I fixed this by changing the cst" to dst. This simplifies the step and avoids the subsequent vanishing quotes problem. :-)


<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">`.
visual mode) followed by `S<p class="important"`.

<p class="important">
<em>Hello</em> world!
</p>

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
Expand Down