X-Git-Url: https://ruderich.org/simon/gitweb/?a=blobdiff_plain;f=doc%2Fsurround.txt;h=4387fa265dc1f6f0de05af1bb4606e7a0ba94e80;hb=HEAD;hp=fec64a203d2f16190a15f9946f4591999c2d619a;hpb=01663d8c8d5f65f5b29727b7df94808e503a00c9;p=config%2Fdotfiles.git diff --git a/doc/surround.txt b/doc/surround.txt deleted file mode 100644 index fec64a2..0000000 --- a/doc/surround.txt +++ /dev/null @@ -1,218 +0,0 @@ -*surround.txt* Plugin for deleting, changing, and adding "surroundings" - -Author: Tim Pope *surround-author* -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" Look ma, I'm HTML! - 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 are explained in |surround-targets| -but essentially it is the last character of a |text-object|. This mapping -deletes the difference between the "inner" object and "an" 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 -
Yo!*
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" Hello world! - (123+4*56)/2 cs)] [123+456]/2 - (123+4*56)/2 cs)[ [ 123+456 ]/2 -
Yo!*
cst

Yo!

- -*ys* takes an valid Vim motion or text object as the first object, and wraps -it using the second argument as with |cs|. (Unfortunately there's no good -mnemonic for "ys".) - - 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. In blockwise visual mode, each -line is surrounded. - -An "S" in visual mode (*vS*) behaves similarly but always places the -surroundings on separate lines. Additionally, the surrounded text is -indented. In blockwise visual mode, using "S" instead of "s" instead skips -trailing whitespace. - -Note that "s" and "S" already have valid meaning in visual mode, but it is -identical to "c". If you have muscle memory for "s" and would like to use a -different key, add your own mapping and the existing one will be disabled. -> - vmap s Vsurround - vmap S VSurround -< - *i_CTRL-G_s* *i_CTRL-G_S* -Finally, there is an experimental insert mode mapping on s and . -Beware that the latter won't work on terminals with flow control (if you -accidentally freeze your terminal, use 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 or -carriage return is pressed, the prefix, cursor, and suffix will be placed on -three separate lines. S (not 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. -In order for a target to work, the corresponding text object must be -supported in the version of Vim used (Vim 7 adds several text objects, and -thus is highly recommended). All targets are currently just one character. - -Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves -and their counterpart. 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, (which is really ) 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 or >. If 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 -> - \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 = "" -< -This can be used in a PHP file as in the following example. - - Old text Command New text ~ - print "Hello *world!" yss- - -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
. 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")} = "\r
" -< -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: