diff options
Diffstat (limited to 'vim/doc')
| -rw-r--r-- | vim/doc/DrawIt.txt | 489 | ||||
| l--------- | vim/doc/imaps.txt.gz | 1 | ||||
| l--------- | vim/doc/latex-suite-quickstart.txt.gz | 1 | ||||
| l--------- | vim/doc/latex-suite.txt.gz | 1 | ||||
| l--------- | vim/doc/latexhelp.txt.gz | 1 | ||||
| -rw-r--r-- | vim/doc/surround.txt | 205 | ||||
| -rw-r--r-- | vim/doc/tags | 56 |
7 files changed, 754 insertions, 0 deletions
diff --git a/vim/doc/DrawIt.txt b/vim/doc/DrawIt.txt new file mode 100644 index 0000000..8e72f64 --- /dev/null +++ b/vim/doc/DrawIt.txt @@ -0,0 +1,489 @@ +DrawIt.txt* The DrawIt Tool Nov 25, 2013 + +Authors: Charles E. Campbell <NdrchipO@ScampbellPfamily.AbizM> + Sylvain Viart <molo@multimania.com> + (remove NOSPAM from Campbell's email first) +Copyright: Copyright (C) 2004-2013 Charles E. Campbell + Permission is hereby granted to use and distribute this code, + with or without modifications, provided that this copyright + notice is copied with it. Like anything else that's free, + DrawIt.vim and DrawItPlugin.vim are provided *as is*; it comes + with no warranty of any kind, either expressed or implied. By + using this plugin, you agree that in no event will the copyright + holder be liable for any damages resulting from the use of this + software. + + +============================================================================== +1. Contents *drawit-contents* {{{1 + + 1. Contents......................: |drawit-contents| + 2. DrawIt Manual.................: |drawit| + 3. DrawIt Usage..................: |drawit-usage| + Starting....................: |drawit-start| + Stopping....................: |drawit-stop| + User Map Protection.........: |drawit-protect| + Drawing.....................: |drawit-drawing| + Tip.........................: |drawit-tip| + Changing Drawing Characters.: |drawit-setdrawit| + Moving......................: |drawit-moving| + Erasing.....................: |drawit-erase| + Example.....................: |drawit-example| + Visual Block Mode...........: |drawit-visblock| + Brushes.....................: |drawit-brush| + DrawIt Modes................: |drawit-modes| + 4. DrawIt History................: |drawit-history| + + +============================================================================== +2. DrawIt Manual *drawit* {{{1 + *drawit-manual* + /===============+============================================================\ + || Starting & | || + || Stopping | Explanation || + ++--------------+-----------------------------------------------------------++ + || \di | start DrawIt |drawit-start| || + || \ds | stop DrawIt |drawit-stop| || + || :DIstart | start DrawIt |drawit-start| || + || :DIstart S | start DrawIt in single-bar mode |drawit-start| || + || :DIstart D | start DrawIt in double-bar mode |drawit-start| || + || :DIsngl | start DrawIt in single-bar mode |drawit-start| |drawit-sngl| || + || :DIdbl | start DrawIt in double-bar mode |drawit-start| |drawit-dbl| || + || :DIstop | stop DrawIt |drawit-stop| || + || :DrawIt[!] | start/stop DrawIt |drawit-start| |drawit-stop| || + || | || + ++==============+===========================================================++ + || Maps | Explanation || + ++--------------+-----------------------------------------------------------++ + || | The DrawIt routines use a replace, move, and || + || | replace/insert strategy. The package also lets one insert|| + || | spaces, draw arrows by using the following characters or || + || | keypad characters: || + || +-----------------------------------------------------------++ + || <left> | move and draw left |drawit-drawing| || + || <right> | move and draw right, inserting lines/space as needed || + || <up> | move and draw up, inserting lines/space as needed || + || <down> | move and draw down, inserting lines/space as needed || + || <s-left> | move cursor left |drawit-move| || + || <s-right> | move cursor right, inserting lines/space as needed || + || <s-up> | move cursor up, inserting lines/space as needed || + || <s-down> | move cursor down, inserting lines/space as needed || + || <space> | toggle into and out of erase mode || + || > | insert a > and move right (draw -> arrow) || + || < | insert a < and move left (draw <- arrow) || + || ^ | insert a ^ and move up (draw ^ arrow) || + || v | insert a v and move down (draw v arrow) || + || <pgdn> | replace with a \, move down and right, and insert a \ || + || <end> | replace with a /, move down and left, and insert a / || + || <pgup> | replace with a /, move up and right, and insert a / || + || <home> | replace with a \, move up and left, and insert a \ || + || \> | insert a fat > and move right (draw -> arrow) || + || \< | insert a fat < and move left (draw <- arrow) || + || \^ | insert a fat ^ and move up (draw ^ arrow) || + || \v | insert a fat v and move down (draw v arrow) || + ||<s-leftmouse> | drag and draw with current brush |drawit-brush| || + ||<c-leftmouse> | drag and move current brush |drawit-brush| || + || | || + ||==============+===========================================================++ + ||Visual Cmds | Explanation || + ||--------------+-----------------------------------------------------------++ + || | The drawing mode routines use visual-block mode to || + || | select endpoints for lines, arrows, and ellipses. Bresen- || + || | ham and Bresenham-like algorithms are used for this. || + || | || + || | These routines need a block of spaces, and so the canvas || + || | routine must first be used to create such a block. The || + || | canvas routine will query the user for the number of || + || | lines to hold |'textwidth'| spaces. || + || +-----------------------------------------------------------++ + || \a | draw arrow from corners of visual-block selected region || |drawit-a| + || \b | draw box on visual-block selected region || |drawit-b| + || \c | the canvas routine (will query user, see above) || |drawit-c| + || \e | draw an ellipse on visual-block selected region || |drawit-e| + || \f | flood figure with a character (you will be prompted) || |drawit-f| + || \l | draw line from corners of visual-block selected region || |drawit-l| + || \s | spacer: appends spaces up to the textwidth (default: 78) || |drawit-s| + || | || + ++==============+===========================================================++ + || Function and Explanation || + ++--------------+-----------------------------------------------------------++ + || :call SetDrawIt('vertical','horizontal','crossing','\','/','X','*') || + || set drawing characters for motions for moving || + || and for the ellipse drawing boundary |drawit-setdrawit| || + || default motion || + || | up/down, || + || - left/right, || + || + -| crossing, || + || \ downright, || + || / downleft, and || + || X \/ crossing || + ++=======================+==================================================++ + || Commands | Explanation || + ++-----------------------+--------------------------------------------------++ + || :SetBrush a-z | sets brush (register) to given register || + || :'<,'>SetBrush a-z | yanks visual block to brush |drawit-brush||| || + || :DInrml | switch to normal mode |drawit-nrml| || + || :DIsngl | switch to single-line mode |drawit-sngl| || + || :DIdbl | switch to double-line mode |drawit-dbl| || + \============================================================================/ + + +============================================================================== +3. DrawIt Usage *drawit-usage* {{{1 + +STARTING *drawit-start* {{{2 +\di (starts in normal drawing mode) *drawit-\di* +:DrawIt (starts in normal drawing mode) *drawit-DrawIt* +:DIstart (starts in normal drawing mode) *drawit-DIstart* +:DIstart S (starts in single-bar drawing mode) +:DIstart D (starts in double-bar drawing mode) +:DInrml (starts in normal drawing mode) *drawit-DInrml* +:DIsngl (starts in single-bar drawing mode) *drawit-DIsngl* +:DIdbl (starts in double-bar drawing mode) *drawit-DIdbl* + +Typically one puts <drawit.vim> into the .vim/plugin directory +(vimfiles\plugin for Windows) where it becomes always available. It uses a +minimal interface (\di: you can think of it as *D*raw*I*t or *D*rawIt +*I*nitialize) to start it and (\ds: *D*rawIt *S*top) to stop it. Instead of +using "\" you may specify your own preference for a map leader (see +|mapleader|). + +With a trailing 'S', :DIstart will begin in single-bar mode (see |drawit-sngl|). +With a trailing 'D', :DIstart will begin in double-bar mode (see |drawit-dbl|). +Similarly, :DIsngl and :DIdbl will start DrawIt as well as begin in +single-bar or double-bar mode, respectively. + +A message, "[DrawIt]", will appear on the message line. + + +STOPPING *drawit-stop* {{{2 +\ds +:DIstop +:DrawIt! + +When you are done with DrawIt, use \ds to stop DrawIt mode. Stopping DrawIt +will restore your usual options and remove the maps DrawIt set up. + +A message, "[DrawIt off]", will appear on the message line. + + *drawit-utf16* + *drawit-utf8* *drawit-unicode* +NORMAL, SINGLE BAR, AND DOUBLE BAR MODES *drawit-sngl* *drawit-dbl* +:DInrml :DIsngl :DIdbl + +One may use these commands to start up Drawit in normal, single-bar, or +double-bar modes, respectively. When your |'encoding'| is utf-8 or utf-16, +DrawIt supports drawing with special box characters (single-bar, double_bar). +These commands are also used to switch to normal, single-bar, or double-bar +modes. + + +USER MAP PROTECTION *drawit-protect* {{{2 + +Starting DrawIt causes it to set up a number of maps which facilitate drawing. +DrawIt accommodates users with conflicting maps by saving both maps and user +options and before setting them to what DrawIt needs. When you stop DrawIt +(|drawit-stop|), DrawIt will restore the user's maps and options as they were +before DrawIt was started. + + +OPTIONS *drawit-options* {{{2 + + *g:drawit_insertmode* +g:drawit_insertmode : if this variable exists and is 1 then maps are + made which make cursor-control drawing available + while in insert mode, too. Otherwise, DrawIt's + maps only affect normal mode. + +DRAWING *drawit-drawing* {{{2 + +After DrawIt is started, use the number pad or arrow keys to move the cursor +about. As the cursor moves, DrawIt will then leave appropriate "line" +characters behind as you move horizontally, vertically, or diagonally, and +will transparently enlarge your file to accommodate your drawing as needed. +The trail will consist of -, |, \, / characters (depending on which direction +and SetDrawIt() changes), and + and X characters where line crossings occur. +You may use h-j-k-l to move about your display and generally use editing +commands as you wish even while in DrawIt mode. + +Another tool that may be used to convert Ascii-art into nice pictures is +available at https://github.com/christiangoltz/shaape . + + +CHANGING DRAWING CHARACTERS *drawit-setdrawit* {{{2 + +The SetDrawIt() function is available for those who wish to change the +characters that DrawIt uses. > + + ex. :call SetDrawIt('*','*','*','*','*','*','*') + ex. :call SetDrawIt('-','|','-','\','/','/','*') +< +The first example shows how to change all the DrawIt drawing characters to +asterisks, and the second shows how to give crossing priority to - and /. +The default setting is equivalent to: > + + :call SetDrawIt('|','-','+','\','/','X','*') +< +where SetDrawit()'s arguments refer, in order, to the > + + vertical drawing character + horizontal drawing character + horizontal/vertical crossing drawing character + down right drawing character + down left drawing character + diagonal crossing drawing character + ellipse boundary drawing character +< + +TIP *drawit-tip* + +I have found that sometimes one or more of the <home>, <end>, <pageup>, +and <pagedown> keys give unique sequences but are not interpreted +properly by Vim. This problem impacts DrawIt as it uses those four +keys to signify diagonal moves/drawing. One solution I use is to +put into my <.vimrc> file mapings like: + + map ^V... <home> + +where the ellipsis (...) is the actual character sequence produced by +hitting the key. The way to generate such maps is to type "map ", +followed by three control-v presses, press the associated key, then +a space followed by the proper interpretation sequence (ie. <home>). + + +MOVING *drawit-move* *drawit-moving* {{{2 + +DrawIt supports shifting the arrow keys to cause motion of the cursor. The +motion of the cursor will not modify what's below the cursor. The cursor +will move and lines and/or spaces will be inserted to support the move as +required. Your terminal may not support shifted arrow keys, however, or Vim +may not catch them as such. For example, on the machine I use, shift-up +(<s-up>) produced <Esc>[161q, but vim didn't know that sequence was a <s-up>. +I merely made a nmap: + + nmap <Esc>[161q <s-up> + +and vim thereafter recognized the <s-up> command. + + +ERASING *drawit-erase* {{{2 +<space> + +The <space> key will toggle DrawIt's erase mode/DrawIt mode. When in [DrawIt +erase] mode, a message "[DrawIt erase]" will appear and the number pad will +now cause spaces to be drawn instead of the usual drawing characters. The +drawing behavior will be restored when the <space> key toggles DrawIt back +to regular DrawIt mode. + + +EXAMPLES *drawit-example* {{{2 + +Needless to say, the square spirals which follow were done with DrawIt and +a bit of block editing with Vim: > + + +------------ -----------+ +------------ -----------+ +------------ + |+----------+ +---------+| |+----------+ +---------+| |+----------+ + ||+--------+| |+-------+|| ||+--------+| |+-------+|| ||+--------+| + |||-------+|| ||+------||| |||-------+|| ||+------||| |||-------+|| + ||+-------+|| ||+------+|| ||+-------+|| ||+------+|| ||+-------+|| + |+---------+| |+--------+| |+---------+| |+--------+| |+---------+| + +-----------+ +----------+ +-----------+ +----------+ +-----------+ + +VISUAL BLOCK MODE FOR ARROWS LINES BOXES AND ELLIPSES *drawit-visblock* {{{2 + +\a : draw arrow from corners of visual-block selected region *drawit-a* +\b : draw box on visual-block selected region *drawit-b* +\c : the canvas routine (will query user, see above) *drawit-c* +\e : draw an ellipse on visual-block selected region *drawit-e* +\f : flood figure with a character (you will be prompted) *drawit-f* +\l : draw line from corners of visual-block selected region *drawit-l* +\s : spacer: appends spaces up to the textwidth (default: 78) *drawit-s* + +The DrawIt package has been merged with Sylvain Viart's drawing package (by +permission) which provides DrawIt with visual-block selection of +starting/ending point drawing of arrows (\a), lines (\l), and boxes (\b). +Additionally I wrote an ellipse drawing function using visual block +specification (|drawit-e|). + +One may create a block of spaces for these maps to operate in; the "canvas" +routine (\c) will help create such blocks. First, the s:Canvas() routine will +query the user for the number of lines s/he wishes to have, and will then fill +those lines with spaces out to the |'textwidth'| if user has specified it; +otherwise, the display width will be used. + +Although most of the maps use visual-block selection, that isn't true of the +\f map. Instead, it assume that you have already drawn some closed figure +and want to fill it with some character. + +The Sylvain Viart functions and the ellipse drawing function depend +upon using visual block mode. As a typical use: > + + Example: * \h + DrawIt asks: how many lines under the cursor? 10 + DrawIt then appends 10 lines filled with blanks + out to textwidth (if defined) or 78 columns. + * ctrl-v (move) \b + DrawIt then draws a box + * ctrl-v (move) \e + DrawIt then draws an ellipse +< +Select the first endpoint with ctrl-v and then move to the other endpoint. +One may then select \a for arrows, \b for boxes, \e for ellipses, or \l for +lines. The internal s:AutoCanvas() will convert tabs to spaces and will +extend with spaces as needed to support the visual block. Note that when +DrawIt is enabled, virtualedit is also enabled (to "all"). +> + Examples: + + __ _ *************** +-------+ + \_ _/ **** **** | | + \_ _/ ** ---------> ** | | + \_ _/ **** **** | | + \__/ <------- *************** +-------+ + + \l \a \e and \a \b +< + *drawit-setbrush* +BRUSHES *drawit-brush* {{{2 +> + :SetBrush [a-z] +< + Set the current brush to the selected brush register: +> + ex. :SetBrush b + + :'<,'>SetBrush [a-z] +< + Select text for the brush by using visual-block mode: ctrl-v, move . + Then set the current text into the brush register: (default brush: a) +> + <leftmouse> +< + Select a visual-block region. One may use "ay, for example, + to yank selected text to register a. +> + <shift-leftmouse> +< + One may drag and draw with the current brush (default brush: a) + by holding down the shift key and the leftmouse button and moving + the mouse. Blanks in the brush are considered to be transparent. +> + <ctrl-leftmouse> +< + One may drag and move a selection with <ctrl-leftmouse>. First, + select the region using the <leftmouse>. Release the mouse button, + then press ctrl and the <leftmouse> button; while continuing to press + the button, move the mouse. The selected block of text will then + move along with the cursor. +> + \ra ... \rz +< + Replace text with the given register's contents (ie. the brush). +> + \pa ... \pz +< + Like \ra ... \rz, except that blanks are considered to be transparent. + + Example: Draw the following > + \ \ + o o + * + --- +< Then use ctrl-v, move, "ay to grab a copy into register a. + By default, the current brush uses register a (change brush + with :SetBrush [reg]). Hold the <shift> and <leftbutton> + keys down and move the mouse; as you move, a copy of the + brush will be left behind. + + +DRAWIT MODES *drawit-modes* {{{2 + + -[DrawIt] regular DrawIt mode (|drawit-start|) + -[DrawIt off] DrawIt is off (|drawit-stop| ) + -[DrawIt erase] DrawIt will erase using the number pad (|drawit-erase|) + + g:DrChipTopLvlMenu: by default its "DrChip"; you may set this to whatever + you like in your <.vimrc>. This variable controls where + DrawIt's menu items are placed. + + +============================================================================== +4. History *drawit-history* {{{1 + + 13 Sep 05, 2013 * improved s:Strlen() -- now uses |strdisplaywidth()| + if available. + Sep 13, 2013 * (Paul Wagland) found a case where lines were + being drawn with the wrong character. This + affected the Bresenham-algorithm based + drawing facility (ie. lines and arrows + specified by visual blocks; + |drawit-a|, |drawit-l|). + 12 Nov 16, 2012 * (Alexandre Viau) arrows weren't being drawn. + Fixed. + Nov 29, 2012 * (Kim Jang-hwan) reported that with + g:Align_xstrlen set to 3 that the cursor was + moved (linewise) after invocation. This + problem also afflicted DrawIt. Fixed. + 11 Jan 21, 2010 * (Evan Stern) several places were using + hardcoded drawing characters instead of + b:di_... equivalents. + Feb 22, 2011 * for menus, &go =~# used to insure correct case + Sep 22, 2011 * ctrl-leftmouse (see |drawit-brush|) now moves the + selected text entirely, no longer leaving a copy + of the text where it was initially. + Nov 07, 2011 * included support for utf-8 box drawing characters + Nov 16, 2011 * included support for utf-8 single-double characters + Nov 16, 2011 * included support for cp437 box drawing characters + Dec 06, 2011 * included support for box and line drawing (\b, \l) + support for utf-8 / cp437 box drawing characters + Dec 06, 2011 * fat arrows now use utf-8 characters when available + Jan 30, 2012 * \f supported when using utf-8/cp437 box drawing + characters as boundary characters + 10 Jun 12, 2008 * Fixed a bug with ctrl-leftmouse (which was leaving + a space in the original selected text) + Mar 24, 2009 * :DrawIt starts, :DrawIt! stops DrawIt mode. + Mar 24, 2009 * I've included <script> modifiers to the maps to + cause rhs remapping only with mappings local to + the script (see |:map-script|) + 9 Sep 14, 2007 * Johann-Guenter Simon fixed a bug with s:DrawErase(); + it called SetDrawIt() and that call hadn't been + updated to account for the new b:di_ellipse + parameter. + 8 Feb 12, 2007 * fixed a bug which prevented multi-character user + maps from being restored properly + May 03, 2007 * Extended SetDrawIt() to handle b:di_ellipse, the + ellipse boundary drawing character + * Changed "Holer" to "Canvas", and wrote AutoCanvas(), + which allows one to use the visual-block drawing + maps without creating a canvas first. + * DrawIt implements using the ctrl-leftmouse to move + a visual-block selected region. + * Floods can now be done inside an ellipse + * DrawIt's maps are now all users of <buffer> + 7 Feb 16, 2005 * now checks that "m" is in &go before attempting to + use menus + Aug 17, 2005 * report option workaround + Nov 01, 2005 * converted DrawIt to use autoload feature of vim 7.0 + Dec 28, 2005 * now uses cecutil to save/restore user maps + Jan 18, 2006 * cecutil now updated to use keepjumps + Jan 23, 2006 * :DIstart and :DIstop commands provided; thus users + using "set noremap" can still use DrawIt. + Jan 26, 2006 * DrawIt menu entry now keeps its place + Apr 10, 2006 * Brushes were implemented + 6 Feb 24, 2003 * The latest DrawIt now provides a fill function. + \f will ask for a character to fill the figure + surrounding the current cursor location. Plus + I suggest reading :he drawit-tip for those whose + home/pageup/pagedown/end keys aren't all working + properly with DrawIt. + 08/18/03 * \p[a-z] and \r[a-z] implemented + 08/04/03 * b:..keep variables renamed to b:di_..keep variables + StopDrawIt() now insures that erase mode is off + 03/11/03 * included g:drawit_insertmode handling + 02/21/03 * included flood function + 12/11/02 * deletes trailing whitespace only if holer used + 8/27/02 * fat arrowheads included + * shift-arrow keys move but don't modify + + --------------------------------------------------------------------- +vim:tw=78:ts=8:ft=help:fdm=marker diff --git a/vim/doc/imaps.txt.gz b/vim/doc/imaps.txt.gz new file mode 120000 index 0000000..cf5808b --- /dev/null +++ b/vim/doc/imaps.txt.gz @@ -0,0 +1 @@ +/usr/share/vim/addons/doc/imaps.txt.gz
\ No newline at end of file diff --git a/vim/doc/latex-suite-quickstart.txt.gz b/vim/doc/latex-suite-quickstart.txt.gz new file mode 120000 index 0000000..5ef4db2 --- /dev/null +++ b/vim/doc/latex-suite-quickstart.txt.gz @@ -0,0 +1 @@ +/usr/share/vim/addons/doc/latex-suite-quickstart.txt.gz
\ No newline at end of file diff --git a/vim/doc/latex-suite.txt.gz b/vim/doc/latex-suite.txt.gz new file mode 120000 index 0000000..35c3d5a --- /dev/null +++ b/vim/doc/latex-suite.txt.gz @@ -0,0 +1 @@ +/usr/share/vim/addons/doc/latex-suite.txt.gz
\ No newline at end of file diff --git a/vim/doc/latexhelp.txt.gz b/vim/doc/latexhelp.txt.gz new file mode 120000 index 0000000..f8197a0 --- /dev/null +++ b/vim/doc/latexhelp.txt.gz @@ -0,0 +1 @@ +/usr/share/vim/addons/doc/latexhelp.txt.gz
\ No newline at end of file diff --git a/vim/doc/surround.txt b/vim/doc/surround.txt new file mode 100644 index 0000000..30a642a --- /dev/null +++ b/vim/doc/surround.txt @@ -0,0 +1,205 @@ +*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. + +If s is used, a leading but not trailing space is added. This is useful for +removing parentheses from a function call with csbs. + +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: diff --git a/vim/doc/tags b/vim/doc/tags new file mode 100644 index 0000000..54ecdda --- /dev/null +++ b/vim/doc/tags @@ -0,0 +1,56 @@ +cs surround.txt /*cs* +drawit DrawIt.txt /*drawit* +drawit-DIdbl DrawIt.txt /*drawit-DIdbl* +drawit-DInrml DrawIt.txt /*drawit-DInrml* +drawit-DIsngl DrawIt.txt /*drawit-DIsngl* +drawit-DIstart DrawIt.txt /*drawit-DIstart* +drawit-DrawIt DrawIt.txt /*drawit-DrawIt* +drawit-\di DrawIt.txt /*drawit-\\di* +drawit-a DrawIt.txt /*drawit-a* +drawit-b DrawIt.txt /*drawit-b* +drawit-brush DrawIt.txt /*drawit-brush* +drawit-c DrawIt.txt /*drawit-c* +drawit-contents DrawIt.txt /*drawit-contents* +drawit-dbl DrawIt.txt /*drawit-dbl* +drawit-drawing DrawIt.txt /*drawit-drawing* +drawit-e DrawIt.txt /*drawit-e* +drawit-erase DrawIt.txt /*drawit-erase* +drawit-example DrawIt.txt /*drawit-example* +drawit-f DrawIt.txt /*drawit-f* +drawit-history DrawIt.txt /*drawit-history* +drawit-l DrawIt.txt /*drawit-l* +drawit-manual DrawIt.txt /*drawit-manual* +drawit-modes DrawIt.txt /*drawit-modes* +drawit-move DrawIt.txt /*drawit-move* +drawit-moving DrawIt.txt /*drawit-moving* +drawit-options DrawIt.txt /*drawit-options* +drawit-protect DrawIt.txt /*drawit-protect* +drawit-s DrawIt.txt /*drawit-s* +drawit-setbrush DrawIt.txt /*drawit-setbrush* +drawit-setdrawit DrawIt.txt /*drawit-setdrawit* +drawit-sngl DrawIt.txt /*drawit-sngl* +drawit-start DrawIt.txt /*drawit-start* +drawit-stop DrawIt.txt /*drawit-stop* +drawit-tip DrawIt.txt /*drawit-tip* +drawit-unicode DrawIt.txt /*drawit-unicode* +drawit-usage DrawIt.txt /*drawit-usage* +drawit-utf16 DrawIt.txt /*drawit-utf16* +drawit-utf8 DrawIt.txt /*drawit-utf8* +drawit-visblock DrawIt.txt /*drawit-visblock* +ds surround.txt /*ds* +g:drawit_insertmode DrawIt.txt /*g:drawit_insertmode* +i_CTRL-G_S surround.txt /*i_CTRL-G_S* +i_CTRL-G_s surround.txt /*i_CTRL-G_s* +surround surround.txt /*surround* +surround-customizing surround.txt /*surround-customizing* +surround-issues surround.txt /*surround-issues* +surround-mappings surround.txt /*surround-mappings* +surround-replacements surround.txt /*surround-replacements* +surround-targets surround.txt /*surround-targets* +surround.txt surround.txt /*surround.txt* +vS surround.txt /*vS* +vgS surround.txt /*vgS* +yS surround.txt /*yS* +ySS surround.txt /*ySS* +ys surround.txt /*ys* +yss surround.txt /*yss* |