Update README to clarify some points for Vim beginners.

[namick]

Hi Tim, thanks for all your work with Vim and Ruby!

As I continue down the road toward Vim understanding I sometimes need to teach something to really understand it myself. I decided to update the README here as an exercise to understand what can be done with Vim better. If you do decide to pull this commit, please double check that my changes are actually accurate.

From the commit:

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

[tpope]

Any reason you deleted the trailing > from the HTML examples?

Other than that, this looks solid!

[namick]

No reason other than it seems to work fine without the trailing > and it's one less keystroke. Is there a case where it would be necessarily to type it?

[ChrisJohnsen]

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]

I see, yes, that is better. Updated.

[ChrisJohnsen]

@namick It seems like the same number of keystrokes either way. Both > and Enter will end the prompted input and invoke the wrapping (there is no need to type an additional Enter after the >). This is documented in doc/surround.txt in the paragraph beginning “If t or < is used” (e.g. see line 131 in efc017 (current master)).

If you want to go with Enter instead of >, then probably all the example tag surround replacements should explicitly mention having to type Enter.

Overall, it seems simpler to just keep the > in the examples. It is less bulky than having to write “and then press Enter”, and it probably feels “more natural” if users think of just typing in the opening tag (if you were typing an opening tag hand, you would use naturally type >, not Enter to close the tag). Also, (in my opinion) using > makes the examples look a bit nicer since the keys you type look just like the tag that ends up being used.

[ChrisJohnsen]

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]

Indeed.

[tpope]

@ChrisJohnsen thanks for this. I only skimmed.

[tpope]

@namick either > or <CR> is most definitely required.

[namick]

@tpope for some reason I didn't get that the ending > removed the need to hit enter. I agree it is better to type > as it is easier to read.

[namick]

@ChrisJohnsen thanks for all your help with this. I implemented your suggestions. Let me know if you notice anything else.

Also, thanks for alerting me to the surround.txt file. Here I am editing documentation without first reading the real documentation. :-)

[corneliusroemer]

Since I don't seem to be the only one who didn't find the proper documentation in doc/surround.txt I suggest this be made clear in the readme through a link as suggested in #322