tomkersten-vixploder 0.1.1 → 0.1.2

data/lib/dotfiles/vim/doc/snippets_emu.txt

@@ -0,0 +1,354 @@
+*snippets_emu.txt*  For Vim version 7.0. Last change: 2006 Dec 26
+
+
+		  VIM REFERENCE MANUAL    by Panos Laganakos and Felix Ingram
+
+
+1. SnippetsEmu Features                         |snippets_emu-features|
+        Basic Snippets                              |basic-snippet|
+        Named Tags                                  |named-tags|
+        Tag Commands                                |snippet-commands|
+        Buffer Specific Snippets                    |snip-buffer-specific|
+        Filetype Specific Snippets                  |snip-ftplugin|
+        Snippets menu                               |snip-menu|
+2. SnippetsEmu Options                          |snippets_emu-options|
+        Start and End Tags                          |snip-start-end-tags|
+        Element Delimiter                           |snip-start-end-tags|
+        Remapping the default jump key              |snip-remap-key|
+3. Detailed Explanations                        |snip-detailed-explanations|
+        Valid Tag Names                             |snip-tag-name-syntax|
+        Advanced Tag Command Examples               |snip-advanced-tag-commands|
+4. SnippetsEmu Contact Details                  |snip-contact-details|
+5. Contributors                                 |snip-contributors|
+6. SnippetsEmu Known Bugs                       |snippets_emu-bugs|
+7. Troubleshooting                              |snippets_emu-troubleshooting|
+
+{Vi does not have any of these features}
+
+==============================================================================
+SNIPPETSEMU FEATURES					*snippets_emu-features*
+
+SnippetsEmu attempts to emulate several of the snippets features of the OS X
+editor TextMate, in particular the variable bouncing and replacement behaviour.
+Simple usage is built up around the following functionality:
+
+	Basic Snippet					|basic-snippet|
+	Named Tags					|named-tags|
+	Executable Snippet				|snippet-commands|
+        Buffer Specific Snippets                        |snip-buffer-specific|
+
+                                                               *basic-snippet*
+                                                               *:Snippet*
+Basic Snippet ~
+
+A basic snippet can save you a lot of typing. Define a word trigger and on
+insertion it will be expanded to the full snippet. SnippetsEmu allows the
+user to define markers within the larger piece of text which will be used
+to place the cursor upon expansion.
+
+The command used to define a snippet is 'Snippet'.
+
+Basic Syntax: >
+
+	:Snippet trigger_name The cursor will be placed here: <{}> Trailing text
+
+In insert mode typing 'trigger_name<Tab>' will remove 'trigger_name' and
+replace it with the text: 'The cursor will be placed here:  Trailing text'.
+The cursor will be placed between the two spaces before the word 'Trailing'
+
+NOTE: All text should be entered on the same command line. The formatting of
+this document may mean that examples are wrapped but they should all be
+entered on a single line.
+
+                                                                  *named-tags*
+Named tags ~
+
+Instead of the simple '<{}>' tags used for cursor placement a user can define
+named tags. When the value of a named tag is changed then all other tags with
+that name will be changed to the same value.
+
+E.g. >
+
+    :Snippet trigger My name is <{forename}> <{surname}>. Call me <{forename}>.
+
+In insert mode typing 'trigger<Tab>' will place the cursor inside the
+'<{forename}>' tag. Whatever is entered inside the tag will replace the other
+similarly named tag at the end of the line after the user presses 'Tab'.
+
+If no value is entered for a named tag then the tag's name will be used
+instead. This is one way of defining default values.
+
+Using the above example, entering 'trigger<Tab>' and pressing 'Tab' twice
+will result in the following text: >
+
+    My name is forename surname. Please call me forename.
+
+The rules for what constitutes a valid tag name are explained below. See
+|snip-tag-name-syntax|.
+                                                            *snippet-commands*
+Tag commands ~
+
+Tags can contain commands. Commands can be any Vim function, including user
+defined functions.
+
+A common example is performing substitutions.
+
+E.g. >
+
+    :Snippet trigger My name is <{name}>.  I SAID: MY NAME IS
+    <{name:substitute(@z,'.','\u&','g')}>!
+
+The value entered in the <{name}> tag will be passed to the command in the
+second <{name}> tag in the @z register (any value already in @z will be
+preserved and restored). The substitute command will change the entered value
+to be in upper case. I.e. Entering 'trigger<Tab>' and typing 'Tycho<Tab>'
+will result in the following text: >
+    
+    My name is Tycho. I SAID: MY NAME IS TYCHO!
+~
+                                                           *snip-special-vars*
+There is a set of special variables which can be included in snippets. These
+will be replaced before the snippet's text is inserted into the buffer. The
+list of available variables is detailed below:
+
+ * SNIP_FILE_NAME - The current file name (from 'expand("%")')
+ * SNIP_ISO_DATE - The current date in YYYY-MM-DD format.
+
+                                                       *snip-snippet-commands*
+In addition to tag commands it is also possible to define commands which will
+be executed before the snippet is inserted into the buffer. These are defined
+within double backticks. 
+
+E.g.
+>
+    :Snippet date The current date is ``strftime("%c")``
+
+Commands are standard Vim commands and will be 'exec'uted and the command
+output substituted into the text.
+
+                                                        *snip-buffer-specific*
+Buffer Specific Snippets ~
+
+The Snippet command defines buffer specific snippets. This is the recommended
+option when using filetype specific snippets. It is possible to define
+'global' snippets which will act across all buffers. These can be defined
+using the legacy 'Iabbr' command (note the capital 'I'). 
+
+E.g. >
+    Iabbr for for <{var}> in <{list}>:<CR><{}>
+~
+                                                               *snip-ftplugin*
+The preferred practice for defining filetype specific snippets is to include 
+them in files named <filetype>_snippets.vim and for these files to be placed in the
+~/.vim/after/ftplugin directory (or vimfiles\after\ftplugin under Windows).
+When a file of a specific type is loaded so will all of the defined snippets.
+The 'after' directory is used to ensure that the plugin has been loaded. It is
+also recommended that the following is included at the top of the file: >
+    
+    if !exists('loaded_snippet') || &cp
+        finish
+    endif
+
+This will stop errors being generated if the plugin has not loaded for any
+reason.
+
+Users wishing to add their own filetype snippets should add them to a separate
+file to ensure they are not lost when upgrading the plugin. Naming the files
+<filetype>_mysnippets.vim or similar is the preferred practice.
+
+                                                                   *snip-menu*
+When loading the plugin will search for all files named '*_snippets.vim'.
+These will be added to the 'Snippets' menu which is available in Normal mode.
+Selecting options from the menu will source the file and hence load any
+snippets defined within it.
+
+                                           *creating-snippets* *CreateSnippet*
+[range]CreateSnippet
+               The CreateSnippet command allows the simple creation of
+               snippets for use within your own file. Without a range the
+               current line will be used. When passed a range then all the
+               lines in the range will be converted for use in a command.
+
+               Snippets created by the command will be added to a scratch
+               buffer called 'Snippets'. The current value of an empty tag
+               (snip_start_tag.snip_end_tag, '<{}>' by default) will be added
+               to the unnamed register and so can be inserted with appropriate
+               paste commands.
+
+                                                         *CreateBundleSnippet*
+[range]CreateBundleSnippet
+               CreateBundleSnippet works exactly like CreateSnippet but the
+               resulting text will be suitable for including in one of the
+               included bundles. The unnamed register will include the text
+               '"st.et."' so start and end tag agnostic empty tags can be
+               included.
+
+===============================================================================
+SNIPPETSEMU OPTIONS                                     *snippets_emu-options*
+                                                         *snip-start-end-tags*
+Start and End Tags ~
+
+By default the start and end tags are set to be '<{' and '}>'. These can be
+changed by setting the following variables in vimrc: >
+
+    g:snip_start_tag
+    g:snip_end_tag
+
+They can be also changed for a specific buffer by setting the following: >
+
+    b:snip_start_tag
+    b:snip_end_tag
+~
+                                                         *snip-elem-delimiter*
+Element Delimiter ~
+
+The value of snip_elem_delim is used to separate a tag's name and its command.
+By default it is set to ':' but can be set as above either globally or for a
+specific buffer using the following variables: >
+    
+    g:snip_elem_delim
+    b:snip_elem_delim
+~
+                                                              *snip-remap-key*
+Remapping the default jump key ~
+
+The trigger key is mapped to Tab by default. Some people may wish to remap
+this if it causes conflicts with other plugins. The key can be set in your
+<.vimrc> by setting the 'g:snippetsEmu_key' variable.
+An example
+>
+    let g:snippetsEmu_key = "<S-Tab>"
+
+Snippets will now be triggered by Shift-Tab rather than just Tab. NB, this
+example may not work in all terminals as some trap Shift-Tab before it gets
+to Vim.
+
+~
+==============================================================================
+DETAILED EXPLANATIONS                             *snip-detailed-explanations*
+                                                        *snip-tag-name-syntax*
+Valid Tag Names ~
+
+Tag names cannot contain whitespace unless they are enclosed in quotes.
+
+Valid Examples: >
+    <{validName}>
+    <{"valid name"}>
+    <{tagName:command}>
+    <{"Tag Name":command}>
+
+Invalid Examples: >
+    <{invalid name}>
+    <{Tag Name:command}>
+    <{:command}>
+
+~
+                                                  *snip-advanced-tag-commands*
+Advanced Tag Command Examples ~
+
+Commands in tags can be as complex as desired. Readability is the main
+limitation as the command will be placed in the document before execution.
+
+The preferred method for defining complex commands is to hide the
+functionality in a user function.
+
+Example:
+>
+    
+    function! Count(haystack, needle)
+        let counter = 0
+        let index = match(a:haystack, a:needle)
+        while index > -1
+            let counter = counter + 1
+            let index = match(a:haystack, a:needle, index+1)
+        endwhile
+        return counter
+    endfunction
+
+    function! PyArgList(count)
+        if a:count == 0
+            return "(,)"
+        else
+            return '('.repeat('<{}>, ', a:count).')'
+        endif
+    endfunction
+
+    Snippet pf print "<{s}>" % <{s:PyArgList(Count(@z, '%[^%]'))}><CR><{}>
+
+The above snippet will expand 'pf' to 'print "<{s}>" ...'. The user then
+enters a format string. Once the string is entered the Count and PyArgList
+functions are used to generate a number of empty tags.
+
+                                                            *snip-limitations*
+The above represents once of the limitations of the plugin. Due to the way
+tags are identified it is not possible to include empty tags in another tag's
+command. The only way to generate empty tags is to return them from a function
+as in the above example. For other examples see the included bundles.
+
+                                                                *snip-bundles*
+The included bundles are not defined in the 'preferred style'. In order to
+accommodate users who wish to redefine the default tags all snippet
+definitions are 'executed' with the 'exec' command.
+
+E.g.
+>
+    exec "Snippet test This isn't the right way to ".st.et." define snippets"
+
+Executing the command allows 'st' and 'et' to be used in place of start and
+end tags. 'st' and 'et' are defined elsewhere in the bundle file.
+
+==============================================================================
+SNIPPETSEMU CONTACT DETAILS                             *snip-contact-details*
+
+To contact the author please email:
+
+F <dot> Ingram <dot> lists <at> gmail <dot> com
+
+The author welcomes corrections to this documentation, example snippets and
+bug reports.
+
+The plugin is also currently hosted at Google Code:
+    http://code.google.com/p/snippetsemu
+
+Bug reports can also be posted on the hosting site:
+    http://code.google.com/p/snippetsemu/issues/list
+
+                                                           *snip-contributors*
+Contributors to SnippetsEmu ~
+
+Patches:
+Ori Avtalion - Improvements to Snippet command
+Freddy Vulto - Improved behaviour
+Andy Block - Bug with commands on same line. This is why I should do better
+test suites.
+bzklrm - Removal of some normal commands
+Priit Tamboom - Sorting out left and right mappings
+
+Documentation:
+Panos Laganakos - Greek translation (coming soon)
+
+Bundles:
+Panos Laganakos - Python snippets
+Alex Pounds - Django snippets
+Chris Lasher - Python snippets
+knipknap - Python snippets
+James Widman - C snippets
+
+==============================================================================
+SNIPPETSEMU KNOWN BUGS                  		   *snippets_emu-bugs*
+
+Bugs are currently tracked on Google Code. Please post any you find on the
+issue tracker:
+    http://code.google.com/p/snippetsemu/issues/list
+
+==============================================================================
+SNIPPETSEMU TROUBLESHOOTING                     *snippets_emu-troubleshooting*
+
+Problem:    Bundles are not loading.
+Answer:     Ensure that you have filetype plugins turned on. Include the
+            following in your vimrc: >
+
+                filetype plugin on
+
+
+vim:tw=78:sw=4:ts=8:ft=help:norl:

data/lib/dotfiles/vim/doc/surround.txt

@@ -0,0 +1,218 @@
+*surround.txt*  Plugin for deleting, changing, and adding "surroundings"
+
+Author:  Tim Pope <vimNOSPAM@tpope.info>        *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"<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|.  (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 <Leader>s <Plug>Vsurround
+  vmap <Leader>S <Plug>VSurround
+<
+                                                *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.
+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 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: