diff options
| author | Anton Bobov <abobov@gmail.com> | 2013-11-14 11:28:27 +0600 |
|---|---|---|
| committer | Anton Bobov <abobov@gmail.com> | 2013-11-14 18:31:37 +0600 |
| commit | d0597921f6ee9b2bdfd7e0581df2bd7d59f5dfc9 (patch) | |
| tree | e1840de57b9f27df43e910330c311ff253989e4a /files/.vim/doc | |
| parent | c10e0e31a4233e82ba83504c145d746b206435cd (diff) | |
Remove unused vim plugins.
Diffstat (limited to 'files/.vim/doc')
| -rw-r--r-- | files/.vim/doc/CSApprox.txt | 599 | ||||
| -rw-r--r-- | files/.vim/doc/imaps.txt | 116 | ||||
| -rw-r--r-- | files/.vim/doc/imaps.txt.gz | bin | 1995 -> 0 bytes | |||
| -rw-r--r-- | files/.vim/doc/matchit.txt | 406 | ||||
| -rw-r--r-- | files/.vim/doc/project.txt | 710 |
5 files changed, 0 insertions, 1831 deletions
diff --git a/files/.vim/doc/CSApprox.txt b/files/.vim/doc/CSApprox.txt deleted file mode 100644 index d91bb62..0000000 --- a/files/.vim/doc/CSApprox.txt +++ /dev/null @@ -1,599 +0,0 @@ -*CSApprox.txt* Bringing GVim colorschemes to the terminal! - - *csapprox* *csapprox.vim* - - _____ ____ ___ ~ - / ___// __// _ | ___ ___ ____ ___ __ __ ~ - / /__ _\ \ / __ | / _ \ / _ \ / __// _ \ \ \ / ~ - \___//___//_/ |_|/ .__// .__//_/ \___//_\_\ ~ - /_/ /_/ ~ - For Vim version 7.0 or newer - Last changed 01 Apr 2009 - - By Matt Wozniski - mjw@drexel.edu - - Reference Manual~ - - *csapprox-toc* - -1. Introduction |csapprox-intro| -2. Requirements |csapprox-requirements| -3. Configuration |csapprox-configure| -4. Rationale/Design |csapprox-design| -5. Known Bugs and Limitations |csapprox-limitations| -6. Appendix - Terminals and Palettes |csapprox-terminal-list| -7. Changelog |csapprox-changelog| -8. Contact Info |csapprox-author| - -The functionality mentioned here is a plugin, see |add-plugin|. -You can avoid loading this plugin by setting the "CSApprox_loaded" global -variable in your |vimrc| file: > - :let g:CSApprox_loaded = 1 - -============================================================================== -1. Introduction *csapprox-intro* - -It's hard to find colorschemes for terminal Vim. Most colorschemes are -written to only support GVim, and don't work at all in terminal Vim. - -This plugin makes GVim-only colorschemes Just Work in terminal Vim, as long -as the terminal supports 88 or 256 colors - and most do these days. This -usually requires no user interaction (but see below for what to do if things -don't Just Work). After getting this plugin happily installed, any time you -use :colorscheme it will do its magic and make the colorscheme Just Work. - -Whenever you change colorschemes using the :colorscheme command this script -will be executed. It will take the colors that the scheme specified for use -in the GUI and use an approximation algorithm to try to gracefully degrade -them to the closest color available in your terminal. If you are running in -a GUI or if your terminal doesn't support 88 or 256 colors, no changes are -made. Also, no changes will be made if the colorscheme seems to have been -high color already. - -If for some reason this transparent method isn't suitable to you (for instance -if your environment can't be configured to meet the |csapprox-requirements|, -or you need to work in Vim 6), another option is also available: using the -|:CSApproxSnapshot| command to create a new GUI/88-/256-color terminal -colorscheme. To use this command, a user would generally start GVim, choose a -colorscheme that sets up the desired colors, and then use |:CSApproxSnapshot| -to create a new colorscheme based on those colors that works in high color -terminals. This method is more flexible than the transparent mode and works -in more places, but also requires more user intervention, and makes it harder -to deal with colorschemes being updated and such. - *:CSApproxSnapshot* -The full syntax for the command is: > - :CSApproxSnapshot[!] /path/to/new/colorscheme -< For example: > - :CSApproxSnapshot ~/.vim/colors/foobar.vim -< -NOTE: The generated colorscheme will only work in 88- and 256-color terminals, - and in GVim. It will not work at all in a terminal with 16 or fewer - colors. There's just no reliable way to approximate down from - 16,777,216 colors to 16 colors, especially without there being any - standard for what those 16 colors look like other than 'orange-ish', - 'red-ish', etc. - -NOTE: Although :CSApproxSnapshot can be used in both GVim and terminal Vim, - the resulting colors might be slightly off when run from terminal Vim. - I can find no way around this; Vim internally sets different colors when - running in a terminal than running in the GUI, and there's no way for - terminal Vim to figure out what color would have been used in GVim. - -============================================================================== -2. Requirements *csapprox-requirements* - -For CSApprox to work, there are 2 major requirements that must be met. - -a) GUI support *csapprox-gui-support* *csapprox-+gui* - -If CSApprox is being used to adjust a scheme's colors transparently, then the -terminal "vim" binary that is being run must be built with GUI support (see -|csapprox-limitations| for an explanation). If |:CSApproxSnapshot| is being -used to create a terminal colorscheme for high color terminals, then the -"vim" binary being used to create the scheme must be built with +gui, but the -scheme can be used in terminal "vim" binaries that weren't built with +gui. -NOTE that creating snapshots with GVim will work better than making them with -Vim, and (obviously) all "gvim" binaries are built with +gui. - -Unfortunately, several Linux distributions only include GUI support in their -"gvim" binary, and not in their "vim" binary. You can check if GUI support is -available with the following command: - :echo has('gui') - -If that prints 0, the first thing to try would be searching for a larger vim -package provided by your distribution, like "vim-enhanced" on RedHat/CentOS -or "vim-gtk" or "vim-gnome" on Debian/Ubuntu. - -If you are unable to obtain a "vim" binary that includes GUI support, but -have a "gvim" binary available, you can probably launch Vim with GUI support -anyway by calling gvim with the |-v| flag in the shell: > - gvim -v - -If the above works, you can remove the need to call "gvim -v" instead of "vim" -all the time by creating a symbolic link from your "gvim" binary to "vim" -somewhere in your $PATH, for example: - sudo ln -s $(which gvim) $(which vim) - -If launching as "gvim -v" doesn"t work, and no package with GUI support is -available, you will need to compile Vim yourself and ensure that GUI support -is included to use CSApprox in its transparent mode, or create a snapshotted -scheme from GVim to use its snapshot mode. If this is inconvenient for you, -make sure that the Vim maintainer for your distribution knows it; they made a -conscious decision to build "vim" without +gui and "gvim" without terminal -support. - -b) Properly configured terminal *csapprox-terminal* - -As said above, many modern terminals support 88 or 256 colors, but most of -these default to setting $TERM to something generic (usually "xterm"). Since -Vim uses the value of the "colors" attribute for the current $TERM in terminfo -to figure out the number of colors used internally as 't_Co', this plugin will -either need for 't_Co' to be set to 88 or 256 in |vimrc|, or for $TERM to be -set to something that implies high color support. Possible choices include -"xterm-256color" for 256 color support and "rxvt-unicode" for 88 color -support. - *csapprox-palettes* -Also, there are three different 256 color cube palettes available and CSApprox -has no way to tell which you're using unless $TERM is set to something that is -specific to the terminal, like "konsole-256color" or "Eterm". Because of this, the -most sane behavior is assuming the user is using the most popular palette, -which is used by all but Konsole and Eterm, whenever $TERM is set to something -generic like "xterm" or "screen". You can override this default, however - -see |csapprox-configure|. - *csapprox-terminal-example* -To turn on high color support without fixing $TERM, you can change t_Co in -your .vimrc, and set either CSApprox_konsole or CSApprox_eterm if appropriate. -One way would be to put something like this into your |vimrc|: -> - if (&term == 'xterm' || &term =~? '^screen') && hostname() == 'my-machine' - " On my machine, I use Konsole with 256 color support - set t_Co=256 - let g:CSApprox_konsole = 1 - endif - -Gnome Terminal, as of the time that I am writing this, doesn't support having -the terminal emulator set $TERM to something adequately descriptive. In cases -like this, something like the following would be appropriate: -> - if &term =~ '^\(xterm\|screen\)$' && $COLORTERM == 'gnome-terminal' - set t_Co=256 - endif - -============================================================================== -3. Configuration *csapprox-configure* - -There are several global variables that can be set to configure the behavior -of CSApprox. They are listed roughly based on the likelihood that the end -user might want to know about them. - -g:CSApprox_loaded *g:CSApprox_loaded* - If set in your |vimrc|, CSApprox is not loaded. Has no effect on - snapshotted schemes. - -g:CSApprox_verbose_level *g:CSApprox_verbose_level* - When CSApprox is run, the 'verbose' option will be temporarily raised to - the value held in this variable unless it is already greater. The default - value is 1, which allows CSApprox to default to warning whenever something - is wrong, even if it is recoverable, but allows the user to quiet us if he - wants by changing this variable to 0. The most important messages will be - shown at verbosity level 1; some less important ones will be shown at - higher verbosity levels. Has no effect on snapshotted schemes. - -g:CSApprox_eterm *g:CSApprox_eterm* - If set to a non-zero number, CSApprox will use the Eterm palette when - 'term' is set to "xterm" or begins with "screen". Otherwise, the xterm - palette would be used. This also affects snapshotted schemes. - -g:CSApprox_konsole *g:CSApprox_konsole* - If set to a non-zero number, CSApprox will use the Konsole palette when - 'term' is set to "xterm" or begins with "screen". Otherwise, the xterm - palette would be used. This also affects snapshotted schemes. - -g:CSApprox_attr_map *g:CSApprox_attr_map* - Since some attributes (like 'guisp') can't be used in a terminal, and - others (like 'italic') are often very ugly in terminals, a generic way to - map between a requested attribute and another attribute is included. This - variable should be set to a Dictionary, where the keys are strings - representing the attributes the author wanted set, and the values are the - strings that the user wants set instead. If a value is '', it means the - attribute should just be ignored. The default is to replace 'italic' with - 'underline', and to use 'fg' instead of 'sp': > - let g:CSApprox_attr_map = { 'italic' : 'underline', 'sp' : 'fg' } -< - Your author prefers disabling bold and italic entirely, so uses this: > - let g:CSApprox_attr_map = { 'bold' : '', 'italic' : '', 'sp' : 'fg' } -< - - Note: This transformation is considered at the time a snapshotted scheme - is created, rather than when it is used. - - Note: You can only map an attribute representing a color to another - attribute representing a color; likewise with boolean attributes. - After all, sp -> bold and italic -> fg would be nonsensical. - - *g:CSApprox_hook_pre* *g:CSApprox_hook_{scheme}_pre* - *g:CSApprox_hook_post* *g:CSApprox_hook_{scheme}_post* -g:CSApprox_hook_pre -g:CSApprox_hook_post -g:CSApprox_hook_{scheme}_pre -g:CSApprox_hook_{scheme}_post *csapprox-hooks* - These variables provide a method for adjusting tweaking the approximation - algorithm, either for all schemes, or on a per scheme basis. For - snapshotted schemes, these will only take effect when the snapshotted - scheme is created, rather than when it is used. Each of these variables - may be set to either a String containing a command to be :execute'd, or a - List of such Strings. The _pre hooks are executed before any - approximations have been done. In order to affect the approximation at - this stage, you would need to change the gui colors for a group; the cterm - colors will then be approximated from those gui colors. Example: -> - let g:CSApprox_hook_pre = 'hi Comment guibg=#ffddff' -< - The advantage to tweaking the colors at this stage is that CSApprox will - handle approximating the given gui colors to the proper cterm colors, - regardless of the number of colors the terminal supports. The - disadvantage is that certain things aren't possible, including clearing - the background or foreground color for a group, selecting a precise cterm - color to be used, and overriding the mappings made by g:CSApprox_attr_map. - Another notable disadvantage is that overriding things at this level will - actually affect the gui colors, in case the :gui is used to start gvim - from the running vim instance. - - To overcome these disadvantages, the _post hooks are provided. These - hooks will be executed only after all approximations have been completed. - At this stage, in order to have changes appear the cterm* colors must be - modified. For example: - *csapprox-transparency* -> - let g:CSApprox_hook_post = ['hi Normal ctermbg=NONE ctermfg=NONE', - \ 'hi NonText ctermbg=NONE ctermfg=NONE' ] -< - Setting g:CSApprox_hook_post as shown above will clear the background of - the Normal and NonText groups, forcing the terminal's default background - color to be used instead, including any pseudotransparency done by that - terminal emulator. As noted, though, the _post functions do not allow - CSApprox to approximate the colors. This may be desired, but if this is - an inconvenience the function named by g:CSApprox_approximator_function - can still be called manually. For example: -> - let g:CSApprox_hook_post = 'exe "hi Comment ctermbg="' - \ . '. g:CSApprox_approximator_function(0xA0,0x50,0x35)' -< - The _{scheme}_ versions are exactly like their counterparts, except that - they will only be executed if the value of g:colors_name matches the - scheme name embedded in the variable name. They will be executed after - the corresponding hook without _{scheme}_, which provides a way to - override a less specific hook with a more specific one. For example, to - clear the Normal and NonText groups, but only for the colorscheme - "desert", one could do the following: -> - let g:CSApprox_hook_desert_post = ['hi Normal ctermbg=NONE ctermfg=NONE', - \ 'hi NonText ctermbg=NONE ctermfg=NONE' ] -< - One final example: If you want CSApprox to be active for nearly all - colorschemes, but want one or two particular schemes to be ignored, you - can take advantage of the CSApprox logic that skips over any color scheme - that is already high color by setting a color to a number above 255. Note - that most colors greater than 15 will work, but some will not - 256 should - always work. For instance, you can prevent CSApprox from modifying the - colors of the zellner colorscheme like this: -> - let g:CSApprox_hook_zellner_pre = 'hi _FakeGroup ctermbg=256' -< - NOTE: Any characters that would stop the string stored in g:colors_name - from being a valid variable name will be removed before the - _{scheme}_ hook is searched. Basically, this means that first all - characters that are neither alphanumeric nor underscore will be - removed, then any leading digits will be removed. So, for a - colorscheme named "123 foo_bar-baz456.vim", the hook searched for - will be, eg, g:CSApprox_hook_foo_barbaz456_post - -g:CSApprox_use_showrgb *g:CSApprox_use_showrgb* - By default, CSApprox will use a built in mapping of color names to values. - This optimization greatly helps speed, but means that colors addressed by - name might not match up perfectly between gvim (which uses the system's - real rgb database) and CSApprox (which uses the builtin database). To - force CSApprox to try the systemwide database first, and only fall back on - the builtin database if it isn't available, set this variable non-zero. - -g:CSApprox_approximator_function *g:CSApprox_approximator_function* - If the default approximation function doesn't work well enough, the user - (or another author wishing to extend this plugin) can write another - approximation function. This function should take three numbers, - representing r, g, and b in decimal, and return the index on the color - cube that best matches those colors. Assigning a |Funcref| to this - variable will override the default approximator with the one the Funcref - references. This option will take effect at the time a snapshotted scheme - is created, rather than when it's used. - -g:CSApprox_redirfallback *g:CSApprox_redirfallback* - Until Vim 7.2.052, there was a bug in the Vim function synIDattr() that - made it impossible to determine syntax information about the |guisp| - attribute. CSApprox includes a workaround for this problem, as well as a - test that ought to disable this workaround if synIDattr() works properly. - If this test should happen to give improper results somehow, the user can - force the behavior with this variable. When set to 1, the workaround will - always be used, and when set to 0, synIDattr() is blindly used. Needless - to say, if this automatic detection should ever fail, the author would - like to be notified! This option will take effect at the time a - snapshotted scheme is created, rather than when it's used. - -============================================================================== -4. Rationale/Design *csapprox-design* - -There is a wealth of colorschemes available for Vim. Unfortunately, since -traditional terminal emulators have only supported 2, 8 or 16 colors, -colorscheme authors have tended to avoid writing colorschemes for terminal -Vim, sticking instead to GVim. Even now that nearly every popular terminal -supports either 88 or 256 colors, few colorschemes are written to support -them. This may be because the terminal color codes are just numbers from 0 to -87 or 255 with no semantic meaning, or because the same number doesn't yield -the same color in all terminals, or simply because the colorscheme author -doesn't use the terminal and doesn't want to take the time to support -terminals. - -Whatever the reason, this leaves users of many modern terminal emulators in -the awkward position of having a terminal emulator that supports many colors, -but having very few colorschemes that were written to utilize those colors. - -This is where CSApprox comes in. It attempts to fill this void allowing GVim -colorschemes to be used in terminal Vim. CSApprox has two distinct modes of -operation. In the first mode, it attempts to make GVim colorschemes -transparently backwards compatible with terminal Vim in a high color terminal. -Basically, whenever a colorscheme is run it should set some colors for the -GUI, and this script will then run and attempt to figure out the closest color -available in the terminal's color palette to the color the scheme author asked -for. Unfortunately, this does not work well all the time, and it has some -limitations (see |csapprox-limitations|). Most of the time, however, this -gives a very close approximation to the GVim colors without requiring any -changes to the colorscheme, or any user interaction. It only requires that -the plugin be installed on the machine where Vim is being run, and that the -user's environment meets the needs specified at |csapprox-requirements|. In -the event that this doesn't work, a second option - using :CSApproxSnapshot -to create a new, 88-/256-color capable colorscheme - is available. - -Ideally, the aim is for CSApprox to be completely transparent to the user. -This is why the approach I take is entirely different from the GuiColorScheme -script, which will break on any but the simplest colorschemes. Unfortunately, -given the difficulty of determining exactly which terminal emulator the user -is running, and what features it supports, and which color palette it's using, -perfect transparency is difficult. So, to this end, I've attempted to default -to settings that make it unlikely that this script ever makes things worse -(this is why I chose not to override t_Co to 256 myself), and I've attempted -to make it easy to override my choice of defaults when necessary (through -g:CSApprox_approximator_function, g:CSApprox_konsole, g:CSApprox_eterm, -g:CSApprox_attr_map, etc). - -In the event that the transparent solution is undesirable, or that the user's -environment can't be configured to allow it (no GVim and no Vim with +gui, for -instance), |:CSApproxSnapshot| should provide a workable alternative - less -cool, and less flexible, but it will work in more environments, and the -snapshotted colorscheme will even work in Vim 6. - -If any of my design choices seem to be causing extra work with no real -advantages, though, I'd like to hear about it. Feel free to email me with any -improvements or complaints. - -============================================================================== -5. Known Bugs and Limitations *csapprox-limitations* - -GUI support is required for transparently adapting schemes. - - There is nothing I can do about this given my chosen design. CSApprox works - by being notified every time a colorscheme sets some GUI colors, then - approximating those colors to similar terminal colors. Unfortunately, when - Vim is not built with GUI support, it doesn't bother to store the GUI - colors, so querying for them fails. This leaves me completely unable to - tell what the colorscheme was trying to do. See |csapprox-+gui| for some - potential workarounds if your distribution doesn't provide a Vim with +gui. - -User intervention is sometimes required for information about the terminal. - - This is really an insurmountable problem. Unfortunately, most terminal - emulators default to setting $TERM to 'xterm', even when they're not really - compatible with an xterm. $TERM is really the only reliable way to - find anything at all out about the terminal you're running in, so there's no - way to know if the terminal supports 88 or 256 colors without either the - terminal telling me (using $TERM) or the user telling me (using 't_Co'). - Similarly, unless $TERM is set to something that implies a certain color - palette ought to be used, there's no way for me to know, so I'm forced to - default to the most common, xterm's palette, and allow the user to override - my choice with |g:CSApprox_konsole| or |g:CSApprox_eterm|. An example of - configuring Vim to work around a terminal where $TERM is set to something - generic without configuring the terminal properly is shown at - |csapprox-terminal-example|. - -Some colorschemes could fail to be converted if they try to be too smart. - - A colorscheme could decide to only set colors for the mode Vim is running - in. If a scheme only sets GUI colors when the GUI is running, instead of - using the usual approach of setting all colors and letting Vim choose which - to use, my approach falls apart. My method for figuring out what the scheme - author wants the scheme to look like absolutely depends upon him setting the - GUI colors in all modes. Fortunately, the few colorschemes that do this - seem to be, by and large, intended for 256 color terminals already, meaning - that skipping them is the proper behavior. Note that this will only affect - transparently adapted schemes and snapshots made from terminal Vim; - snapshots made from GVim are immune to this problem. - -Transparently adapting schemes is slow. - - For me, it takes Vim's startup time from 0.15 seconds to 0.35 seconds. This - is probably still acceptable, but it is definitely worth trying to cut down - on this time in future versions. Snapshotted schemes are faster to use, - since all of the hard evaluations are made when they're made instead of when - they're used. - - NOTE: As of CSApprox 3.50, the overhead is down to about 0.10 seconds on my - test machine. - -============================================================================== -6. Appendix - Terminals and Palettes *csapprox-terminal-list* - -What follows is a list of terminals known to have and known not to have high -color support. This list is certainly incomplete; feel free to contact me -with more to add to either list. - - *csapprox-terminals-good* -------------------------------- Good Terminals ------------------------------- - -The most recent versions of each of these terminals can be compiled with -either 88 or 256 color support. - - *csapprox-xterm* -xterm: - 256 color palette - Colors composed of: [ 0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF ] - Greys composed of: [ 0x08, 0x12, 0x1C, 0x26, 0x30, 0x3A, 0x44, 0x4E, - 0x58, 0x62, 0x6C, 0x76, 0x80, 0x8A, 0x94, 0x9E, - 0xA8, 0xB2, 0xBC, 0xC6, 0xD0, 0xDA, 0xE4, 0xEE ] - - *csapprox-urxvt* -rxvt-unicode (urxvt): - 88 colors by default (but a patch is available to use xterm's palette) - Colors composed of: [ 0x00, 0x8B, 0xCD, 0xFF ] - Greys composed of: [ 0x2E, 0x5C, 0x73, 0x8B, 0xA2, 0xB9, 0xD0, 0xE7 ] - - *csapprox-pterm* *csapprox-putty* -PuTTY (pterm; putty.exe): - 256 colors; same palette as xterm - - *csapprox-mrxvt* -Mrxvt (mrxvt): - 256 colors; same palette as xterm - - *csapprox-gnome-terminal* -GNOME Terminal (gnome-terminal): - 256 colors; same palette as xterm - - *csapprox-roxterm* -ROXTerm (roxterm): - 256 colors; same palette as xterm - - *csapprox-xfce4-terminal* -Terminal (xfce4-terminal): - 256 colors; same palette as xterm - - *csapprox-iterm.app* -iTerm (iTerm.app): - 256 colors; same palette as xterm - *csapprox-konsole* -Konsole (konsole): - 256 color palette - Colors composed of: [ 0x00, 0x33, 0x66, 0x99, 0xCC, 0xFF ] - Same greyscales as xterm - You should set the g:CSApprox_konsole variable unless $TERM begins with - 'konsole', case insensitive - - *csapprox-eterm* -eterm (Eterm): - 256 color palette - Colors composed of: [ 0x00, 0x2A, 0x55, 0x7F, 0xAA, 0xD4 ] - Same greyscales as xterm - You should set the g:CSApprox_eterm variable unless $TERM begins with - 'eterm', case insensitive - - *csapprox-screen* -GNU Screen (screen): - 256 color support. Internally, uses the xterm palette, but this is only - relevant when running screen inside a terminal with fewer than 256 colors, - in which case screen will attempt to map between its own 256 color cube - and the colors supported by the real terminal to the best of its ability, - in much the same way as CSApprox maps between GUI and terminal colors. - - *csapprox-terminals-bad* --------------------------------- Bad Terminals ------------------------------- -This is a list of terminals known _not_ to have high color support. If any of -these terminals have high color support added at some point in the future, -please tell me and I'll update this information. - - *csapprox-terminal.app* -Terminal.app (as of OS X 10.5.2) - - *csapprox-aterm* -aterm (as of version 1.00.01) - - *csapprox-xiterm* -xiterm (as of version 0.5) - - *csapprox-wterm* -wterm (as of version 6.2.9) - - *csapprox-mlterm* -mlterm (as of version 2.9.4) - - *csapprox-kterm* -kterm (as of version 6.2.0) - -============================================================================== -7. Changelog *csapprox-changelog* - - 3.50 01 Apr 2009 Fix a major regression that prevented the Eterm and - Konsole colors from being correctly snapshotted - - Fix a related bug causing incorrect terminal colors - after calling :CSApproxSnapshot - - Fix a bug causing black to be used instead of dark grey - - Have snapshots calculate g:colors_name programmatically - - Introduce many tweaks for better speed - - Clarify some things at :help csapprox-terminal-example - - Default to using our own list of rgb.txt colors rather - than searching, for performance. Add a new variable, - g:CSApprox_use_showrgb, which forces us to try finding - the colors using the "showrgb" program instead, and fall - back on our own list if it isn't available - - Remove g:CSApprox_extra_rgb_txt_dirs - not needed in - light of the above change - - 3.05 31 Jan 2009 Fix a harmless "Undefined variable" error in - :CSApproxSnapshot - - Fix a behavioral bug when dumping out colors defined - external to the scheme. - - 3.00 21 Jan 2009 Update the docs for better info on :CSApproxSnapshot - - Allow snapshotted schemes to work on Vim 6, and work - properly in Konsole and Eterm (thanks David Majnemer!) - - Fix a bug causing a syntax error when using GVim while - CSApprox was loaded. (thanks again, David Majnemer!) - - 2.00 14 Dec 2008 Add a hooks system, allowing users to specify a command - to run, either before or after the approximation - algorithm is run, for all schemes or one specific one. - - Also rewrite :CSApproxSnapshot to be more maintainable - and less of a hack, and fix several bugs that it - contained. - - 1.50 19 Nov 2008 Add CSApproxSnapshot command, as an alternative solution - when the user has gvim or a vim with gui support, but - sometimes needs to use a vim without gui support. - - 1.10 28 Oct 2008 Enable running on systems with no rgb.txt (Penn Su) - Begin distributing a copy of rgb.txt with CSApprox - - 1.00 04 Oct 2008 First public release - - 0.90 14 Sep 2008 Initial beta release - -============================================================================== -8. Contact Info *csapprox-author* - -Your author, a Vim nerd with some free time, was sick of seeing terminals -always get the short end of the stick. He'd like to be notified of any -problems you find - after all, he took the time to write all this lovely -documentation, and this plugin, which took more time than you could possibly -imagine to get working transparently for every colorscheme he could get his -hands on. You can contact him with any problems or praises at mjw@drexel.edu - -============================================================================== -vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: diff --git a/files/.vim/doc/imaps.txt b/files/.vim/doc/imaps.txt deleted file mode 100644 index 087b3db..0000000 --- a/files/.vim/doc/imaps.txt +++ /dev/null @@ -1,116 +0,0 @@ - IMAP -- A fluid replacement for :imap - *imaps.txt* - Srinath Avadhanula <srinath AT fastmail DOT fm> - - - - Abstract - ======== -This plugin provides a function IMAP() which emulates vims |:imap| function. The -motivation for providing this plugin is that |:imap| suffers from problems -which get increasingly annoying with a large number of mappings. - -Consider an example. If you do > - imap lhs something - - -then a mapping is set up. However, there will be the following problems: -1. The 'ttimeout' option will generally limit how easily you can type the lhs. - if you type the left hand side too slowly, then the mapping will not be - activated. - -2. If you mistype one of the letters of the lhs, then the mapping is deactivated - as soon as you backspace to correct the mistake. - -3. The characters in lhs are shown on top of each other. This is fairly - distracting. This becomes a real annoyance when a lot of characters initiate - mappings. - -This script provides a function IMAP() which does not suffer from these -problems. - - - - *imaps.txt-toc* -|im_1| Using IMAP - -================================================================================ -Viewing this file - -This file can be viewed with all the sections and subsections folded to ease -navigation. By default, vim does not fold help documents. To create the folds, -press za now. The folds are created via a foldexpr which can be seen in the -last section of this file. - -See |usr_28.txt| for an introduction to folding and |fold-commands| for key -sequences and commands to work with folds. - -================================================================================ -Using IMAP *im_1* *imaps-usage* - - - -Each call to IMAP is made using the syntax: > - call IMAP (lhs, rhs, ft [, phs, phe]) - - -This is equivalent to having <lhs> map to <rhs> for all files of type <ft>. - -Some characters in the <rhs> have special meaning which help in cursor placement -as described in |imaps-placeholders|. The optional arguments define these -special characters. - -Example One: > - call IMAP ("bit`", "\\begin{itemize}\<cr>\\item <++>\<cr>\\end{itemize}<++>", "tex") - - -This effectively sets up the map for "bit`" whenever you edit a latex file. When -you type in this sequence of letters, the following text is inserted: > - \begin{itemize} - \item * - \end{itemize}<++> - -where * shows the cursor position. The cursor position after inserting the text -is decided by the position of the first "place-holder". Place holders are -special characters which decide cursor placement and movement. In the example -above, the place holder characters are <+ and +>. After you have typed in the -item, press <C-j> and you will be taken to the next set of <++>'s. Therefore by -placing the <++> characters appropriately, you can minimize the use of movement -keys. - -Set g:Imap_UsePlaceHolders to 0 to disable placeholders altogether. - -Set g:Imap_PlaceHolderStart and g:Imap_PlaceHolderEnd to something else if you -want different place holder characters. Also, b:Imap_PlaceHolderStart and -b:Imap_PlaceHolderEnd override the values of g:Imap_PlaceHolderStart and -g:Imap_PlaceHolderEnd respectively. This is useful for setting buffer specific -place holders. - -Example Two: You can use the <C-r> command to insert dynamic elements such as -dates. > - call IMAP ('date`', "\<c-r>=strftime('%b %d %Y')\<cr>", '') - - - -With this mapping, typing date` will insert the present date into the file. - -================================================================================ -About this file - -This file was created automatically from its XML variant using db2vim. db2vim is -a python script which understands a very limited subset of the Docbook XML 4.2 -DTD and outputs a plain text file in vim help format. - -db2vim can be obtained via anonymous CVS from sourceforge.net. Use - -cvs -d:pserver:anonymous@cvs.vim-latex.sf.net:/cvsroot/vim-latex co db2vim - -Or you can visit the web-interface to sourceforge CVS at: -http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vim-latex/db2vim/ - -The following modelines should nicely fold up this help manual. - -vim:ft=help:fdm=expr:nowrap -vim:foldexpr=getline(v\:lnum-1)=~'-\\{80}'?'>2'\:getline(v\:lnum-1)=~'=\\{80}'?'>1'\:getline(v\:lnum)=~'=\\{80}'?'0'\:getline(v\:lnum)=~'-\\{80}'?'1'\:'=' -vim:foldtext=substitute(v\:folddashes.substitute(getline(v\:foldstart),'\\s*\\*.*',"",""),'^--','--\ \ \ \ ','') -================================================================================ diff --git a/files/.vim/doc/imaps.txt.gz b/files/.vim/doc/imaps.txt.gz Binary files differdeleted file mode 100644 index fbb8ea8..0000000 --- a/files/.vim/doc/imaps.txt.gz +++ /dev/null diff --git a/files/.vim/doc/matchit.txt b/files/.vim/doc/matchit.txt deleted file mode 100644 index 8a3a96e..0000000 --- a/files/.vim/doc/matchit.txt +++ /dev/null @@ -1,406 +0,0 @@ -*matchit.txt* Extended "%" matching - -For instructions on installing this file, type - :help matchit-install -inside Vim. - -For Vim version 6.3. Last change: 2007 Aug 29 - - - VIM REFERENCE MANUAL by Benji Fisher - -*matchit* *matchit.vim* - -1. Extended matching with "%" |matchit-intro| -2. Activation |matchit-activate| -3. Configuration |matchit-configure| -4. Supporting a New Language |matchit-newlang| -5. Known Bugs and Limitations |matchit-bugs| - -The functionality mentioned here is a plugin, see |add-plugin|. -This plugin is only available if 'compatible' is not set. -You can avoid loading this plugin by setting the "loaded_matchit" variable -in your |vimrc| file: > - :let loaded_matchit = 1 - -{Vi does not have any of this} - -============================================================================== -1. Extended matching with "%" *matchit-intro* - - *matchit-%* -% Cycle forward through matching groups, such as "if", "else", "endif", - as specified by |b:match_words|. - - *g%* *v_g%* *o_g%* -g% Cycle backwards through matching groups, as specified by - |b:match_words|. For example, go from "if" to "endif" to "else". - - *[%* *v_[%* *o_[%* -[% Go to [count] previous unmatched group, as specified by - |b:match_words|. Similar to |[{|. - - *]%* *v_]%* *o_]%* -]% Go to [count] next unmatched group, as specified by - |b:match_words|. Similar to |]}|. - - *v_a%* -a% In Visual mode, select the matching group, as specified by - |b:match_words|, containing the cursor. Similar to |v_a[|. - A [count] is ignored, and only the first character of the closing - pattern is selected. - -In Vim, as in plain vi, the percent key, |%|, jumps the cursor from a brace, -bracket, or paren to its match. This can be configured with the 'matchpairs' -option. The matchit plugin extends this in several ways: - - You can match whole words, such as "if" and "endif", not just - single characters. You can also specify a |regular-expression|. - You can define groups with more than two words, such as "if", - "else", "endif". Banging on the "%" key will cycle from the "if" to - the first "else", the next "else", ..., the closing "endif", and back - to the opening "if". Nested structures are skipped. Using |g%| goes - in the reverse direction. - By default, words inside comments and strings are ignored, unless - the cursor is inside a comment or string when you type "%". If the - only thing you want to do is modify the behavior of "%" so that it - behaves this way, you do not have to define |b:match_words|, since the - script uses the 'matchpairs' option as well as this variable. - -See |matchit-details| for details on what the script does, and |b:match_words| -for how to specify matching patterns. - -MODES: *matchit-modes* *matchit-v_%* *matchit-o_%* - -Mostly, % and related motions (|g%| and |[%| and |]%|) work just like built-in -|motion| commands in |Operator-pending| and |Visual| modes. However, you -cannot make these motions |linewise| or |characterwise|, since the |:omap|s -that define them start with "v" in order to make the default behavior -inclusive. (See |o_v|.) In other words, "dV%" will not work. The -work-around is to go through Visual mode: "V%d" will work. - -LANGUAGES: *matchit-languages* - -Currently, the following languages are supported: Ada, ASP with VBS, Csh, -DTD, Entity, Essbase, Fortran, HTML, JSP (same as HTML), LaTeX, Lua, Pascal, -SGML, Shell, Tcsh, Vim, XML. Other languages may already have support via -the default |filetype-plugin|s in the standard vim distribution. - -To support a new language, see |matchit-newlang| below. - -DETAILS: *matchit-details* *matchit-parse* - -Here is an outline of what matchit.vim does each time you hit the "%" key. If -there are |backref|s in |b:match_words| then the first step is to produce a -version in which these back references have been eliminated; if there are no -|backref|s then this step is skipped. This step is called parsing. For -example, "\(foo\|bar\):end\1" is parsed to yield -"\(foo\|bar\):end\(foo\|bar\)". This can get tricky, especially if there are -nested groups. If debugging is turned on, the parsed version is saved as -|b:match_pat|. - - *matchit-choose* -Next, the script looks for a word on the current line that matches the pattern -just constructed. It includes the patterns from the 'matchpairs' option. -The goal is to do what you expect, which turns out to be a little complicated. -The script follows these rules: - - Insist on a match that ends on or after the cursor. - Prefer a match that includes the cursor position (that is, one that - starts on or before the cursor). - Prefer a match that starts as close to the cursor as possible. - If more than one pattern in |b:match_words| matches, choose the one - that is listed first. - -Examples: - - Suppose you > - :let b:match_words = '<:>,<tag>:</tag>' -< and hit "%" with the cursor on or before the "<" in "a <tag> is born". - The pattern '<' comes first, so it is preferred over '<tag>', which - also matches. If the cursor is on the "t", however, then '<tag>' is - preferred, because this matches a bit of text containing the cursor. - If the two groups of patterns were reversed then '<' would never be - preferred. - - Suppose you > - :let b:match_words = 'if:end if' -< (Note the space!) and hit "%" with the cursor at the end of "end if". - Then "if" matches, which is probably not what you want, but if the - cursor starts on the "end " then "end if" is chosen. (You can avoid - this problem by using a more complicated pattern.) - -If there is no match, the cursor does not move. (Before version 1.13 of the -script, it would fall back on the usual behavior of |%|). If debugging is -turned on, the matched bit of text is saved as |b:match_match| and the cursor -column of the start of the match is saved as |b:match_col|. - -Next, the script looks through |b:match_words| (original and parsed versions) -for the group and pattern that match. If debugging is turned on, the group is -saved as |b:match_ini| (the first pattern) and |b:match_tail| (the rest). If -there are |backref|s then, in addition, the matching pattern is saved as -|b:match_word| and a table of translations is saved as |b:match_table|. If -there are |backref|s, these are determined from the matching pattern and -|b:match_match| and substituted into each pattern in the matching group. - -The script decides whether to search forwards or backwards and chooses -arguments for the |searchpair()| function. Then, the cursor is moved to the -start of the match, and |searchpair()| is called. By default, matching -structures inside strings and comments are ignored. This can be changed by -setting |b:match_skip|. - -============================================================================== -2. Activation *matchit-activate* - -You can use this script as a plugin, by copying it to your plugin directory. -See |add-global-plugin| for instructions. You can also add a line to your -|vimrc| file, such as > - :source $VIMRUNTIME/macros/matchit.vim -or > - :runtime macros/matchit.vim -Either way, the script should start working the next time you start up Vim. - -(Earlier versions of the script did nothing unless a |buffer-variable| named -|b:match_words| was defined. Even earlier versions contained autocommands -that set this variable for various file types. Now, |b:match_words| is -defined in many of the default |filetype-plugin|s instead.) - -For a new language, you can add autocommands to the script or to your vimrc -file, but the recommended method is to add a line such as > - let b:match_words = '\<foo\>:\<bar\>' -to the |filetype-plugin| for your language. See |b:match_words| below for how -this variable is interpreted. - -TROUBLESHOOTING *matchit-troubleshoot* - -The script should work in most installations of Vim. It may not work if Vim -was compiled with a minimal feature set, for example if the |+syntax| option -was not enabled. If your Vim has support for syntax compiled in, but you do -not have |syntax| highlighting turned on, matchit.vim should work, but it may -fail to skip matching groups in comments and strings. If the |filetype| -mechanism is turned off, the |b:match_words| variable will probably not be -defined automatically. - -============================================================================== -3. Configuration *matchit-configure* - -There are several variables that govern the behavior of matchit.vim. Note -that these are variables local to the buffer, not options, so use |:let| to -define them, not |:set|. Some of these variables have values that matter; for -others, it only matters whether the variable has been defined. All of these -can be defined in the |filetype-plugin| or autocommand that defines -|b:match_words| or "on the fly." - -The main variable is |b:match_words|. It is described in the section below on -supporting a new language. - - *MatchError* *matchit-hl* *matchit-highlight* -MatchError is the highlight group for error messages from the script. By -default, it is linked to WarningMsg. If you do not want to be bothered by -error messages, you can define this to be something invisible. For example, -if you use the GUI version of Vim and your command line is normally white, you -can do > - :hi MatchError guifg=white guibg=white -< - *b:match_ignorecase* -If you > - :let b:match_ignorecase = 1 -then matchit.vim acts as if 'ignorecase' is set: for example, "end" and "END" -are equivalent. If you > - :let b:match_ignorecase = 0 -then matchit.vim treats "end" and "END" differently. (There will be no -b:match_infercase option unless someone requests it.) - - *b:match_debug* -Define b:match_debug if you want debugging information to be saved. See -|matchit-debug|, below. - - *b:match_skip* -If b:match_skip is defined, it is passed as the skip argument to -|searchpair()|. This controls when matching structures are skipped, or -ignored. By default, they are ignored inside comments and strings, as -determined by the |syntax| mechanism. (If syntax highlighting is turned off, -nothing is skipped.) You can set b:match_skip to a string, which evaluates to -a non-zero, numerical value if the match is to be skipped or zero if the match -should not be skipped. In addition, the following special values are -supported by matchit.vim: - s:foo becomes (current syntax item) =~ foo - S:foo becomes (current syntax item) !~ foo - r:foo becomes (line before cursor) =~ foo - R:foo becomes (line before cursor) !~ foo -(The "s" is meant to suggest "syntax", and the "r" is meant to suggest -"regular expression".) - -Examples: - - You can get the default behavior with > - :let b:match_skip = 's:comment\|string' -< - If you want to skip matching structures unless they are at the start - of the line (ignoring whitespace) then you can > - :let b:match_skip = 'R:^\s*' -< Do not do this if strings or comments can span several lines, since - the normal syntax checking will not be done if you set b:match_skip. - - In LaTeX, since "%" is used as the comment character, you can > - :let b:match_skip = 'r:%' -< Unfortunately, this will skip anything after "\%", an escaped "%". To - allow for this, and also "\\%" (an excaped backslash followed by the - comment character) you can > - :let b:match_skip = 'r:\(^\|[^\\]\)\(\\\\\)*%' -< - See the $VIMRUNTIME/ftplugin/vim.vim for an example that uses both - syntax and a regular expression. - -============================================================================== -4. Supporting a New Language *matchit-newlang* - *b:match_words* -In order for matchit.vim to support a new language, you must define a suitable -pattern for |b:match_words|. You may also want to set some of the -|matchit-configure| variables, as described above. If your language has a -complicated syntax, or many keywords, you will need to know something about -Vim's |regular-expression|s. - -The format for |b:match_words| is similar to that of the 'matchpairs' option: -it is a comma (,)-separated list of groups; each group is a colon(:)-separated -list of patterns (regular expressions). Commas and backslashes that are part -of a pattern should be escaped with backslashes ('\:' and '\,'). It is OK to -have only one group; the effect is undefined if a group has only one pattern. -A simple example is > - :let b:match_words = '\<if\>:\<endif\>,' - \ . '\<while\>:\<continue\>:\<break\>:\<endwhile\>' -(In Vim regular expressions, |\<| and |\>| denote word boundaries. Thus "if" -matches the end of "endif" but "\<if\>" does not.) Then banging on the "%" -key will bounce the cursor between "if" and the matching "endif"; and from -"while" to any matching "continue" or "break", then to the matching "endwhile" -and back to the "while". It is almost always easier to use |literal-string|s -(single quotes) as above: '\<if\>' rather than "\\<if\\>" and so on. - -Exception: If the ":" character does not appear in b:match_words, then it is -treated as an expression to be evaluated. For example, > - :let b:match_words = 'GetMatchWords()' -allows you to define a function. This can return a different string depending -on the current syntax, for example. - -Once you have defined the appropriate value of |b:match_words|, you will -probably want to have this set automatically each time you edit the -appropriate file type. The recommended way to do this is by adding the -definition to a |filetype-plugin| file. - -Tips: Be careful that your initial pattern does not match your final pattern. -See the example above for the use of word-boundary expressions. It is usually -better to use ".\{-}" (as many as necessary) instead of ".*" (as many as -possible). See |\{-|. For example, in the string "<tag>label</tag>", "<.*>" -matches the whole string whereas "<.\{-}>" and "<[^>]*>" match "<tag>" and -"</tag>". - - *matchit-spaces* *matchit-s:notend* -If "if" is to be paired with "end if" (Note the space!) then word boundaries -are not enough. Instead, define a regular expression s:notend that will match -anything but "end" and use it as follows: > - :let s:notend = '\%(\<end\s\+\)\@<!' - :let b:match_words = s:notend . '\<if\>:\<end\s\+if\>' -< *matchit-s:sol* -This is a simplified version of what is done for Ada. The s:notend is a -|script-variable|. Similarly, you may want to define a start-of-line regular -expression > - :let s:sol = '\%(^\|;\)\s*' -if keywords are only recognized after the start of a line or after a -semicolon (;), with optional white space. - - *matchit-backref* *matchit-\1* -In any group, the expressions |\1|, |\2|, ..., |\9| refer to parts of the -INITIAL pattern enclosed in |\(|escaped parentheses|\)|. These are referred -to as back references, or backrefs. For example, > - :let b:match_words = '\<b\(o\+\)\>:\(h\)\1\>' -means that "bo" pairs with "ho" and "boo" pairs with "hoo" and so on. Note -that "\1" does not refer to the "\(h\)" in this example. If you have -"\(nested \(parentheses\)\) then "\d" refers to the d-th "\(" and everything -up to and including the matching "\)": in "\(nested\(parentheses\)\)", "\1" -refers to everything and "\2" refers to "\(parentheses\)". If you use a -variable such as |s:notend| or |s:sol| in the previous paragraph then remember -to count any "\(" patterns in this variable. You do not have to count groups -defined by |\%(\)|. - -It should be possible to resolve back references from any pattern in the -group. For example, > - :let b:match_words = '\(foo\)\(bar\):more\1:and\2:end\1\2' -would not work because "\2" cannot be determined from "morefoo" and "\1" -cannot be determined from "andbar". On the other hand, > - :let b:match_words = '\(\(foo\)\(bar\)\):\3\2:end\1' -should work (and have the same effect as "foobar:barfoo:endfoobar"), although -this has not been thoroughly tested. - -You can use |zero-width| patterns such as |\@<=| and |\zs|. (The latter has -not been thouroughly tested in matchit.vim.) For example, if the keyword "if" -must occur at the start of the line, with optional white space, you might use -the pattern "\(^\s*\)\@<=if" so that the cursor will end on the "i" instead of -at the start of the line. For another example, if HTML had only one tag then -one could > - :let b:match_words = '<:>,<\@<=tag>:<\@<=/tag>' -so that "%" can bounce between matching "<" and ">" pairs or (starting on -"tag" or "/tag") between matching tags. Without the |\@<=|, the script would -bounce from "tag" to the "<" in "</tag>", and another "%" would not take you -back to where you started. - -DEBUGGING *matchit-debug* *:MatchDebug* - -If you are having trouble figuring out the appropriate definition of -|b:match_words| then you can take advantage of the same information I use when -debugging the script. This is especially true if you are not sure whether -your patterns or my script are at fault! To make this more convenient, I have -made the command :MatchDebug, which defines the variable |b:match_debug| and -creates a Matchit menu. This menu makes it convenient to check the values of -the variables described below. You will probably also want to read -|matchit-details| above. - -Defining the variable |b:match_debug| causes the script to set the following -variables, each time you hit the "%" key. Several of these are only defined -if |b:match_words| includes |backref|s. - - *b:match_pat* -The b:match_pat variable is set to |b:match_words| with |backref|s parsed. - *b:match_match* -The b:match_match variable is set to the bit of text that is recognized as a -match. - *b:match_col* -The b:match_col variable is set to the cursor column of the start of the -matching text. - *b:match_wholeBR* -The b:match_wholeBR variable is set to the comma-separated group of patterns -that matches, with |backref|s unparsed. - *b:match_iniBR* -The b:match_iniBR variable is set to the first pattern in |b:match_wholeBR|. - *b:match_ini* -The b:match_ini variable is set to the first pattern in |b:match_wholeBR|, -with |backref|s resolved from |b:match_match|. - *b:match_tail* -The b:match_tail variable is set to the remaining patterns in -|b:match_wholeBR|, with |backref|s resolved from |b:match_match|. - *b:match_word* -The b:match_word variable is set to the pattern from |b:match_wholeBR| that -matches |b:match_match|. - *b:match_table* -The back reference '\'.d refers to the same thing as '\'.b:match_table[d] in -|b:match_word|. - -============================================================================== -5. Known Bugs and Limitations *matchit-bugs* - -Just because I know about a bug does not mean that it is on my todo list. I -try to respond to reports of bugs that cause real problems. If it does not -cause serious problems, or if there is a work-around, a bug may sit there for -a while. Moral: if a bug (known or not) bothers you, let me know. - -The various |:vmap|s defined in the script (%, |g%|, |[%|, |]%|, |a%|) may -have undesired effects in Select mode |Select-mode-mapping|. At least, if you -want to replace the selection with any character in "ag%[]" there will be a -pause of |'updatetime'| first. - -It would be nice if "\0" were recognized as the entire pattern. That is, it -would be nice if "foo:\end\0" had the same effect as "\(foo\):\end\1". I may -try to implement this in a future version. (This is not so easy to arrange as -you might think!) - -============================================================================== -vim:tw=78:fo=tcq2: diff --git a/files/.vim/doc/project.txt b/files/.vim/doc/project.txt deleted file mode 100644 index 8f85c23..0000000 --- a/files/.vim/doc/project.txt +++ /dev/null @@ -1,710 +0,0 @@ -*project.txt* Plugin for managing multiple projects with multiple sources - For Vim version 6.x and Vim version 7.x. - Last Change: Fri 13 Oct 2006 10:20:13 AM EDT - - - By Aric Blumer - aricvim email-at-sign charter.net - - *project* *project-plugin* - Contents: - - Commands...................|project-invoking| - Inheritance.............|project-inheritance| - Mappings...................|project-mappings| - Adding Mappings.....|project-adding-mappings| - Settings...................|project-settings| - Example File................|project-example| - Tips...........................|project-tips| - - -You can use this plugin's basic functionality to set up a list of -frequently-accessed files for easy navigation. The list of files will be -displayed in a window on the left side of the Vim window, and you can press -<Return> or double-click on filenames in the list to open the files. I find -this easier to use than having to navigate a directory hierarchy with the -|file-explorer|. - -You can also instruct the Plugin to change to a directory and to run Vim -scripts when you select a file. These scripts can, for example, modify the -environment to include compilers in $PATH. This makes it very easy to use -quickfix with multiple projects that use different environments. - -Other features include: - o Loading/Unloading all the files in a Project (\l, \L, \w, and \W) - o Grepping all the files in a Project (\g and \G) - o Running a user-specified script on a file (can be used to launch an - external program on the file) (\1 through \9) - o Running a user-specified script on all the files in a Project - (\f1-\f9 and \F1-\F9) - o High degree of user-configurability - o Also works with |netrw| using the XXXX://... notation where XXXX is - ftp, rcp, scp, or http. - -All of this is specified within a simple text file and a few global variables -in your vimrc file. - -You must set 'nocompatible' in your |vimrc| file to use this plugin. You can -stop the plugin from being loaded by setting the "loaded_project" variable: > - :let loaded_project = 1 - - -============================================================================== -COMMANDS *project-invoking* - -You can use the plugin by placing it in your plugin directory (e.g., -~/.vim/plugin). See |add-global-plugin|. When you start vim the next time, you -then enter the command > - :Project -or > - :Project {file} - -If you do not specify the filename, $HOME/.vimprojects is used. - -To have Vim come up with the Project Window enabled automatically (say, from a -GUI launcher), run Vim like this: [g]vim +Project - -Note that you can invoke :Project on only one file at a time. If you wish to -change the Project File, do a :bwipe in the Project Buffer, then re-invoke the -Plugin as described above. - -Several Projects can be kept and displayed in the same file, each in a fold -delimited by { and } (see |fold.txt|). There can be any number of nested -folds to provide you with a Project hierarchy. Any line without a { or a } in -the file is considered to be a filename. Blank lines are ignored, and any -text after a # is ignored. - -Because the plugin uses standard Vim folds, you can use any of the -|fold-commands|. You can double-click on the first line of a fold to open and -close it. You can select a file to open by putting the cursor on its name and -pressing <Return> or by double-clicking on it. The plugin will create a new -window to the right or use the |CTRL-W_p| equivalent if it exists. - - *project-syntax* -Each Project Entry has this form: - -project_entry ::= - <Description>={projpath} [{options}] { - [ filename ] - [ project_entry ] - } - -{options} is one or more of the following (on the same line): - CD={path} - in={filename} - out={filename} - filter="{pat}" - flags={flag} - -Note that a project_entry can reside within a project_entry. This allows you -to set up a hierarchy within your Project. - -The <Description> will be displayed in the foldtext and cannot contain "=". -There can be no space character directly on either side of the =. - -The {projpath} is the path in which the files listed in the Project's fold -will be found, and it may contain environment variables. If the path is a -relative path, then the plugin constructs the whole path from the Project's -parent, grandparent, etc., all the way up the hierarchy. An outermost -project_entry must have an absolute path. See the |project-inheritance| -example below. {projpath} may contain spaces, but they must be escaped like -normal Vim escapes. Here are two examples of the same directory: -> - Example=/my/directory/with\ spaces { - } - Example="/my/directory/with spaces" { - } - -I recommend this for Windows®: > - - Example="c:\My Documents" { - } - -But Vim is smart enough to do this, too: > - - Example=c:\My\ Documents { - } - -CD= provides the directory that Vim will change to when you select a file in -that fold (using |:cd|). This allows you, for example, to enter |:make| to use -the local Makefile. A CD=. means that Vim will make {projpath} or its -inherited equivalent the current working directory. When CD is omitted, the -directory is not changed. There can be no space on either side of the =. The -value of CD can also be a relative path from a parent's CD. See the -|project-inheritance| example below. This directive is ignored for |netrw| -projects. Spaces are allowed in the path as for {projpath}. - -in= and out= provide the means to run arbitrary Vim scripts whenever you enter -or leave a file's buffer (see the |BufEnter| and |BufLeave| autocommand -events). The idea is to have a Vim script that sets up or tears down the -environment for the Project like this: - -in.vim: > - let $PROJECT_HOME='~/my_project' - " Put the compiler in $PATH - if $PATH !~ '/path/to/my/compiler' - let $PATH=$PATH.':/path/to/my/compiler' - endif - -out.vim: > - " Remove compiler from $PATH - if $PATH =~ '/path/to/my/compiler' - let $PATH=substitute($PATH, ':/path/to/my/compiler', '', 'g') - endif - -Then you can use :make with the proper environment depending on what file you -are currently editing. If the path to the script is relative, then it is -relative from {projpath}. These directives are inherited by Subprojects -unless the Subproject specifies its own. For use with |netrw| projects, the -paths specified for in= and out= must be absolute and local. - -filter= specifies a |glob()| file pattern. It is used to regenerate the list -of files in a Project fold when using the \r (<LocalLeader>r) map in the -Project Window. The filter value must be in quotes because it can contain -multiple file patterns. If filter is omitted, then the * pattern is used. -There can be no space on either side of the =. A Subproject will inherit the -filter of its parent unless it specifies its own filter. - -flags= provides the means to enable/disable features for a particular fold. -The general mnemonic scheme is for lower case to turn something off and upper -case to turn something on. {flag} can contain any of the following -characters: - - flag Description ~ - - l Turn off recursion for this fold for \L. Subfolds are also - blocked from the recursion. - - r Turn off refresh. When present, do not refresh this fold when - \r or \R is used. This does not affect subfold recursion. - - S Turn on sorting for refresh and create. - - s Turn off sorting for refresh and create. - - T Turn on top gravity. Forces folds to the top of the current - fold when refreshing. It has the same affect as the 'T' flag - in g:proj_flags, but controls the feature on a per-fold basis. - - t Turn off top gravity. Forces folds to the bottom of the - current fold when refreshing. - - w Turn off recursion for this fold for \W. Subfolds are also - blocked from the recursion. - - -Flags are not inherited by Subprojects. - -Any text outside a fold is ignored. - - -============================================================================== -INHERITANCE *project-inheritance* - -It's best to show inheritance by comparing these two Project Files: -> - Parent=~/my_project CD=. filter="Make* *.mk" flags=r { - Child1=c_code { - } - Child2=include CD=. filter="*.h" { - } - } - -Child1's path is "~/my_project/c_code" because ~/my_project is inherited. It -also inherits the CD from Parent. Since Parent has CD=., the Parent's cwd is -"~/my_project". Child1 therefore inherits a CD of "~/my_project". Finally, -Child1 inherits the filter from Parent. The flags are not inherited. - -Child2 only inherits the "~/my_project" from Parent. - -Thus, the example above is exactly equivalent to this: -> - Parent=~/my_project CD=. filter="Make* *.mk" flags=r { - Child1=~/my_project/c_code CD=~/my_project filter="Make* *.mk" { - } - Child2=~/my_project/include CD=~/my_project/include filter="*.h" { - } - } - -(For a real Project, Child1 would not want to inherit its parent's filter, but -this example shows the concept.) You can always enter \i to display what the -cursor's project inherits. - - -============================================================================== -MAPPINGS *project-mappings* - -Map Action ~ - -\r Refreshes the Project fold that the cursor is in by placing in the - fold all the files that match the filter. The Project is refreshed - using an indent of one space for every foldlevel in the hierarchy. - - You may place a "# pragma keep" (without the quotes) at the end of a - line, and the file entry on that line will not be removed when you - refresh. This is useful, for example, when you have . as an entry so - you can easily browse the directory. - - Note that this mapping is actually <LocalLeader>r, and the default of - |<LocalLeader>| is \. - - This does not work for Projects using |netrw|. - -\R Executes \r recursively in the current fold and all folds below. - This does not work for Projects using |netrw|. - -\c Creates a Project fold entry. It asks for the description, the path - to the files, the CD parameter, and the filename |glob()| pattern. - From this information, it will create the Project Entry below the - cursor. - - This does not work for Projects using |netrw|. - -\C Creates a Project fold entry like \c, but recursively includes all the - subdirectories. - -<Return> - Select a file to open in the |CTRL-W_p| window or in a new window. If - the cursor is on a fold, open or close it. - -<S-Return> -\s - Same as <Return> but horizontally split the target window. - <LocalLeader>s is provided for those terminals that don't recognize - <S-Return>. - -\S - Load all files in a project by doing horizontal splits. - -<C-Return> -\o - Same as <Return> but ensure that the opened file is the only other - window. <LocalLeader>o is provided for those terminals that don't - recognize <C-Return>. - -<M-Return> -\v - Same as <Return> but only display the file--the cursor stays in the - Project Window. - -<2-LeftMouse> - (Double-click) If on a closed fold, open it. If on an open fold - boundary, close it. If on a filename, open the file in the |CTRL-W_p| - window or in a new window. - -<S-2-LeftMouse> - Same as <S-Return>. - -<C-2-LeftMouse> - Same as <C-Return>. - -<RightMouse> - Increase the width of the Project Window by g:proj_window_increment or - toggle between a width of - g:proj_window_width + g:proj_window_increment - and - g:proj_window_width. - - Whether you toggle or monotonically increase the width is determined - by the 't' flag of the g:proj_flags variable (see |project-flags|). - - Note that a Right Mouse click will not automatically place the cursor - in the Project Window if it is in a different window. The window will - go back to the g:proj_window_width width when you leave the window. - -<space> Same as <RightMouse> - -<CTRL-Up> -\<Up> - Move the text or fold under the cursor up one row. This may not work - in a terminal because the terminal is unaware of this key combination. - <LocalLeader><Up> is provided for those terminals that don't recognize - <C-Up>. - - -<CTRL-Down> -\<Down> - Move the text or fold under the cursor down one row. This may not work - in a terminal because the terminal is unaware of this key combination. - <LocalLeader><Down> is provided for those terminals that don't - recognize <C-Down>. - -\i Show in the status line the completely resolved and inherited - parameters for the fold the cursor is in. This is intended for - debugging your relative path and inherited parameters for manually - entered Projects. - -\I Show in the status line the completely resolved filename. Uses the - Project_GetFname(line('.')) function. - -\1 - \9 - Run the command specified in g:proj_run{x} where {x} is the number - of the key. See the documentation of g:proj_run1 below. - -\f1-\f9 - Run the command specified in g:proj_run_fold{x} where {x} is the - number of the key. The command is run on the files at the current - Project level. See the |project-settings| below. - -\F1-\F9 - Run the command specified in g:proj_run_fold{x} where {x} is the - number of the key. The command is run on the files at the current - Project level and all Subprojects. See the |project-settings| below. - -\0 Display the commands that are defined for \1 through \9. - -\f0 Display the commands that are defined for \f1 through \f9 and \F1 - through \F0. Same as \F0. - -\l Load all the files in the current Project level into Vim. While files - are being loaded, you may press any key to stop. - -\L Load all the files in the current Project and all Subprojects into - Vim. Use this mapping with caution--I wouldn't suggest using \L to - load a Project with thousands of files. (BTW, my Project file has more - than 5,300 files in it!) While files are being loaded, you may press - any key to stop. - -\w Wipe all the files in the current Project level from Vim. (If files - are modified, they will be saved first.) While files are being wiped, - you may press any key to stop. - -\W Wipe all the files in the current Project and all Subprojects from - Vim. (If files are modified, they will be saved first.) While files - are being wiped, you may press any key to stop. - -\g Grep all the files in the current Project level. - -\G Grep all the files in the current Project level and all Subprojects. - -\e Set up the Environment for the Project File as though you had selected - it with <Return>. This allows you to do a \e and a :make without - having to open any files in the project. - -\E Explore (using |file-explorer|) the directory of the project the - cursor is in. Does not work with netrw. - -<F12> When the 'g' flag is present in g:proj_flags (see |project-flags|) - this key toggles the Project Window open and closed. You may remap - this toggle function by putting the following in your vimrc and - replacing <Leader>P with whatever key combination you wish: - - nmap <silent> <Leader>P <Plug>ToggleProject - -Note that the Project Plugin remaps :help because the Help Window and the -Project Window get into a fight over placement. The mapping avoids the -problem. - -============================================================================== -ADDING MAPPINGS *project-adding-mappings* - -You can add your own mappings or change the mappings of the plugin by placing -them in the file $HOME/.vimproject_mappings. This file, if it exists, will be -sourced when the plugin in loaded. Here is an example that will count the -number of entries in a project when you press \K (Kount, C is taken :-): > - - function! s:Wc() - let b:loadcount=0 - function! SpawnExec(infoline, fname, lineno, data) - let b:loadcount = b:loadcount + 1 - if getchar(0) != 0 | let b:stop_everything=1 | endif - endfunction - call Project_ForEach(1, line('.'), "*SpawnExec", 0, '') - delfunction SpawnExec - echon b:loadcount." Files\r" - unlet b:loadcount - if exists("b:stop_everything") - unlet b:stop_everything - echon "Aborted.\r" - endif - endfunction - - nnoremap <buffer> <silent> <LocalLeader>K :call <SID>Wc()<CR> - -Here's another example of how I integrated the use of perforce with the plugin -in my $HOME/.vimproject_mappings: -> - function! s:DoP4(cmd) - let name=Project_GetFname(line('.')) - let dir=substitute(name, '\(.*\)/.*', '\1', 'g') - exec 'cd '.dir - exec "!".a:cmd.' '.Project_GetFname(line('.')) - cd - - endfunction - - nmap <buffer> <silent> \pa :call <SID>DoP4("p4add")<CR> - nmap <buffer> <silent> \pe :call <SID>DoP4("p4edit")<CR> -< -(Note that I CD to the directory the file is in so I can pick of the $P4CONFIG -file. See the perforce documentation.) - -This creates the mappings \pe to check out the file for edit and \pa to add -the file to the depot. - -Here is another example where I remap the <Return> mapping to use an external -program to launch a special kind of file (in this case, it launches ee to view -a jpg file). It is a bit contrived, but it works. -> - let s:sid = substitute(maparg('<Return>', 'n'), '.*\(<SNR>.\{-}\)_.*', '\1', '') - function! s:LaunchOrWhat() - let fname=Project_GetFname(line('.')) - if fname =~ '\.jpg$' - exec 'silent! !ee "'.fname.'"&' - else - call {s:sid}_DoFoldOrOpenEntry('', 'e') - endif - endfunction - nnoremap <buffer> <silent> <Return> \|:call <SID>LaunchOrWhat()<CR> -< -If the file ends in .jpg, the external program is launched, otherwise the -original mapping of <Return> is run. - -============================================================================== -SETTINGS *project-settings* - -You can set these variables in your vimrc file before the plugin is loaded to -change its default behavior - -g:proj_window_width - The width of the Project Window that the plugin attempts to maintain. - Default: 24 - - The Project Plugin is not always successful in keeping the window - where I want it with the size specified here, but it does a decent - job. - -g:proj_window_increment - The increment by which to increase the width of the Project Window - when pressing <space> or clicking the <LeftMouse>. Default: 100 - (See |project-mappings|.) - - *project-flags* -g:proj_flags - Default: "imst" - Various flags to control the behavior of the Project Plugin. This - variable can contain any of the following character flags. - - flag Description ~ - - b When present, use the |browse()| when selecting directories - for \c and \C. This is off by default for Windows, because - the windows browser does not allow you to select directories. - - c When present, the Project Window will automatically close when - you select a file. - - F Float the Project Window. That is, turn off automatic - resizing and placement. This allows placement between other - windows that wish to share similar placement at the side of - the screen. It is also particularly helpful for external - window managers. - - g When present, the mapping for <F12> will be created to toggle - the Project Window open and closed. - - i When present, display the filename and the current working - directory in the command line when a file is selected for - opening. - - l When present, the Project Plugin will use the |:lcd| command - rather than |:cd| to change directories when you select a file - to open. This flag is really obsolete and not of much use - because of L below. - - L Similar to l, but install a BufEnter/Leave |:autocommand| to - ensure that the current working directory is changed to the - one specified in the fold CD specification whenever that - buffer is active. (|:lcd| only changes the CWD for a window, - not a buffer.) - - m Turn on mapping of the |CTRL-W_o| and |CTRL-W_CTRL_O| normal - mode commands to make the current buffer the only visible - buffer, but keep the Project Window visible, too. - - n When present, numbers will be turned on for the project - window. - - s When present, the Project Plugin will use syntax highlighting - in the Project Window. - - S Turn on sorting for refresh and create. - - t When present, toggle the size of the window rather than just - increase the size when pressing <space> or right-clicking. - See the entry for <RightMouse> in |project-mappings|. - - T When present, put Subproject folds at the top of the fold when - refreshing. - - v When present, use :vimgrep rather than :grep when using \G. - -g:proj_run1 ... g:proj_run9 - Contains a Vim command to execute on the file. See the - mappings of \1 to \9 above. - - %f is replaced with the full path and filename - %F is replaced with the full path and filename with spaces - quoted - %n is replaced with the filename alone - %N is replaced with the filename alone with spaces quoted - %h is replaced with the home directory - %H is replaced with the home directory with spaces quoted - %r is replaced with the directory relative to the CD path - %R is replaced with the directory relative to the CD path - with spaces quoted - %d is replaced with the CD directory. - %D is replaced with the CD directory.with spaces quoted - %% is replaced with a single % that is not used in - expansion. - - (Deprecated: %s is also replaced with the full path and - filename for backward compatibility.) - - For example, gvim will be launched on the file under the - cursor when you enter \3 if the following is in your vimrc - file: > - let g:proj_run3='silent !gvim %f' -< Here are a few other examples: > - let g:proj_run1='!p4 edit %f' - let g:proj_run2='!p4 add %f' - let g:proj_run4="echo 'Viewing %f'|sil !xterm -e less %f &" -< - On Windows systems you will want to put the %f, %h, and %d in - single quotes to avoid \ escaping. - -g:proj_run_fold1 ... g:proj_run_fold9 - Contains a Vim command to execute on the files in a fold. See - the mappings of \f1 to \f9 and \F1 to \F9 above. - - %f is the filename, %h is replaced with the project home - directory, and %d is replaced with the CD directory. Multiple - filenames can be handled in two ways: - - The first (default) way is to have %f replaced with all the - absolute filenames, and the command is run once. The second - is to have the command run for each of the non-absolute - filenames (%f is replaced with one filename at a time). To - select the second behavior, put an '*' character at the - beginning of the g:proj_run_fold{x} variable. (The '*' is - stripped before the command is run.) - - For example, note the difference between the following: > - let g:proj_run_fold3="*echo '%h/%f'" - let g:proj_run_fold4="echo '%f'" -< - Note that on Windows systems, you will want the %f, %h, and %c - within single quotes, or the \ in the paths will cause - problems. The alternative is to put them in |escape()|. - - -============================================================================== -PROJECT EXAMPLE FILE *project-example* - -Here is an example ~/.vimprojects file: > - - 1 My Project=~/c/project CD=. in=in.vim out=out.vim flags=r { - 2 Makefile - 3 in.vim - 4 out.vim - 5 GUI Files=. filter="gui*.c gui*.h" { - 6 gui_window.c - 7 gui_dialog.c - 8 gui_list.c - 9 gui.h # Header file - 10 } - 11 Database Files=. filter="data*.c data*.h" { - 12 data_read.c - 13 data_write.c - 14 data.h - 15 } - 16 OS-Specific Files { - 17 Win32=. filter="os_win32*.c os_win32*.h" { - 18 os_win32_gui.c - 19 os_win32_io.c - 20 } - 21 Unix=. filter="os_unix*.c os_unix*.h" { - 22 os_unix_gui.c - 23 os_unix_io.c - 24 } - 25 } - 26 } - -(Don't type in the line numbers, of course.) - - -============================================================================== -TIPS ON USING PROJECT PLUGIN *project-tips* - -1. You can create a Project Entry by entering this: > - - Label=~/wherever CD=. filter="*.c *.h" { - } -< - Then you can put the cursor in the fold and press \r. The script will fill - in the files (C files in this case) from this directory for you. This is - equivalent to \c without any dialogs. - -2. You can edit the Project File at any time to add, remove, or reorder files - in the Project list. - -3. If the Project Window ever gets closed, you can just enter > - :Project -< to bring it back again. (You don't need to give it the filename; the - plugin remembers.) - - If you have the 'm' flag set in g:proj_flags, then you get the Project - Window to show up again by pressing |CTRL-W_o|. This, of course, will - close any other windows that may be open that the cursor is not in. - -4. Adding files to a Project is very easy. To add, for example, the 'more.c' - file to the Project, just insert the filename in the Project Entry then - hit <Return> on it. - -5. When |quickfix| loads files, it is not equivalent to pressing <Return> on - a filename, so the directory will not be changed and the scripts will not - be run. (If I could make this otherwise, I would.) The solution is to use - the \L key to load all of the files in the Project before running - quickfix. - -6. If the Project window gets a bit cluttered with folds partially - open/closed, you can press |zM| to close everything and tidy it up. - -7. For advanced users, I am exporting the function Project_GetAllFnames() - which returns all the filenames within a fold and optionally all its - Subprojects. Also, I export Project_ForEach() for running a function for - each filename in the project. See the code for examples on how to use - these. Finally, I export Project_GetFname(line_number) so that you can - write your own mappings and get the filename for it. - -8. Some people have asked how to do a global mapping to take the cursor to - the Project window. One of my goals for the plugin is for it to be as - self-contained as possible, so I'm not going to add it by default. But you - can put this in your vimrc: -> - nmap <silent> <Leader>P :Project<CR> - -< -9. You can put the . entry in a project, and it will launch the - |file-explorer| plugin on the directory. To avoid removal when you - refresh, make the entry look like this: -> - . # pragma keep -< -============================================================================== -THANKS - - The following people have sent me patches to help with the Project - Plugin development: - - Tomas Zellerin - Lawrence Kesteloot - Dave Eggum - A Harrison - Thomas Link - Richard Bair - Eric Arnold - Peter Jones - Eric Van Dewoestine - - - vim:ts=8 sw=8 noexpandtab tw=78 ft=help: |