Permalink
Browse files

Merge commit '096bf5e5b59ac61e4e6e9f65782c003e4e487a3f' as '.vim/bund…

…le/surround'
  • Loading branch information...
2 parents 5ca34b4 + 096bf5e commit bc034c8a2454e1b7aa6e75f0033a9608eaddfc14 @jvoorhis committed Dec 13, 2012
@@ -0,0 +1 @@
+/doc/tags
@@ -0,0 +1,97 @@
+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
+-------
+
+Copyright (c) Tim Pope. Distributed under the same terms as Vim itself.
+See `:help license`.
@@ -0,0 +1,211 @@
+*surround.txt* Plugin for deleting, changing, and adding "surroundings"
+
+Author: Tim Pope <http://tpo.pe/>
+License: Same terms as Vim itself (see |license|)
+
+This plugin is only available if 'compatible' is not set.
+
+INTRODUCTION *surround*
+
+This plugin is a tool for dealing with pairs of "surroundings." Examples
+of surroundings include parentheses, quotes, and HTML tags. They are
+closely related to what Vim refers to as |text-objects|. Provided
+are mappings to allow for removing, changing, and adding surroundings.
+
+Details follow on the exact semantics, but first, consider the following
+examples. An asterisk (*) is used to denote the cursor position.
+
+ Old text Command New text ~
+ "Hello *world!" ds" Hello world!
+ [123+4*56]/2 cs]) (123+456)/2
+ "Look ma, I'm *HTML!" cs"<q> <q>Look ma, I'm HTML!</q>
+ if *x>3 { ysW( if ( x>3 ) {
+ my $str = *whee!; vllllS' my $str = 'whee!';
+
+While a few features of this plugin will work in older versions of Vim,
+Vim 7 is recommended for full functionality.
+
+MAPPINGS *surround-mappings*
+
+Delete surroundings is *ds* . The next character given determines the target
+to delete. The exact nature of the target is explained in |surround-targets|
+but essentially it is the last character of a |text-object|. This mapping
+deletes the difference between the "i"nner object and "a"n object. This is
+easiest to understand with some examples:
+
+ Old text Command New text ~
+ "Hello *world!" ds" Hello world!
+ (123+4*56)/2 ds) 123+456/2
+ <div>Yo!*</div> dst Yo!
+
+Change surroundings is *cs* . It takes two arguments, a target like with
+|ds|, and a replacement. Details about the second argument can be found
+below in |surround-replacements|. Once again, examples are in order.
+
+ Old text Command New text ~
+ "Hello *world!" cs"' 'Hello world!'
+ "Hello *world!" cs"<q> <q>Hello world!</q>
+ (123+4*56)/2 cs)] [123+456]/2
+ (123+4*56)/2 cs)[ [ 123+456 ]/2
+ <div>Yo!*</div> cst<p> <p>Yo!</p>
+
+*ys* takes a valid Vim motion or text object as the first object, and wraps
+it using the second argument as with |cs|. (It's a stretch, but a good
+mnemonic for "ys" is "you surround".)
+
+ Old text Command New text ~
+ Hello w*orld! ysiw) Hello (world)!
+
+As a special case, *yss* operates on the current line, ignoring leading
+whitespace.
+
+ Old text Command New text ~
+ Hello w*orld! yssB {Hello world!}
+
+There is also *yS* and *ySS* which indent the surrounded text and place it
+on a line of its own.
+
+In visual mode, a simple "S" with an argument wraps the selection. This is
+referred to as the *vS* mapping, although ordinarily there will be
+additional keystrokes between the v and S. In linewise visual mode, the
+surroundings are placed on separate lines and indented. In blockwise visual
+mode, each line is surrounded.
+
+A "gS" in visual mode, known as *vgS* , behaves similarly. In linewise visual
+mode, the automatic indenting is suppressed. In blockwise visual mode, this
+enables surrounding past the end of the line with 'virtualedit' set (there
+seems to be no way in Vim Script to differentiate between a jagged end of line
+selection and a virtual block selected past the end of the line, so two maps
+were needed).
+
+ *i_CTRL-G_s* *i_CTRL-G_S*
+Finally, there is an experimental insert mode mapping on <C-G>s and <C-S>.
+Beware that the latter won't work on terminals with flow control (if you
+accidentally freeze your terminal, use <C-Q> to unfreeze it). The mapping
+inserts the specified surroundings and puts the cursor between them. If,
+immediately after the mapping and before the replacement, a second <C-S> or
+carriage return is pressed, the prefix, cursor, and suffix will be placed on
+three separate lines. <C-G>S (not <C-G>s) also exhibits this behavior.
+
+TARGETS *surround-targets*
+
+The |ds| and |cs| commands both take a target as their first argument. The
+possible targets are based closely on the |text-objects| provided by Vim.
+All targets are currently just one character.
+
+Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves
+and their counterparts. If the opening mark is used, contained whitespace is
+also trimmed. The targets b, B, r, and a are aliases for ), }, ], and >
+(the first two mirror Vim; the second two are completely arbitrary and
+subject to change).
+
+Three quote marks, ', ", `, represent themselves, in pairs. They are only
+searched for on the current line.
+
+A t is a pair of HTML or XML tags. See |tag-blocks| for details. Remember
+that you can specify a numerical argument if you want to get to a tag other
+than the innermost one.
+
+The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|,
+respectively. These are special in that they have nothing to delete, and
+used with |ds| they are a no-op. With |cs|, one could consider them a
+slight shortcut for ysi (cswb == ysiwb, more or less).
+
+A p represents a |paragraph|. This behaves similarly to w, W, and s above;
+however, newlines are sometimes added and/or removed.
+
+REPLACEMENTS *surround-replacements*
+
+A replacement argument is a single character, and is required by |cs|, |ys|,
+and |vS|. Undefined replacement characters (with the exception of alphabetic
+characters) default to placing themselves at the beginning and end of the
+destination, which can be useful for characters like / and |.
+
+If either ), }, ], or > is used, the text is wrapped in the appropriate pair
+of characters. Similar behavior can be found with (, {, and [ (but not <),
+which append an additional space to the inside. Like with the targets above,
+b, B, r, and a are aliases for ), }, ], and >. To fulfill the common need for
+code blocks in C-style languages, <C-}> (which is really <C-]>) adds braces on
+lines separate from the content.
+
+If t or < is used, Vim prompts for an HTML/XML tag to insert. You may specify
+attributes here and they will be stripped from the closing tag. End your
+input by pressing <CR> or >. If <C-T> is used, the tags will appear on lines
+by themselves.
+
+A deprecated replacement of a LaTeX environment is provided on \ and l. The
+name of the environment and any arguments will be input from a prompt. This
+will be removed once a more fully functional customization system is
+implemented. The following shows the resulting environment from
+csp\tabular}{lc<CR>
+>
+ \begin{tabular}{lc}
+ \end{tabular}
+<
+CUSTOMIZING *surround-customizing*
+
+The following adds a potential replacement on "-" (ASCII 45) in PHP files.
+(To determine the ASCII code to use, :echo char2nr("-")). The carriage
+return will be replaced by the original text.
+>
+ autocmd FileType php let b:surround_45 = "<?php \r ?>"
+<
+This can be used in a PHP file as in the following example.
+
+ Old text Command New text ~
+ print "Hello *world!" yss- <?php print "Hello world!" ?>
+
+Additionally, one can use a global variable for globally available
+replacements.
+>
+ let g:surround_45 = "<% \r %>"
+ let g:surround_61 = "<%= \r %>"
+<
+Advanced, experimental, and subject to change: One can also prompt for
+replacement text. The syntax for this is to surround the replacement in pairs
+of low numbered control characters. If this sounds confusing, that's because
+it is (but it makes the parsing easy). Consider the following example for a
+LaTeX environment on the "l" replacement.
+>
+ let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\1}"
+<
+When this replacement is used, the user is prompted with an "environment: "
+prompt for input. This input is inserted between each set of \1's.
+Additional inputs up to \7 can be used.
+
+Furthermore, one can specify a regular expression substitution to apply.
+>
+ let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\r}.*\r\1}"
+<
+This will remove anything after the first } in the input when the text is
+placed within the \end{} slot. The first \r marks where the pattern begins,
+and the second where the replacement text begins.
+
+Here's a second example for creating an HTML <div>. The substitution cleverly
+prompts for an id, but only adds id="" if it is non-blank. You may have to
+read this one a few times slowly before you understand it.
+>
+ let g:surround_{char2nr("d")} = "<div\1id: \r..*\r id=\"&\"\1>\r</div>"
+<
+Inputting text replacements is a proof of concept at this point. The ugly,
+unintuitive interface and the brevity of the documentation reflect this.
+
+Finally, It is possible to always append a string to surroundings in insert
+mode (and only insert mode). This is useful with certain plugins and mappings
+that allow you to jump to such markings.
+>
+ let g:surround_insert_tail = "<++>"
+<
+ISSUES *surround-issues*
+
+Vim could potentially get confused when deleting/changing occurs at the very
+end of the line. Please report any repeatable instances of this.
+
+Do we need to use |inputsave()|/|inputrestore()| with the tag replacement?
+
+Indenting is handled haphazardly. Need to decide the most appropriate
+behavior and implement it. Right now one can do :let b:surround_indent = 1
+(or the global equivalent) to enable automatic re-indenting by Vim via |=|;
+should this be the default?
+
+ vim:tw=78:ts=8:ft=help:norl:
Oops, something went wrong.

0 comments on commit bc034c8

Please sign in to comment.