dissimulo/drunkendotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit.

Browse Source
This commit is contained in:
yan
2011-11-17 15:45:33 -06:00
commit 882015bc6d
1819 changed files with 111625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
vim/doc/AnsiEsc.txt Normal file
View File

@@ -0,0 +1,134 @@
*AnsiEsc.txt* Ansi Escape Sequence Visualization Dec 13, 2010
Author: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamily.AbizM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2010 by Charles E. Campbell, Jr. *AnsiEsc-copyright*
The VIM LICENSE applies to AnsiEsc.vim and AnsiEsc.txt
(see |copyright|) except use "AnsiEsc" instead of "Vim".
No warranty, express or implied. Use At-Your-Own-Risk.
==============================================================================
1. Contents *AnsiEsc* *AnsiEsc-contents*
1. Contents ...................................|AnsiEsc-contents|
2. AnsiEsc Manual ...................................|AnsiEsc|
3. AnsiEsc History ...................................|AnsiEsc-history|
==============================================================================
2. Manual *AnsiEsc-manual*
CONCEAL -- the best mode.
For this, your vim must have +conceal. A typical way to get the
conceal feature:
* cd ..wherever../vim72/
* wget http://vince.negri.googlepages.com/conceal-ownsyntax.diff
* patch -p0 < conceal-ownsyntax.diff
* make distclean
* configure --with-features=huge
* make
* make install
Normal: -- ansi escape sequences themselves are Ignore'd~
Ansi escape sequences have the expected effect on subsequent
text, but the ansi escape sequences themselves still take up
screen columns. The sequences are displayed using "Ignore"
highlighting; depending on your colorscheme, this should either
make the sequences blend into your background or be visually
suppressed. If the sequences aren't suppressed, you need to
improve your colorscheme!
USAGE~
:AnsiEsc -- toggles Ansi escape sequence highlighting
:AnsiEsc! -- rebuilds highlighting for new/removed three
or more element Ansi escape sequences.
RESULT~
Ansi escape sequences become concealed or ignored (depending
on whether your vim supports Negri's conceal mode), and their
effect on subsequent text is emulated with Vim's syntax
highlighting.
Syntax highlighting for one and two element codes are
hard-coded into AnsiEsc.vim. There are too many possibilities
for three or more element codes; these are supported by
examining the file for such sequences and only building syntax
highlighting rules for such sequences as are actually present
in the document.
EXAMPLE~
You'll want to use :AnsiEsc to see the following properly!
(using Vince Negri's conceal option or vim 7.3)
Color Escape Sequences
 -   1   2   3   4   5   7 
black black black black black black black
red red red red red red red
green green green green green green green
yellow yellow yellow yellow yellow yellow yellow
blue blue blue blue blue blue blue
magenta magenta magenta magenta magenta magenta magenta
cyan cyan cyan cyan cyan cyan cyan
white white white white white white white
Black B B B B B B B B
Red R R R R R R R R
Green G G G G G G G G
Yellow Y Y Y Y Y Y Y Y
Blue B B B B B B B B
Magenta M M M M M M M M
Cyan C C C C C C C C
White W W W W W W W W
Here's the vim logo:
/ \
/ \
/ \
/ \
+----+ +----+ \
++ ++ +- | \
/| | / / \
X | | / /O \
\| | / /+-+ +-\//-+
| |/ / | | | v |
| / / | | | + +|
| / | |/| |\/||
+----\ +-+ +-+ ++
\ /
\ /
==============================================================================
3. AnsiEsc History *AnsiEsc-history* {{{1
v12 Jul 23, 2010 * changed conc to |'cole'| to correspond to vim 7.3's
change
Aug 10, 2010 * (Rainer M Schmid) changed conceallevel setting to
depend on whether the version is before vim 7.3;
for 7.3, also sets concealcursor
* Restores conc/cole/cocu settings when AnsiEsc is
toggled off.
Dec 13, 2010 * Included some additional sequences involving 0
v11 Apr 20, 2010 * AnsiEsc now supports enabling/disabling via a menu
* <esc>[K and <esc>[00m now supported (as
grep --color=always issues them)
v10 May 06, 2009 * Three or more codes in an ANSI escape sequence are
supported by building custom syntax and highlighting
commands.
May 20, 2009 * cecutil bugfix
v9 May 12, 2008 * Now in plugin + autoload format. Provides :AnsiEsc
command to toggle Ansi-escape sequence processing.
Jan 01, 2009 * Applies Ignore highlighting to extended Ansi escape
sequences support 256-colors.
Mar 18, 2009 * Includes "rapid blink" ansi escape sequences. Vim
doesn't have a blinking attribute, so such text uses
"standout" for vim and "undercurl" for gvim.
v8 Aug 16, 2006 * Uses undercurl, and so is only available for vim 7.0
v7 Dec 14, 2004 * Works better with vim2ansi output and Vince Negri's
conceal patch for vim 6.x.
v2 Nov 24, 2004 * This version didn't use Vince Negri's conceal patch
(used Ignore highlighting)
==============================================================================
Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker:

619
vim/doc/CSApprox.txt Normal file
View File

@@ -0,0 +1,619 @@
*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.
*:CSApprox*
A command is also provided to run the approximation manually. This might be
useful if some colors were set outside of a colorscheme file, for instance.
By default, it will not change any colors unless no highlight group is set to
a color above 15, which is CSApprox's normal behavior. This probably isn't
useful in most use cases, though. On the other hand, if a ! is provided,
CSApprox will skip that test and update the cterm value for every highlight
group from the corresponding gui color. Syntax:
>
:CSApprox[!]
<
==============================================================================
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.
It isn't possible to approximate only a particular set of groups.
Unfortunately, the :CSApprox command will always update all groups, even if
only a small set of groups has changed. A future improvement would be to
provide a function called, say, CSApprox(), that takes an optional list of
highlight groups (default: all) and only does approximation for those
groups.
==============================================================================
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:

547
vim/doc/EasyGrep.txt Normal file
View File

@@ -0,0 +1,547 @@
*EasyGrep.txt*
==============================================================================
EasyGrep *EasyGrep*
==============================================================================
Author: Dan Price vim@danprice.fastmail.net *EasyGrep_Author*
Goal: To be an easy to use, powerful find and |EasyGrep_Motivation|
replace tool for users of all skill levels.
Version: 0.96 |EasyGrep_History|
License: Public domain, no restrictions whatsoever |EasyGrep_License|
Contribute: Please report any bugs or suggestions |EasyGrep_Bugs|
to the address above. |EasyGrep_Future|
==============================================================================
Table of Contents *EasyGrep_Contents*
==============================================================================
1. Motivation.................|EasyGrep_Motivation|
2. Operation..................|EasyGrep_Operation|
2.1 Modes..................|EasyGrep_OperationModes|
3. Keymaps....................|EasyGrep_Keymaps|
3.1 Option Mappings........|EasyGrep_KeymapsOptions|
3.2 Mapping Customization..|EasyGrep_KeymapsCustomization|
4. Commands...................|EasyGrep_Commands|
5. Options....................|EasyGrep_Options|
5.1 Summary...............|EasyGrep_OptionsSummary|
5.2 Explorer..............|EasyGrep_OptionsExplorer|
5.3 Details...............|EasyGrep_OptionsDetail|
6. Bugs.......................|EasyGrep_Bugs|
7. Future.....................|EasyGrep_Future|
8. History....................|EasyGrep_History|
9. License....................|EasyGrep_License|
==============================================================================
Motivation *EasyGrep_Motivation*
==============================================================================
EasyGrep's main goal is to make search and replace in files easy. Other Vim
plugins provide similar functionality, but few provide the same level of
functionality with as little configuration as EasyGrep does. In the common
case, all it takes to search for a string across multiple files is three
keypresses: <leader>vv. No clicks, no commands, no project/tags setup -- just
three keys. When you need a substitution, it also takes the same number of
keys to start a replace in files. After using EasyGrep, you'll wonder at how
you got around without it.
While EasyGrep's default configuration will satisfy many users, it provides
more than a dozen options for those who need more control |EasyGrep_Options|.
When you need to change options, EasyGrep provides an options explorer that
indicates which files will be searched and allows visual customization of its
options |EasyGrep_OptionsExplorer|. When this isn't fast enough, EasyGrep
provides key mappings for each option to toggle its value
|EasyGrep_KeymapsOptions|. If you can't find an option you need, contact me
|EasyGrep_Author| and if it doesn't already exist, we'll make it happen.
I hope that EasyGrep makes Vim more fun, productive, and easy for you to use.
Happy Vimming!
==============================================================================
Operation *EasyGrep_Operation*
==============================================================================
EasyGrep makes using Vim's grep capabilities easier. When using EasyGrep,
searching for a word is as easy as typing a three keypress mapping
|EasyGrep_Keymaps|. In addition to keymaps, search and replace can be invoked
through commands |EasyGrep_Commands|.
To determine which files to search, EasyGrep provides three modes, described
in the next section.
Search Modes |EasyGrep_OperationModes|
All
All files will be searched (default).
Buffers
Files currently open in vim will be searched. Recursion has no meaning in
this mode, and will be turned off.
TrackExt
Files that match the extension of the currently opened file will be
searched. Additionally, this extension can be mapped to a user defined
set of extensions that will also be searched |EasyGrepFileAssociations|.
For example: in the default configuration, when test.cpp is open, files
that match any one of
*.cpp *.hpp *.cxx *.hxx *.cc *.c *.h
will be searched when a Grep is initiated. I find this mode to be the
most useful.
User
Specify a custom set of file extensions to search.
These modes can be quickly changed through the |EasyGrep_OptionsExplorer| or
|EasyGrep_KeymapsOptions|.
==============================================================================
Keymaps *EasyGrep_Keymaps*
==============================================================================
EasyGrep uses Vim's leader key, which is by default '\'. For information on
this key, type ":help mapleader".
<Leader>vv - Grep for the word under the cursor, match all occurences,
like 'g*'. See ":help gstar".
<Leader>vV - Grep for the word under the cursor, match whole word, like
'*'. See ":help star".
<Leader>va - Like vv, but add to existing list.
<Leader>vA - Like vV, but add to existing list.
<Leader>vr - Perform a global search on the word under the cursor
and prompt for a pattern with which to replace it.
<Leader>vR - Like vr, but match whole word.
Each of these commands has an 'all occurences' and 'whole word' option,
designated by the case of the last character. If you would prefer that these
be reversed, see |EasyGrepInvertWholeWord|.
In addition to grepping the word under the cursor, text may be visually
selected and these mappings may be used analogously to as they are used above.
Visual selections will automatically be escaped so as not to confuse the
selection with a regular expression.
e.g. Selecting the text inside the quotes here "/<word\>" will match
against "\<word\>" but not against "word".
To search with a regular expression, see the :Grep command |EasyGrep_Commands|
Each of the above commands will search files according to settings
controlled by:
<Leader>vo - Open an options explorer to select the files to search in and
set grep options.
For the options provided, see |EasyGrep_Options|.
*EasyGrep_KeymapsOptions*
For each of the options presented in the options explorer, there is a mapping
that allows a direct change of this option. The pattern is <Leader>vy* ,
where star is the value listed in the options window for each of the options.
e.g. To toggle recursive mode, type '\vyr'
See |EasyGrepOptionPrefix| to change the prefix from '\vy' or to turn these
keymappings off.
*EasyGrep_KeymapsCustomization*
Beyond EasyGrepOptionPrefix, other keymaps may be remapped to your liking.
See the "Keymaps" section of EasyGrep.vim for the names of these items.
Mappings take the form:
map <silent> (keycombination) <plug>(MappingName)
e.g.
map <silent> ,op <plug>EgMapGrepOptions
==============================================================================
Commands *EasyGrep_Commands*
==============================================================================
:Grep [arg]
Search for the specified arg, like <Leader>vv. When an ! is added,
search like <Leader>vV
:GrepAdd [arg]
Search for the specified arg, add to existing file list, as in
<Leader>va. When an ! is added, search like <Leader>vA
The Above commands can additionally accept command switches:
-r Perform a recursive search
-R Perform a recursive search
-i Perform a case-insensitive search
-I Perform a case-sensitive search
:Replace [target] [replacement]
:Replace /[target]/[replacement]/
Perform a global search and replace. The function searches
the same set of files a grep for the desired target and opens a dialog to
confirm replacement. In the second, forward slash delineated form, back
and forward slashes must be explicitly escaped.
:ReplaceUndo
Undoes the last :Replace operation. Does not stack successive
searches; only the last replace may be undone. This function may not
work well when edits are made between a call to Replace and a call to
ReplaceUndo.
Note: currently implemented ReplaceUndo will fail to restore replacements
that make use of backreferences.|EasyGrep_Bugs|
:GrepOptions
Open the options explorer to set options.
For each of the search and replace commands, searching with regular
expressions is supported. Note that regular expressions are handled as
indicated by the 'magic' option (see ":help 'magic'").
==============================================================================
Options *EasyGrep_Options*
==============================================================================
Options Summary *EasyGrep_OptionsSummary*
Option Description
------------------------------------------------------------------------------
|EasyGrepFileAssociations| Specifies the location of the EasyGrep
file associations
------------------------------------------------------------------------------
|EasyGrepMode| Mode of operation
------------------------------------------------------------------------------
|EasyGrepCommand| Whether to use vimgrep or grepprg
------------------------------------------------------------------------------
|EasyGrepRecursive| Recursive searching
------------------------------------------------------------------------------
|EasyGrepIgnoreCase| Case-sensitivity in searches
------------------------------------------------------------------------------
|EasyGrepHidden| Include hidden files in searches
------------------------------------------------------------------------------
|EasyGrepAllOptionsInExplorer| How many options to show in the explorer
------------------------------------------------------------------------------
|EasyGrepWindow| Quickfix or location list
------------------------------------------------------------------------------
|EasyGrepOpenWindowOnMatch| Open grep window on successful match
------------------------------------------------------------------------------
|EasyGrepEveryMatch| Match multiple times per line
------------------------------------------------------------------------------
|EasyGrepJumpToMatch| Jump to first match
------------------------------------------------------------------------------
|EasyGrepSearchCurrentBufferDir| Whether to search current buffers dir
in addition to working dir
------------------------------------------------------------------------------
|EasyGrepInvertWholeWord| Invert the meaning of whole word for vv
and vV keymaps
------------------------------------------------------------------------------
|EasyGrepFileAssociationsInExplorer| Whether to show the file associations
list in the options explorer
------------------------------------------------------------------------------
|EasyGrepReplaceWindowMode| Controls whether to use tabs or splits
when replacing in files
------------------------------------------------------------------------------
|EasyGrepReplaceAllPerFile| Replace on per file or global basis
------------------------------------------------------------------------------
|EasyGrepOptionPrefix| Specify the keymap for toggling options
------------------------------------------------------------------------------
|EasyGrepExtraWarnings| Whether to show extra warnings
------------------------------------------------------------------------------
Options Explorer *EasyGrep_OptionsExplorer*
To invoke the options explorer, type '\vo' (default). The options
explorer presents all of EasyGrep's customizable options and provides
information on the file patterns that will be searched when invoking a
Grep.
A useful exercise for beginners is to toggle between EasyGrep's options
and modes (|EasyGrep_OperationModes|) and type 'e' to see which files will
be searched for a given configuration.
Options Details *EasyGrep_OptionsDetail*
*EasyGrepFileAssociations*
Specifies the location of a file that contains groups of files that should be
associated with one another. When set to an empty string "", no file read
will be attempted.
This file has a simple syntax used to logically link different files types.
A simple configuration is shown below:
C=*.c *.h
C++=*.cpp *.hpp *.cxx *.hxx *.cc <C>
VHDL=*.hdl *.vhd *.vhdl *.vbe *.vst
Web=*.htm *.html *.js
For example, in this configuration, whenever the active file has the .c
extension, files with the .h extension will also be search. A special feature
of this syntax is the ability to link groups together. For example, the C++
group links to all files that are in the C group.
*EasyGrepMode*
Specifies the mode in which to start.
0 - All files
1 - Open Buffers
2 - Track the current extension
Note: I find option 2 to be the most powerful, but option 0 is activated by
default because it is the most intuitive for users who haven't take the
time to understand how the script works. See |EasyGrep_OperationModes|.
*EasyGrepCommand*
Specifies the grep command to use.
0 - vimgrep
1 - grep (follows grepprg)
*EasyGrepRecursive*
Specifies that recursive search be activated on start.
*EasyGrepIgnoreCase*
Specifies the case sensitivity of searches. Note that this can be further
overrided for vimgrep searches with \c and \C.
*EasyGrepHidden*
Specifies that hidden files search be activated on start. Note that hidden
implies the unix meaning of those files that are prepended with a '.', and not
the Windows meaning of those files with a hidden attribute.
*EasyGrepAllOptionsInExplorer*
Specifies that all options be included in the explorer window.
Note: settting this option is very useful when you want to try out and
learn all of the options available in this script.
*EasyGrepWindow*
Specifies the window to use for matches.
0 - quickfix
1 - location list
*EasyGrepOpenWindowOnMatch*
Specifies whether to open the with matches after a search.
*EasyGrepEveryMatch*
Specifies that multiple matches on the same line be treated as different
matches, like the g option to vimgrep.
*EasyGrepJumpToMatch*
Specifies that jump to first match be activated, like the j option to vimgrep.
*EasyGrepSearchCurrentBufferDir*
Setting this option causes EasyGrep to search the current buffer's
directory in addition to the current working directory.
*EasyGrepInvertWholeWord*
Specifies that the whole word search keys should be inverted from their
default meaning. For example, when this option is activated, <Leader>vv
matches whole word, while <Leader>vV matches everything that includes the
word. Note that this affects both keymappings and commands.
*EasyGrepFileAssociationsInExplorer*
Specifies whether to show the file associations list in the options explorer
window.
*EasyGrepOptionPrefix*
Specifies the prefix that is used when building keymaps for setting options
directly. To specify that no option keymaps be created, set this to the empty
string.
Default:
let g:EasyGrepOptionPrefix='<leader>vy'
Custom:
let g:EasyGrepOptionPrefix=',oe'
None:
let g:EasyGrepOptionPrefix=''
*EasyGrepReplaceWindowMode*
Specifies the mode that the script will use when a buffer needs to be changed
while performing a global replace.
0 - Open a new tab for each window
1 - Perform a split of the current window with the next window
2 - autowriteall; create no new windows
Note: Option 1 has the possibility of running out of vertical space to
split more windows. Actions are taken to make this a non-issue, but this
option can often be more clunky than other options.
Note: As a result of the limitation above, option 0 is the only mode that
won't require saving the files during a replace.
*EasyGrepReplaceAllPerFile*
Specifies that selecting 'a' (for all) will apply the replacements on a per
file basis, as opposed to globally as is the default.
*EasyGrepExtraWarnings*
Specifies that warnings be issued for conditions that may be valid but confuse
some users.
==============================================================================
Future *EasyGrep_Future*
==============================================================================
------------------------------------------------------------------------------
Show search progress?
------------------------------------------------------------------------------
Allow entries in the file associations list to be regular expressions
------------------------------------------------------------------------------
Idea: create capability to include paths other than the active directory (and
below) in a search. e.g. ../../include, $INCLUDE, etc.
------------------------------------------------------------------------------
Idea: set file/directory exclusions
------------------------------------------------------------------------------
==============================================================================
Bugs *EasyGrep_Bugs*
==============================================================================
If you discover any bugs not listed here, please contact the |EasyGrep_Author|
------------------------------------------------------------------------------
ReplaceUndo can't correctly restore replacements that use numbered
sub-expressions
------------------------------------------------------------------------------
ReplaceUndo can't currently replace the text accurately in all cases if case
insensitivity is turned on
------------------------------------------------------------------------------
Increase the granularity of the match inside of a Replace call so that you can
individually decide per line
------------------------------------------------------------------------------
Cursorline doesn't always follow to the line at which the replacement is going
to happen
------------------------------------------------------------------------------
Successive warning messages can hide a previous message
------------------------------------------------------------------------------
ReplaceUndo opens a window even if it is already open?
------------------------------------------------------------------------------
Report that a swap file can't be opened
------------------------------------------------------------------------------
Don't warn when the current file will actually be searched because recursion
is on and it is below the current directory
------------------------------------------------------------------------------
==============================================================================
History *EasyGrep_History*
==============================================================================
0.96
Feature: Expanded upon the list of file associations
Feature: Expanded searches to the current buffer's directory
in addition to the current working directory
Feature: Added command line arguments to :Grep and :Replace for
recursive searches and case sensitivity
Feature: Added toggle for window replace mode
Feature: Added toggle for showing file associations list in options
explorer
Bugfix: Case insensitivity would fail in replacing some patterns
0.95
Feature: Added search and replace on visual selections
Feature: Improved Grepping for items that can be interpreted as regular
expressions. Selections are assumed to be literal, whereas explicit
commands are assumed to be regular expressions.
Feature: Removed option g:EasyGrepNoDirectMappings in favor of
g:EasyGrepOptionPrefix, which allows the option prefix to be changed.
Bugfix: The tracked extension would sometimes fail to be updated when
switching between buffers
Documentation: Split the documentation into its own file; greatly
expanded upon its contents
Change: Activating a mode that is already activated will no longer
deactivate it
Change: GrepOptions no longer accepts an argument; use user mode instead
Change: Clarified mapping names; custom mappings will need to
be reset.
0.9
Feature: Added forward slash delineated pattern to the Replace command
e.g. :Replace /target/replacement/
that allows more complicated replacements; you can now work with
patterns that have spaces in them.
Bugfix: If cursorline is off at the start of a replace, now ensuring
that cursorline is turned off for all buffers, and not just the last one
Bugfix: fixed an issue with an extra tab being opened during a
replacement
0.8
Implemented case sensitivity that is independent of ignorecase, thanks
to Doro Wu for contributing to this functionality
Changed shortcut key for hidden files from 'i' to 'h'
0.7
Expanded search of EasyGrepFileAssociations list to every component of
'runtimepath'. This solves a starting message for those who placed
EasyGrepFileAssociations in a location other than the first location in
'runtimepath'.
0.6
Fixed paths with spaces in them
Folds will now be disabled where replacements are to be made
Fixed an error with checking for extra warnings
Better highlighting while replacing
Recursive mode can no longer be activated when Buffers mode is activated
0.5
Fixed an issue with tracking the file extension where sometimes the
desired extension wouldn't be registered.
Better reporting when no files match.
Now warning when searching from a working directory that doesn't match
the current file's directory.
Added g:EasyGrepExtraWarnings option.
0.4
Improved Replace and ReplaceUndo
Added two configurable modes for how the windows operate when doing a
global replace.
Fixed an issue with linked filetypes.
0.3
Added experimental :Replace and :ReplaceUndo commands; keymapped
<leader>vr for :Replace
Improved response when no matches
0.2
Added option to toggle showing fewer or more options; showing fewer
options by default.
Added option '?' to print the current configuration and save it to a
register.
Now creating direct mappings by default; see g:EasyGrepNoDirectMappings
to turn this off.
0.1
Initial version
==============================================================================
License *EasyGrep_License*
==============================================================================
Public domain, no restrictions whatsoever
When writing EasyGrep, I wanted it to be free in the broadest sense. Of
course, most (if not all) plugins for Vim are free, but I wanted mine to be
freer still: I've released EasyGrep in the public domain. It took a lot of
time and learning to get EasyGrep to work, and I want anyone to take advantage
of my contribution. If you see some (or many) snippets of EasyGrep's code
that you need, use it -- you don't need to ask me, think about any copyright,
worry about violating a license, or even note that the code came from me, just
use it. My only request is that if you are thinking of forking EasyGrep (or
enhancing, as some authors claim to do), please contact me to let me know what
you feel is lacking in EasyGrep, and I promise I'll be receptive to correcting
these issues.
==============================================================================
vim:tw=78:ts=4:ft=help:norl:fdm=marker

184
vim/doc/IndentAnything.txt Normal file
View File

@@ -0,0 +1,184 @@
*IndentAnything* For Vim version 7.0
The IndentAnything plugin is intended to make it easier to write new
indentation scripts and/or supplement existing ones. It makes the assumption
that all indentable languages have similar characteristics:
- blocks of code over multiple lines
- continuation lines
- comments
The rules of indentation are specified in a series of variables.
================================================================================
*b:defaultIndentExpr*
b:defaultIndentExpr
If defined, this value is executed to find the starting indent for a
line. The default is to use the indentation of the previous code
line. But IndentAnything can be used to suplement other, existing
indentation scripts.
For example:
>
let b:defaultIndentExpr = &indentexpr
setlocal indentexpr=IndentAnything()
<
*b:indentTrios*
b:indentTrios
This is the core of indenting anything. The original version of this
script was meant to be a simple "get indentation inside parenthesis".
But a pair of paranthesis is just like any other pair of characters or
keywords that specify a block of code that should be indented.
This is a list of indent "trios" (start, middle, end). The values
kept in this variable are the arguments that will be passed to
|searchpair()|.
The following example specifies that there should be a level of
indentation inside parenthesis and braces. It also takes into account
the case statements inside a switch block.
>
let b:indentTrios = [
\ [ '(', '', ')' ],
\ [ '{', '\(default:\|case.*:\)', '}' ]
\]
<
Note: There is logic that makes the distinction between matches at the
beginning of lines or not. These patterns should not include '^'
(beginning-of-line), or that logic will break.
*b:lineContList*
b:lineContList
This is a list of dictionaries specifying the lines that are continued
by the next line. For example, in shell scripts, a trailing '\'
indicates that the next line is a continuation.
The dictionaries contain the following keys:
pattern : The regular expression matching a line that is continued.
Used to determine if the current line is a continuation, and
should therefore be indented another level.
ignore : Pattern matching the CURRENT line if it should ignore a
previous continued line.
The following example handles if, else, for, and while statements that are
NOT followed by a code block ('{') and lines ending in an operator
whose RHS is on the next line:
>
let b:lineContList = [
\ { 'pattern' : '^\s*\(if\|for\|while\)\s*(.*)\s*\(\(//.*\)\|/\*.*\*/\s*\)\?\_$\(\_s*{\)\@!' },
\ { 'pattern' : '^\s*else' . '\s*\(\(//.*\)\|/\*.*\*/\s*\)\?\_$\(\_s*{\)\@!' },
\ { 'pattern' : '\(+\|=\|+=\|-=\)\s*\(\(//.*\)\|/\*.*\*/\s*\)\?$' }
\]
<
*b:contTraversesLineComments*
b:contTraversesLineComments
If a continued line and its continuation can have line-comments
between them, then the value of this variable should be non-zero.
For example,
>
if (x)
// comment here
statement
<
*b:commentRE* *b:lineCommentRE*
*b:blockCommentRE*
b:commentRE
b:lineCommentRE
b:blockCommentRE
These are regular expressions that match the syntax names for comments
for the filetype being indented. Line comments (like '// ...') and
block comments (like '/* ... */') are supported.
Example:
>
let b:commentRE = 'javaScript\(Line\)\?Comment'
let b:lineCommentRE = 'javaScriptLineComment'
let b:blockCommentRE = 'javaScriptComment'
<
*b:stringRE* *b:singleQuoteStringRE*
*b:doubleQuoteStringRE*
b:stringRE
b:singleQuoteStringRE
b:doubleQuoteStringRE
These are regular expressions that match the syntax names for strings
for the filetype being indented. There are strings in single-quotes
(''), double-quotes (""), and an expression for strings of any kind.
This is used mostly for avoiding matching of pairs and continuation
patterns inside strings.
Example:
>
let b:stringRE = 'javaScriptString\(S\|D\)'
let b:singleQuoteStringRE = 'javaScriptStringS'
let b:doubleQuoteStringRE = 'javaScriptStringD'
<
*b:blockCommentStartRE*
*b:blockCommentMiddleRE*
*b:blockCommentEndRE*
*b:blockCommentMiddleExtra*
b:blockCommentStartRE
b:blockCommentMiddleRE
b:blockCommentEndRE
b:blockCommentMiddleExtra
This allows for special indentation for block comments. For example,
to properly indent C-style comments, use the following:
>
let b:blockCommentStartRE = '/\*'
let b:blockCommentMiddleRE = '\*'
let b:blockCommentEndRE = '\*/'
let b:blockCommentMiddleExtra = 1
<
This will indent the following code like so:
>
statement;
/*
* comment
*/
statement;
<
The second statement indented one character less than the last line of
the comment. The value of |b:blockCommentMiddleExtra| will cause the
middle lines of the comment (those starting with '*') to be indented
by that many more characters. This value can also be negative.
The example here duplicates the behavior of cindent. However, this
will work for any style block comment. For example, HTML comments
could be indented like this:
>
<!--
- Comment
-->
<br>
<
This will be most effective if the 'comments' option is configured
properly for the filetype. The above works best with the following:
>
setl comments=sr:<!--,m:-,e:-->
let b:blockCommentStartRE = '<!--'
let b:blockCommentMiddleRE = '-'
let b:blockCommentEndRE = '-->'
let b:blockCommentMiddleExtra = 3
<
vim:noet:sw=8:
vim:tw=78:ts=8:ft=help:norl:

991
vim/doc/NERD_commenter.txt Normal file
View File

@@ -0,0 +1,991 @@
*NERD_commenter.txt* Plugin for commenting code
NERD COMMENTER REFERENCE MANUAL~
==============================================================================
CONTENTS *NERDCommenterContents*
1.Intro...................................|NERDCommenter|
2.Functionality provided..................|NERDComFunctionality|
2.1 Functionality Summary.............|NERDComFunctionalitySummary|
2.2 Functionality Details.............|NERDComFunctionalityDetails|
2.2.1 Comment map.................|NERDComComment|
2.2.2 Nested comment map..........|NERDComNestedComment|
2.2.3 Toggle comment map..........|NERDComToggleComment|
2.2.4 Minimal comment map.........|NERDComMinimalComment|
2.2.5 Invert comment map..........|NERDComInvertComment|
2.2.6 Sexy comment map............|NERDComSexyComment|
2.2.7 Yank comment map............|NERDComYankComment|
2.2.8 Comment to EOL map..........|NERDComEOLComment|
2.2.9 Append com to line map......|NERDComAppendComment|
2.2.10 Insert comment map.........|NERDComInsertComment|
2.2.11 Use alternate delims map...|NERDComAltDelim|
2.2.12 Comment aligned maps.......|NERDComAlignedComment|
2.2.13 Uncomment line map.........|NERDComUncommentLine|
2.3 Supported filetypes...............|NERDComFiletypes|
2.4 Sexy Comments.....................|NERDComSexyComments|
2.5 The NERDComment function..........|NERDComNERDComment|
3.Options.................................|NERDComOptions|
3.1 Options summary...................|NERDComOptionsSummary|
3.2 Options details...................|NERDComOptionsDetails|
3.3 Default delimiter Options.........|NERDComDefaultDelims|
4. Customising key mappings...............|NERDComMappings|
5. Issues with the script.................|NERDComIssues|
5.1 Delimiter detection heuristics....|NERDComHeuristics|
5.2 Nesting issues....................|NERDComNesting|
6.About.. ............................|NERDComAbout|
7.Changelog...............................|NERDComChangelog|
8.Credits.................................|NERDComCredits|
9.License.................................|NERDComLicense|
==============================================================================
1. Intro *NERDCommenter*
The NERD commenter provides many different commenting operations and styles
which are invoked via key mappings and a menu. These operations are available
for most filetypes.
There are also options that allow to tweak the commenting engine to your
taste.
==============================================================================
2. Functionality provided *NERDComFunctionality*
------------------------------------------------------------------------------
2.1 Functionality summary *NERDComFunctionalitySummary*
The following key mappings are provided by default (there is also a menu
with items corresponding to all the mappings below):
[count],cc |NERDComComment|
Comment out the current line or text selected in visual mode.
[count],cn |NERDComNestedComment|
Same as ,cc but forces nesting.
[count],c<space> |NERDComToggleComment|
Toggles the comment state of the selected line(s). If the topmost selected
line is commented, all selected lines are uncommented and vice versa.
[count],cm |NERDComMinimalComment|
Comments the given lines using only one set of multipart delimiters.
[count],ci |NERDComInvertComment|
Toggles the comment state of the selected line(s) individually.
[count],cs |NERDComSexyComment|
Comments out the selected lines ``sexily''
[count],cy |NERDComYankComment|
Same as ,cc except that the commented line(s) are yanked first.
,c$ |NERDComEOLComment|
Comments the current line from the cursor to the end of line.
,cA |NERDComAppendComment|
Adds comment delimiters to the end of line and goes into insert mode between
them.
|NERDComInsertComment|
Adds comment delimiters at the current cursor position and inserts between.
Disabled by default.
,ca |NERDComAltDelim|
Switches to the alternative set of delimiters.
[count],cl
[count],cb |NERDComAlignedComment|
Same as |NERDComComment| except that the delimiters are aligned down the
left side (,cl) or both sides (,cb).
[count],cu |NERDComUncommentLine|
Uncomments the selected line(s).
------------------------------------------------------------------------------
2.2 Functionality details *NERDComFunctionalityDetails*
------------------------------------------------------------------------------
2.2.1 Comment map *NERDComComment*
Default mapping: [count],cc
Mapped to: <plug>NERDCommenterComment
Applicable modes: normal visual visual-line visual-block.
Comments out the current line. If multiple lines are selected in visual-line
mode, they are all commented out. If some text is selected in visual or
visual-block mode then the script will try to comment out the exact text that
is selected using multi-part delimiters if they are available.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
------------------------------------------------------------------------------
2.2.2 Nested comment map *NERDComNestedComment*
Default mapping: [count],cn
Mapped to: <plug>NERDCommenterNest
Applicable modes: normal visual visual-line visual-block.
Performs nested commenting. Works the same as ,cc except that if a line is
already commented then it will be commented again.
If |'NERDUsePlaceHolders'| is set then the previous comment delimiters will
be replaced by place-holder delimiters if needed. Otherwise the nested
comment will only be added if the current commenting delimiters have no right
delimiter (to avoid syntax errors)
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
Related options:
|'NERDDefaultNesting'|
------------------------------------------------------------------------------
2.2.3 Toggle comment map *NERDComToggleComment*
Default mapping: [count],c<space>
Mapped to: <plug>NERDCommenterToggle
Applicable modes: normal visual-line.
Toggles commenting of the lines selected. The behaviour of this mapping
depends on whether the first line selected is commented or not. If so, all
selected lines are uncommented and vice versa.
With this mapping, a line is only considered to be commented if it starts with
a left delimiter.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
------------------------------------------------------------------------------
2.2.4 Minimal comment map *NERDComMinimalComment*
Default mapping: [count],cm
Mapped to: <plug>NERDCommenterMinimal
Applicable modes: normal visual-line.
Comments the selected lines using one set of multipart delimiters if possible.
For example: if you are programming in c and you select 5 lines and press ,cm
then a '/*' will be placed at the start of the top line and a '*/' will be
placed at the end of the last line.
Sets of multipart comment delimiters that are between the top and bottom
selected lines are replaced with place holders (see |'NERDLPlace'|) if
|'NERDUsePlaceHolders'| is set for the current filetype. If it is not, then
the comment will be aborted if place holders are required to prevent illegal
syntax.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
------------------------------------------------------------------------------
2.2.5 Invert comment map *NERDComInvertComment*
Default mapping: ,ci
Mapped to: <plug>NERDCommenterInvert
Applicable modes: normal visual-line.
Inverts the commented state of each selected line. If the a selected line is
commented then it is uncommented and vice versa. Each line is examined and
commented/uncommented individually.
With this mapping, a line is only considered to be commented if it starts with
a left delimiter.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
------------------------------------------------------------------------------
2.2.6 Sexy comment map *NERDComSexyComment*
Default mapping: [count],cs
Mapped to: <plug>NERDCommenterSexy
Applicable modes: normal, visual-line.
Comments the selected line(s) ``sexily''... see |NERDComSexyComments| for
a description of what sexy comments are. Can only be done on filetypes for
which there is at least one set of multipart comment delimiters specified.
Sexy comments cannot be nested and lines inside a sexy comment cannot be
commented again.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
Related options:
|'NERDCompactSexyComs'|
------------------------------------------------------------------------------
2.2.7 Yank comment map *NERDComYankComment*
Default mapping: [count],cy
Mapped to: <plug>NERDCommenterYank
Applicable modes: normal visual visual-line visual-block.
Same as ,cc except that it yanks the line(s) that are commented first.
------------------------------------------------------------------------------
2.2.8 Comment to EOL map *NERDComEOLComment*
Default mapping: ,c$
Mapped to: <plug>NERDCommenterToEOL
Applicable modes: normal.
Comments the current line from the current cursor position up to the end of
the line.
------------------------------------------------------------------------------
2.2.9 Append com to line map *NERDComAppendComment*
Default mapping: ,cA
Mapped to: <plug>NERDCommenterAppend
Applicable modes: normal.
Appends comment delimiters to the end of the current line and goes
to insert mode between the new delimiters.
------------------------------------------------------------------------------
2.2.10 Insert comment map *NERDComInsertComment*
Default mapping: disabled by default.
Map it to: <plug>NERDCommenterInInsert
Applicable modes: insert.
Adds comment delimiters at the current cursor position and inserts
between them.
NOTE: prior to version 2.1.17 this was mapped to ctrl-c. To restore this
mapping add >
let NERDComInsertMap='<c-c>'
<
to your vimrc.
------------------------------------------------------------------------------
2.2.11 Use alternate delims map *NERDComAltDelim*
Default mapping: ,ca
Mapped to: <plug>NERDCommenterAltDelims
Applicable modes: normal.
Changes to the alternative commenting style if one is available. For example,
if the user is editing a c++ file using // comments and they hit ,ca
then they will be switched over to /**/ comments.
See also |NERDComDefaultDelims|
------------------------------------------------------------------------------
2.2.12 Comment aligned maps *NERDComAlignedComment*
Default mappings: [count],cl [count],cb
Mapped to: <plug>NERDCommenterAlignLeft
<plug>NERDCommenterAlignBoth
Applicable modes: normal visual-line.
Same as ,cc except that the comment delimiters are aligned on the left side or
both sides respectively. These comments are always nested if the line(s) are
already commented.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
------------------------------------------------------------------------------
2.2.13 Uncomment line map *NERDComUncommentLine*
Default mapping: [count],cu
Mapped to: <plug>NERDCommenterUncomment
Applicable modes: normal visual visual-line visual-block.
Uncomments the current line. If multiple lines are selected in
visual mode then they are all uncommented.
When uncommenting, if the line contains multiple sets of delimiters then the
``outtermost'' pair of delimiters will be removed.
The script uses a set of heurisics to distinguish ``real'' delimiters from
``fake'' ones when uncommenting. See |NERDComIssues| for details.
If a [count] is given in normal mode, the mapping works as though that many
lines were selected in visual-line mode.
Related options:
|'NERDRemoveAltComs'|
|'NERDRemoveExtraSpaces'|
------------------------------------------------------------------------------
2.3 Supported filetypes *NERDComFiletypes*
Filetypes that can be commented by this plugin:
abaqus abc acedb ada ahdl amiga aml ampl ant apache apachestyle asm68k asm asn
aspvbs atlas autohotkey autoit automake ave awk basic b bc bdf bib bindzone
bst btm caos catalog c cfg cg ch changelog cl clean clipper cmake conf config
context cpp crontab cs csc csp css cterm cupl csv cvs dcl debchangelog
debcontrol debsources def diff django docbk dns dosbatch dosini dot dracula
dsl dtd dtml dylan ecd eiffel elf elmfilt erlang eruby eterm expect exports
fetchmail fgl focexec form fortran foxpro fstab fvwm fx gdb gdmo geek
gentoo-package-keywords' gentoo-package-mask' gentoo-package-use' gnuplot
gtkrc haskell hb h help hercules hog html htmldjango htmlos ia64 icon idlang
idl indent inform inittab ishd iss ist jam java javascript jess jgraph
jproperties jproperties jsp kconfig kix kscript lace lex lftp lifelines lilo
lisp lite lotos lout lprolog lscript lss lua lynx m4 mail make maple masm
master matlab mel mf mib mma model moduala. modula2 modula3 monk mush muttrc
named nasm nastran natural ncf netdict netrw nqc nroff nsis objc ocaml occam
omlet omnimark openroad opl ora otl ox pascal passwd pcap pccts perl pfmain
php phtml pic pike pilrc pine plaintex plm plsql po postscr pov povini ppd
ppwiz procmail progress prolog psf ptcap python python qf radiance ratpoison r
rc readline rebol registry remind rexx robots rpl rtf ruby sa samba sas sass
sather scheme scilab screen scsh sdl sed selectbuf sgml sgmldecl sgmllnx sh
sicad simula sinda skill slang sl slrnrc sm smarty smil smith sml snnsnet
snnspat snnsres snobol4 spec specman spice sql sqlforms sqlj sqr squid st stp
strace svn systemverilog tads taglist tags tak tasm tcl terminfo tex text
plaintex texinfo texmf tf tidy tli trasys tsalt tsscl tssgm uc uil vb verilog
verilog_systemverilog vgrindefs vhdl vim viminfo virata vo_base vrml vsejcl
webmacro wget winbatch wml wvdial xdefaults xf86conf xhtml xkb xmath xml
xmodmap xpm2 xpm xslt yacc yaml z8a
If a language is not in the list of hardcoded supported filetypes then the
&commentstring vim option is used.
------------------------------------------------------------------------------
2.4 Sexy Comments *NERDComSexyComments*
These are comments that use one set of multipart comment delimiters as well as
one other marker symbol. For example: >
/*
* This is a c style sexy comment
* So there!
*/
/* This is a c style sexy comment
* So there!
* But this one is ``compact'' style */
<
Here the multipart delimiters are /* and */ and the marker is *.
------------------------------------------------------------------------------
2.5 The NERDComment function *NERDComNERDComment*
All of the NERD commenter mappings and menu items invoke a single function
which delegates the commenting work to other functions. This function is
public and has the prototype: >
function! NERDComment(isVisual, type)
<
The arguments to this function are simple:
- isVisual: if you wish to do any kind of visual comment then set this to
1 and the function will use the '< and '> marks to find the comment
boundries. If set to 0 then the function will operate on the current
line.
- type: is used to specify what type of commenting operation is to be
performed, and it can be one of the following: "sexy", "invert",
"minimal", "toggle", "alignLeft", "alignBoth", "norm", "nested",
"toEOL", "append", "insert", "uncomment", "yank"
For example, if you typed >
:call NERDComment(1, 'sexy')
<
then the script would do a sexy comment on the last visual selection.
==============================================================================
3. Options *NERDComOptions*
------------------------------------------------------------------------------
3.1 Options summary *NERDComOptionsSummary*
|'loaded_nerd_comments'| Turns off the script.
|'NERDAllowAnyVisualDelims'| Allows multipart alternative delims to
be used when commenting in
visual/visual-block mode.
|'NERDBlockComIgnoreEmpty'| Forces right delims to be placed when
doing visual-block comments.
|'NERDCommentWholeLinesInVMode'| Changes behaviour of visual comments.
|'NERDCreateDefaultMappings'| Turn the default mappings on/off.
|'NERDDefaultNesting'| Tells the script to use nested comments
by default.
|'NERDMenuMode'| Specifies how the NERD commenter menu
will appear (if at all).
|'NERDLPlace'| Specifies what to use as the left
delimiter placeholder when nesting
comments.
|'NERDUsePlaceHolders'| Specifies which filetypes may use
placeholders when nesting comments.
|'NERDRemoveAltComs'| Tells the script whether to remove
alternative comment delimiters when
uncommenting.
|'NERDRemoveExtraSpaces'| Tells the script to always remove the
extra spaces when uncommenting
(regardless of whether NERDSpaceDelims
is set)
|'NERDRPlace'| Specifies what to use as the right
delimiter placeholder when nesting
comments.
|'NERDSpaceDelims'| Specifies whether to add extra spaces
around delimiters when commenting, and
whether to remove them when
uncommenting.
|'NERDCompactSexyComs'| Specifies whether to use the compact
style sexy comments.
------------------------------------------------------------------------------
3.3 Options details *NERDComOptionsDetails*
To enable any of the below options you should put the given line in your
~/.vimrc
*'loaded_nerd_comments'*
If this script is driving you insane you can turn it off by setting this
option >
let loaded_nerd_comments=1
<
------------------------------------------------------------------------------
*'NERDAllowAnyVisualDelims'*
Values: 0 or 1.
Default: 1.
If set to 1 then, when doing a visual or visual-block comment (but not a
visual-line comment), the script will choose the right delimiters to use for
the comment. This means either using the current delimiters if they are
multipart or using the alternative delimiters if THEY are multipart. For
example if we are editing the following java code: >
float foo = 1221;
float bar = 324;
System.out.println(foo * bar);
<
If we are using // comments and select the "foo" and "bar" in visual-block
mode, as shown left below (where '|'s are used to represent the visual-block
boundary), and comment it then the script will use the alternative delims as
shown on the right: >
float |foo| = 1221; float /*foo*/ = 1221;
float |bar| = 324; float /*bar*/ = 324;
System.out.println(foo * bar); System.out.println(foo * bar);
<
------------------------------------------------------------------------------
*'NERDBlockComIgnoreEmpty'*
Values: 0 or 1.
Default: 1.
This option affects visual-block mode commenting. If this option is turned
on, lines that begin outside the right boundary of the selection block will be
ignored.
For example, if you are commenting this chunk of c code in visual-block mode
(where the '|'s are used to represent the visual-block boundary) >
#include <sys/types.h>
#include <unistd.h>
#include <stdio.h>
|int| main(){
| | printf("SUCK THIS\n");
| | while(1){
| | fork();
| | }
|} |
<
If NERDBlockComIgnoreEmpty=0 then this code will become: >
#include <sys/types.h>
#include <unistd.h>
#include <stdio.h>
/*int*/ main(){
/* */ printf("SUCK THIS\n");
/* */ while(1){
/* */ fork();
/* */ }
/*} */
<
Otherwise, the code block would become: >
#include <sys/types.h>
#include <unistd.h>
#include <stdio.h>
/*int*/ main(){
printf("SUCK THIS\n");
while(1){
fork();
}
/*} */
<
------------------------------------------------------------------------------
*'NERDCommentWholeLinesInVMode'*
Values: 0, 1 or 2.
Default: 0.
By default the script tries to comment out exactly what is selected in visual
mode (v). For example if you select and comment the following c code (using |
to represent the visual boundary): >
in|t foo = 3;
int bar =| 9;
int baz = foo + bar;
<
This will result in: >
in/*t foo = 3;*/
/*int bar =*/ 9;
int baz = foo + bar;
<
But some people prefer it if the whole lines are commented like: >
/*int foo = 3;*/
/*int bar = 9;*/
int baz = foo + bar;
<
If you prefer the second option then stick this line in your vimrc: >
let NERDCommentWholeLinesInVMode=1
<
If the filetype you are editing only has no multipart delimiters (for example
a shell script) and you hadnt set this option then the above would become >
in#t foo = 3;
#int bar = 9;
<
(where # is the comment delimiter) as this is the closest the script can
come to commenting out exactly what was selected. If you prefer for whole
lines to be commented out when there is no multipart delimiters but the EXACT
text that was selected to be commented out if there IS multipart delimiters
then stick the following line in your vimrc: >
let NERDCommentWholeLinesInVMode=2
<
Note that this option does not affect the behaviour of commenting in
|visual-block| mode.
------------------------------------------------------------------------------
*'NERDCreateDefaultMappings'*
Values: 0 or 1.
Default: 1.
If set to 0, none of the default mappings will be created.
See also |NERDComMappings|.
------------------------------------------------------------------------------
*'NERDRemoveAltComs'*
Values: 0 or 1.
Default: 1.
When uncommenting a line (for a filetype with an alternative commenting style)
this option tells the script whether to look for, and remove, comment
delimiters of the alternative style.
For example, if you are editing a c++ file using // style comments and you go
,cu on this line: >
/* This is a c++ comment baby! */
<
It will not be uncommented if the NERDRemoveAltComs is set to 0.
------------------------------------------------------------------------------
*'NERDRemoveExtraSpaces'*
Values: 0 or 1.
Default: 1.
By default, the NERD commenter will remove spaces around comment delimiters if
either:
1. |'NERDSpaceDelims'| is set to 1.
2. NERDRemoveExtraSpaces is set to 1.
This means that if we have the following lines in a c code file: >
/* int foo = 5; */
/* int bar = 10; */
int baz = foo + bar
<
If either of the above conditions hold then if these lines are uncommented
they will become: >
int foo = 5;
int bar = 10;
int baz = foo + bar
<
Otherwise they would become: >
int foo = 5;
int bar = 10;
int baz = foo + bar
<
If you want the spaces to be removed only if |'NERDSpaceDelims'| is set then
set NERDRemoveExtraSpaces to 0.
------------------------------------------------------------------------------
*'NERDLPlace'*
*'NERDRPlace'*
Values: arbitrary string.
Default:
NERDLPlace: "[>"
NERDRPlace: "<]"
These options are used to control the strings used as place-holder delimiters.
Place holder delimiters are used when performing nested commenting when the
filetype supports commenting styles with both left and right delimiters.
To set these options use lines like: >
let NERDLPlace="FOO"
let NERDRPlace="BAR"
<
Following the above example, if we have line of c code: >
/* int horse */
<
and we comment it with ,cn it will be changed to: >
/*FOO int horse BAR*/
<
When we uncomment this line it will go back to what it was.
------------------------------------------------------------------------------
*'NERDMenuMode'*
Values: 0, 1, 2, 3.
Default: 3
This option can take 4 values:
"0": Turns the menu off.
"1": Turns the 'comment' menu on with no menu shortcut.
"2": Turns the 'comment 'menu on with <alt>-c as the shortcut.
"3": Turns the 'Plugin -> comment' menu on with <alt>-c as the shortcut.
------------------------------------------------------------------------------
*'NERDUsePlaceHolders'*
Values: 0 or 1.
Default 1.
This option is used to specify whether place-holder delimiters should be used
when creating a nested comment.
------------------------------------------------------------------------------
*'NERDSpaceDelims'*
Values: 0 or 1.
Default 0.
Some people prefer a space after the left delimiter and before the right
delimiter like this: >
/* int foo=2; */
<
as opposed to this: >
/*int foo=2;*/
<
If you want spaces to be added then set NERDSpaceDelims to 1 in your vimrc.
See also |'NERDRemoveExtraSpaces'|.
------------------------------------------------------------------------------
*'NERDCompactSexyComs'*
Values: 0 or 1.
Default 0.
Some people may want their sexy comments to be like this: >
/* Hi There!
* This is a sexy comment
* in c */
<
As opposed to like this: >
/*
* Hi There!
* This is a sexy comment
* in c
*/
<
If this option is set to 1 then the top style will be used.
------------------------------------------------------------------------------
*'NERDDefaultNesting'*
Values: 0 or 1.
Default 1.
When this option is set to 1, comments are nested automatically. That is, if
you hit ,cc on a line that is already commented it will be commented again
------------------------------------------------------------------------------
3.3 Default delimiter customisation *NERDComDefaultDelims*
If you want the NERD commenter to use the alternative delimiters for a
specific filetype by default then put a line of this form into your vimrc: >
let NERD_<filetype>_alt_style=1
<
Example: java uses // style comments by default, but you want it to default to
/* */ style comments instead. You would put this line in your vimrc: >
let NERD_java_alt_style=1
<
See |NERDComAltDelim| for switching commenting styles at runtime.
==============================================================================
4. Key mapping customisation *NERDComMappings*
To change a mapping just map another key combo to the internal <plug> mapping.
For example, to remap the |NERDComComment| mapping to ",omg" you would put
this line in your vimrc: >
map ,omg <plug>NERDCommenterComment
<
This will stop the corresponding default mappings from being created.
See the help for the mapping in question to see which <plug> mapping to
map to.
See also |'NERDCreateDefaultMappings'|.
==============================================================================
5. Issues with the script *NERDComIssues*
------------------------------------------------------------------------------
5.1 Delimiter detection heuristics *NERDComHeuristics*
Heuristics are used to distinguish the real comment delimiters
Because we have comment mappings that place delimiters in the middle of lines,
removing comment delimiters is a bit tricky. This is because if comment
delimiters appear in a line doesnt mean they really ARE delimiters. For
example, Java uses // comments but the line >
System.out.println("//");
<
clearly contains no real comment delimiters.
To distinguish between ``real'' comment delimiters and ``fake'' ones we use a
set of heuristics. For example, one such heuristic states that any comment
delimiter that has an odd number of non-escaped " characters both preceding
and following it on the line is not a comment because it is probably part of a
string. These heuristics, while usually pretty accurate, will not work for all
cases.
------------------------------------------------------------------------------
5.2 Nesting issues *NERDComNesting*
If we have some line of code like this: >
/*int foo */ = /*5 + 9;*/
<
This will not be uncommented legally. The NERD commenter will remove the
"outter most" delimiters so the line will become: >
int foo */ = /*5 + 9;
<
which almost certainly will not be what you want. Nested sets of comments will
uncomment fine though. Eg: >
/*int/* foo =*/ 5 + 9;*/
<
will become: >
int/* foo =*/ 5 + 9;
<
(Note that in the above examples I have deliberately not used place holders
for simplicity)
==============================================================================
6. About *NERDComAbout*
The author of the NERD commenter is Martyzillatron --- the half robot, half
dinosaur bastard son of Megatron and Godzilla. He enjoys destroying
metropolises and eating tourist busses.
Drop him a line at martin_grenfell at msn.com. He would love to hear from you.
its a lonely life being the worlds premier terror machine. How would you feel
if your face looked like a toaster and a t-rex put together? :(
The latest stable versions can be found at
http://www.vim.org/scripts/script.php?script_id=1218
The latest dev versions are on github
http://github.com/scrooloose/nerdcommenter
==============================================================================
8. Changelog *NERDComChangelog*
2.2.2
- remove the NERDShutup option and the message is suppresses, this makes
the plugin silently rely on &commentstring for unknown filetypes.
- add support for dhcpd, limits, ntp, resolv, rgb, sysctl, udevconf and
udevrules. Thanks to Thilo Six.
- match filetypes case insensitively
- add support for mp (metapost), thanks to Andrey Skvortsov.
- add support for htmlcheetah, thanks to Simon Hengel.
- add support for javacc, thanks to Matt Tolton.
- make <%# %> the default delims for eruby, thanks to tpope.
- add support for javascript.jquery, thanks to Ivan Devat.
- add support for cucumber and pdf. Fix sass and railslog delims,
thanks to tpope
2.2.1
- add support for newlisp and clojure, thanks to Matthew Lee Hinman.
- fix automake comments, thanks to Elias Pipping
- make haml comments default to -# with / as the alternative delimiter,
thanks to tpope
- add support for actionscript and processing thanks to Edwin Benavides
- add support for ps1 (powershell), thanks to Jason Mills
- add support for hostsaccess, thanks to Thomas Rowe
- add support for CVScommit
- add support for asciidoc, git and gitrebase. Thanks to Simon Ruderich.
- use # for gitcommit comments, thanks to Simon Ruderich.
- add support for mako and genshi, thanks to Keitheis.
- add support for conkyrc, thanks to David
- add support for SVNannotate, thanks to Miguel Jaque Barbero.
- add support for sieve, thanks to Stefan Walk
- add support for objj, thanks to Adam Thorsen.
2.2.0
- rewrote the mappings system to be more "standard".
- removed all the mapping options. Now, mappings to <plug> mappings are
used
- see :help NERDComMappings, and :help NERDCreateDefaultMappings for
more info
- remove "prepend comments" and "right aligned comments".
- add support for applescript, calbire, man, SVNcommit, potwiki, txt2tags and SVNinfo.
Thanks to nicothakis, timberke, sgronblo, mntnoe, Bernhard Grotz, John
O'Shea, François and Giacomo Mariani respectively.
- bugfix for haskell delimiters. Thanks to mntnoe.
2.1.18
- add support for llvm. Thanks to nicothakis.
- add support for xquery. Thanks to Phillip Kovalev.
2.1.17
- fixed haskell delimiters (hackily). Thanks to Elias Pipping.
- add support for mailcap. Thanks to Pascal Brueckner.
- add support for stata. Thanks to Jerónimo Carballo.
- applied a patch from ewfalor to fix an error in the help file with the
NERDMapleader doc
- disable the insert mode ctrl-c mapping by default, see :help
NERDComInsertComment if you wish to restore it
==============================================================================
8. Credits *NERDComCredits*
Thanks to the follow people for suggestions and patches:
Nick Brettell
Matthew Hawkins
Mathieu Clabaut
Greg Searle
Nguyen
Litchi
Jorge Scandaliaris
Shufeng Zheng
Martin Stubenschrott
Markus Erlmann
Brent Rice
Richard Willis
Igor Prischepoff
Harry
David Bourgeois
Eike Von Seggern
Torsten Blix
Alexander Bosecke
Stefano Zacchiroli
Norick Chen
Joseph Barker
Gary Church
Tim Carey-Smith
Markus Klinik
Anders
Seth Mason
James Hales
Heptite
Cheng Fang
Yongwei Wu
David Miani
Jeremy Hinegardner
Marco
Ingo Karkat
Zhang Shuhan
tpope
Ben Schmidt
David Fishburn
Erik Falor
JaGoTerr
Elias Pipping
mntnoe
Mark S.
Thanks to the following people for sending me new filetypes to support:
The hackers The filetypes~
Sam R verilog
Jonathan Derque context, plaintext and mail
Vigil fetchmail
Michael Brunner kconfig
Antono Vasiljev netdict
Melissa Reid omlet
Ilia N Ternovich quickfix
John O'Shea RTF, SVNcommitlog and vcscommit, SVNCommit
Anders occam
Mark Woodward csv
fREW gentoo-package-mask,
gentoo-package-keywords,
gentoo-package-use, and vo_base
Alexey verilog_systemverilog, systemverilog
Lizendir fstab
Michael Böhler autoit, autohotkey and docbk
Aaron Small cmake
Ramiro htmldjango and django
Stefano Zacchiroli debcontrol, debchangelog, mkd
Alex Tarkovsky ebuild and eclass
Jorge Rodrigues gams
Rainer Müller Objective C
Jason Mills Groovy, ps1
Normandie Azucena vera
Florian Apolloner ldif
David Fishburn lookupfile
Niels Aan de Brugh rst
Don Hatlestad ahk
Christophe Benz Desktop and xsd
Eyolf Østrem lilypond, bbx and lytex
Ingo Karkat dosbatch
Nicolas Weber markdown, objcpp
tinoucas gentoo-conf-d
Greg Weber D, haml
Bruce Sherrod velocity
timberke cobol, calibre
Aaron Schaefer factor
Mr X asterisk, mplayerconf
Kuchma Michael plsql
Brett Warneke spectre
Pipp lhaskell
Renald Buter scala
Vladimir Lomov asymptote
Marco mrxvtrc, aap
nicothakis SVNAnnotate, CVSAnnotate, SVKAnnotate,
SVNdiff, gitAnnotate, gitdiff, dtrace
llvm, applescript
Chen Xing Wikipedia
Jacobo Diaz dakota, patran
Li Jin gentoo-env-d, gentoo-init-d,
gentoo-make-conf, grub, modconf, sudoers
SpookeyPeanut rib
Greg Jandl pyrex/cython
Christophe Benz services, gitcommit
A Pontus vimperator
Stromnov slice, bzr
Martin Kustermann pamconf
Indriði Einarsson mason
Chris map
Krzysztof A. Adamski group
Pascal Brueckner mailcap
Jerónimo Carballo stata
Phillip Kovalev xquery
Bernhard Grotz potwiki
sgronblo man
François txt2tags
Giacomo Mariani SVNinfo
Matthew Lee Hinman newlisp, clojure
Elias Pipping automake
Edwin Benavides actionscript, processing
Thomas Rowe hostsaccess
Simon Ruderich asciidoc, git, gitcommit, gitrebase
Keitheis mako, genshi
David conkyrc
Miguel Jaque Barbero SVNannotate
Stefan Walk sieve
Adam Thorsen objj
Thilo Six dhcpd, limits, ntp, resolv, rgb, sysctl,
udevconf, udevrules
Andrey Skvortsov mp
Simon Hengel htmlcheetah
Matt Tolton javacc
Ivan Devat javascript.jquery
tpope cucumber,pdf
==============================================================================
9. License *NERDComLicense*
The NERD commenter is released under the wtfpl.
See http://sam.zoy.org/wtfpl/COPYING.

1199
vim/doc/NERD_tree.txt Normal file
View File

File diff suppressed because it is too large Load Diff

502
vim/doc/bufexplorer.txt Normal file
View File

@@ -0,0 +1,502 @@
*bufexplorer.txt* Buffer Explorer Last Change: 16 Feb 2010
Buffer Explorer *buffer-explorer* *bufexplorer*
Version 7.2.7
Plugin for easily exploring (or browsing) Vim |:buffers|.
|bufexplorer-installation| Installation
|bufexplorer-usage| Usage
|bufexplorer-windowlayout| Window Layout
|bufexplorer-customization| Customization
|bufexplorer-changelog| Change Log
|bufexplorer-todo| Todo
|bufexplorer-credits| Credits
For Vim version 7.0 and above.
This plugin is only available if 'compatible' is not set.
{Vi does not have any of this}
==============================================================================
INSTALLATION *bufexplorer-installation*
To install:
- Download the bufexplorer.zip.
- Extract the zip archive into your runtime directory.
The archive contains plugin/bufexplorer.vim, and doc/bufexplorer.txt.
- Start Vim or goto an existing instance of Vim.
- Execute the following command:
>
:helptag <your runtime directory>/doc
<
This will generate all the help tags for any file located in the doc
directory.
==============================================================================
USAGE *bufexplorer-usage*
To start exploring in the current window, use: >
\be or :BufExplorer
To start exploring in a newly split horizontal window, use: >
\bs or :BufExplorerHorizontalSplit
To start exploring in a newly split vertical window, use: >
\bv or :BufExplorerVerticalSplit
If you would like to use something other than '\', you may simply change the
leader (see |mapleader|).
Note: If the current buffer is modified when bufexplorer started, the current
window is always split and the new bufexplorer is displayed in that new
window.
Commands to use once exploring:
<F1> Toggle help information.
<enter> Opens the buffer that is under the cursor into the current
window.
<leftmouse> Opens the buffer that is under the cursor into the current
window.
<shift-enter> Opens the buffer that is under the cursor in another tab.
d |:delete|the buffer under the cursor from the list. The
buffer's 'buflisted' is cleared. This allows for the buffer to
be displayed again using the 'show unlisted' command.
R Toggles relative path/absolute path.
T Toggles to show only buffers for this tab or not.
D |:wipeout|the buffer under the cursor from the list. When a
buffers is wiped, it will not be shown when unlisted buffer are
displayed.
f Toggles whether you are taken to the active window when
selecting a buffer or not.
o Opens the buffer that is under the cursor into the current
window.
p Toggles the showing of a split filename/pathname.
q Quit exploring.
r Reverses the order the buffers are listed in.
s Selects the order the buffers are listed in. Either by buffer
number, file name, file extension, most recently used (MRU), or
full path.
t Opens the buffer that is under the cursor in another tab.
u Toggles the showing of "unlisted" buffers.
Once invoked, Buffer Explorer displays a sorted list (MRU is the default
sort method) of all the buffers that are currently opened. You are then
able to move the cursor to the line containing the buffer's name you are
wanting to act upon. Once you have selected the buffer you would like,
you can then either open it, close it(delete), resort the list, reverse
the sort, quit exploring and so on...
===============================================================================
WINDOW LAYOUT *bufexplorer-windowlayout*
-------------------------------------------------------------------------------
" Press <F1> for Help
" Sorted by mru | Locate buffer | Absolute Split path
"=
01 %a bufexplorer.txt C:\Vim\vimfiles\doc line 87
02 # bufexplorer.vim c:\Vim\vimfiles\plugin line 1
-------------------------------------------------------------------------------
| | | | |
| | | | +-- Current Line #.
| | | +-- Relative/Full Path
| | +-- Buffer Name.
| +-- Buffer Attributes. See|:buffers|for more information.
+-- Buffer Number. See|:buffers|for more information.
===============================================================================
CUSTOMIZATION *bufexplorer-customization*
*g:bufExplorerDefaultHelp*
To control whether the default help is displayed or not, use: >
let g:bufExplorerDefaultHelp=0 " Do not show default help.
let g:bufExplorerDefaultHelp=1 " Show default help.
The default is to show the default help.
*g:bufExplorerDetailedHelp*
To control whether detailed help is display by, use: >
let g:bufExplorerDetailedHelp=0 " Do not show detailed help.
let g:bufExplorerDetailedHelp=1 " Show detailed help.
The default is NOT to show detailed help.
*g:bufExplorerFindActive*
To control whether you are taken to the active window when selecting a buffer,
use: >
let g:bufExplorerFindActive=0 " Do not go to active window.
let g:bufExplorerFindActive=1 " Go to active window.
The default is to be taken to the active window.
*g:bufExplorerReverseSort*
To control whether to sort the buffer in reverse order or not, use: >
let g:bufExplorerReverseSort=0 " Do not sort in reverse order.
let g:bufExplorerReverseSort=1 " Sort in reverse order.
The default is NOT to sort in reverse order.
*g:bufExplorerShowDirectories*
Directories usually show up in the list from using a command like ":e .".
To control whether to show directories in the buffer list or not, use: >
let g:bufExplorerShowDirectories=1 " Show directories.
let g:bufExplorerShowDirectories=0 " Don't show directories.
The default is to show directories.
*g:bufExplorerShowRelativePath*
To control whether to show absolute paths or relative to the current
directory, use: >
let g:bufExplorerShowRelativePath=0 " Show absolute paths.
let g:bufExplorerShowRelativePath=1 " Show relative paths.
The default is to show absolute paths.
*g:bufExplorerShowUnlisted*
To control whether to show unlisted buffer or not, use: >
let g:bufExplorerShowUnlisted=0 " Do not show unlisted buffers.
let g:bufExplorerShowUnlisted=1 " Show unlisted buffers.
The default is to NOT show unlisted buffers.
*g:bufExplorerSortBy*
To control what field the buffers are sorted by, use: >
let g:bufExplorerSortBy='extension' " Sort by file extension.
let g:bufExplorerSortBy='fullpath' " Sort by full file path name.
let g:bufExplorerSortBy='mru' " Sort by most recently used.
let g:bufExplorerSortBy='name' " Sort by the buffer's name.
let g:bufExplorerSortBy='number' " Sort by the buffer's number.
The default is to sort by mru.
*g:bufExplorerSplitBelow*
To control where the new split window will be placed above or below the
current window, use: >
let g:bufExplorerSplitBelow=1 " Split new window below current.
let g:bufExplorerSplitBelow=0 " Split new window above current.
The default is to use what ever is set by the global &splitbelow
variable.
*g:bufExplorerSplitOutPathName*
To control whether to split out the path and file name or not, use: >
let g:bufExplorerSplitOutPathName=1 " Split the path and file name.
let g:bufExplorerSplitOutPathName=0 " Don't split the path and file
" name.
The default is to split the path and file name.
*g:bufExplorerSplitRight*
To control where the new vsplit window will be placed to the left or right of
current window, use: >
let g:bufExplorerSplitRight=0 " Split left.
let g:bufExplorerSplitRight=1 " Split right.
The default is to use the global &splitright.
*g:bufExplorerShowTabBuffer*
To control weither or not to show buffers on for the specific tab or not, use: >
let g:bufExplorerShowTabBuffer=0 " No.
let g:bufExplorerShowTabBuffer=1 " Yes.
The default is not to show.
===============================================================================
CHANGE LOG *bufexplorer-changelog*
7.2.7 - Fix:
* My 1st attempt to fix the "cache" issue where buffers information
has changed but the cache/display does not reflect those changes.
More work still needs to be done.
7.2.6 - Fix:
* Thanks to Michael Henry for pointing out that I totally forgot to
update the inline help to reflect the previous change to the 'd'
and 'D' keys. Opps!
7.2.5 - Fix:
* Philip Morant suggested switching the command (bwipe) associated
with the 'd' key with the command (bdelete) associated with the 'D'
key. This made sense since the 'd' key is more likely to be used
compared to the 'D' key.
7.2.4 - Fix:
* I did not implement the patch provided by Godefroid Chapelle
correctly. I missed one line which happened to be the most
important one :)
7.2.3 - Enhancements:
* Thanks to David Fishburn for helping me out with a much needed
code overhaul as well as some awesome performance enhancements.
He also reworked the handling of tabs.
* Thanks to Vladimir Dobriakov for making the suggestions on
enhancing the documentation to include a better explaination of
what is contained in the main bufexplorer window.
* Thanks to Yuriy Ershov for added code that when the bufexplorer
window is opened, the cursor is now positioned at the line with the
active buffer (useful in non-MRU sort modes).
* Yuriy also added the abiltiy to cycle through the sort fields in
reverse order.
Fixes:
* Thanks to Michael Henry for supplying a patch that allows
bufexplorer to be opened even when there is one buffer or less.
* Thanks to Godefroid Chapelle for supplying a patch that fixed
MRU sort order after loading a session.
7.2.2 - Fixes:
* Thanks to David L. Dight for spotting and fixing an issue when
using ctrl^. bufexplorer would incorrectly handle the previous
buffer so that when ctrl^ was pressed the incorrect file was opened.
7.2.1 - Fixes:
* Thanks to Dimitar for spotting and fixing a feature that was
inadvertently left out of the previous version. The feature was
when bufexplorer was used together with WinManager, you could use
the tab key to open a buffer in a split window.
7.2.0 - Enhancements:
* For all those missing the \bs and \bv commands, these have now
returned. Thanks to Phil O'Connell for asking for the return of
these missing features and helping test out this version.
Fixes:
* Fixed problem with the bufExplorerFindActive code not working
correctly.
* Fixed an incompatibility between bufexplorer and netrw that caused
buffers to be incorrectly removed from the MRU list.
7.1.7 - Fixes:
* TaCahiroy fixed several issues related to opening a buffer in a
tab.
7.1.6 - Fixes:
* Removed ff=unix from modeline in bufexplorer.txt. Found by Bill
McCarthy.
7.1.5 - Fixes:
* Could not open unnamed buffers. Fixed by TaCahiroy.
7.1.4 - Fixes:
* Sometimes when a file's path has 'white space' in it, extra buffers
would be created containing each piece of the path. i.e:
opening c:\document and settings\test.txt would create a buffer
named "and" and a buffer named "Documents". This was reported and
fixed by TaCa Yoss.
7.1.3 - Fixes:
* Added code to allow only one instance of the plugin to run at a
time. Thanks Dennis Hostetler.
7.1.2 - Fixes:
* Fixed a jumplist issue spotted by JiangJun. I overlooked the
'jumplist' and with a couple calls to 'keepjumps', everything is
fine again.
* Went back to just having a plugin file, no autoload file. By having
the autoload, WinManager was no longer working and without really
digging into the cause, it was easier to go back to using just a
plugin file.
7.1.1 - Fixes:
* A problem spotted by Thomas Arendsen Hein.
When running Vim (7.1.94), error E493 was being thrown.
Enhancements:
* Added 'D' for 'delete' buffer as the 'd' command was a 'wipe'
buffer.
7.1.0 - Another 'major' update, some by Dave Larson, some by me.
* Making use of 'autoload' now to make the plugin load quicker.
* Removed '\bs' and '\bv'. These are now controlled by the user. The
user can issue a ':sp' or ':vs' to create a horizontal or vertical
split window and then issue a '\be'
* Added handling of tabs.
7.0.17 - Fixed issue with 'drop' command.
Various enhancements and improvements.
7.0.16 - Fixed issue reported by Liu Jiaping on non Windows systems, which was
...
Open file1, open file2, modify file1, open bufexplorer, you get the
following error:
--------8<--------
Error detected while processing function
<SNR>14_StartBufExplorer..<SNR>14_SplitOpen:
line 4:
E37: No write since last change (add ! to override)
But the worse thing is, when I want to save the current buffer and
type ':w', I get another error message:
E382: Cannot write, 'buftype' option is set
--------8<--------
7.0.15 - Thanks to Mark Smithfield for suggesting bufexplorer needed to handle
the ':args' command.
7.0.14 - Thanks to Randall Hansen for removing the requirement of terminal
versions to be recompiled with 'gui' support so the 'drop' command
would work. The 'drop' command is really not needed in terminal
versions.
7.0.13 - Fixed integration with WinManager.
Thanks to Dave Eggum for another update.
- Fix: The detailed help didn't display the mapping for toggling
the split type, even though the split type is displayed.
- Fixed incorrect description in the detailed help for toggling
relative or full paths.
- Deprecated s:ExtractBufferNbr(). Vim's str2nr() does the same
thing.
- Created a s:Set() function that sets a variable only if it hasn't
already been defined. It's useful for initializing all those
default settings.
- Removed checks for repetitive command definitions. They were
unnecessary.
- Made the help highlighting a little more fancy.
- Minor reverse compatibility issue: Changed ambiguous setting
names to be more descriptive of what they do (also makes the code
easier to follow):
Changed bufExplorerSortDirection to bufExplorerReverseSort
Changed bufExplorerSplitType to bufExplorerSplitVertical
Changed bufExplorerOpenMode to bufExplorerUseCurrentWindow
- When the BufExplorer window closes, all the file-local marks are
now deleted. This may have the benefit of cleaning up some of the
jumplist.
- Changed the name of the parameter for StartBufExplorer from
"split" to "open". The parameter is a string which specifies how
the buffer will be open, not if it is split or not.
- Deprecated DoAnyMoreBuffersExist() - it is a one line function
only used in one spot.
- Created four functions (SplitOpen(), RebuildBufferList(),
UpdateHelpStatus() and ReSortListing()) all with one purpose - to
reduce repeated code.
- Changed the name of AddHeader() to CreateHelp() to be more
descriptive of what it does. It now returns an array instead of
updating the window directly. This has the benefit of making the
code more efficient since the text the function returns is used a
little differently in the two places the function is called.
- Other minor simplifications.
7.0.12 - MAJOR Update.
This version will ONLY run with Vim version 7.0 or greater.
Dave Eggum has made some 'significant' updates to this latest
version:
- Added BufExplorerGetAltBuf() global function to be used in the
user’s rulerformat.
- Added g:bufExplorerSplitRight option.
- Added g:bufExplorerShowRelativePath option with mapping.
- Added current line highlighting.
- The split type can now be changed whether bufexplorer is opened
in split mode or not.
- Various major and minor bug fixes and speed improvements.
- Sort by extension.
Other improvements/changes:
- Changed the help key from '?' to <F1> to be more 'standard'.
- Fixed splitting of vertical bufexplorer window.
Hopefully I have not forgot something :)
7.0.11 - Fixed a couple of highlighting bugs, reported by David Eggum. He also
changed passive voice to active on a couple of warning messages.
7.0.10 - Fixed bug report by Xiangjiang Ma. If the 'ssl' option is set,
the slash character used when displaying the path was incorrect.
7.0.9 - Martin Grenfell found and eliminated an annoying bug in the
bufexplorer/winmanager integration. The bug was were an
annoying message would be displayed when a window was split or
a new file was opened in a new window. Thanks Martin!
7.0.8 - Thanks to Mike Li for catching a bug in the WinManager integration.
The bug was related to the incorrect displaying of the buffer
explorer's window title.
7.0.7 - Thanks to Jeremy Cowgar for adding a new enhancement. This
enhancement allows the user to press 'S', that is capital S, which
will open the buffer under the cursor in a newly created split
window.
7.0.6 - Thanks to Larry Zhang for finding a bug in the "split" buffer code.
If you force set g:bufExplorerSplitType='v' in your vimrc, and if you
tried to do a \bs to split the bufexplorer window, it would always
split horizontal, not vertical. He also found that I had a typeo in
that the variable g:bufExplorerSplitVertSize was all lower case in
the documentation which was incorrect.
7.0.5 - Thanks to Mun Johl for pointing out a bug that if a buffer was
modified, the '+' was not showing up correctly.
7.0.4 - Fixed a problem discovered first by Xiangjiang Ma. Well since I've
been using vim 7.0 and not 6.3, I started using a function (getftype)
that is not in 6.3. So for backward compatibility, I conditionaly use
this function now. Thus, the g:bufExplorerShowDirectories feature is
only available when using vim 7.0 and above.
7.0.3 - Thanks to Erwin Waterlander for finding a problem when the last
buffer was deleted. This issue got me to rewrite the buffer display
logic (which I've wanted to do for sometime now).
Also great thanks to Dave Eggum for coming up with idea for
g:bufExplorerShowDirectories. Read the above information about this
feature.
7.0.2 - Thanks to Thomas Arendsen Hein for finding a problem when a user
has the default help turned off and then brought up the explorer. An
E493 would be displayed.
7.0.1 - Thanks to Erwin Waterlander for finding a couple problems.
The first problem allowed a modified buffer to be deleted. Opps! The
second problem occurred when several files were opened, BufExplorer
was started, the current buffer was deleted using the 'd' option, and
then BufExplorer was exited. The deleted buffer was still visible
while it is not in the buffers list. Opps again!
7.0.0 - Thanks to Shankar R. for suggesting to add the ability to set
the fixed width (g:bufExplorerSplitVertSize) of a new window
when opening bufexplorer vertically and fixed height
(g:bufExplorerSplitHorzSize) of a new window when opening
bufexplorer horizontally. By default, the windows are normally
split to use half the existing width or height.
6.3.0 - Added keepjumps so that the jumps list would not get cluttered with
bufexplorer related stuff.
6.2.3 - Thanks to Jay Logan for finding a bug in the vertical split position
of the code. When selecting that the window was to be split
vertically by doing a '\bv', from then on, all splits, i.e. '\bs',
were split vertically, even though g:bufExplorerSplitType was not set
to 'v'.
6.2.2 - Thanks to Patrik Modesto for adding a small improvement. For some
reason his bufexplorer window was always showing up folded. He added
'setlocal nofoldenable' and it was fixed.
6.2.1 - Thanks goes out to Takashi Matsuo for added the 'fullPath' sorting
logic and option.
6.2.0 - Thanks goes out to Simon Johann-Ganter for spotting and fixing a
problem in that the last search pattern is overridden by the search
pattern for blank lines.
6.1.6 - Thanks to Artem Chuprina for finding a pesky bug that has been around
for sometime now. The <esc> key mapping was causing the buffer
explored to close prematurely when vim was run in an xterm. The <esc>
key mapping is now removed.
6.1.5 - Thanks to Khorev Sergey. Added option to show default help or not.
6.1.4 - Thanks goes out to Valery Kondakoff for suggesting the addition of
setlocal nonumber and foldcolumn=0. This allows for line numbering
and folding to be turned off temporarily while in the explorer.
6.1.3 - Added folding. Did some code cleanup. Added the ability to force the
newly split window to be temporarily vertical, which was suggested by
Thomas Glanzmann.
6.1.2 - Now pressing the <esc> key will quit, just like 'q'.
Added folds to hide winmanager configuration.
If anyone had the 'C' option in their cpoptions they would receive
a E10 error on startup of BufExplorer. cpo is now saved, updated and
restored. Thanks to Charles E Campbell, Jr.
Attempted to make sure there can only be one BufExplorer window open
at a time.
6.1.1 - Thanks to Brian D. Goodwin for adding toupper to FileNameCmp. This
way buffers sorted by name will be in the correct order regardless of
case.
6.0.16 - Thanks to Andre Pang for the original patch/idea to get bufexplorer
to work in insertmode/modeless mode (evim). Added Initialize
and Cleanup autocommands to handle commands that need to be
performed when starting or leaving bufexplorer.
6.0.15 - Srinath Avadhanulax added a patch for winmanager.vim.
6.0.14 - Fix a few more bug that I thought I already had fixed. Thanks
to Eric Bloodworth for adding 'Open Mode/Edit in Place'. Added
vertical splitting.
6.0.13 - Thanks to Charles E Campbell, Jr. for pointing out some embarrassing
typos that I had in the documentation. I guess I need to run
the spell checker more :o)
6.0.12 - Thanks to Madoka Machitani, for the tip on adding the augroup command
around the MRUList autocommands.
6.0.11 - Fixed bug report by Xiangjiang Ma. '"=' was being added to the
search history which messed up hlsearch.
6.0.10 - Added the necessary hooks so that the Srinath Avadhanula's
winmanager.vim script could more easily integrate with this script.
Tried to improve performance.
6.0.9 - Added MRU (Most Recently Used) sort ordering.
6.0.8 - Was not resetting the showcmd command correctly.
Added nifty help file.
6.0.7 - Thanks to Brett Carlane for some great enhancements. Some are added,
some are not, yet. Added highlighting of current and alternate
filenames. Added splitting of path/filename toggle. Reworked
ShowBuffers().
Changed my email address.
6.0.6 - Copyright notice added. Needed this so that it could be distributed
with Debian Linux. Fixed problem with the SortListing() function
failing when there was only one buffer to display.
6.0.5 - Fixed problems reported by David Pascoe, in that you where unable to
hit 'd' on a buffer that belonged to a files that no longer existed
and that the 'yank' buffer was being overridden by the help text when
the bufexplorer was opened.
6.0.4 - Thanks to Charles Campbell, Jr. for making this plugin more plugin
*compliant*, adding default keymappings of <Leader>be and <Leader>bs
as well as fixing the 'w:sortDirLabel not being defined' bug.
6.0.3 - Added sorting capabilities. Sort taken from explorer.vim.
6.0.2 - Can't remember. (2001-07-25)
6.0.1 - Initial release.
===============================================================================
TODO *bufexplorer-todo*
- Nothing as of now, buf if you have any suggestions, drop me an email.
===============================================================================
CREDITS *bufexplorer-credits*
Author: Jeff Lanzarotta <delux256-vim at yahoo dot com>
Credit must go out to Bram Moolenaar and all the Vim developers for
making the world's best editor (IMHO). I also want to thank everyone who
helped and gave me suggestions. I wouldn't want to leave anyone out so I
won't list names.
===============================================================================
vim:tw=78:noet:wrap:ts=8:ft=help:norl:

646
vim/doc/conque_term.txt Normal file
View File

@@ -0,0 +1,646 @@
*ConqueTerm* Plugin to run a shell inside a Vim buffer
The ConqueTerm plugin will turn a Vim buffer into a terminal emulator, allowing
you to run and interact with a shell or shell application inside the buffer.
1. Installation |conque-term-setup|
1.1 Requirements for Unix |conque-term-requirements|
1.2 Requirements for Windows |conque-term-windows|
1.3 Installation |conque-term-installation|
2. Usage |conque-term-usage|
2.1 General Usage |conque-term-gen-usage|
2.2 Special keys |conque-term-special-keys|
2.2.1 Send text to Conque |conque-term-send|
2.2.2 Toggle terminal input mode |conque-term-input-mode|
2.2.3 Sending the <Esc> key press |conque-term-esc|
3. Configuration |conque-term-options|
3.1 General |conque-config-general|
3.1.1 Python version |ConqueTerm_PyVersion|
3.1.2 Fast mode |ConqueTerm_FastMode|
3.1.3 Color support |ConqueTerm_Color|
3.1.4 Session Support |ConqueTerm_SessionSupport|
3.1.5 Keep updating terminal buffer |ConqueTerm_ReadUnfocused|
3.1.6 Insert mode when entering buffer |ConqueTerm_InsertOnEnter|
3.1.7 Close buffer when program exits |ConqueTerm_CloseOnEnd|
3.1.8 Hide start messages |ConqueTerm_StartMessages|
3.1.9 Regex for highlighting your prompt |ConqueTerm_PromptRegex|
3.1.10 Syntax type |ConqueTerm_Syntax|
3.2 Keyboard |conque-config-keyboard|
3.2.1 The <Esc> key |ConqueTerm_EscKey|
3.2.2 Toggle terminal input mode |ConqueTerm_ToggleKey|
3.2.3 Enable <C-w> in insert mode |ConqueTerm_CWInsert|
3.2.4 Execute current file in Conque |ConqueTerm_ExecFileKey|
3.2.5 Send current file contents to Conque|ConqueTerm_SendFileKey|
3.2.6 Send selected text to Conque |ConqueTerm_SendVisKey|
3.2.7 Function Keys |ConqueTerm_SendFunctionKeys|
3.3 Unix |conque-config-unix|
3.3.1 Choose your terminal type |ConqueTerm_TERM|
3.4 Windows |conque-config-windows|
3.4.1 Python executable |ConqueTerm_PyExe|
3.4.2 Windows character code page |ConqueTerm_CodePage|
3.4.3 Terminal color method |ConqueTerm_ColorMode|
4. VimScript API |conque-term-api|
4.1 conque_term#open() |conque-term-open|
4.2 conque_term#subprocess() |conque-term-subprocess|
4.3 conque_term#get_instance() |conque-term-get-instance|
4.4 CONQUE_OBJECT.write() |conque-term-write|
4.5 CONQUE_OBJECT.writeln() |conque-term-writeln|
4.6 CONQUE_OBJECT.read() |conque-term-read|
4.7 CONQUE_OBJECT.set_callback() |conque-term-set-callback|
4.8 CONQUE_OBJECT.close() |conque-term-close|
4.9 Registering functions |conque-term-events|
5. Misc |conque-term-misc|
5.1 Known bugs |conque-term-bugs|
5.2 Contribute |conque-term-contribute|
5.3 Feedback |conque-term-feedback|
==============================================================================
1. Installation *conque-term-setup*
Conque is designed for both Unix and Windows operating systems, however the
requirements are slightly different. Please check section below corresponding
to your installed OS.
1.1 Requirements for Unix *conque-term-requirements*
* [G]Vim 7.0+ with +python and/or +python3
* Python 2.3+ and/or 3.x
* Unix-like OS: Linux, OS X, Solaris, Cygwin, etc
The most common stumbling block is getting a version of Vim which has the
python interface enabled. Most all software package managers will have a copy
of Vim with Python support, so that is often the easiest way to get it. If
you're compiling Vim from source, be sure to use the --enable-pythoninterp
option, or --enable-python3interp for Python 3. On OS X the best option is
MacVim, which installs with Python support by default.
1.2 Requirements for Windows *conque-term-windows*
* [G]Vim 7.3 with +python and/or +python3
* Python 2.7 and/or 3.1
* Modern Windows OS (XP or later)
Conque only officially supports the latest GVim 7.3 Windows installer
available at www.vim.org. If you are currently using Vim 7.2 or earlier you
will need to upgrade to 7.3 for Windows support. The Windows installer already
has the +python/+python3 interface built in.
The official 7.3 release of Vim for Windows only works with Python versions
2.7 and/or 3.1. You can download and install Python from their website
http://www.python.org/download
If you are compiling Vim + Python from source on Windows, the requirements
become only Vim 7.3+ and Python 2.7+.
1.3 Installation *conque-term-installation*
Download the latest vimball from http://conque.googlecode.com
Open the .vba file with Vim and run the following commands:
>
:so %
:q
<
That's it! The :ConqueTerm command will be available the next time you start
Vim. You can delete the .vba file when you've verified Conque was successfully
installed.
==============================================================================
2. Usage *conque-term-usage*
2.1 General Usage *conque-term-gen-usage*
Type :ConqueTerm <command> to launch an application in the current buffer. Eg:
>
:ConqueTerm bash
:ConqueTerm mysql -h localhost -u joe_lunchbox Menu
:ConqueTerm Powershell.exe
<
Use :ConqueTermSplit or :ConqueTermVSplit to open Conque in a new horizontal
or vertical buffer. Use :ConqueTermTab to open Conque in a new tab.
In insert mode you can interact with the shell as you would expect in a
normal terminal. All key presses will be sent to the terminal, including
control characters. See |conque-term-special-keys| for more information,
particularly regarding the <Esc> key.
In normal mode you can use Vim commands to browse your terminal output and
scroll back through the history. Most all Vim functionality will work, such
as searching, yanking or highlighting text.
2.2 Special keys *conque-term-special-keys*
There are several keys which can be configured to have special behavior with
Conque.
2.2.1 Send text to Conque *conque-term-send*
Conque gives you three different commands to send text from a different
buffer, probably a source code file, to the Conque terminal buffer. All three
are configurable to use your choice of key combinations.
To send a visually selected range of text to an existing terminal buffer,
press the <F9> key.
To send the entire contents of the file you are editing to an existing
terminal buffer, press the <F10> key.
Finally, to execute the current file in a new terminal buffer press the <F11>
key. This will split the screen with a new Conque buffer. The file you are
editing must be executable for this command to work.
See |conque-term-options| for information about configuring these commands.
2.2.2 Toggle terminal input mode *conque-term-input-mode*
If you want to use insert mode to edit the terminal screen, press <F8>. You
will now be able to edit the terminal output freely without your cursor
jumping the the active prompt line. This may be useful if you want to reformat
terminal output for readability.
While the terminal is paused new output will not be displayed on the screen
until you press <F8> again to resume.
You can configure Conque to use a different key with the |ConqueTerm_ToggleKey|
option.
2.2.3 Sending the <Esc> key press *conque-term-esc*
By default if you press the <Esc> key in a Conque buffer you will leave insert
mode. But what if you want the <Esc> character to be sent to your terminal?
There are two options. By default, pressing <Esc> twice will send one <Esc>
character to the terminal and you will remain in insert mode, while pressing
it once will leave insert mode.
Alternatively you can use the |ConqueTerm_EscKey| option to choose a
different key for leaving insert mode. If a custom key is set, then all <Esc>
key presses will be sent to the terminal.
2.3 Registering functions *conque-term-register*
Conque allows you to write your own VimScript functions which will be called
at certain events. See the API section |conque-term-events| for more.
==============================================================================
3. Options *conque-term-options*
You can set the following options in your .vimrc (default values shown)
3.1 General *conque-config-general*
3.1.1 Python version *ConqueTerm_PyVersion*
Conque will work with either Python 2.x or 3.x, assuming the interfaces have
been installed. By default it will try to use Python 2 first, then will try
Python 3. If you want Conque to use Python 3, set this variable to 3.
Note: even if you set this to 3, if you don't have the python3 interface
Conque will fall back to using Python 2.
>
let g:ConqueTerm_PyVersion = 2
<
3.1.2 Fast Mode *ConqueTerm_FastMode*
Disable features which could make Conque run slowly. This includes most
terminal colors and some unicode support. Set this to 1 to enable fast mode.
>
let g:ConqueTerm_FastMode = 0
<
3.1.3 Color support *ConqueTerm_Color*
Terminal colors have the potential to slow down terminal screen rendering,
depending on how many colors are used and how fast the computer is. This
option allows you to choose how much color support will be enabled.
If set to 0, terminal colors will be disabled. This will allow the terminal to
render most quickly. Syntax highlighting will still work. For example
highlighting quoted strings or MySQL output.
If set to 1, terminal colors will be enabled, but only for the most recent 200
lines of terminal output. Older output will be periodically stripped of color
highlighting to keep the display responsive.
If set to 2, terminal colors will always be enabled. If your programs don't
use color output very frequently this is a good choice.
Note: Color support is automatically disabled in "fast mode".
>
let g:ConqueTerm_Color = 1
<
3.1.4 Session Support *ConqueTerm_SessionSupport*
Vim's :mksession command allows you to save your current buffer configuration
to a file, which can be loaded at a later time after you've closed Vim.
By default, Conque buffers are not restored. This is mostly for safety
reasons; you may not want Vim to automatically re-run a destructive command.
However, if you're not working with missile launch code, and want Vim to
restart your Conque buffers when you load a session file, set this variable
to 1. Note your original subprocess and shell output will not be restored, but
the same command will be started in your buffer.
>
let g:ConqueTerm_SessionSupport = 0
<
3.1.5 Keep updating terminal buffer *ConqueTerm_ReadUnfocused*
If set to 1 then your Conque buffers will continue to update after you've
switched to another buffer.
Note: Conque buffers may continue to update, but they will not scroll down as
new lines are added beyond the bottom of the visible buffer area. This is a
limitation of the Vim scripting language for which I haven't found a
workaround.
>
let g:ConqueTerm_ReadUnfocused = 1
<
3.1.6 Insert mode when entering buffer *ConqueTerm_InsertOnEnter*
If set to 1 then you will automatically go into insert mode when you enter the
buffer. This diverges from normal Vim behavior. If 0 you will still be in
normal mode.
>
let g:ConqueTerm_InsertOnEnter = 0
<
3.1.7 Close buffer when program exits *ConqueTerm_CloseOnEnd*
If you want your terminal buffer to be closed and permanently deleted when the
program running inside of it exits, set this option to 1. Otherwise the buffer
will become a simple text buffer after the program exits, and you can edit the
program output in insert mode.
>
let g:ConqueTerm_CloseOnEnd = 0
<
3.1.8 Show start messages *ConqueTerm_StartMessages*
Display warning messages when starting up ConqueTerm if your system is
configured incorrectly.
>
let g:ConqueTerm_StartMessages = 1
<
3.1.9 Regex for highlighting your prompt *ConqueTerm_PromptRegex*
Use this regular expression for sytax highlighting your terminal prompt. Your
terminal will generally run faster if you use Vim highlighting instead of
terminal colors for your prompt. You can also use it to do more advanced
syntax highlighting for the prompt line.
>
let g:ConqueTerm_PromptRegex = '^\w\+@[0-9A-Za-z_.-]\+:[0-9A-Za-z_./\~,:-]\+\$'
<
3.1.10 Choose Vim syntax type *ConqueTerm_Syntax*
Set the buffer syntax. The default 'conque_term' has highlighting for MySQL,
but not much else.
>
let g:ConqueTerm_Syntax = 'conque_term'
<
3.2 Keyboard *conque-config-keyboard*
3.2.1 The <Esc> key *ConqueTerm_EscKey*
If a custom key is set, then all <Esc> key presses will be sent to the
terminal and you must use this custom key to leave insert mode. If left to the
default value of '<Esc>' then you must press it twice to send the escape
character to the terminal, while pressing it once will leave insert mode.
Note: You cannot use a key which is internally coded with the escape
character. This includes the <F-> keys and often the <A-> and <M-> keys.
Picking a control key, such as <C-k> will be your best bet.
>
let g:ConqueTerm_EscKey = '<Esc>'
<
3.2.2 Toggle terminal input mode *ConqueTerm_ToggleKey*
Press this key to pause terminal input and output display. You will then be
able to edit the terminal screen as if it were a normal text buffer. Press
this key again to resume terminal mode.
>
let g:ConqueTerm_ToggleKey = '<F8>'
<
3.2.3 Enable <C-w> in insert mode *ConqueTerm_CWInsert*
If set to 1 then you can leave the Conque buffer using the <C-w> commands
while you're still in insert mode. If set to 0 then the <C-w> character will
be sent to the terminal. If both this option and ConqueTerm_InsertOnEnter are
set you can go in and out of the terminal buffer while never leaving insert
mode.
>
let g:ConqueTerm_CWInsert = 0
<
3.2.4 Execute current file in Conque *ConqueTerm_ExecFileKey*
Press this key to execute the file you're currently editing in a Conque
buffer. Is equivelent to running the command :ConqueTermSplit YOUR_FILE. Your
file must be executable for this command to work correctly.
>
let g:ConqueTerm_ExecFileKey = '<F11>'
<
3.2.5 Send current file contents to Conque *ConqueTerm_SendFileKey*
Press this key to send your entire file contents to the most recently opened
Conque buffer as keyboard input.
>
let g:ConqueTerm_SendFileKey = '<F10>'
<
3.2.6 Send selected text to Conque *ConqueTerm_SendVisKey*
Use this key to send the currently selected text to the most recently created
Conque buffer.
>
let g:ConqueTerm_SendVisKey = '<F9>'
<
3.2.7 Function Keys *ConqueTerm_SendFunctionKeys*
By default, function keys (the F1-F12 row at the top of your keyboard) are not
passed to the terminal. Set this option to 1 to send these key events.
Note: Unless you configured |ConqueTerm_SendVisKey| and |ConqueTerm_ToggleKey|
to use different keys, <F8> and <F9> will not be sent to the terminal even if
you set this option to 1.
>
let g:ConqueTerm_SendFunctionKeys = 0
<
3.3 Unix *conque-config-unix*
3.3.1 Choose your terminal type, Unix ONLY *ConqueTerm_TERM*
Use this option to tell Conque what type of terminal it should identify itself
as. Conque officially uses the more limited VT100 terminal type for
developement and testing, although it supports some more advanced features
such as colors and title strings.
You can change this setting to a more advanced type, namely 'xterm', but your
results may vary depending on which programs you're running.
>
let g:ConqueTerm_TERM = 'vt100'
<
3.4 Windows *conque-config-windows*
3.4.1 Python executable, Windows ONLY *ConqueTerm_PyExe*
The Windows version of Conque needs to know the path to the python.exe
executable for the version of Python Conque is using. If you installed Python
in the default location, or added the Python directory to your system path,
Conque should be able to find python.exe without you changing this variable.
For example, you might set this to 'C:\Program Files\Python27\python.exe'
>
let g:ConqueTerm_PyExe = ''
<
3.4.2 Windows character code page *ConqueTerm_CodePage*
Set the "code page" Windows will use for your console. Leave this value set to
zero to use the environment code page.
Note: Displaying unicode characters on Conque for Windows needs work.
>
let g:ConqueTerm_CodePage = 0
<
3.4.3 Terminal color method, Windows ONLY *ConqueTerm_ColorMode*
Vim syntax highlighting by coordinate (e.g. the 3-7th characters on the 42nd
line) can be very slow. If you set this variable to 'conceal', you can use
the new conceal feature to render terminal colors. Requires Vim 7.3 and only
works on the Windows version of Conque. This will make colors render faster,
however it will also add hidden characters to the screen, which may be
annoying if you're copying and pasting terminal output out of the Conque
buffer. Set this to an empty string '' to disable concealed highlighting.
>
let g:ConqueTerm_ColorMode = 'conceal'
<
==============================================================================
4. VimScript API *conque-term-api*
The Conque scripting API allows you to create and interact with Conque
terminals with the VimScript language.
4.1 conque_term#open({command}, [buf_opts], [remain]) *conque-term-open*
The open() function will create a new terminal buffer and start your command.
The {command} must be an executable, either an absolute path or relative to
your system path.
You can pass in a list of vim commands [buf_opts] which will be executed after
the new buffer is created but before the command is started. These are
typically commands to alter the size, position or configuration of the buffer
window.
Note: If you don't pass in a command such as 'split', the terminal will open
in the current buffer.
If you don't want the new terminal buffer to become the new active buffer, set
[remain] to 1. Only works if you create a split screen using [options].
Returns a Conque terminal object.
Examples:
>
let my_terminal = conque_term#open('/bin/bash')
let my_terminal = conque_term#open('ipython', ['split', 'resize 20'], 1)
<
4.2 conque_term#subprocess({command}) *conque-term-subprocess*
Starts a new subprocess with your {command}, but no terminal buffer is ever
created. This may be useful if you need asynchronous interaction with a
subprocess, but want to handle the output on your own.
Returns a Conque terminal object.
Example:
>
let my_subprocess = conque_term#subprocess('tail -f /var/log/foo.log')
<
4.3 conque_term#get_instance( [terminal_number] ) *conque-term-get-instance*
Use the get_instance() function to retrieve an existing terminal object. The
terminal could have been created either with the user command :ConqueTerm or
with an API call to conque_term#open() or subprocess().
Use the optional [terminal_number] to retrieve a specific terminal instance.
Otherwise if the current buffer is a Conque terminal, it will be returned,
else the most recently created terminal. The terminal number is what you see
at the end of a terminal buffer name, e.g. "bash - 2".
Returns a Conque terminal object.
Example:
>
nnoremap <F4> :call conque_term#get_instance().writeln('clear')<CR>
<
4.4 CONQUE_OBJECT.write({text}) *conque-term-write*
Once you have a terminal object from open(), subprocess() or get_instance()
you can send text input to it with the write() method.
No return value.
Examples:
>
call my_terminal.write("whoami\n")
call my_terminal.write("\<C-c>")
<
4.5 CONQUE_OBJECT.writeln({text}) *conque-term-writeln*
The same as write() except adds a \n character to the end if your input.
Examples:
>
call my_subprocess.writeln('make')
<
4.6 CONQUE_OBJECT.read( [timeout], [update_buffer] ) *conque-term-read*
Read new output from a Conque terminal subprocess. New output will be returned
as a string, and the terminal buffer will also be updated by default.
If you are reading immediately after calling the write() method, you may want
to wait [timeout] milliseconds for output to be ready.
If you want to prevent the output from being displayed in the terminal buffer,
set [update_buffer] to 0. This option has no effect if the terminal was
created with the subprocess() function, since there never is a buffer to
update.
Returns output string.
Note: The terminal buffer will not automatically scroll down if the new output
extends beyond the bottom of the visible buffer. Vim doesn't allow "unfocused"
buffers to be scrolled at the current version, although hopefully this will
change.
Examples:
>
call my_terminal.writeln('whoami')
let output = my_terminal.read(500)
call my_terminal.writeln('ls -lha')
let output = my_terminal.read(1000, 1)
<
4.7 CONQUE_OBJECT.set_callback( {funcname} ) *conque-term-set-callback*
Register a callback function for this subprocess instance. This function will
automatically be called whenever new output is available. Only practical with
subprocess() objects.
Conque checkes for new subprocess output once a second when Vim is idle. If
new output is found your function will be called.
Pass in the callback function name {funcname} as a string.
No return value.
Note: this method requires the g:ConqueTerm_ReadUnfocused option to be set.
Note: this method is experimental, results may vary.
Example:
>
let sp = conque_term#subprocess('tail -f /home/joe/log/error_log')
function! MyErrorAlert(output)
echo a:output
endfunction
call sp.set_callback('MyErrorAlert')
<
4.8 CONQUE_OBJECT.close() *conque-term-close*
Kill your terminal subprocess. Sends the ABORT signal. You probably want to
close your subprocess in a more graceful manner with the write() method, but
this can be used when needed. Does not close the terminal buffer, if it
exists.
This method will be called on all existing Conque subprocesses when Vim exits.
Example:
>
let term = conque_term#open('ping google.com', ['belowright split'])
call term.read(5000)
call term.close()
<
4.9 Registering functions *conque-term-events*
Conque provides the option to register callback functions which will be
executed at several different events. The currently available events are:
after_startup After your application has loaded into the buffer.
buffer_enter When you switch to a Conque buffer.
buffer_leave When you leave a Conque buffer.
You may use the function conque_term#register_function(event, function_name)
to add additional hooks at a particular event. The second argument should be
the name of a callback function which has one parameter, the current
terminal object (see|conque-term-api|for more about terminal objects).
For example:
>
function MyConqueStartup(term)
" set buffer syntax using the name of the program currently running
let syntax_associations = { 'ipython': 'python', 'irb': 'ruby' }
if has_key(syntax_associations, a:term.program_name)
execute 'setlocal syntax=' . syntax_associations[a:term.program_name]
else
execute 'setlocal syntax=' . a:term.program_name
endif
" shrink window height to 10 rows
resize 10
" silly example of terminal api usage
if a:term.program_name == 'bash'
call a:term.writeln('svn up ~/projects/*')
endif
endfunction
call conque_term#register_function('after_startup', 'MyConqueStartup')
<
==============================================================================
5. Misc *conque-term-misc*
5.1 Known bugs *conque-term-bugs*
The following are known limitations:
- Font/color highlighting is imperfect and slow. If you don't care about
color in your shell, set g:ConqueTerm_Color = 0 in your .vimrc
- Conque only supports the extended ASCII character set for input, not utf-8.
- VT100 escape sequence support is not complete.
- Alt/Meta key support in Vim isn't great in general, and conque is no
exception. Pressing <Esc><Esc>x or <Esc><M-x> instead of <M-x> works in
most cases.
5.2 Contribute *conque-term-contribute*
The two contributions most in need are improvements to Vim itself. I currently
use hacks to capture key press input from the user, and to poll the terminal
for more output. The Vim todo.txt document lists proposed improvements to give
users this behavior without hacks. Having a key press event should allow
Conque to work with multi- byte input. If you are a Vim developer, please
consider prioritizing these two items:
- todo.txt (Autocommands, line ~3137)
8 Add an event like CursorHold that is triggered repeatedly, not just
once after typing something.
5.3 Feedback *conque-term-feedback*
Bugs, suggestions and patches are all welcome.
For more information visit http://conque.googlecode.com
Check out the latest from svn at http://conque.googlecode.com/svn/trunk/
vim:tw=78:ts=8:ft=help:norl:

818
vim/doc/delimitMate.txt Normal file
View File

@@ -0,0 +1,818 @@
*delimitMate.txt* Trying to keep those beasts at bay! v2.6 *delimitMate*
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMM MMMMMMMMM MMMMMMMMMMMMMMMMMMMMMMMMMM MMMMM MMMMMMMMMMMMMMMMMMMMM ~
MMMM MMMMMMMMM MMMMMMMMMMMMMMMMMMMMMMMMMM MMM MMMMMMMMMMMMMMMMMMMMM
MMMM MMMMMMMMM MMMMMMMMMMMMMMMMMMMMM MMM M M MMMMMMMMMM MMMMMMMMM ~
MMMM MMM MMM MM MM M M MMM MM MM MM MM MMM MMM MMM MM
MM MM M MM MMMMMM MMMMMMM MMM MMMMM MM M MMM MMM M M ~
M M MM MM MM MM M M MM MMM MMM MMMMM MMMMM MMM MMM M
M M MM MMMMM MM MM M M MM MMM MMM MMMMM MMM MMM MMM MMMM ~
M M MM M MM MM MM M M MM MMM MMM MMMMM MM M MMM MMM M M
MM MMM MMM MM MM M M MM MMM MM MMMMM MMM MMM MMM MM ~
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
==============================================================================
0.- CONTENTS *delimitMate-contents*
1. Introduction____________________________|delimitMateIntro|
2. Customization___________________________|delimitMateOptions|
2.1 Options summary____________________|delimitMateOptionSummary|
2.2 Options details____________________|delimitMateOptionDetails|
3. Functionality___________________________|delimitMateFunctionality|
3.1 Automatic closing & exiting________|delimitMateAutoClose|
3.2 Expansion of space and CR__________|delimitMateExpansion|
3.3 Backspace__________________________|delimitMateBackspace|
3.4 Smart Quotes_______________________|delimitMateSmartQuotes|
3.5 Balancing matching pairs___________|delimitMateBalance|
3.6 FileType based configuration_______|delimitMateFileType|
3.7 Syntax awareness___________________|delimitMateSyntax|
4. Commands________________________________|delimitMateCommands|
5. Mappings________________________________|delimitMateMappings|
6. Functions_______________________________|delimitMateFunctions|
7. TODO list_______________________________|delimitMateTodo|
8. Maintainer______________________________|delimitMateMaintainer|
9. Credits_________________________________|delimitMateCredits|
10. History_________________________________|delimitMateHistory|
==============================================================================
1.- INTRODUCTION *delimitMateIntro*
This plug-in provides automatic closing of quotes, parenthesis, brackets,
etc.; besides some other related features that should make your time in insert
mode a little bit easier.
Most of the features can be modified or disabled permanently, using global
variables, or on a FileType basis, using autocommands. With a couple of
exceptions and limitations, this features don't brake undo, redo or history.
NOTE 1: If you have any trouble with this plugin, please run |:DelimitMateTest|
in a new buffer to see what is not working.
NOTE 2: |'timeout'| needs to be set when working in the terminal, otherwise you
might find weird behaviour with mappings including <Esc> or arrow keys.
NOTE 3: Abbreiations set with |:iabbrev| will not be expanded by delimiters
used on delimitMate, you should use <C-]> (read |i_CTRL-]|) to expand them on
the go.
==============================================================================
2. CUSTOMIZATION *delimitMateOptions*
You can create your own mappings for some features using the global functions.
Read |DelimitMateFunctions| for more info.
------------------------------------------------------------------------------
2.1 OPTIONS SUMMARY *delimitMateOptionSummary*
The behaviour of this script can be customized setting the following options
in your vimrc file. You can use local options to set the configuration for
specific file types, see |delimitMateOptionDetails| for examples.
|'loaded_delimitMate'| Turns off the script.
|'delimitMate_autoclose'| Tells delimitMate whether to automagically
insert the closing delimiter.
|'delimitMate_matchpairs'| Tells delimitMate which characters are
matching pairs.
|'delimitMate_quotes'| Tells delimitMate which quotes should be
used.
|'delimitMate_nesting_quotes'| Tells delimitMate which quotes should be
allowed to be nested.
|'delimitMate_expand_cr'| Turns on/off the expansion of <CR>.
|'delimitMate_expand_space'| Turns on/off the expansion of <Space>.
|'delimitMate_smart_quotes'| Turns on/off the "smart quotes" feature.
|'delimitMate_smart_matchpairs'| Turns on/off the "smart matchpairs" feature.
|'delimitMate_balance_matchpairs'|Turns on/off the "balance matching pairs"
feature.
|'delimitMate_excluded_regions'| Turns off the script for the given regions or
syntax group names.
|'delimitMate_excluded_ft'| Turns off the script for the given file types.
|'delimitMate_apostrophes'| Tells delimitMate how it should "fix"
balancing of single quotes when used as
apostrophes. NOTE: Not needed any more, kept
for compatibility with older versions.
------------------------------------------------------------------------------
2.2 OPTIONS DETAILS *delimitMateOptionDetails*
Add the shown lines to your vimrc file in order to set the below options.
Buffer variables take precedence over global ones and can be used along with
autocmd to modify delimitMate's behavior for specific file types, read more in
|delimitMateFileType|.
Note: Use buffer variables only to set options for specific file types using
:autocmd, use global variables to set options for every buffer. Read more in
|g:var| and |b:var|.
------------------------------------------------------------------------------
*'loaded_delimitMate'*
*'b:loaded_delimitMate'*
This option prevents delimitMate from loading.
e.g.: >
let loaded_delimitMate = 1
au FileType mail let b:loaded_delimitMate = 1
<
------------------------------------------------------------------------------
*'delimitMate_autoclose'*
*'b:delimitMate_autoclose'*
Values: 0 or 1. ~
Default: 1 ~
If this option is set to 0, delimitMate will not add a closing delimiter
automagically. See |delimitMateAutoClose| for details.
e.g.: >
let delimitMate_autoclose = 0
au FileType mail let b:delimitMate_autoclose = 0
<
------------------------------------------------------------------------------
*'delimitMate_matchpairs'*
*'b:delimitMate_matchpairs'*
Values: A string with |'matchpairs'| syntax, plus support for multi-byte~
characters.~
Default: &matchpairs ~
Use this option to tell delimitMate which characters should be considered
matching pairs. Read |delimitMateAutoClose| for details.
e.g: >
let delimitMate_matchpairs = "(:),[:],{:},<:>"
au FileType vim,html let b:delimitMate_matchpairs = "(:),[:],{:},<:>"
<
------------------------------------------------------------------------------
*'delimitMate_quotes'*
*'b:delimitMate_quotes'*
Values: A string of characters separated by spaces. ~
Default: "\" ' `" ~
Use this option to tell delimitMate which characters should be considered as
quotes. Read |delimitMateAutoClose| for details.
e.g.: >
let delimitMate_quotes = "\" ' ` *"
au FileType html let b:delimitMate_quotes = "\" '"
<
------------------------------------------------------------------------------
*'delimitMate_nesting_quotes'*
*'b:delimitMate_nesting_quotes'*
Values: A list of quotes. ~
Default: [] ~
Quotes listed here will not be able to jump out of the empty pair, thus
allowing the autoclosed quotes to be nested.
e.g.: >
let delimitMate_nesting_quotes = ['"','`']
au FileType python let b:delimitMate_nesting_quotes = ['"']
<
------------------------------------------------------------------------------
*'delimitMate_expand_cr'*
*'b:delimitMate_expand_cr'*
Values: 1 or 0 ~
Default: 0 ~
This option turns on/off the expansion of <CR>. Read |delimitMateExpansion|
for details. NOTE This feature requires that 'backspace' is either set to 2 or
has "eol" and "start" as part of its value.
e.g.: >
let delimitMate_expand_cr = 1
au FileType mail let b:delimitMate_expand_cr = 1
<
------------------------------------------------------------------------------
*'delimitMate_expand_space'*
*'b:delimitMate_expand_space'*
Values: 1 or 0 ~
Default: 0 ~
This option turns on/off the expansion of <Space>. Read |delimitMateExpansion|
for details.
e.g.: >
let delimitMate_expand_space = 1
au FileType tcl let b:delimitMate_expand_space = 1
<
------------------------------------------------------------------------------
*'delimitMate_smart_quotes'*
*'b:delimitMate_smart_quotes'*
Values: 1 or 0 ~
Default: 1 ~
This option turns on/off the smart quotes feature. Read
|delimitMateSmartQuotes| for details.
e.g.: >
let delimitMate_smart_quotes = 0
au FileType tcl let b:delimitMate_smart_quotes = 1
<
------------------------------------------------------------------------------
*'delimitMate_smart_matchpairs'*
*'b:delimitMate_smart_matchpairs'*
Values: Regexp ~
Default: '^\%(\w\|\!\|£\|\$\|_\|["'']\s*\S\)' ~
This regex is matched against the text to the right of cursor, if it's not
empty and there is a match delimitMate will not autoclose the pair. At the
moment to match the text, an escaped bang (\!) in the regex will be replaced
by the character being inserted, while an escaped number symbol (\#) will be
replaced by the closing pair.
e.g.: >
let delimitMate_smart_matchpairs = ''
au FileType tcl let b:delimitMate_smart_matchpairs = '^\%(\w\|\$\)'
<
------------------------------------------------------------------------------
*'delimitMate_balance_matchpairs'*
*'b:delimitMate_balance_matchpairs'*
Values: 1 or 0 ~
Default: 0 ~
This option turns on/off the balancing of matching pairs. Read
|delimitMateBalance| for details.
e.g.: >
let delimitMate_balance_matchpairs = 1
au FileType tcl let b:delimitMate_balance_matchpairs = 1
<
------------------------------------------------------------------------------
*'delimitMate_excluded_regions'*
Values: A string of syntax group names names separated by single commas. ~
Default: Comment ~
This options turns delimitMate off for the listed regions, read |group-name|
for more info about what is a region.
e.g.: >
let delimitMate_excluded_regions = "Comments,String"
<
------------------------------------------------------------------------------
*'delimitMate_excluded_ft'*
Values: A string of file type names separated by single commas. ~
Default: Empty. ~
This options turns delimitMate off for the listed file types, use this option
only if you don't want any of the features it provides on those file types.
e.g.: >
let delimitMate_excluded_ft = "mail,txt"
<
------------------------------------------------------------------------------
*'delimitMate_apostrophes'*
Values: Strings separated by ":". ~
Default: No longer used. ~
NOTE: This feature is turned off by default, it's been kept for compatibility
with older version, read |delimitMateSmartQuotes| for details.
If auto-close is enabled, this option tells delimitMate how to try to fix the
balancing of single quotes when used as apostrophes. The values of this option
are strings of text where a single quote would be used as an apostrophe (e.g.:
the "n't" of wouldn't or can't) separated by ":". Set it to an empty string to
disable this feature.
e.g.: >
let delimitMate_apostrophes = ""
au FileType tcl let delimitMate_apostrophes = ""
<
==============================================================================
3. FUNCTIONALITY *delimitMateFunctionality*
------------------------------------------------------------------------------
3.1 AUTOMATIC CLOSING AND EXITING *delimitMateAutoClose*
With automatic closing enabled, if an opening delimiter is inserted the plugin
inserts the closing delimiter and places the cursor between the pair. With
automatic closing disabled, no closing delimiters is inserted by delimitMate,
but when a pair of delimiters is typed, the cursor is placed in the middle.
When the cursor is inside an empty pair or located next to the left of a
closing delimiter, the cursor is placed outside the pair to the right of the
closing delimiter.
When |'delimitMate_smart_matchpairs'| is not empty and it matches the text to
the right of the cursor, delimitMate will not automatically insert the closing
pair.
Unless |'delimitMate_matchpairs'| or |'delimitMate_quotes'| are set, this
script uses the values in '&matchpairs' to identify the pairs, and ", ' and `
for quotes respectively.
<S-Tab> will jump over a single closing delimiter or quote, <C-G>g will jump
over contiguous delimiters and/or quotes.
The following table shows the behaviour, this applies to quotes too (the final
position of the cursor is represented by a "|"):
With auto-close: >
Type | You get
=======================
( | (|)
–––––––––––|–––––––––––
() | ()|
–––––––––––|–––––––––––
(<S-Tab> | ()|
–––––––––––|–––––––––––
{("<C-G>g | {("")}|
<
Without auto-close: >
Type | You get
=========================
() | (|)
–––––––––-----|––––––––––
()) | ()|
–––––––––-----|––––––––––
()<S-Tab> | ()|
––––––––––––––|–––––––––––
{}()""<C-G>g | {("")}|
<
NOTE: Abbreviations will not be expanded by delimiters used on delimitMate,
you should use <C-]> (read |i_CTRL-]|) to expand them on the go.
------------------------------------------------------------------------------
3.2 EXPANSION OF SPACE AND CAR RETURN *delimitMateExpansion*
When the cursor is inside an empty pair of delimiters, <Space> and <CR> can be
expanded, see |'delimitMate_expand_space'| and
|'delimitMate_expand_cr'|:
Expand <Space> to: >
<Space><Space><Left> | You get
====================================
(|) | ( | )
<
Expand <CR> to: >
<CR><CR><Up> | You get
============================
(|) | (
| |
| )
<
NOTE that the expansion of <CR> will brake the redo command.
Since <Space> and <CR> are used everywhere, I have made the functions involved
in expansions global, so they can be used to make custom mappings. Read
|delimitMateFunctions| for more details.
------------------------------------------------------------------------------
3.3 BACKSPACE *delimitMateBackspace*
If you press backspace inside an empty pair, both delimiters are deleted. When
expansions are enabled, <BS> will also delete the expansions. NOTE that
deleting <CR> expansions will brake the redo command.
If you type <S-BS> (shift + backspace) instead, only the closing delimiter
will be deleted. NOTE that this will not usually work when using Vim from the
terminal, see 'delimitMate#JumpAny()' below to see how to fix it.
e.g. typing at the "|": >
What | Before | After
==============================================
<BS> | call expand(|) | call expand|
---------|-------------------|-----------------
<BS> | call expand( | ) | call expand(|)
---------|-------------------|-----------------
<BS> | call expand( | call expand(|)
| | |
| ) |
---------|-------------------|-----------------
<S-BS> | call expand(|) | call expand(|
<
------------------------------------------------------------------------------
3.4 SMART QUOTES *delimitMateSmartQuotes*
Only one quote will be inserted following a quote, a "\" or, following or
preceding a keyword character. This should cover closing quotes after a
string, opening quotes before a string, escaped quotes and apostrophes. Except
for apostrophes, this feature can be disabled setting the option
|'delimitMate_smart_quotes'| to 0.
e.g. typing at the "|": >
What | Before | After
=======================================
" | Text | | Text "|"
" | "String| | "String"|
" | let i = "| | let i = "|"
'm | I| | I'm|
<
------------------------------------------------------------------------------
3.4 SMART MATCHPAIRS *delimitMateSmartMatchpairs*
This is similar to "smart quotes", but applied to the characters in
|'delimitMate_matchpairs'|. The difference is that delimitMate will not
auto-close the pair when the regex matches the text on the right of the
cursor. See |'delimitMate_smart_matchpairs'| for more details.
e.g. typing at the "|": >
What | Before | After
=======================================
( | function| | function(|)
( | |var | (|var
<
------------------------------------------------------------------------------
3.5 BALANCING MATCHING PAIRS *delimitMateBalance*
When inserting an opening paren and |'delimitMate_balance_matchpairs'| is
enabled, delimitMate will try to balance the closing pairs in the current
line.
e.g. typing at the "|": >
What | Before | After
=======================================
( | | | (|)
( | |) | (|)
(( | |) | ((|))
<
------------------------------------------------------------------------------
3.6 FILE TYPE BASED CONFIGURATION *delimitMateFileType*
delimitMate options can be set globally for all buffers using global
("regular") variables in your |vimrc| file. But |:autocmd| can be used to set
options for specific file types (see |'filetype'|) using buffer variables in
the following way: >
au FileType mail,text let b:delimitMate_autoclose = 0
^ ^ ^ ^ ^
| | | | |
| | | | - Option value.
| | | - Option name.
| | - Buffer variable.
| - File types for which the option will be set.
- Don't forget to put this event.
<
NOTE that you should use buffer variables (|b:var|) only to set options with
|:autocmd|, for global options use regular variables (|g:var|) in your vimrc.
------------------------------------------------------------------------------
3.7 SYNTAX AWARENESS *delimitMateSyntax*
The features of this plug-in might not be always helpful, comments and strings
usualy don't need auto-completion. delimitMate monitors which region is being
edited and if it detects that the cursor is in a comment it'll turn itself off
until the cursor leaves the comment. The excluded regions can be set using the
option |'delimitMate_excluded_regions'|. Read |group-name| for a list of
regions or syntax group names.
NOTE that this feature relies on a proper syntax file for the current file
type, if the appropiate syntax file doesn't define a region, delimitMate won't
know about it.
==============================================================================
4. COMMANDS *delimitMateCommands*
------------------------------------------------------------------------------
:DelimitMateReload *:DelimitMateReload*
Re-sets all the mappings used for this script, use it if any option has been
changed or if the filetype option hasn't been set yet.
------------------------------------------------------------------------------
:DelimitMateSwitch *:DelimitMateSwitch*
Switches the plug-in on and off.
------------------------------------------------------------------------------
:DelimitMateTest *:DelimitMateTest*
This command tests every mapping set-up for this script, useful for testing
custom configurations.
The following output corresponds to the default values, it will be different
depending on your configuration. "Open & close:" represents the final result
when the closing delimiter has been inserted, either manually or
automatically, see |delimitMateExpansion|. "Delete:" typing backspace in an
empty pair, see |delimitMateBackspace|. "Exit:" typing a closing delimiter
inside a pair of delimiters, see |delimitMateAutoclose|. "Space:" the
expansion, if any, of space, see |delimitMateExpansion|. "Visual-L",
"Visual-R" and "Visual" shows visual wrapping, see
|delimitMateVisualWrapping|. "Car return:" the expansion of car return, see
|delimitMateExpansion|. The cursor's position at the end of every test is
represented by an "|": >
* AUTOCLOSE:
Open & close: (|)
Delete: |
Exit: ()|
Space: ( |)
Visual-L: (v)
Visual-R: (v)
Car return: (
|)
Open & close: {|}
Delete: |
Exit: {}|
Space: { |}
Visual-L: {v}
Visual-R: {v}
Car return: {
|}
Open & close: [|]
Delete: |
Exit: []|
Space: [ |]
Visual-L: [v]
Visual-R: [v]
Car return: [
|]
Open & close: "|"
Delete: |
Exit: ""|
Space: " |"
Visual: "v"
Car return: "
|"
Open & close: '|'
Delete: |
Exit: ''|
Space: ' |'
Visual: 'v'
Car return: '
|'
Open & close: `|`
Delete: |
Exit: ``|
Space: ` |`
Visual: `v`
Car return: `
|`
<
==============================================================================
5. MAPPINGS *delimitMateMappings*
delimitMate doesn't override any existing map, so you may encounter that it
doesn't work as expected because a mapping is missing. In that case, the
conflicting mappings should be resolved by either disabling the conflicting
mapping or creating a custom mappings.
In order to make custom mappings easier and prevent overwritting existing
ones, delimitMate uses the |<Plug>| + |hasmapto()| (|usr_41.txt|) construct
for its mappings.
These are the default mappings:
<BS> is mapped to <Plug>delimitMateBS
<S-BS> is mapped to <Plug>delimitMateS-BS
<S-Tab> is mapped to <Plug>delimitMateS-Tab
<C-G>g is mapped to <Plug>delimitMateJumpMany
<Del> is mapped to <Plug>delimitMateDel
<Esc> is mapped to <Plug>delimitMateEsc
<Left> is mapped to <Plug>delimitMateLeft
<Right> is mapped to <Plug>delimitMateRight
<Home> is mapped to <Plug>delimitMateHome
<End> is mapped to <Plug>delimitMateEnd
<Up> is mapped to <Plug>delimitMateUp
<Down> is mapped to <Plug>delimitMateDown
<PageUp> is mapped to <Plug>delimitMatePageUp
<PageDown> is mapped to <Plug>delimitMatePageDown
<S-Down> is mapped to <Plug>delimitMateS-Down
<S-Up> is mapped to <Plug>delimitMateS-Up
<LeftMouse> is mapped to <Plug>delimitMateMLeftMouse
<RightMouse> is mapped to <Plug>delimitMateMRightMouse
The rest of the mappings correspond to parens, quotes, CR, Space, etc. and they
depend on the values of the delimitMate options, they have the following form:
<Plug>delimitMate + char
e.g.: for "(":
( is mapped to <Plug>delimitMate(
e.g.: If you have <CR> expansion enabled, you might want to skip it on pop-up
menus:
imap <expr> <CR> pumvisible() ?
\"\<c-y>" :
\ "<Plug>delimitMateCR"
==============================================================================
6. FUNCTIONS *delimitMateFunctions*
------------------------------------------------------------------------------
delimitMate#WithinEmptyPair() *delimitMate#WithinEmptyPair()*
Returns 1 if the cursor is inside an empty pair, 0 otherwise.
e.g.: >
inoremap <expr> <CR> delimitMate#WithinEmptyPair() ?
\ "\<C-R>=delimitMate#ExpandReturn()\<CR>" :
\ "external_mapping"
<
------------------------------------------------------------------------------
delimitMate#ShouldJump() *delimitMate#ShouldJump()*
Returns 1 if there is a closing delimiter or a quote to the right of the
cursor, 0 otherwise.
------------------------------------------------------------------------------
delimitMate#JumpAny(key) *delimitMate#JumpAny()*
This function returns a mapping that will make the cursor jump to the right
when delimitMate#ShouldJump() returns 1, returns the argument "key" otherwise.
e.g.: You can use this to create your own mapping to jump over any delimiter.
>
inoremap <C-Tab> <C-R>=delimitMate#JumpAny("\<C-Tab>")<CR>
<
==============================================================================
7. TODO LIST *delimitMateTodo*
- Automatic set-up by file type.
- Make block-wise visual wrapping work on un-even regions.
==============================================================================
8. MAINTAINER *delimitMateMaintainer*
Hi there! My name is Israel Chauca F. and I can be reached at:
mailto:israelchauca@gmail.com
Feel free to send me any suggestions and/or comments about this plugin, I'll
be very pleased to read them.
==============================================================================
9. CREDITS *delimitMateCredits*
Contributors: ~
- Kim Silkebækken ~
Fixed mappings being echoed in the terminal.
- Eric Van Dewoestine ~
Implemented smart matchpairs.
Some of the code that makes this script was modified or just shamelessly
copied from the following sources:
- Ian McCracken ~
Post titled: Vim, Part II: Matching Pairs:
http://concisionandconcinnity.blogspot.com/
- Aristotle Pagaltzis ~
From the comments on the previous blog post and from:
http://gist.github.com/144619
- Karl Guertin ~
AutoClose:
http://www.vim.org/scripts/script.php?script_id=1849
- Thiago Alves ~
AutoClose:
http://www.vim.org/scripts/script.php?script_id=2009
- Edoardo Vacchi ~
ClosePairs:
http://www.vim.org/scripts/script.php?script_id=2373
This script was inspired by the auto-completion of delimiters on TextMate.
==============================================================================
10. HISTORY *delimitMateHistory*
Version Date Release notes ~
|---------|------------|-----------------------------------------------------|
2.6 2011-01-14 * Current release:
- Add smart_matchpairs feature.
- Add mapping to jump over contiguous delimiters.
- Fix behaviour of b:loaded_delimitMate.
|---------|------------|-----------------------------------------------------|
2.5.1 2010-09-30 * - Remove visual wrapping. Surround.vim offers a much
better implementation.
- Minor mods to DelimitMateTest.
|---------|------------|-----------------------------------------------------|
2.5 2010-09-22 * - Better handling of mappings.
- Add report for mappings in |:DelimitMateTest|.
- Allow the use of "|" and multi-byte characters in
|'delimitMate_quotes'| and |'delimitMate_matchpairs'|.
- Allow commands to be concatenated using |.
|---------|------------|-----------------------------------------------------|
2.4.1 2010-07-31 * - Fix problem with <Home> and <End>.
- Add missing doc on |'delimitMate_smart_quotes'|,
|delimitMateBalance| and
|'delimitMate_balance_matchpairs'|.
|---------|------------|-----------------------------------------------------|
2.4 2010-07-29 * - Unbalanced parens: see :help delimitMateBalance.
- Visual wrapping now works on block-wise visual
with some limitations.
- Arrow keys didn't work on terminal.
- Added option to allow nested quotes.
- Expand Smart Quotes to look for a string on the
right of the cursor.
|---------|------------|-----------------------------------------------------|
2.3.1 2010-06-06 * - Fix: an extra <Space> is inserted after <Space>
expansion.
|---------|------------|-----------------------------------------------------|
2.3 2010-06-06 * - Syntax aware: Will turn off when editing comments
or other regions, customizable.
- Changed format of most mappings.
- Fix: <CR> expansion doesn't brake automatic
indentation adjustments anymore.
- Fix: Arrow keys would insert A, B, C or D instead
of moving the cursor when using Vim on a terminal.
|---------|------------|-----------------------------------------------------|
2.2 2010-05-16 * - Added command to switch the plug-in on and off.
- Fix: some problems with <Left>, <Right> and <CR>.
- Fix: A small problem when inserting a delimiter at
the beginning of the line.
|---------|------------|-----------------------------------------------------|
2.1 2010-05-10 * - Most of the functions have been moved to an
autoload script to avoid loading unnecessary ones.
- Fixed a problem with the redo command.
- Many small fixes.
|---------|------------|-----------------------------------------------------|
2.0 2010-04-01 * New features:
- All features are redo/undo-wise safe.
- A single quote typed after an alphanumeric
character is considered an apostrophe and one
single quote is inserted.
- A quote typed after another quote inserts a single
quote and the cursor jumps to the middle.
- <S-Tab> jumps out of any empty pair.
- <CR> and <Space> expansions are fixed, but the
functions used for it are global and can be used in
custom mappings. The previous system is still
active if you have any of the expansion options
set.
- <S-Backspace> deletes the closing delimiter.
* Fixed bug:
- s:vars were being used to store buffer options.
|---------|------------|-----------------------------------------------------|
1.6 2009-10-10 * Now delimitMate tries to fix the balancing of single
quotes when used as apostrophes. You can read
|delimitMate_apostrophes| for details.
Fixed an error when |b:delimitMate_expand_space|
wasn't set but |delimitMate_expand_space| wasn't.
|---------|------------|-----------------------------------------------------|
1.5 2009-10-05 * Fix: delimitMate should work correctly for files
passed as arguments to Vim. Thanks to Ben Beuchler
for helping to nail this bug.
|---------|------------|-----------------------------------------------------|
1.4 2009-09-27 * Fix: delimitMate is now enabled on new buffers even
if they don't have set the file type option or were
opened directly from the terminal.
|---------|------------|-----------------------------------------------------|
1.3 2009-09-24 * Now local options can be used along with autocmd
for specific file type configurations.
Fixes:
- Unnamed register content is not lost on visual
mode.
- Use noremap where appropiate.
- Wrapping a single empty line works as expected.
|---------|------------|-----------------------------------------------------|
1.2 2009-09-07 * Fixes:
- When inside nested empty pairs, deleting the
innermost left delimiter would delete all right
contiguous delimiters.
- When inside an empty pair, inserting a left
delimiter wouldn't insert the right one, instead
the cursor would jump to the right.
- New buffer inside the current window wouldn't
have the mappings set.
|---------|------------|-----------------------------------------------------|
1.1 2009-08-25 * Fixed an error that ocurred when mapleader wasn't
set and added support for GetLatestScripts
auto-detection.
|---------|------------|-----------------------------------------------------|
1.0 2009-08-23 * Initial upload.
|---------|------------|-----------------------------------------------------|
`\|||/´ MMM \|/ www __^__ ~
(o o) (o o) @ @ (O-O) /(o o)\\ ~
ooO_(_)_Ooo__ ooO_(_)_Ooo___oOO_(_)_OOo___oOO__(_)__OOo___oOO__(_)__OOo_____ ~
_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|____ ~
__|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_ ~
_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|_____|____ ~
vim:tw=78:et:ts=2:sw=2:ft=help:norl:formatoptions+=tcroqn:autoindent:

5
vim/doc/ft-gitcommit-plugin.txt Normal file
View File

@@ -0,0 +1,5 @@
GIT COMMIT *ft-gitcommit-plugin*
One command, :DiffGitCached, is provided to show a diff of the current commit
in the preview window. It is equivalent to calling "git diff --cached" plus
any arguments given to the command.

161
vim/doc/greplace.txt Normal file
View File

@@ -0,0 +1,161 @@
*greplace.txt* Plugin for replacing pattern across multiple files
Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com)
For Vim version 7.0 and above
Last change: 2007 March 2
Overview~
The Global Replace plugin allows you to search and replace a pattern across
multiple files. The lines containing a specified pattern in multiple files are
displayed in a buffer. You can edit the lines in this buffer and make the
desired modifications to them. The plugin can then incorporate these changes
back into the corresponding files interactively.
==============================================================================
Installation~
1. Download the greplace.vim file and unzip the files into the $HOME/.vim
or the $HOME/vimfiles or the $VIM/vimfiles directory. After this step, you
should have the following two files (the directory structure should be
preserved):
plugin/greplace.vim - main global replace plugin file
doc/greplace.txt - documentation (help) file
2. Change to the $HOME/.vim/doc or $HOME/vimfiles/doc or $VIM/vimfiles/doc
directory, start Vim and run the ":helptags ." command to process the
help file. Without this step, you cannot jump to the help topics.
3. Restart Vim.
To uninstall the global replace plugin, remove the plugin/greplace.vim and
doc/greplace.txt files from the $HOME/.vim or $HOME/vimfiles directory.
==============================================================================
The following commands are provided by this plugin:
:Gsearch Search for a given pattern in the specified group of
files and display the matches in the replace buffer.
:Gbuffersearch Search for a given pattern in all the buffers
in the Vim buffer list.
:Gargsearch Search for a given pattern in all the files in the
Vim argument list.
:Gqfopen Use the results from the quickfix list.
:Greplace Incorporate the modifications from the replace buffer
into the corresponding files.
One example sequence of commands for using this plugin is:
:Gsearch mypattern *.java *.c
<The above command will search for mypattern in *.java and *.c
files in the current directory and display the matching lines
in a buffer.>
<You can now use the Vim editing commands to modify the buffer>
:Greplace
<The above command will load each of the buffer which needs to be changed
and ask you to confirm whether to make the change or not>
:wall
<To save all the modified buffers>
In the above sequence, instead of ":Gsearch", you can use ":Gbuffersearch" or
":Gargsearch" commands to search for a pattern in the files in the Vim buffer
list or the argument list.
The ":Gsearch" command uses the Vim ":grep" command to search for the pattern
in the specified files. The ":grep" command uses the program specified by the
"grepprg" option to search for the pattern. By default, the "grepprg" option
is set to either grep (on Unix) or findstr (on MS-Windows). By modifying the
"grepprg" option, you can also use other programs for searching. To use the
Vim internal grep, set the "grepprg" option to "internal".
The syntax of the ":Gsearch" command is:
>
:Gsearch [<grep-option(s)>] [[<pattern>] [<filename(s)>]]
<
The arguments to the ":Gsearch" command are optional.
The first set of arguments, if present, specify the options to the grep
program. These options must start with "-" (for Unix) and "/" (for
MS-Windows). For example, to ignore case, you can use "-i" for the Unix
grep program.
The next argument specifies the pattern. You cannot use space characters in
the pattern. To specify space characters in the pattern, don't specify the
pattern in the command-line. See below for more information.
The last set of arguments specify the filenames. You can use wildcards in the
filenames. You can also complete directory and file names by pressing <Tab>.
If the pattern or the filenames is not supplied as argument to the ":Gsearch"
command, then you will be prompted to enter the pattern and the filenames. The
default value for the search pattern is the keyword under the cursor. In the
prompt for entering the pattern, you can enter a pattern with space
characters. In the prompt for entering the filenames, you can press <Tab> to
complete the directory and file names.
To search for a pattern in the files in the Vim buffer list, use the
":Gbuffersearch" command. The syntax of this command is:
>
:Gbuffersearch [<grep-option(s)>]
<
This command is similar to the ":Gsearch" command. This command searches for
the specified pattern in all the files in the buffer list. You cannot specify
filenames to this command.
To search for a pattern in the files in the Vim argument list, use the
":Gargsearch" command. The syntax of this command is:
>
:Gargsearch [<grep-option(s)>]
<
This command is similar to the ":Gsearch" command. This command will search
for the specified pattern in all the files in the argument list. You cannot
specify filenames to this command.
The difference between the ":Gbuffersearch" command and the Vim
":bufdo %s/pattern/replace/c" command is that the ":Gbuffersearch" command
allows you to inspect and change the matching lines in a buffer and then
incorporate the changes. You can also make different changes to different
lines. With a single ":bufdo" command, you can make only the one type of
change in all the buffers. The same difference applies for the ":Gargsearch"
and the ":argdo" command.
Sometimes, you may have the desired list of filenames and the matching lines
in them already in the quickfix list. For example, you can run tools like
cscope, GNU id-utils, GNU global, etc., and get the results into the quickfix
list. To use this list of files for replacing text, you can use the ":Gqfopen"
command. This command doesn't take the pattern or filenames arguments. It
parses the file names and lines in them from the current quickfix list and
displays it in the replace buffer.
You can edit the contents of the replace buffer using the Vim editing
commands. You cannot save the contents to a regular file. You should not
change the filename or line numbers in the replace buffer. You should not add
additional lines in this buffer. If you don't want to make any changes, you
can close the replace buffer.
You can use the ":Greplace" command to store the modified lines from the
replace buffer back to the corresponding files. This command is available only
in the replace buffer.
The ":Greplace" command will prompt you to confirm each of the changes. At
this prompt, you can press 'y' to accept the change, 'n' to reject the change,
'a' to accept all the changes, 'b' to accept all the changes in the current
buffer and 'q' or <Escape> to exit the replace prompt and stop making the
changes.
To incorporate the modifications without the prompt, add "!" to the
":Greplace" command. This will force the ":Greplace" command to make the
changes without any prompts for confirmation.
The modified files will not be automatically saved. You can save all of them
using the ":wall" command or you can individually inspect the buffers for the
changes and then save the buffer using the ":w" command. You can undo the
changes individually by using the Vim "u" command.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:

116
vim/doc/imaps.txt Normal file
View File

@@ -0,0 +1,116 @@
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| sufffers 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 sytax: >
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 hoders.
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*\\*.*',"",""),'^--','--\ \ \ \ ','')
================================================================================

406
vim/doc/matchit.txt Normal file
View File

@@ -0,0 +1,406 @@
*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:

82
vim/doc/ragtag.txt Normal file
View File

@@ -0,0 +1,82 @@
*ragtag.txt* Ghetto XML/HTML mappings (formerly allml.vim)
Author: Tim Pope <vimNOSPAM@tpope.org> *ragtag-author*
License: Same terms as Vim itself (see |license|)
This plugin is only available if 'compatible' is not set.
INTRODUCTION *ragtag*
These are my personal mappings for XML/XHTML editing, particularly with
dynamic content like PHP/ASP/eRuby. Because they are personal, less effort
has been put into customizability (if you like these mappings but the lack of
customizability poses an issue for you, let me know). Examples shown are for
eRuby.
You might find these helpful in your vimrc:
>
inoremap <M-o> <Esc>o
inoremap <C-j> <Down>
let g:ragtag_global_maps = 1
<
MAPPINGS *ragtag-mappings*
The table below shows what happens if the binding is pressed on the end of a
line consisting of "foo".
Mapping Changed to (cursor = ^) ~
<C-X>= foo<%= ^ %> *ragtag-CTRL-X_=*
<C-X>+ <%= foo^ %> *ragtag-CTRL-X_+*
<C-X>- foo<% ^ %> *ragtag-CTRL-X_-*
<C-X>_ <% foo^ %> *ragtag-CTRL-X__*
<C-X>' foo<%# ^ %> *ragtag-CTRL-X_'*
(mnemonic: ' is a comment in ASP VBS)
<C-X>" <%# foo^ %> *ragtag-CTRL-X_quote*
<C-X><Space> <foo>^</foo> *ragtag-CTRL-X_<Space>*
<C-X><CR> <foo>\n^\n</foo> *ragtag-CTRL-X_<CR>*
<C-X>/ Last HTML tag closed *ragtag-CTRL-X_/*
<C-X>! <!DOCTYPE...>/<?xml ...?> (menu) *ragtag-CTRL-X_!*
<C-X>@ <link rel="stylesheet" ...> *ragtag-CTRL-X_@*
(mnemonic: @ is used for importing in a CSS file)
<C-X># <meta http-equiv="Content-Type" ... /> *ragtag-CTRL-X_#*
<C-X>$ <script src="/javascripts/^.js"></script> *ragtag-CTRL-X_$*
(mnemonic: $ is valid in javascript identifiers)
For the bindings that generate HTML tag pairs, in a few cases, attributes will
be automatically added. For example, script becomes >
<script type="text/javascript">
<
ENCODING *ragtag-encoding*
This plugin used to provide a set of general purpose XML/URL encoding/decoding
mappings. These mappings have been extracted to a (highly recommended) plugin
named unimpaired.vim. Left behind were the following four insert mode
mappings (mostly useful as stupid party tricks).
*ragtag-CTRL-V_%*
<Plug>ragtagUrlV URL encode the next character.
<C-V>%
*ragtag-CTRL-V_&*
<Plug>ragtagXmlV XML encode the next character.
<C-V>&
*ragtag-CTRL-X_%*
<Plug>ragtagUrlEncode Toggle a mode that automatically URL encodes unsafe
<C-X>% characters.
*ragtag-CTRL-X_&*
<Plug>ragtagXmlEncode Toggle a mode that automatically XML encodes unsafe
<C-X>& characters.
SURROUNDINGS *ragtag-surroundings*
Combined with surround.vim, you also get three "replacements". Below, the ^
indicates the location of the wrapped text. See |surround| for details.
Character Replacement ~
- <% ^ %>
= <%= ^ %>
# <%# ^ %>
vim:tw=78:et:ft=help:norl:

1134
vim/doc/rails.txt Executable file
View File

File diff suppressed because it is too large Load Diff

338
vim/doc/ruby_debugger.txt Normal file
View File

@@ -0,0 +1,338 @@
*ruby_debugger.txt* Plugin for debugging Ruby applications
Author: Anton Astashov
<anton (yup) astashov (dot) net> |ruby-debugger-plugin-author|
|ruby-debugger-introduction| Introduction and Feature Summary
|ruby-debugger-installation| Installation
|ruby-debugger-quickstart| QuickStart
|ruby-debugger-details| Some additional details about the plugin
|ruby-debugger-tests| Debugging of tests
|ruby-debugger-ruby19| Using the plugin with ruby 1.9
|ruby-debugger-issues| Troubleshooting
|ruby-debugger-bugs| Bugreporting
|ruby-debugger-about| About
This plugin is only available if 'compatible' is not set.
The plugin requires Vim to be compiled with +signs and +clientserver and Vim
version >= 7. To check it, run >
:echo has("signs") && has("clientserver") && v:version > 700
Result should be equal to 1
If you use Linux, make sure you have "lsof" installed. See >
http://en.wikipedia.org/wiki/Lsof
Also, it requires ruby-debug-ide gem. To install it, run >
gem install ruby-debug-ide
Please make sure, that vim/gvim, rdebug-ide and ruby directories are set in your
$PATH variable
{Vi does not have any of this}
==============================================================================
INTRODUCTION *ruby-debugger-introduction* *ruby-debugger*
This plugin implements interactive Ruby debugger in Vim.
1. It can debug any Ruby application (Rails, by default), using ruby-debug-ide
gem
2. The debugger looks like in the Netbeans - you can go through the code, watch
variables, breakpoints in separate window, set and remove breakpoints.
3. It supports command-line rdebug commands. E.g., you can you can execute >
:RdbCommand p User.all
in command line of VIM and it will display result like usual echo VIM command.
==============================================================================
INSTALLATION *ruby-debugger-installation*
Clone current version of the repo from GitHub: >
git clone git://github.com/astashov/vim-ruby-debugger.git
or if you don't have Git, download the archive from here: >
http://github.com/astashov/vim-ruby-debugger/tarball/master
Then, copy files from ./vim directory to vimfiles (Windows) or ~/.vim
(everything else). Or, if you use pathogen, copy ./vim directory contents
to ~/.vim/bundle/vim-ruby-debugger. You should have the following files: >
plugin/ruby_debugger.vim
autoload/ruby_debugger.vim
bin/ruby_debugger.rb
doc/ruby_debugger.txt
The first one is a debugger plugin loader (maps shortcuts and commands),
second is ruby-debugger itself. Third is a small ruby script, that makes an
interaction between the VIM and the ruby-debug-ide gem, and fourth is the
help file.
Then, run: >
:helptags ~/.vim/doc
for generating local tags file.
Now you can use the >
:help ruby-debugger
and watch help file you just added.
==============================================================================
QUICKSTART *ruby-debugger-quickstart*
1. Run Vim. If you use gvim, it will automatically start the server, but if
you use vim, you need to set servername explicitly, e.g., >
vim --servername VIM
2. Go to the directory with some your Rails application. >
:cd ~/projects/rails
3. Run Server with Debugger: >
:Rdebugger
It will kill any listeners of ports 39767 and 39768 and run rdebug-ide and
~/.vim/bin/ruby_debugger.rb on these ports accordingly.
3. Set breakpoint somewhere by <Leader>b (usually, '\b'). You should see
"xx" symbol at the current line.
4. Open page with the breakpoint in the browser. Vim should automatically set
its current line to breakpoint.
5. After this, you can use commands:
* <Leader>b - set breakpoint at current line
* <Leader>v - open/close window with variables. You can expand/collapse
variables by 'o' in normal mode or left-mouse double-click
* <Leader>m - open/close window with breakpoints. You can open file with
breakpoint by pressing 'o' or left-mouse double-click on it,
or delete the breakpoint by pressing 'd' on it.
* <Leader>t - open/close window with backtrace. You can open file/line in
this window by pressing 'o' or left-mouse double-click on it
* <Leader>n - step over
* <Leader>s - step into
* <Leader>f - step out
* <Leader>c - continue
* <Leader>d - remove all breakpoints
==============================================================================
DETAILS *ruby-debugger-details*
1. Of course, you can set your own mappings instead of mine. For this, just
add this to your .vimrc and change keys for mapping:
>
map <Leader>b :call g:RubyDebugger.toggle_breakpoint()<CR>
map <Leader>v :call g:RubyDebugger.open_variables()<CR>
map <Leader>m :call g:RubyDebugger.open_breakpoints()<CR>
map <Leader>t :call g:RubyDebugger.open_frames()<CR>
map <Leader>s :call g:RubyDebugger.step()<CR>
map <Leader>f :call g:RubyDebugger.finish()<CR>
map <Leader>n :call g:RubyDebugger.next()<CR>
map <Leader>c :call g:RubyDebugger.continue()<CR>
map <Leader>e :call g:RubyDebugger.exit()<CR>
map <Leader>d :call g:RubyDebugger.remove_breakpoints()<CR>
>
2. Standard output and errors (STDOUT and STDERR) of running script is
redirected to ~/.vim/tmp/ruby_debugger_output file (only for POSIX
systems - Linux, MacOS)
3. If you are using POSIX OS (Linux, MacOS), you can try fast C implementation
of message sender to debugger. For this, copy "socket" file from
additionals/bin/ to ~/.vim/bin/, add execution rights to it (chmod +x)
and add this string to your .vimrc: >
let g:ruby_debugger_fast_sender = 1
4. You can specify path to Ruby (if it is not in your PATH environment or
you want to use specific version of Ruby)
4. To run some other Ruby application (not Rails), you should specify its
path as argument of Rdebugger command. E.g. >
:Rdebugger bla.rb
If your script receives arguments, quote it into single quotes: >
:Rdebugger '/path/to/bla.rb 1234 bla_bla'
5. To run some rdebug command, use :RdbCommand. E.g.: >
:RdbCommand where
6. To eval some code, use :RdbEval. E.g.: >
:RdbEval u.name
:RdbEval app_config['settings'].map { |s| s.capitalize }
7. To add condition to some breakpoint, you can move cursor on the breakpoint,
and type command: >
:RdbCond condition
E.g.: >
:RdbCond current_user.name == "John"
Then, execution will be stopped on the breakpoint only if condition is true
8. To add exceptions catcher, use command: >
:RdbCatch NameOfException
This way, when exception is raised, debugger will catch it, jump to file/line
of the exception and you'll be allowed to watch variables, backtrace, etc there.
To reset all catched exceptions just restart the server by :Rdebugger command.
You can watch placed catchers in the Breakpoints Window (<Leader>m by default).
See the bottom line of the window.
WARNING!!! If you try to set catcher to unexisted exception (e.g., if you
mistyped class of the exception), ruby-debug-ide will be crashed! Then, you
will have to restart the server by :Rdebugger command
9. To stop running server, you can use :RdbStop command: >
:RdbStop
10. For communicating with the rdebug the plugin uses temp file:
~/.vim/tmp/ruby_debugger. Rdebug writes some response to this file, "kicks"
the plugin remotely calling RubyDebugger.receive_command() by Vim's
client-server functionality and the plugin make actions. For this reason,
you need Vim compiled with +clientserver.
11. The plugin logs all its actions to ~/.vim/tmp/ruby_debugger_log.
12. You also can run Unit tests for the plugin. For this, copy to
~/.vim/autoload/ ruby_debugger.vim from additionals/autoload (instead of vim/autoload).
It has the same functionality, but with unit tests at end of the file.
To run unit tests, change current directory to some rails project and run >
call g:TU.run()
13. To watch standard output of executing of Ruby script, you can use >
:RdbLog
It actually just opens ~/.vim/tmp/ruby_debugger_output, with options: >
setlocal autoread
setlocal wrap
setlocal nonumber
Also, if plugin AnsiEsc is installed
(http://www.vim.org/scripts/script.php?script_id=302, (it colorizes ANSI escape
sequences, they are used heavily by e.g. ActiveRecord logging)), it will be run
automatically after :RdbLog call to colorize ruby_debugger_output.
==============================================================================
DEBUGGING OF TESTS *ruby-debugger-tests*
The plugin supports debugging of Test::Unit tests, RSpec specs and Cucumber
features by :RdbTest command. Just open file with the test, set some
breakpoints and type: >
:RdbTest
It equals to running >
:Rdebugger /path/to/some_test.rb " for Test::Unit tests
:Rdebugger '/usr/bin/spec /path/to/some_spec.rb' " for RSpec
:Rdebugger '/usr/bin/cucumber /path/to/some.feature' " for Cucumber feautres
For debugging Cucumber features, you should set breakpoints in step
definitions file (e.g., user_steps.rb), but start debugger by :RdbTest command
in blabla.feature file. You can't set breakpoints in .feature file (I mean you
can, but they will be ignored), because... well, it is just plain text! :)
If you store spec or cucumber executables in some different place, not in
/usr/bin (e.g., if you have Windows), you should set path to them explicitly.
For this, set some variables in your .vimrc. E.g.: >
let g:ruby_debugger_spec_path = 'c:\gembins\spec' " set Rspec path
let g:ruby_debugger_cucumber_path = 'c:\gembins\cucumber' " set Cucumber path
==============================================================================
RUBY 1.9 *ruby-debugger-ruby19*
If you want to use vim-ruby-debugger with Ruby 1.9, the best way will be using
'rvm' (http://rvm.beginrescueend.com/). Install it and then install ruby 1.9:
>
rvm install 1.9.2
Then, switch to ruby 1.9.2 version: >
rvm 1.9.2
Make sure you use correct version of Ruby: >
which ruby
it will show path to current ruby executable, e.g. >
/Users/anton/.rvm/rubies/ruby-1.9.2-p0/bin/ruby
Then install ruby-debug-ide19 gem: >
gem install ruby-debug-ide19
After installation of the gem, you need make sure path to rdebug-ide points now
to RVM dir: >
$ which rdebug-ide
/Users/anton/.rvm/gems/ruby-1.9.2-p0/bin/rdebug-ide
Now you can use vim-ruby-debugger for debugging ruby 1.9 scripts. If you want
to debug Rails 3 applications, you (of course) need to install it: >
gem install rails
then create new Rails 3 app somewhere: >
rails new demo
go to the dir with the project, and run vim there. Then, run: >
:Rdebugger 'script/rails server'
to run Rails 3 app. Then, you can set breakpoints, watch variables, etc, as
usual.
I really recommend to try it with Ruby 1.9 and Rails 3, the plugin will help
you to learn how Rails 3 works inside - it is a good experience! :)
==============================================================================
TROUBLESHOOTING *ruby-debugger-issues*
1. Sometimes (e.g., if you use Mac OS and mvim), you can notice strange and
not correct behavior of the plugin (only a couple commands work, you can't see
variables list, next/step commands don't work). Make sure variable
'g:ruby_debugger_progname' contains proper name of Vim's executable (mvim
if you run mvim, gvim for gvim, vim for vim): >
:echo g:ruby_debugger_progname
If it contains some incorrect value, set it in your .vimrc. E.g. for mvim: >
let g:ruby_debugger_progname = 'mvim'
If Vim's executable directory is not in your PATH environment variable, set
full path to executable: >
let g:ruby_debugger_progname = '/opt/local/bin/mvim'
2. If you try to set exceptions catcher to unexisted exception class,
ruby-debug-ide will be crushed with error. This is issue of the
ruby-debud-ide.
3. By default, if Vim is compiled with +ruby, the plugin is trying to send
messages to debugger by built-in Ruby interface (details are in ':help ruby').
Some users have issues with built-in Ruby interface, so they may try to
"degradate" to external Ruby script instead of using built-in Ruby interface.
For that, add to your .vimrc: >
let g:ruby_debugger_builtin_sender = 0
and the plugin will call external ruby interpreter instead of built-in
interface.
==============================================================================
BUGS *ruby-debugger-bugs*
If you meet any bug (even small), please, report about it. You can write email
to me (|ruby-debugger-plugin-author|), or even better - write about your issue
here:
>
http://github.com/astashov/vim-ruby-debugger/issues
>
Also, any feedback is highly desired. Please, send all comments, complaints
and compliments to the author.
Thanks!
==============================================================================
ABOUT *ruby-debugger-about* *ruby-debugger-plugin-author*
This plugin was written by Anton Astashov.
Email: anton (at) astashov (dot) net
Website: astashov.net
The latest version of plugin can be found at:
http://github.com/astashov/vim-ruby-debugger
This plugin is distributable under the same terms as Vim itself. See
|license|. No warranties, expressed or implied.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:

279
vim/doc/snipMate.txt Normal file
View File

@@ -0,0 +1,279 @@
*snipMate.txt* Plugin for using TextMate-style snippets in Vim.
snipMate *snippet* *snippets* *snipMate*
Last Change: May 8, 2009
|snipMate-description| Description
|snipMate-syntax| Snippet syntax
|snipMate-usage| Usage
|snipMate-settings| Settings
|snipMate-features| Features
|snipMate-disadvantages| Disadvantages to TextMate
|snipMate-contact| Contact
For Vim version 7.0 or later.
This plugin only works if 'compatible' is not set.
{Vi does not have any of these features.}
==============================================================================
DESCRIPTION *snipMate-description*
snipMate.vim implements some of TextMate's snippets features in Vim. A
snippet is a piece of often-typed text that you can insert into your
document using a trigger word followed by a <tab>.
For instance, in a C file using the default installation of snipMate.vim, if
you type "for<tab>" in insert mode, it will expand a typical for loop in C: >
for (i = 0; i < count; i++) {
}
To go to the next item in the loop, simply <tab> over to it; if there is
repeated code, such as the "i" variable in this example, you can simply
start typing once it's highlighted and all the matches specified in the
snippet will be updated.
==============================================================================
SYNTAX *snippet-syntax*
Snippets can be defined in two ways. They can be in their own file, named
after their trigger in 'snippets/<filetype>/<trigger>.snippet', or they can be
defined together in a 'snippets/<filetype>.snippets' file.
The syntax for snippets in *.snippets files is the following: >
snippet trigger
expanded text
more expanded text
Note that the first hard tab after the snippet trigger is required, and not
expanded in the actual snippet. The syntax for *.snippet files is the same,
only without the trigger declaration and starting indentation.
Also note that snippets must be defined using hard tabs. They can be expanded
to spaces later if desired (see |snipMate-indenting|).
"#" is used as a line-comment character in *.snippets files; however, they can
only be used outside of a snippet declaration. E.g.: >
# this is a correct comment
snippet trigger
expanded text
snippet another_trigger
# this doesn't work!
expanded text
<
This should hopefully be obvious with the included syntax highlighting.
*snipMate-${#}*
Tab stops ~
By default, the cursor is placed at the end of a snippet. To specify where the
cursor is to be placed next, use "${#}", where the # is the number of the tab
stop. E.g., to place the cursor first on the id of a <div> tag, and then allow
the user to press <tab> to go to the middle of it:
>
snippet div
<div id="${1}">
${2}
</div>
<
*snipMate-placeholders* *snipMate-${#:}* *snipMate-$#*
Placeholders ~
Placeholder text can be supplied using "${#:text}", where # is the number of
the tab stop. This text then can be copied throughout the snippet using "$#",
given # is the same number as used before. So, to make a C for loop: >
snippet for
for (${2:i}; $2 < ${1:count}; $1++) {
${4}
}
This will cause "count" to first be selected and change if the user starts
typing. When <tab> is pressed, the "i" in ${2}'s position will be selected;
all $2 variables will default to "i" and automatically be updated if the user
starts typing.
NOTE: "$#" syntax is used only for variables, not for tab stops as in TextMate.
Variables within variables are also possible. For instance: >
snippet opt
<option value="${1:option}">${2:$1}</option>
Will, as usual, cause "option" to first be selected and update all the $1
variables if the user starts typing. Since one of these variables is inside of
${2}, this text will then be used as a placeholder for the next tab stop,
allowing the user to change it if he wishes.
To copy a value throughout a snippet without supplying default text, simply
use the "${#:}" construct without the text; e.g.: >
snippet foo
${1:}bar$1
< *snipMate-commands*
Interpolated Vim Script ~
Snippets can also contain Vim script commands that are executed (via |eval()|)
when the snippet is inserted. Commands are given inside backticks (`...`); for
TextMates's functionality, use the |system()| function. E.g.: >
snippet date
`system("date +%Y-%m-%d")`
will insert the current date, assuming you are on a Unix system. Note that you
can also (and should) use |strftime()| for this example.
Filename([{expr}] [, {defaultText}]) *snipMate-filename* *Filename()*
Since the current filename is used often in snippets, a default function
has been defined for it in snipMate.vim, appropriately called Filename().
With no arguments, the default filename without an extension is returned;
the first argument specifies what to place before or after the filename,
and the second argument supplies the default text to be used if the file
has not been named. "$1" in the first argument is replaced with the filename;
if you only want the filename to be returned, the first argument can be left
blank. Examples: >
snippet filename
`Filename()`
snippet filename_with_default
`Filename('', 'name')`
snippet filename_foo
`filename('$1_foo')`
The first example returns the filename if it the file has been named, and an
empty string if it hasn't. The second returns the filename if it's been named,
and "name" if it hasn't. The third returns the filename followed by "_foo" if
it has been named, and an empty string if it hasn't.
*multi_snip*
To specify that a snippet can have multiple matches in a *.snippets file, use
this syntax: >
snippet trigger A description of snippet #1
expand this text
snippet trigger A description of snippet #2
expand THIS text!
In this example, when "trigger<tab>" is typed, a numbered menu containing all
of the descriptions of the "trigger" will be shown; when the user presses the
corresponding number, that snippet will then be expanded.
To create a snippet with multiple matches using *.snippet files,
simply place all the snippets in a subdirectory with the trigger name:
'snippets/<filetype>/<trigger>/<name>.snippet'.
==============================================================================
USAGE *snipMate-usage*
*'snippets'* *g:snippets_dir*
Snippets are by default looked for any 'snippets' directory in your
'runtimepath'. Typically, it is located at '~/.vim/snippets/' on *nix or
'$HOME\vimfiles\snippets\' on Windows. To change that location or add another
one, change the g:snippets_dir variable in your |.vimrc| to your preferred
directory, or use the |ExtractSnips()|function. This will be used by the
|globpath()| function, and so accepts the same syntax as it (e.g.,
comma-separated paths).
ExtractSnipsFile({directory}, {filetype}) *ExtractSnipsFile()* *.snippets*
ExtractSnipsFile() extracts the specified *.snippets file for the given
filetype. A .snippets file contains multiple snippet declarations for the
filetype. It is further explained above, in |snippet-syntax|.
ExtractSnips({directory}, {filetype}) *ExtractSnips()* *.snippet*
ExtractSnips() extracts *.snippet files from the specified directory and
defines them as snippets for the given filetype. The directory tree should
look like this: 'snippets/<filetype>/<trigger>.snippet'. If the snippet has
multiple matches, it should look like this:
'snippets/<filetype>/<trigger>/<name>.snippet' (see |multi_snip|).
*ResetSnippets()*
The ResetSnippets() function removes all snippets from memory. This is useful
to put at the top of a snippet setup file for if you would like to |:source|
it multiple times.
*list-snippets* *i_CTRL-R_<Tab>*
If you would like to see what snippets are available, simply type <c-r><tab>
in the current buffer to show a list via |popupmenu-completion|.
==============================================================================
SETTINGS *snipMate-settings* *g:snips_author*
The g:snips_author string (similar to $TM_FULLNAME in TextMate) should be set
to your name; it can then be used in snippets to automatically add it. E.g.: >
let g:snips_author = 'Hubert Farnsworth'
snippet name
`g:snips_author`
<
*snipMate-expandtab* *snipMate-indenting*
If you would like your snippets to be expanded using spaces instead of tabs,
just enable 'expandtab' and set 'softtabstop' to your preferred amount of
spaces. If 'softtabstop' is not set, 'shiftwidth' is used instead.
*snipMate-remap*
snipMate does not come with a setting to customize the trigger key, but you
can remap it easily in the two lines it's defined in the 'after' directory
under 'plugin/snipMate.vim'. For instance, to change the trigger key
to shift-tab, just change this: >
ino <tab> <c-r>=TriggerSnippet()<cr>
snor <tab> <esc>i<right><c-r>=TriggerSnippet()<cr>
to this: >
ino <s-tab> <c-r>=TriggerSnippet()<cr>
snor <s-tab> <esc>i<right><c-r>=TriggerSnippet()<cr>
==============================================================================
FEATURES *snipMate-features*
snipMate.vim has the following features among others:
- The syntax of snippets is very similar to TextMate's, allowing
easy conversion.
- The position of the snippet is kept transparently (i.e. it does not use
markers/placeholders written to the buffer), which allows you to escape
out of an incomplete snippet, something particularly useful in Vim.
- Variables in snippets are updated as-you-type.
- Snippets can have multiple matches.
- Snippets can be out of order. For instance, in a do...while loop, the
condition can be added before the code.
- (New) File-based snippets are supported.
- (New) Triggers after non-word delimiters are expanded, e.g. "foo"
in "bar.foo".
==============================================================================
DISADVANTAGES *snipMate-disadvantages*
snipMate.vim currently has the following disadvantages to TextMate's snippets:
- There is no way to go back a tab stop, like shift-tab in TextMate.
- There is no $0; the order of tab stops must be explicitly stated.
- Placeholders within placeholders are not possible. E.g.: >
'<div${1: id="${2:some_id}}">${3}</div>'
<
In TextMate this would first highlight ' id="some_id"', and if
you hit delete it would automatically skip ${2} and go to ${3}
on the next <tab>, but if you didn't delete it it would highlight
"some_id" first. You cannot do this in snipMate.vim.
- Regex cannot be performed on variables, such as "${1/.*/\U&}"
- Placeholders cannot span multiple lines.
- Activating snippets in different scopes of the same file is
not possible.
Perhaps some of these features will be added in a later release.
==============================================================================
CONTACT *snipMate-contact* *snipMate-author*
To contact the author (Michael Sanders), please email:
msanders42+snipmate <at> gmail <dot> com
I greatly appreciate any suggestions or improvements offered for the script.
vim:tw=78:ts=8:ft=help:norl:

307
vim/doc/supertab.txt Normal file
View File

@@ -0,0 +1,307 @@
*supertab.txt*
Authors:
Original: Gergely Kontra <kgergely@mcl.hu>
Current: Eric Van Dewoestine <ervandew@gmail.com> (as of version 0.4)
Contributors:
Christophe-Marie Duquesne <chm.duquesne@gmail.com> (documentation)
Please direct all correspondence to Eric.
This plugin is licensed under the terms of the BSD License. Please see
supertab.vim for the license in its entirety.
==============================================================================
Supertab *supertab*
1. Introduction |supertab-intro|
2. Supertab Usage |supertab-usage|
3. Supertab Options |supertab-options|
Default completion type |supertab-defaultcompletion|
Secondary default completion type |supertab-contextdefault|
Completion contexts |supertab-completioncontexts|
Context text |supertab-contexttext|
Context Discover |supertab-contextdiscover|
Example |supertab-contextexample|
Completion Duration |supertab-duration|
Preventing Completion After/Before... |supertab-preventcomplete|
Changing default mapping |supertab-forwardbackward|
Inserting true tabs |supertab-mappingtabliteral|
Enhanced longest match support |supertab-longestenhanced|
Preselecting the first entry |supertab-longesthighlight|
==============================================================================
1. Introduction *supertab-intro*
Supertab is a plugin which allows you to perform all your insert completion
(|ins-completion|) using the tab key.
Supertab requires Vim version 7.0 or above.
==============================================================================
2. Supertab usage *supertab-usage*
Using Supertab is as easy as hitting <Tab> or <S-Tab> (shift+tab) while in
insert mode, with at least one non whitespace character before the cursor, to
start the completion and then <Tab> or <S-Tab> again to cycle forwards or
backwards through the available completions.
Example ('|' denotes the cursor location):
bar
baz
b|<Tab> Hitting <Tab> here will start the completion, allowing you to
then cycle through the suggested words ('bar' and 'baz').
==============================================================================
3. Supertab Options *supertab-options*
Supertab is configured via several global variables that you can set in your
|vimrc| file according to your needs. Below is a comprehensive list of
the variables available.
Default Completion Type *supertab-defaultcompletion*
*g:SuperTabDefaultCompletionType*
g:SuperTabDefaultCompletionType (default value: "<c-p>")
Used to set the default completion type. There is no need to escape this
value as that will be done for you when the type is set.
Example: setting the default completion to 'user' completion:
let g:SuperTabDefaultCompletionType = "<c-x><c-u>"
Note: a special value of 'context' is supported which will result in
super tab attempting to use the text preceding the cursor to decide which
type of completion to attempt. Currently super tab can recognize method
calls or attribute references via '.', '::' or '->', and file path
references containing '/'.
let g:SuperTabDefaultCompletionType = "context"
/usr/l<tab> # will use filename completion
myvar.t<tab> # will use user completion if completefunc set,
# or omni completion if omnifunc set.
myvar-><tab> # same as above
When using context completion, super tab will fall back to a secondary default
completion type set by |g:SuperTabContextDefaultCompletionType|.
Note: once the buffer has been initialized, changing the value of this setting
will not change the default complete type used. If you want to change the
default completion type for the current buffer after it has been set, perhaps
in an ftplugin, you'll need to call SuperTabSetDefaultCompletionType like so,
supplying the completion type you wish to switch to:
call SuperTabSetDefaultCompletionType("<c-x><c-u>")
Secondary default completion type *supertab-contextdefault*
*g:SuperTabContextDefaultCompletionType*
g:SuperTabContextDefaultCompletionType (default value: "<c-p>")
Sets the default completion type used when g:SuperTabDefaultCompletionType is
set to 'context' and no completion type is returned by any of the configured
contexts.
Completion contexts *supertab-completioncontexts*
*g:SuperTabCompletionContexts*
g:SuperTabCompletionContexts (default value: ['s:ContextText'])
Sets the list of contexts used for context completion. This value should
be a list of function names which provide the context implementation.
When supertab starts the default completion, each of these contexts will be
consulted, in the order they were supplied, to determine the completion type
to use. If a context returns a completion type, that type will be used,
otherwise the next context in the list will be consulted. If after executing
all the context functions, no completion type has been determined, then the
value of g:SuperTabContextDefaultCompletionType will be used.
Built in completion contexts:
s:ContextText *supertab-contexttext*
The text context will examine the text near the cursor to decide which type
of completion to attempt. Currently the text context can recognize method
calls or attribute references via '.', '::' or '->', and file path
references containing '/'.
/usr/l<tab> # will use filename completion
myvar.t<tab> # will use user completion if completefunc set, or
# omni completion if omnifunc set.
myvar-><tab> # same as above
Supported configuration attributes:
g:SuperTabContextTextFileTypeExclusions
List of file types for which the text context will be skipped.
g:SuperTabContextTextOmniPrecedence
List of omni completion option names in the order of precedence that they
should be used if available. By default, user completion will be given
precedence over omni completion, but you can use this variable to give
omni completion higher precedence by placing it first in the list.
s:ContextDiscover *supertab-contextdiscover*
This context will use the 'g:SuperTabContextDiscoverDiscovery' variable to
determine the completion type to use. It will evaluate each value, in the
order they were defined, until a variable evaluates to a non-zero or
non-empty value, then the associated completion type is used.
Supported configuration properties:
g:SuperTabContextDiscoverDiscovery
List of variable:completionType mappings.
Example context configuration: *supertab-contextexample*
let g:SuperTabCompletionContexts = ['s:ContextText', 's:ContextDiscover']
let g:SuperTabContextTextOmniPrecedence = ['&omnifunc', '&completefunc']
let g:SuperTabContextDiscoverDiscovery =
\ ["&completefunc:<c-x><c-u>", "&omnifunc:<c-x><c-o>"]
In addition to the default completion contexts, you can plug in your own
implementation by creating a globally accessible function that returns
the completion type to use (eg. "\<c-x>\<c-u>").
function MyTagContext()
if filereadable(expand('%:p:h') . '/tags')
return "\<c-x>\<c-]>"
endif
" no return will result in the evaluation of the next
" configured context
endfunction
let g:SuperTabCompletionContexts =
\ ['MyTagContext', 's:ContextText', 's:ContextDiscover']
Note: supertab also supports the b:SuperTabCompletionContexts variable
allowing you to set the list of contexts separately for the current buffer,
like from an ftplugin for example.
Completion Duration *supertab-duration*
*g:SuperTabRetainCompletionDuration*
g:SuperTabRetainCompletionDuration (default value: 'insert')
Determines if, and for how long, the current completion type is retained.
The possible values include:
'completion' - The current completion type is only retained for the
current completion. Once you have chosen a completion
result or exited the completion mode, the default
completion type is restored.
'insert' - The current completion type is saved until you exit insert
mode (via ESC). Once you exit insert mode the default
completion type is restored. (supertab default)
'session' - The current completion type is saved for the duration of
your vim session or until you enter a different completion
mode.
Preventing completion after... *supertab-preventcomplete*
*g:SuperTabNoCompleteBefore*
*g:SuperTabNoCompleteAfter*
g:SuperTabNoCompleteBefore (default value: [])
g:SuperTabNoCompleteAfter (default value: ['\s'])
These two variables are used to control when supertab will attempt completion
or instead fall back to inserting a literal <tab>, by specifying a list of
patterns which are tested against the text before and after the current cursor
position that when matched, prevent completion. So if you don't want supertab
to start completion after a comma or space, you can set
g:SuperTabNoCompleteAfter to [',', '\s'].
Note: That a buffer local version of these variables
(b:SuperTabNoCompleteBefore, b:SuperTabNoCompleteAfter) is also supported
should you wish to have different values depending on the file type for
instance.
Changing the default mapping *supertab-forwardbackward*
*g:SuperTabMappingForward*
*g:SuperTabMappingBackward*
g:SuperTabMappingForward (default value: '<tab>')
g:SuperTabMappingBackward (default value: '<s-tab>')
These two variables allow you to set the keys used to kick off the current
completion. By default this is <tab> and <s-tab>. To change to something
like <c-space> and <s-c-space>, you can add the following to your |vimrc|.
let g:SuperTabMappingForward = '<c-space>'
let g:SuperTabMappingBackward = '<s-c-space>'
Note: if the above does not have the desired effect (which may happen in
console version of vim), you can try the following mappings. Although the
backwards mapping still doesn't seem to work in the console for me, your
milage may vary.
let g:SuperTabMappingForward = '<nul>'
let g:SuperTabMappingBackward = '<s-nul>'
Inserting true tabs *supertab-mappingtabliteral*
*g:SuperTabMappingTabLiteral*
g:SuperTabMappingTabLiteral (default value: '<c-tab>')
Sets the key mapping used to insert a literal tab where supertab would
otherwise attempt to kick off insert completion. The default is '<c-tab>'
(ctrl-tab) which unfortunately might not work at the console. So if you are
using a console vim and want this functionality, you may have to change it to
something that is supported. Alternatively, you can escape the <tab> with
<c-v> (see |i_CTRL-V| for more infos).
Enhanced longest match support *supertab-longestenhanced*
*g:SuperTabLongestEnhanced*
g:SuperTabLongestEnhanced (default value: 0)
When enabled and 'longest' is in your |completeopt| setting, supertab will
provide an enhanced longest match support where typing one or more letters and
hitting tab again while in a completion mode will complete the longest common
match using the new text in the buffer.
For example, say you have a buffer with the following contents:
FooBarFoo
FooBar
Foo
FooBarBaz
And you then type F<tab>. Vim's builtin longest support will complete the
longest common text 'Foo' and offer 'FooBarFoo', 'FooBar', 'Foo', and
'FooBarBaz' as possible completions. With supertab's longest match
enhancement disabled, typing B<tab> while still in the completion mode will
end up completing 'FooBarBaz' or 'FooBarFoo' depending your settings, instead
of the next longest common match of 'FooBar'. With supertab's enhanced
longest match feature enabled, the typing of B<tab> will result in the next
longest text being completed.
Preselecting the first entry *supertab-longesthighlight*
*g:SuperTabLongestHighlight*
g:SuperTabLongestHighlight (default value: 0)
Sets whether or not to pre-highlight the first match when completeopt has the
popup menu enabled and the 'longest' option as well. When enabled, <tab> will
kick off completion and pre-select the first entry in the popup menu, allowing
you to simply hit <enter> to use it.
Mapping <cr> to end completion *supertab-crmapping*
*g:SuperTabCrMapping*
g:SuperTabCrMapping (default value: 1)
When enabled, <cr> will cancel completion mode preserving the current text.
vim:tw=78:ts=8:ft=help:norl:

218
vim/doc/surround.txt Normal file
View File

@@ -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 are explained in |surround-targets|
but essentially it is the last character of a |text-object|. This mapping
deletes the difference between the "inner" object and "an" object. This is
easiest to understand with some examples:
Old text Command New text ~
"Hello *world!" ds" Hello world!
(123+4*56)/2 ds) 123+456/2
<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 an valid Vim motion or text object as the first object, and wraps
it using the second argument as with |cs|. (Unfortunately there's no good
mnemonic for "ys".)
Old text Command New text ~
Hello w*orld! ysiw) Hello (world)!
As a special case, *yss* operates on the current line, ignoring leading
whitespace.
Old text Command New text ~
Hello w*orld! yssB {Hello world!}
There is also *yS* and *ySS* which indent the surrounded text and place it
on a line of its own.
In visual mode, a simple "s" with an argument wraps the selection. This is
referred to as the *vs* mapping, although ordinarily there will be
additional keystrokes between the v and s. In linewise visual mode, the
surroundings are placed on separate lines. In blockwise visual mode, each
line is surrounded.
An "S" in visual mode (*vS*) behaves similarly but always places the
surroundings on separate lines. Additionally, the surrounded text is
indented. In blockwise visual mode, using "S" instead of "s" instead skips
trailing whitespace.
Note that "s" and "S" already have valid meaning in visual mode, but it is
identical to "c". If you have muscle memory for "s" and would like to use a
different key, add your own mapping and the existing one will be disabled.
>
vmap <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 counterpart. If the opening mark is used, contained whitespace is
also trimmed. The targets b, B, r, and a are aliases for ), }, ], and >
(the first two mirror Vim; the second two are completely arbitrary and
subject to change).
Three quote marks, ', ", `, represent themselves, in pairs. They are only
searched for on the current line.
A t is a pair of HTML or XML tags. See |tag-blocks| for details. Remember
that you can specify a numerical argument if you want to get to a tag other
than the innermost one.
The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|,
respectively. These are special in that they have nothing to delete, and
used with |ds| they are a no-op. With |cs|, one could consider them a
slight shortcut for ysi (cswb == ysiwb, more or less).
A p represents a |paragraph|. This behaves similarly to w, W, and s above;
however, newlines are sometimes added and/or removed.
REPLACEMENTS *surround-replacements*
A replacement argument is a single character, and is required by |cs|, |ys|,
and |vs|. Undefined replacement characters (with the exception of alphabetic
characters) default to placing themselves at the beginning and end of the
destination, which can be useful for characters like / and |.
If either ), }, ], or > is used, the text is wrapped in the appropriate pair
of characters. Similar behavior can be found with (, {, and [ (but not <),
which append an additional space to the inside. Like with the targets above,
b, B, r, and a are aliases for ), }, ], and >. To fulfill the common need for
code blocks in C-style languages, <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:

313
vim/doc/syntastic.txt Executable file
View File

@@ -0,0 +1,313 @@
*syntastic.txt* Syntax checking on the fly has never been so pimp.
*syntastic*
It's a bird! It's a plane! ZOMG It's ... ~
_____ __ __ _ ~
/ ___/__ ______ / /_____ ______/ /_(_)____ ~
\__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ ~
___/ / /_/ / / / / /_/ /_/ (__ ) /_/ / /__ ~
/____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/ ~
/____/ ~
Reference Manual~
==============================================================================
CONTENTS *syntastic-contents*
1.Intro...................................|syntastic-intro|
2.Functionality provided..................|syntastic-functionality|
2.1.The statusline flag...............|syntastic-statusline-flag|
2.2.Error signs.......................|syntastic-error-signs|
2.3.Error window......................|syntastic-error-window|
3.Commands................................|syntastic-commands|
4.Options.................................|syntastic-options|
5.Writing syntax checkers.................|syntastic-syntax-checkers|
6.About...................................|syntastic-about|
7.Changelog...............................|syntastic-changelog|
8.Credits.................................|syntastic-credits|
9.License.................................|syntastic-license|
==============================================================================
1. Intro *syntastic-intro*
Syntastic is a syntax checking plugin that runs buffers through external syntax
checkers as they are saved and opened. If syntax errors are detected, the user
is notified and is happy because they didn't have to compile their code or
execute their script to find them.
Syntastic comes in two parts: the syntax checker plugins, and the core script
(i.e. syntastic.vim). The syntax checker plugins are defined on a per-filetype
basis where each one wraps up an external syntax checking program. The core
script delegates off to these plugins and uses their output to provide the
syntastic functionality. Currently, syntax checking plugins exist for c,
coffee, cpp, cucumber, eruby, haml, haskell, html, javascript, lua, perl, php,
python, ruby, sass, sh, tex and xhtml.
NOTE: This list is subject to change without notice. Please check the
syntax_checkers directory for a reliable list of syntax checkers.
If your language is not supported then see |syntastic-syntax-checkers| for
details on how to implement a syntax checking plugin, and be sure to send me a
patch ;-)
This plugin is currently only recommended for *nix users. It is functional on
Windows, but since the syntax checking plugins shell out, the command window
briefly appears whenever one is executed.
==============================================================================
2. Functionality provided *syntastic-functionality*
By default, the script does nothing. The following functionality is provided
and must be enabled/activated as indicated (see the sections below for more
in-depth descriptions):
* A statusline flag appears when syntax errors are detected
* |signs| are placed beside lines with syntax errors, where a different
sign is used for errors and warnings.
* The :Errors command is provided to open a |location-list| for
the syntax errors in the current buffer
Note: This functionality is only available if a syntax checker plugin is
present for the filetype of the buffer in question. See
|syntastic-syntax-checkers| for details.
------------------------------------------------------------------------------
2.1. The statusline flag *syntastic-statusline-flag*
To use the statusline flag, this must appear in your |'statusline'| setting >
%{SyntasticStatuslineFlag()}
<
Something like this could be more useful: >
set statusline+=%#warningmsg#
set statusline+=%{SyntasticStatuslineFlag()}
set statusline+=%*
<
When syntax errors are detected a flag will be shown. The content of the flag
is derived from the |syntastic_stl_format| option
------------------------------------------------------------------------------
2.2. Error signs *syntastic-error-signs*
Syntastic uses the |:sign| commands to mark lines with errors and warnings in
the sign column. To enable this feature, use the |'syntastic_enable_signs'|
option.
------------------------------------------------------------------------------
2.3. The error window *:Errors* *syntastic-error-window*
You can use the :Errors command to display the errors for the current buffer
in the |location-list|.
Note that when you use :Errors, the current location list is overwritten with
Syntastic's own location list.
==============================================================================
3. Commands *syntastic-commands*
:SyntasticDisable [filetype] *:SyntasticDisable*
Disables syntax checking for the the given filetype (if specified), or the
current filetype.
:SyntasticEnable [filetype] *:SyntasticEnable*
Enables syntax checking for the the given filetype (if specified), or the
current filetype.
==============================================================================
4. Options *syntastic-options*
*'syntastic_enable_signs'*
Use this option to tell syntastic to use the |:sign| interface to mark syntax
errors: >
let g:syntastic_enable_signs=1
<
*'syntastic_auto_jump'*
Enable this option if you want the cursor to jump to the first detected error
when saving or opening a file: >
let g:syntastic_auto_jump=1
<
*'syntastic_auto_loc_list'*
Use this option to tell syntastic to automatically open and/or close the
|location-list| (see |syntastic-error-window|).
When set to 1 the error window will be automatically opened when errors are
detected, and closed when none are detected. >
let g:syntastic_auto_loc_list=1
<
When set to 2 the error window will be automatically closed when no errors are
detected, but not opened automatically. >
let g:syntastic_auto_loc_list=2
<
*'syntastic_quiet_warnings'*
Use this option if you only care about syntax errors, not warnings. When set,
this option has the following effects:
* the statusline flag only counts syntax errors
* no |signs| appear unless there is at least one error, whereupon both
errors and warnings are displayed
* the |'syntastic_auto_loc_list'| option only pops up the error window if
there's at least one error, whereupon both errors and warnings are
displayed
>
let g:syntastic_quiet_warnings=1
<
*'syntastic_stl_format'*
Default: [Syntax: line:%F (%t)]
Use this option to control what the syntastic statusline text contains. Several
magic flags are availble to insert information:
%e - number of errors
%w - number of warnings
%t - total number of warnings and errors
%fe - line number of first error
%fw - line number of first warning
%F - line number of first warning or error
Several additional flags are available to hide text under certain conditions:
%E{...} - hide the text in the brackets unless there are errors
%W{...} - hide the text in the brackets unless there are warnings
%B{...} - hide the text in the brackets unless there are both warnings AND
errors
These flags cant be nested.
Example: >
let g:syntastic_stl_format = '[%E{Err: %fe #%e}%B{, }%W{Warn: %fw #%w}]'
<
If this format is used and the current buffer has 5 errors and 1 warning
starting on lines 20 and 10 respectively then this would appear on the
statusline: >
[Err: 20 #5, Warn: 10 #1]
<
If the buffer had 2 warnings, starting on line 5 then this would appear: >
[Warn: 5 #2]
<
*'syntastic_disabled_filetypes'*
Use this option to disable syntax checking on selected filetypes by default.
Should be set to a list of filetypes, e.g. >
let g:syntastic_disabled_filetypes = ['ruby', 'php']
<
Syntax checking can be enabled again via |:SyntasticEnable|.
==============================================================================
5. Writing syntax checkers *syntastic-syntax-checkers*
A syntax checker plugin is really nothing more than a single function. You
should define them in ~/.vim/syntax_checkers/<filetype>.vim, but this is
purely for convenience; Syntastic doesn't actually care where these functions
are defined.
A syntax checker plugin must define a function of the form:
>
SyntaxCheckers_<filetype>_GetLocList()
<
The output of this function must be of the same format as that returned by
the |getloclist()| function. See |getloclist()| and |getqflist()| for
details.
To achieve this, the function should call |SyntasticMake()| or shell out to a
syntax checker, parse the output and munge it into the format.
There are several syntax checker plugins provided with this plugin. The ruby
one is a good example of |SyntasticMake()|, while the haml one is a good
example of how to create the data structure manually.
SyntasticMake({options}) *SyntasticMake()*
{options} must be a dictionary. It can contain "makeprg" and "errorformat"
as keys (both optional).
SyntasticMake will run |:lmake| with the given |'makeprg'| and
|'errorformat'| (using the current settings if none are supplied). It will
store the resulting error list and use it to provide all of the
|syntastic-functionality|. The previous makeprg and errorformat settings
will then be restored, as well as the location list for the window. From
the user's perspective, it will be as though |:lmake| was never run.
Note that the given "makeprg" and "errorformat" will be set using |:let-&|,
so you should not escape spaces.
==============================================================================
6. About *syntastic-about*
The author of syntastic is a mighty wild stallion, hear him roar! >
_ _ _____ _____ ___ ___ ___ ____ _ _ _
| \ | | ____| ____|_ _|_ _|_ _/ ___| | | | |
| \| | _| | _| | | | | | | | _| |_| | |
| |\ | |___| |___ | | | | | | |_| | _ |_|
|_| \_|_____|_____|___|___|___\____|_| |_(_)
<
He likes to trot around in the back yard reading his emails and sipping a
scolding hot cup of Earl Grey. Email him at martin.grenfell at gmail dot com.
He can also be found trolling the #vim channel on the freenode IRC network as
scrooloose.
Bug reports, feedback, suggestions etc are welcomed.
The latest official releases will be on vim.org at some point.
The latest dev versions are on github
http://github.com/scrooloose/syntastic
==============================================================================
7. Changelog *syntastic-changelog*
1.2.0
- New syntax checkers from github:kongo2002
- c (thanks also to github:jperras)
- cpp
- lua
- sh (thanks also to github:jmcantrell)
- add coffee syntax checked by github:lstoll
- add tex syntax checker
- make html checker play nicer with html5, thanks to github:enaeseth
- escape filenames properly when invoking syntax checkers, thanks to
github:jmcantrell
- adjust the ruby syntax checker to avoid some common annoying warnings,
thanks to github:robertwahler
1.1.0 [codenamed: tpimp]
- Dont load rubygems for ruby/eruby syntax checkers. Thanks tpope.
- Improve the javascript syntax checker to catch some warnings that were
getting missed. Thanks tpope.
- Dont automatically focus the error window. Thanks tpope.
- Add support for cucumber [tpope], haskell & perl [Anthony Carapetis],
and xhtml
- Add commands to enable/disable syntax checking at runtime. See :help
syntastic-commands.
- Add an option to specifiy syntax checkers that should be disabled by
default. See :help syntastic_disabled_filetypes.
- Dont use :signs if vim wasnt compiled with support for them.
==============================================================================
8. Credits *syntastic-credits*
Thanks to the following people for testing, bug reports, patches etc. They own,
hard.
Tim Carey-Smith (halorgium)
Tim Pope (tpope)
Travis Jeffery
Anthony Carapetis
==============================================================================
9. License *syntastic-license*
Syntastic is released under the wtfpl.
See http://sam.zoy.org/wtfpl/COPYING.

208
vim/doc/tComment.txt Normal file
View File

@@ -0,0 +1,208 @@
*tComment.txt* tComment -- An easily extensible & universal comment plugin
Author: Thomas Link, micathom AT gmail com?subject=vim
tComment provides easy to use, file-type sensible comments for Vim. It
can handle embedded syntax.
*tComment-Installation*
Installation~
Edit the vba file and type:
:so %
See :help vimball for details. If you use vim 7.0, you may need to
update your vimball installation first.
*tComment-Usage*
Usage~
TComment works like a toggle, i.e., it will comment out text that
contains uncommented lines, and it will remove comment markup for
already commented text (i.e. text that contains no uncommented lines).
If the file-type is properly defined, TComment will figure out which
comment string to use. Otherwise you use |TCommentDefineType()| to
override the default choice.
TComment can properly handle an embedded syntax, e.g., ruby/python/perl
regions in vim scripts, HTML or JavaScript in php code etc.
*tComment-Key-Bindings*
Key bindings~
Most of the time the default toggle keys will do what you want (or to be
more precise: what I think you want it to do ;-).
*g:tcommentMapLeaderOp1*
*g:tcommentMapLeaderOp2*
As operator (the prefix can be customized via g:tcommentMapLeaderOp1
and g:tcommentMapLeaderOp2):
gc{motion} :: Toggle comments (for small comments within one line
the &filetype_inline style will be used, if
defined)
gcc :: Toggle comment for the current line
gC{motion} :: Comment region
gCc :: Comment the current line
*g:tcommentOpModeExtra*
By default the cursor stays put. If you want the cursor to the end of
the commented text, set g:tcommentOpModeExtra to '>' (but this may not
work properly with exclusive motions).
Primary key maps:
<c-_><c-_> :: :TComment
<c-_><space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
<c-_>b :: :TCommentBlock
<c-_>a :: :TCommentAs <QUERY COMMENT TYPE>
<c-_>n :: :TCommentAs &filetype <QUERY COUNT>
<c-_>s :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>
<c-_>i :: :TCommentInline
<c-_>r :: :TCommentRight
<c-_>p :: Comment the current inner paragraph
A secondary set of key maps is defined for normal mode.
<Leader>__ :: :TComment
<Leader>_p :: Comment the current inner paragraph
<Leader>_<space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
<Leader>_i :: :TCommentInline
<Leader>_r :: :TCommentRight
<Leader>_b :: :TCommentBlock
<Leader>_a :: :TCommentAs <QUERY COMMENT TYPE>
<Leader>_n :: :TCommentAs &filetype <QUERY COUNT>
<Leader>_s :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>
Keymaps are configurable via the following variables:
*g:tcommentMapLeader1*
g:tcommentMapLeader1 string (default: <c-_>)
Prefix for the keymaps. Set to '' to disable keymaps with this
prefix.
*g:tcommentMapLeader2*
g:tcommentMapLeader2 string (default: <Leader>_)
Secondary prefix. (The reason for why there are two prefixes is
that <c-_> appears preferable with gvim but can be difficult to
type on the terminal. The secondary prefix isn't used for insert
mode maps. Set to '' to disable keymaps with this prefix.
*tComment-commands*
Alternatively, you can type (? meaning "optional argument"):
*:TComment*
:?<range> TComment ?commentBegin ?commentEnd
:?<range> TComment! ?commentBegin ?commentEnd
NOTE: If there is a visual selection that begins and ends in the same
line, then TCommentInline is used instead.
NOTE: The range is optional and defaults to the current line.
*:TCommentInline*
:?<range> TCommentInline ?commentBegin ?commentEnd
:?<range> TCommentInline! ?commentBegin ?commentEnd
Use the {&ft}_inline comment style.
*:TCommentBlock*
:?<range> TCommentBlock ?commentBegin ?commentEnd
:?<range> TCommentBlock! ?commentBegin ?commentEnd
Comment as "block", e.g. use the {&ft}_block comment style.
NOTE: This command is kind of crude. It doesn't indent or reformat
the text.
*:TCommentAs*
:?<range> TCommentAs filetype
:?<range> TCommentAs! filetype
NOTE: TCommentAs requires g:tcomment_{filetype} to be defined.
NOTE: This command supports command line completion. See 'wildmode'
and 'wildmenu' for how to get the most out of it.
*:TCommentRight*
:?<range> TCommentRight
:?<range> TCommentRight!
NOTE: This command comments out the text to the right of the cursor.
If a visual selection was made (be it block-wise or not), all lines
are commented out at from the current cursor position downwards.
The bang (!) variants always comment out the selected text and don't
work as toggles.
*TCommentDefineType()*
Using this command you can also use different comment styles with
the TCommentDefineType(name, commentstring) function. This function
takes two arguments:
name :: The name is either &filetype or {&filetype}_{style}.
I.e., For block comments the {&filetype}_block and for
inline comments the {&filetype}_inline styles are used.
comment string :: a string mostly as described in
'commentstring'.
If you want to define, e.g., a fancy block comment style for html
you put something like this into ~/.vim/after/plugin/tComment.vim:>
call TCommentDefineType("html_fancy_block", "<!--%s -->\n -- ")
< The part after the newline character is used for marking "middle"
lines.
This comment style could then be accessed via (this command has
command line completion): >
'<,'>TCommentAs html_fancy_block
< If you're editing a html file, this could best be done by the <c-_>s
key map.
Goals~
- Maintain indentation of selected text; the comment markers are left
aligned but the text on the right (i.e., the comment) is indented
like the original text
- Handle embedded syntax like php+html or html+javaScript+css; you
have to set g:tcommentGuessFileType_{&filetype} to 1 or to the
fall-back file-type in order to activate this feature for other file
types than php or html
tComment deduces the correct file type from the syntax name, similar
to the way EnhancedCommentify.vim does it. In opposition to
EnhancedCommentify.vim, it matches the syntax name against a list the
known file types, so that it can deal with, e.g., embedded javaScript
- Easy to customize/adapt for an yet unknown syntax by setting buffer
local variables (b:commentStart, b:commentEnd, or b:commentstring),
global variables (g:tcomment_{&ft} and g:tcomment_{&ft}_block), or the
buffer local &commentstring option (which can be set on a vim
|modeline|)
- Use 'commentstring' or 'comments' as a fallback (i.e., if a file-type
is properly defined, TComment will automatically support it)
- Same short-cut for commenting text and for removing comment markup
- The decision whether text should be commented or uncommented is made
on the basis of the whole selection (not line by line); comments in
code that should be commented aren't uncommented as it is the case
with some other plug-ins
As of version 1.5, the following file types are explicitly defined
(other file-types are most likely supported through the 'commentstring'
or 'comments' variables):
ada, apache, autoit, catalog, cpp, css, c, cfg, conf, desktop,
docbk, dosbatch, dosini, dsl, dylan, eiffel, gtkrc, haskell, html,
io, javaScript, java, lisp, m4, nroff, objc, ocaml, pascal, perl,
php, prolog, ruby, r, scheme, sgml, sh, sql, spec, sps, tcl, tex,
tpl, viki, vim, websec, xml, xslt, yaml
Credits~
The way we check for embedded syntax was originally adapted
from/inspired by Meikel Brandmeyer's EnhancedCommentify.vim
(vimscript #23) but has evolved since.
vim: tw=72

1501
vim/doc/taglist.txt Normal file
View File

File diff suppressed because it is too large Load Diff

819
vim/doc/vcscommand.txt Executable file
View File

@@ -0,0 +1,819 @@
*vcscommand.txt* vcscommand
Copyright (c) 2007 Bob Hiestand
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
For instructions on installing this file, type
:help add-local-help
inside Vim.
Author: Bob Hiestand <bob.hiestand@gmail.com>
Credits: Benji Fisher's excellent MatchIt documentation
==============================================================================
1. Contents *vcscommand-contents*
Installation : |vcscommand-install|
vcscommand Intro : |vcscommand|
vcscommand Manual : |vcscommand-manual|
Customization : |vcscommand-customize|
SSH "integration" : |vcscommand-ssh|
Changes from cvscommand : |cvscommand-changes|
Bugs : |vcscommand-bugs|
==============================================================================
2. vcscommand Installation *vcscommand-install*
The vcscommand plugin comprises five files: vcscommand.vim, vcssvn.vim,
vcscvs.vim, vcssvk.vim and vcscommand.txt (this file). In order to install
the plugin, place the vcscommand.vim, vcssvn.vim, vcssvk.vim, and vcscvs.vim
files into a plugin directory in your runtime path (please see
|add-global-plugin| and |'runtimepath'|.
This help file can be included in the VIM help system by copying it into a
'doc' directory in your runtime path and then executing the |:helptags|
command, specifying the full path of the 'doc' directory. Please see
|add-local-help| for more details.
vcscommand may be customized by setting variables, creating maps, and
specifying event handlers. Please see |vcscommand-customize| for more
details.
==============================================================================
3. vcscommand Intro *vcscommand*
*vcscommand-intro*
The vcscommand plugin provides global ex commands for manipulating
version-controlled source files, currently those controlled either by CVS or
Subversion. In general, each command operates on the current buffer and
accomplishes a separate source control function, such as update, commit, log,
and others (please see |vcscommand-commands| for a list of all available
commands). The results of each operation are displayed in a scratch buffer.
Several buffer variables are defined for those scratch buffers (please see
|vcscommand-buffer-variables|).
The notion of "current file" means either the current buffer, or, in the case
of a directory buffer (such as Explorer or netrw buffers), the directory (and
all subdirectories) represented by the the buffer.
For convenience, any vcscommand invoked on a vcscommand scratch buffer acts as
though it was invoked on the original file and splits the screen so that the
output appears in a new window.
Many of the commands accept revisions as arguments. By default, most operate
on the most recent revision on the current branch if no revision is specified.
Each vcscommand is mapped to a key sequence starting with the |<Leader>|
keystroke. The default mappings may be overridden by supplying different
mappings before the plugin is loaded, such as in the vimrc, in the standard
fashion for plugin mappings. For examples, please see
|vcscommand-mappings-override|.
The vcscommand plugin may be configured in several ways. For more details,
please see |vcscommand-customize|.
==============================================================================
4. vcscommand Manual *vcscommand-manual*
4.1 vcscommand commands *vcscommand-commands*
vcscommand defines the following commands:
|:VCSAdd|
|:VCSAnnotate|
|:VCSBlame|
|:VCSCommit|
|:VCSDelete|
|:VCSDiff|
|:VCSGotoOriginal|
|:VCSLog|
|:VCSRemove|
|:VCSRevert|
|:VCSReview|
|:VCSStatus|
|:VCSUpdate|
|:VCSVimDiff|
The following commands are specific to CVS files:
|:CVSEdit|
|:CVSEditors|
|:CVSUnedit|
|:CVSWatch|
|:CVSWatchAdd|
|:CVSWatchOn|
|:CVSWatchOff|
|:CVSWatchRemove|
|:CVSWatchers|
:VCSAdd *:VCSAdd*
This command adds the current file to source control. Please note, this does
not commit the newly-added file. All parameters to the command are passed to
the underlying VCS.
:VCSAnnotate[!] *:VCSAnnotate*
This command displays the current file with each line annotated with the
version in which it was most recently changed. If an argument is given, the
argument is used as a revision number to display. If not given an argument,
it uses the most recent version of the file (on the current branch, if under
CVS control). Additionally, if the current buffer is a VCSAnnotate buffer
already, the version number on the current line is used.
If '!' is used, the view of the annotated buffer is split so that the
annotation is in a separate window from the content, and each is highlighted
separately.
For CVS buffers, the 'VCSCommandCVSAnnotateParent' option, if set to non-zero,
will cause the above behavior to change. Instead of annotating the version on
the current line, the parent revision is used instead, crossing branches if
necessary.
With no arguments the cursor will jump to the line in the annotated buffer
corresponding to the current line in the source buffer.
:VCSBlame[!] *:VCSBlame*
Alias for |:VCSAnnotate|.
:VCSCommit[!] *:VCSCommit*
This command commits changes to the current file to source control.
If called with arguments, the arguments are the log message.
If '!' is used, an empty log message is committed.
If called with no arguments, this is a two-step command. The first step opens
a buffer to accept a log message. When that buffer is written, it is
automatically closed and the file is committed using the information from that
log message. The commit can be abandoned if the log message buffer is deleted
or wiped before being written.
Alternatively, the mapping that is used to invoke :VCSCommit (by default
|<Leader>|cc, please see |vcscommand-mappings|) can be used in the log message
buffer in Normal mode to immediately commit. This is useful if the
|VCSCommandCommitOnWrite| variable is set to 0 to disable the normal
commit-on-write behavior.
:VCSDelete *:VCSDelete*
Deletes the current file and removes it from source control. All parameters
to the command are passed to the underlying VCS.
:VCSDiff *:VCSDiff*
With no arguments, this displays the differences between the current file and
its parent version under source control in a new scratch buffer.
With one argument, the diff is performed on the current file against the
specified revision.
With two arguments, the diff is performed between the specified revisions of
the current file.
For CVS, this command uses the |VCSCommandCVSDiffOpt| variable to specify diff
options. If that variable does not exist, a plugin-specific default is used.
If you wish to have no options, then set it to the empty string.
For SVN, this command uses the |VCSCommandSVNDiffOpt| variable to specify diff
options. If that variable does not exist, the SVN default is used.
Additionally, |VCSCommandSVNDiffExt| can be used to select an external diff
application.
:VCSGotoOriginal *:VCSGotoOriginal*
This command jumps to the source buffer if the current buffer is a VCS scratch
buffer.
:VCSGotoOriginal!
Like ":VCSGotoOriginal" but also executes :bufwipeout on all VCS scrach
buffers associated with the original file.
:VCSInfo *:VCSInfo*
This command displays extended information about the current file in a new
scratch buffer.
:VCSLock *:VCSLock*
This command locks the current file in order to prevent other users from
concurrently modifying it. The exact semantics of this command depend on the
underlying VCS. This does nothing in CVS. All parameters are passed to the
underlying VCS.
:VCSLog *:VCSLog*
Displays the version history of the current file in a new scratch buffer. If
there is one parameter supplied, it is taken as as a revision parameters to be
passed through to the underlying VCS. Otherwise, all parameters are passed to
the underlying VCS.
:VCSRemove *:VCSRemove*
Alias for |:VCSDelete|.
:VCSRevert *:VCSRevert*
This command replaces the current file with the most recent version from the
repository in order to wipe out any undesired changes.
:VCSReview *:VCSReview*
Displays a particular version of the current file in a new scratch buffer. If
no argument is given, the most recent version of the file on the current
branch is retrieved.
:VCSStatus *:VCSStatus*
Displays versioning information about the current file in a new scratch
buffer. All parameters are passed to the underlying VCS.
:VCSUnlock *:VCSUnlock*
Unlocks the current file in order to allow other users from concurrently
modifying it. The exact semantics of this command depend on the underlying
VCS. All parameters are passed to the underlying VCS.
:VCSUpdate *:VCSUpdate*
Updates the current file with any relevant changes from the repository. This
intentionally does not automatically reload the current buffer, though vim
should prompt the user to do so if the underlying file is altered by this
command.
:VCSVimDiff *:VCSVimDiff*
Uses vimdiff to display differences between versions of the current file.
If no revision is specified, the most recent version of the file on the
current branch is used. With one argument, that argument is used as the
revision as above. With two arguments, the differences between the two
revisions is displayed using vimdiff.
With either zero or one argument, the original buffer is used to perform the
vimdiff. When the scratch buffer is closed, the original buffer will be
returned to normal mode.
Once vimdiff mode is started using the above methods, additional vimdiff
buffers may be added by passing a single version argument to the command.
There may be up to 4 vimdiff buffers total.
Using the 2-argument form of the command resets the vimdiff to only those 2
versions. Additionally, invoking the command on a different file will close
the previous vimdiff buffers.
:CVSEdit *:CVSEdit*
This command performs "cvs edit" on the current file. Yes, the output buffer
in this case is almost completely useless.
:CVSEditors *:CVSEditors*
This command performs "cvs edit" on the current file.
:CVSUnedit *:CVSUnedit*
Performs "cvs unedit" on the current file. Again, yes, the output buffer here
is basically useless.
:CVSWatch *:CVSWatch*
This command takes an argument which must be one of [on|off|add|remove]. The
command performs "cvs watch" with the given argument on the current file.
:CVSWatchAdd *:CVSWatchAdd*
This command is an alias for ":CVSWatch add"
:CVSWatchOn *:CVSWatchOn*
This command is an alias for ":CVSWatch on"
:CVSWatchOff *:CVSWatchOff*
This command is an alias for ":CVSWatch off"
:CVSWatchRemove *:CVSWatchRemove*
This command is an alias for ":CVSWatch remove"
:CVSWatchers *:CVSWatchers*
This command performs "cvs watchers" on the current file.
4.2 Mappings *vcscommand-mappings*
By default, a mapping is defined for each command. These mappings execute the
default (no-argument) form of each command.
|<Leader>|ca VCSAdd
|<Leader>|cn VCSAnnotate
|<Leader>|cN VCSAnnotate!
|<Leader>|cc VCSCommit
|<Leader>|cD VCSDelete
|<Leader>|cd VCSDiff
|<Leader>|cg VCSGotoOriginal
|<Leader>|cG VCSGotoOriginal!
|<Leader>|ci VCSInfo
|<Leader>|cl VCSLog
|<Leader>|cL VCSLock
|<Leader>|cr VCSReview
|<Leader>|cs VCSStatus
|<Leader>|cu VCSUpdate
|<Leader>|cU VCSUnlock
|<Leader>|cv VCSVimDiff
Only for CVS buffers:
|<Leader>|ce CVSEdit
|<Leader>|cE CVSEditors
|<Leader>|ct CVSUnedit
|<Leader>|cwv CVSWatchers
|<Leader>|cwa CVSWatchAdd
|<Leader>|cwn CVSWatchOn
|<Leader>|cwf CVSWatchOff
|<Leader>|cwf CVSWatchRemove
*vcscommand-mappings-override*
The default mappings can be overridden by user-provided instead by mapping to
<Plug>CommandName. This is especially useful when these mappings collide with
other existing mappings (vim will warn of this during plugin initialization,
but will not clobber the existing mappings).
There are three methods for controlling mapping:
First, maps can be overriden for individual commands. For instance, to
override the default mapping for :VCSAdd to set it to '\add', add the
following to the vimrc:
nmap \add <Plug>VCSAdd
Second, the default map prefix ('<Leader>c') can be overridden by defining the
|VCSCommandMapPrefix| variable.
Third, the entire set of default maps can be overridden by defining the
|VCSCommandMappings| variable.
4.3 Automatic buffer variables *vcscommand-buffer-variables*
Several buffer variables are defined in each vcscommand result buffer. These
may be useful for additional customization in callbacks defined in the event
handlers (please see |vcscommand-events|).
The following variables are automatically defined:
b:VCSCommandOriginalBuffer *b:VCSCommandOriginalBuffer*
This variable is set to the buffer number of the source file.
b:VCSCommandCommand *b:VCSCommandCommand*
This variable is set to the name of the vcscommand that created the result
buffer.
b:VCSCommandSourceFile *b:VCSCommandSourceFile*
This variable is set to the name of the original file under source control.
b:VCSCommandVCSType *b:VCSCommandVCSType*
This variable is set to the type of the source control. This variable is also
set on the original file itself.
==============================================================================
5. Configuration and customization *vcscommand-customize*
*vcscommand-config*
The vcscommand plugin can be configured in several ways: by setting
configuration variables (see |vcscommand-options|) or by defining vcscommand
event handlers (see |vcscommand-events|). Additionally, the vcscommand plugin
supports a customized status line (see |vcscommand-statusline| and
|vcscommand-buffer-management|).
5.1 vcscommand configuration variables *vcscommand-options*
Several variables affect the plugin's behavior. These variables are checked
at time of execution, and may be defined at the window, buffer, or global
level and are checked in that order of precedence.
The following variables are available:
|VCSCommandCommitOnWrite|
|VCSCommandCVSDiffOpt|
|VCSCommandCVSExec|
|VCSCommandDeleteOnHide|
|VCSCommandDiffSplit|
|VCSCommandDisableAll|
|VCSCommandDisableMappings|
|VCSCommandDisableExtensionMappings|
|VCSCommandEdit|
|VCSCommandEnableBufferSetup|
|VCSCommandMappings|
|VCSCommandMapPrefix|
|VCSCommandResultBufferNameExtension|
|VCSCommandResultBufferNameFunction|
|VCSCommandSplit|
|VCSCommandSVKExec|
|VCSCommandSVNDiffExt|
|VCSCommandSVNDiffOpt|
|VCSCommandSVNExec|
|VCSCommandVCSTypeOverride|
VCSCommandCommitOnWrite *VCSCommandCommitOnWrite*
This variable, if set to a non-zero value, causes the pending commit
to take place immediately as soon as the log message buffer is written.
If set to zero, only the VCSCommit mapping will cause the pending commit to
occur. If not set, it defaults to 1.
VCSCommandCVSExec *VCSCommandCVSExec*
This variable controls the executable used for all CVS commands If not set,
it defaults to "cvs".
VCSCommandDeleteOnHide *VCSCommandDeleteOnHide*
This variable, if set to a non-zero value, causes the temporary result buffers
to automatically delete themselves when hidden.
VCSCommandCVSDiffOpt *VCSCommandCVSDiffOpt*
This variable, if set, determines the options passed to the diff command of
CVS. If not set, it defaults to 'u'.
VCSCommandDiffSplit *VCSCommandDiffSplit*
This variable overrides the |VCSCommandSplit| variable, but only for buffers
created with |:VCSVimDiff|.
VCSCommandDisableAll *VCSCommandDisableAll*
This variable, if set, prevents the plugin or any extensions from loading at
all. This is useful when a single runtime distribution is used on multiple
systems with varying versions.
VCSCommandDisableMappings *VCSCommandDisableMappings*
This variable, if set to a non-zero value, prevents the default command
mappings from being set. This supercedes
|VCSCommandDisableExtensionMappings|.
VCSCommandDisableExtensionMappings *VCSCommandDisableExtensionMappings*
This variable, if set to a non-zero value, prevents the default command
mappings from being set for commands specific to an individual VCS.
VCSCommandEdit *VCSCommandEdit*
This variable controls whether the original buffer is replaced ('edit') or
split ('split'). If not set, it defaults to 'split'.
VCSCommandEnableBufferSetup *VCSCommandEnableBufferSetup*
This variable, if set to a non-zero value, activates VCS buffer management
mode see (|vcscommand-buffer-management|). This mode means that the
'VCSCommandBufferInfo' variable is filled with version information if the file
is VCS-controlled. This is useful for displaying version information in the
status bar.
VCSCommandMappings *VCSCommandMappings*
This variable, if set, overrides the default mappings used for shortcuts. It
should be a List of 2-element Lists, each containing a shortcut and function
name pair. The value of the '|VCSCommandMapPrefix|' variable will be added to
each shortcut.
VCSCommandMapPrefix *VCSCommandMapPrefix*
This variable, if set, overrides the default mapping prefix ('<Leader>c').
This allows customization of the mapping space used by the vcscommand
shortcuts.
VCSCommandResultBufferNameExtension *VCSCommandResultBufferNameExtension*
This variable, if set to a non-blank value, is appended to the name of the VCS
command output buffers. For example, '.vcs'. Using this option may help
avoid problems caused by autocommands dependent on file extension.
VCSCommandResultBufferNameFunction *VCSCommandResultBufferNameFunction*
This variable, if set, specifies a custom function for naming VCS command
output buffers. This function is expected to return the new buffer name, and
will be passed the following arguments:
command - name of the VCS command being executed (such as 'Log' or
'Diff').
originalBuffer - buffer number of the source file.
vcsType - type of VCS controlling this file (such as 'CVS' or 'SVN').
statusText - extra text associated with the VCS action (such as version
numbers).
VCSCommandSplit *VCSCommandSplit*
This variable controls the orientation of the various window splits that
may occur.
If set to 'horizontal', the resulting windows will be on stacked on top of
one another. If set to 'vertical', the resulting windows will be
side-by-side. If not set, it defaults to 'horizontal' for all but
VCSVimDiff windows. VCSVimDiff windows default to the user's 'diffopt'
setting, if set, otherwise 'vertical'.
VCSCommandSVKExec *VCSCommandSVKExec*
This variable controls the executable used for all SVK commands If not set,
it defaults to "svk".
VCSCommandSVNDiffExt *VCSCommandSVNDiffExt*
This variable, if set, is passed to SVN via the --diff-cmd command to select
an external application for performing the diff.
VCSCommandSVNDiffOpt *VCSCommandSVNDiffOpt*
This variable, if set, determines the options passed with the '-x' parameter
to the SVN diff command. If not set, no options are passed.
VCSCommandSVNExec *VCSCommandSVNExec*
This variable controls the executable used for all SVN commands If not set,
it defaults to "svn".
VCSCommandVCSTypeOverride *VCSCommandVCSTypeOverride*
This variable allows the VCS type detection to be overridden on a path-by-path
basis. The value of this variable is expected to be a List of Lists. Each
item in the high-level List is a List containing two elements. The first
element is a regular expression that will be matched against the full file
name of a given buffer. If it matches, the second element will be used as the
VCS type.
5.2 VCSCommand events *vcscommand-events*
For additional customization, vcscommand can trigger user-defined events.
Event handlers are provided by defining User event autocommands (see
|autocommand|, |User|) in the vcscommand group with patterns matching the
event name.
For instance, the following could be added to the vimrc to provide a 'q'
mapping to quit a vcscommand scratch buffer:
augroup VCSCommand
au User VCSBufferCreated silent! nmap <unique> <buffer> q :bwipeout<cr>
augroup END
The following hooks are available:
VCSBufferCreated This event is fired just after a vcscommand
result buffer is created and populated. It is
executed within the context of the vcscommand
buffer. The vcscommand buffer variables may
be useful for handlers of this event (please
see |vcscommand-buffer-variables|).
VCSBufferSetup This event is fired just after vcscommand buffer
setup occurs, if enabled.
VCSPluginInit This event is fired when the vcscommand plugin
first loads.
VCSPluginFinish This event is fired just after the vcscommand
plugin loads.
VCSVimDiffFinish This event is fired just after the VCSVimDiff
command executes to allow customization of,
for instance, window placement and focus.
Additionally, there is another hook which is used internally to handle loading
the multiple scripts in order. This hook should probably not be used by an
end user without a good idea of how it works. Among other things, any events
associated with this hook are cleared after they are executed (during
vcscommand.vim script initialization).
VCSLoadExtensions This event is fired just before the
VCSPluginFinish. It is used internally to
execute any commands from the VCS
implementation plugins that needs to be
deferred until the primary plugin is
initialized.
5.3 vcscommand buffer naming *vcscommand-naming*
vcscommand result buffers use the following naming convention:
[{VCS type} {VCS command} {Source file name}]
If additional buffers are created that would otherwise conflict, a
distinguishing number is added:
[{VCS type} {VCS command} {Source file name}] (1,2, etc)
5.4 vcscommand status line support *vcscommand-statusline*
It is intended that the user will customize the |'statusline'| option to
include vcscommand result buffer attributes. A sample function that may be
used in the |'statusline'| option is provided by the plugin,
VCSCommandGetStatusLine(). In order to use that function in the status line, do
something like the following:
set statusline=%<%f\ %{VCSCommandGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P
of which %{VCSCommandGetStatusLine()} is the relevant portion.
The sample VCSCommandGetStatusLine() function handles both vcscommand result
buffers and VCS-managed files if vcscommand buffer management is enabled
(please see |vcscommand-buffer-management|).
5.5 vcscommand buffer management *vcscommand-buffer-management*
The vcscommand plugin can operate in buffer management mode, which means that
it attempts to set a buffer variable ('VCSCommandBufferInfo') upon entry into
a buffer. This is rather slow because it means that the VCS will be invoked
at each entry into a buffer (during the |BufEnter| autocommand).
This mode is disabled by default. In order to enable it, set the
|VCSCommandEnableBufferSetup| variable to a true (non-zero) value. Enabling
this mode simply provides the buffer variable mentioned above. The user must
explicitly include information from the variable in the |'statusline'| option
if they are to appear in the status line (but see |vcscommand-statusline| for
a simple way to do that).
The 'VCSCommandBufferInfo' variable is a list which contains, in order, the
revision of the current file, the latest revision of the file in the
repository, and (for CVS) the name of the branch. If those values cannot be
determined, the list is a single element: 'Unknown'.
==============================================================================
6. SSH "integration" *vcscommand-ssh*
The following instructions are intended for use in integrating the
vcscommand.vim plugin with an SSH-based CVS environment.
Familiarity with SSH and CVS are assumed.
These instructions assume that the intent is to have a message box pop up in
order to allow the user to enter a passphrase. If, instead, the user is
comfortable using certificate-based authentication, then only instructions
6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then
work transparently.
6.1 Environment settings *vcscommand-ssh-env*
6.1.1 CVSROOT should be set to something like:
:ext:user@host:/path_to_repository
6.1.2 CVS_RSH should be set to:
ssh
Together, those settings tell CVS to use ssh as the transport when
performing CVS calls.
6.1.3 SSH_ASKPASS should be set to the password-dialog program. In my case,
running gnome, it's set to:
/usr/libexec/openssh/gnome-ssh-askpass
This tells SSH how to get passwords if no input is available.
6.1.4 OPTIONAL. You may need to set SSH_SERVER to the location of the cvs
executable on the remote (server) machine.
6.2 CVS wrapper program *vcscommand-ssh-wrapper*
Now you need to convince SSH to use the password-dialog program. This means
you need to execute SSH (and therefore CVS) without standard input. The
following script is a simple perl wrapper that dissasociates the CVS command
from the current terminal. Specific steps to do this may vary from system to
system; the following example works for me on linux.
#!/usr/bin/perl -w
use strict;
use POSIX qw(setsid);
open STDIN, '/dev/null';
fork and do {wait; exit;};
setsid;
exec('cvs', @ARGV);
6.3 Configuring vcscommand.vim *vcscommand-ssh-config*
At this point, you should be able to use your wrapper script to invoke CVS with
various commands, and get the password dialog. All that's left is to make CVS
use your newly-created wrapper script.
6.3.1 Tell vcscommand.vim what CVS executable to use. The easiest way to do this
is globally, by putting the following in your .vimrc:
let VCSCommandCVSExec=/path/to/cvs/wrapper/script
6.4 Where to go from here *vcscommand-ssh-other*
The script given above works even when non-SSH CVS connections are used,
except possibly when interactively entering the message for CVS commit log
(depending on the editor you use... VIM works fine). Since the vcscommand.vim
plugin handles that message without a terminal, the wrapper script can be used
all the time.
This allows mixed-mode operation, where some work is done with SSH-based CVS
repositories, and others with pserver or local access.
It is possible, though beyond the scope of the plugin, to dynamically set the
CVS executable based on the CVSROOT for the file being edited. The user
events provided (such as VCSBufferCreated and VCSBufferSetup) can be used to
set a buffer-local value (b:VCSCommandCVSExec) to override the CVS executable
on a file-by-file basis. Alternatively, much the same can be done (less
automatically) by the various project-oriented plugins out there.
It is highly recommended for ease-of-use that certificates with no passphrase
or ssh-agent are employed so that the user is not given the password prompt
too often.
==============================================================================
7. Changes from cvscommand *cvscommand-changes*
1. Require Vim 7 in order to leverage several convenient features; also
because I wanted to play with Vim 7.
2. Renamed commands to start with 'VCS' instead of 'CVS'. The exceptions are
the 'CVSEdit' and 'CVSWatch' family of commands, which are specific to CVS.
3. Renamed options, events to start with 'VCSCommand'.
4. Removed option to jump to the parent version of the current line in an
annotated buffer, as opposed to the version on the current line. This made
little sense in the branching scheme used by subversion, where jumping to a
parent branch required finding a different location in the repository. It
didn't work consistently in CVS anyway.
5. Removed option to have nameless scratch buffers.
6. Changed default behavior of scratch buffers to split the window instead of
displaying in the current window. This may still be overridden using the
'VCSCommandEdit' option.
7. Split plugin into multiple plugins.
8. Added 'VCSLock' and 'VCSUnlock' commands. These are implemented for
subversion but not for CVS. These were not kept specific to subversion as they
seemed more general in nature and more likely to be supported by any future VCS
supported by this plugin.
9. Changed name of buffer variables set by commands.
'b:cvsOrigBuffNR' became 'b:VCSCommandOriginalBuffer'
'b:cvscmd' became 'b:VCSCommandCommand'
10. Added new automatic variables to command result buffers.
'b:VCSCommandSourceFile'
'b:VCSCommandVCSType'
==============================================================================
8. Known bugs *vcscommand-bugs*
Please let me know if you run across any.
CVSUnedit may, if a file is changed from the repository, provide prompt text
to determine whether the changes should be thrown away. Currently, that text
shows up in the CVS result buffer as information; there is no way for the user
to actually respond to the prompt and the CVS unedit command does nothing. If
this really bothers anyone, please let me know.
VCSVimDiff, when using the original (real) source buffer as one of the diff
buffers, uses some hacks to try to restore the state of the original buffer
when the scratch buffer containing the other version is destroyed. There may
still be bugs in here, depending on many configuration details.
vim:tw=78:ts=8:ft=help

43
vim/doc/vmp.txt Executable file
View File

@@ -0,0 +1,43 @@
*vmp.txt* Plugin for previewing markdown documents in the browser.
vim-markdown-preview is a customizable plugin for previewing markdown
documents in the browser.
Through custom stylesheets, you can customize the HTML preview of a
document, but defaults stylesheets are provided.
I'm a big GitHub user, so there is a stylesheet that styles a markdown
document like it would appear on the GitHub website.
If you write your own stylesheet, please share it!
See http://github.com/robgleeson/vim-markdown-preview.
== Commands
:Mm
Launches the browser of your choice with a preview of your document.
== Options
All of these options can be customized using the following syntax in your .vimrc :
let g:VMPoutputdirectory = '/home/name/documents'
g:VMPoutputformat
The format to preview your document in.
Defaults to "html". The only supported option at this time.
g:VMPoutputdirectory
The directory where your preview should be stored.
Defaults to "/tmp".
g:VMPhtmlreader
The application or browser to open your preview.
Defaults to "open" on OSX.
Defaults to "start" on MS Windows.
Defaults to "xdg-open" on Unix.
g:VMPstylesheet
The stylesheet to style your preview with.
Stylesheets are searched for in the vim-markdown-preview/stylesheets/ directory.
Defaults to "github.css".
Other options are "safari-reader.css", "simple-print.css".

519
vim/doc/xterm16.txt Normal file
View File

@@ -0,0 +1,519 @@
*xterm16* An adjustable contrast color scheme for GUI & Terminals.
DESCRIPTION *xterm16.vim*
An adjustable contrast fully customizable color scheme for GUI & 8, 16 or
256 color terminals, designed to minimize eyestrain. The main features
are:
- Four color maps:
'allblue' : A colormap with most foreground colors blueish (to
minimize contrast etc.)
'soft' : A colormap with foreground colors of similar
intensities to reduce eyestrain.
'softlight' : A colormap with a bright background (for web
hosting etc.)
'standard' : A colormap for use on terminals with only 8/16
colors.
The first three colormaps will work only on 256 color capable
terminals or the GUI. The last one will work anywhere.
- Adjustable brightness / contrast. Lets you easily adjust the
brightness and contrast settings. Extremely useful (for instance)
when there is a glare on your monitor, or for long late dim light
dim light late at night :)
- Terminal and GUI support. If you use xterm, rxvt or mrxvt (compiled
with 256 colors), then the colors on your terminal will be almost
identical to your GUI colors. On any other terminal emulator, a few
scripts (included) and parts of this help are designed to help you
get the colors you want.
- LCD / CRT Monitor support. The color response of LCD and CRT
monitors is pretty different. This color scheme has an option to
adjust colors on CRT monitors to give a similar appearance.
- Customizable colors. If you find any color unreadable or ugly, you
can change it easily. When adjusting the brightness, your custom
colors will be suitably adjusted too!
- Customizable highlighting groups. If you don't like the highlighting
of any particular group, you can change it to suit your needs. This
is useful for instance if you want the cursor to be brighter than
everything else / etc.
INSTALLATION *xterm16-installation*
For local installation, put the |xterm16.vim| file in your ~/.vim/colors
directory. To install globally put it in $VIMRUNTIME/colors. Finally add
the following lines to your {.vimrc}: >
" Select colormap: 'soft', 'softlight', 'standard' or 'allblue'
let xterm16_colormap = 'allblue'
" Select brightness: 'low', 'med', 'high', 'default' or custom levels.
let xterm16_brightness = 'default'
colo xterm16
< You might also want to put |xterm16.txt| in the help directory (~/.vim/doc
or $VIMRUNTIME/doc).
OPTIONS *xterm16-options*
Colormap, brightness and contrast options: ~
|xterm16_brightness| : Set the brightness / contrast
|xterm16_colormap| : Select the colormap (standard / soft)
|:Brightness| : Adjust the brightness / contrast and or colormap
Customizing colors or highlighting: ~
|xterm16_custom_color| : Customize some (or all) colors.
|xterm16_custom_group| : Customize some (or all) highlighting groups.
|xterm16_CRTColors| : Setup defaults for CRT monitors.
|xterm16_NoHtmlColors| : Disable remapping of html colors.
|xterm16_example| : An example of these options :)
Adjusting colors on terminals: ~
|xterm16_trmcolors| : A short HOWTO to help you get the same colors on
the terminal and GUI.
Options controlling colors on terminals: ~
|xterm16_termtype| : Select the terminal emulator (xterm, rxvt)
|xterm16_ccube| : Specify the color cube of the terminal.
|xterm16_NoRemap| : Disable dark blue remapping on 8 color terminals
|xterm16_TermRegexp| : Regexp of terminals where darkblue is unreadable
PACKAGE CONTENTS *xterm16_filelist*
|changelog.txt| : List of changes
|cpalette.pl| : Perl script to help you set colors in rxvt/xterm etc
|xterm16.ct| : Help change colors on Linux console.
|xterm16.schema| : Help change colors on KDE's terminal (Konsole).
|xterm16.txt| : This help file
|xterm16.vim| : Actual color scheme script
------------------------------------------------------------------------------
ADJUSTING THE BRIGHTNESS OR CONTRAST *xterm16_brightness*
The brightness and contrast are controlled by the global variable
|xterm16_brightness|. This color scheme uses three different color
intensities: {low}, {medium} and {high}. These intensities are used
differently in each of the colormaps. See the |xterm16_colormap| section
for an explanation of how these intensities are used.
The brightness / contrast can be controlled by changing these intensities.
You can do this by setting the global variable |xterm16_brightness|, using
any of the following formats: >
let xterm16_brightness = '#llmmhh'
let xterm16_brightness = 'lmh'
let xterm16_brightness = 'low|default|med|high'
< In the first format, 'll' 'mm' and 'hh' are the intensities (2 digit hex)
of the {low}, {medium} and {high} levels respectively. In the second
format 'l', 'm' and 'h' are numbers from 0 - 5 specifying the respective
intensities. This corresponds to the levels in the 6x6x6 color cube used
by a 256 color terminals. The final format selects either a low, medium or
high brightness respectively. These are different depending on the
colormap you are using. In the 'allblue' colormap they are '123'
(#5f87af), '234' (#87afd7) and '345' (#afd7ff) respectively.
*:Brightness*
You can change the brightness (and optionally the colormap) by using the
command >
:Brightness <brightness> [colormap]
< This is convenient if you want to try out / temporarily change the
brightness or colormap. Once you find a brightness / colormap you like,
set the global variables |xterm16_brightness| and |xterm16_colormap| in
your {.vimrc}.
CHANGING THE COLORMAP *xterm16_colormap*
This color scheme comes with four different color maps: 'standard',
'soft', 'softlight' and 'allblue'. My preference is to use 'allblue' by
default, 'softlight' when there is a glare on my screen, and 'standard'
when I use a terminal with only 8/16 colors (e.g. when I ssh using Putty).
You can select your colormap by setting the global variable
|xterm16_colormap|. The default is to use the 'allblue' colormap if
possible (in GUI or a terminal supporting 256 colors) and the 'standard'
colormap otherwise.
The 'standard' colormap uses 8 standard colors (of {medium} intensity),
and the same colors of {high} intensity. Dark grey is of {low} intensity.
The 'soft' colormap is designed so that all foreground colors appear to be
of similar intensity (to reduce the strain on your eyes). We do this as
follows: The {low} intensity is used for background colors. Some colors
(like green for instance) appear a lot brighter than other colors (like
blue). So we use the {medium} intensity for greenish colors and the {high}
intensity for blueish colors. See |xterm16_brightness| for how to adjust
these intensities to your taste.
The 'softlight' colormap is designed to be readable on a bright
background. It uses {low}, {medium} and {high} intensities in the same way
as the 'soft' colormap. The {low} levels still represent backgrounds, so
you might want to set it to some high number. For example, setting {low}
to 4, {medium} to 1 and {high} to 2 in the 'softlight' colormap produces
reasonable results.
Finally the 'allblue' colormap is designed to that almost all colors are
blueish. I have found this to be least strain on the eyes, while still
being able to tell apart different syntax elements. In this colormap the
{low} is again used for background color levels. The {medium} is the
lowest (non-zero) intensity you want foreground colors, and {high} is the
highest intensity you want foreground colors. For example setting the
{low}, {medium} and {high} levels to 1, 1 and 3 produces reasonable (dark)
results.
NOTE: By default this color scheme is designed for LCD monitors. If you
have a CRT monitor, see |xterm16_CRTColors| for how to adjust the colors
to suit CRT monitors.
NOTE: On terminals WITHOUT 256 colors, you can only use the 'standard'
colormap. The reason for this is because the 'soft', and 'allblue' color
maps have a few unreadable dark colors (used as backgrounds), and possibly
use more than 16 colors in total. If you change your terminal palette to
that of the 'soft' or 'allblue' colormap, then you'll have trouble reading
text in non-Vim applications. If you want to use the 'soft' or 'allblue'
colormaps (as I recommend), either use a terminal supporting 256 colors
(xterm, rxvt, mrxvt), or modify the source :)
------------------------------------------------------------------------------
CUSTOMIZING COLORS *xterm16_custom_color*
Different monitors show colors differently. All colors of this color
scheme are readable on my monitor. However if you have trouble with some
colors, you can change them by setting the variable |xterm16_colorname|.
The color names used are different on each colormap. The 'standard'
colormap uses the colors: >
none black darkred darkgreen darkyellow darkblue darkmagenta darkcyan
grey darkgrey red green yellow blue magenta cyan white
< The 'soft' and 'softlight' colormaps use the colors: >
black darkred darkyellow darkcyan darkblue darkgrey grey lightgrey red
lightbrown yellow green bluegreen skyblue magenta cyan purple white
< The 'allblue' colormap uses the colors: >
black darkred darkcyan darkblue grey1 grey2 grey3 grey4 grey5 grey
white1 red lightbrown yellow dirtygreen green bluegreen yellowgreen
skyblue lightblue lightcyan darkpurple purple lightpurple
< (I know this looks like a lot of colors for a colormap that calls itself
'allblue'. The point is that the colors that usually show up in regular
text / code are all shades of blue (except "Type" and "Special", which are
shades of green). So most code will look pretty much blueish. But error
messages and other vim niceties will be in other colors.)
The format of this variable is one of >
let xterm16_blue = '#rrggbb'
let xterm16_blue = 'nnn'
let xterm16_blue = 'Ldddddd'
< The first format specifies the red / green / blue intensities in two digit
hex. The second format specifies the red / green / blue intensities as a
level between 0-5 number. (This is like specifying the color in a 6x6x6
RGB cube, as used by a 256 color terminals).
Finally the most useful format is the 'Ldddddd'. Here 'L' is the intensity
level (either 'l', 'm' or 'h' for low medium or high respectively). The
first two digits 'dd' are HALF the percentage intensity of the red
intensity. The second two, green and last two blue. So for instance
'm005035' corresponds to a color with no red component, a green component
equal to the 'medium' intensity level, and a blue component that is 70% of
the 'medium' intensity level.
The advantage is that when you change the brightness / contrast, this
color will change accordingly. See |xterm16_example| for an example.
NOTE: If you set the variable |xterm16_CRTColors| then some of your
default colors will be overridden. If you want to use your custom colors,
and the CRT settings, first set |xterm16_CRTColors| and load this color
scheme. The global variables 'xterm16_colorname' will be set for all
modified colors. Now unset |xterm16_CRTColors|, copy these colors into
your vimrc, and modify any other color you like as desired.
CUSTOMIZING HIGHLIGHTING GROUPS *xterm16_custom_group*
If you don't like a few highlighting groups, you can change them by
setting the variables *xterm16fg_GroupName* *xterm16bg_GroupName* and / or
*xterm16attr_GroupName* . These variables control the foreground color,
background color and GUI/cterm attributes of {GroupName} respectively.
{GroupName} is the name of the group whose highlighting you want to
change. For a list of group names see |highlight-groups| and |group-name|.
The format of these variables is the same as the format for colors. In
addition you can also use a named color from the colormap. See
|xterm16_custom_color| above. As an example: >
let xterm16bg_Cursor = '#00ff00' " Make cursor bright green
CRT MONITORS *xterm16_CRTColors*
By default the colors in this color scheme are designed for LCD monitors.
If you have a CRT monitor, set the vim variable |xterm16_CRTColors| in
your .vimrc. This will adjust the colors to suit CRT monitors. With an
unspecified brightness and 'standard' colormap, this will produce exactly
the same colors as the original version of xterm16. If the colors still
look unreadable and you want to change them, read the section on
|xterm16_custom_color|.
NOTE: Setting this variable will override some (maybe all) of your
customized colors. See the note at the end of |xterm16_custom_color|.
NOTE: Setting this variable will have no effect under the 'allblue'
colormap. This colormap does not look too different under CRT monitors.
Also modifications will probably render a few shades of blue used by this
colormap indistinguishable.
HTML HIGHLIGHTING GROUPS *xterm16_NoHtmlColors*
Html groups use cterm attributes (which SUCK), so we change them here. The
GUI attributes are OK, and are unchanged. If you do not want your precious
html groups touched, set the variable |xterm16_NoHtmlColors| in your
{.vimrc}
If html colors don't work correctly, set the variable |html_no_rendering|
*xterm16_example*
As an example, the following will produce exactly the same colors as the
original version of xterm16: >
let g:xterm16_colormap = 'standard'
let g:xterm16_brightness = '#80cdff'
let g:xterm16_darkblue = 'h000050'
let g:xterm16_blue = 'h002550'
let g:xterm16_grey = 'm474747'
< NOTE: This is done by default if you set the variable |xterm16_CRTColors|,
and use a terminal with less than 256 colors (or use the 'standard'
colormap).
------------------------------------------------------------------------------
ADJUSTING COLORS ON TERMINALS *xterm16_trmcolors*
Depending on which terminal emulator you use, you might have to tweak the
settings a little to get good results on your terminal emulator. On 256
color capable terminals, you might have to make vim aware that your
terminal has 256 colors. On terminals that are only capable of using 16
colors, you will have to adjust the palette.
If you use recent versions of xterm, rxvt or mrxvt, or your terminal
emulator claims to support 256 colors, then read the help topic
|xterm16-256cterm|. If not, read the help topic |xterm16-16cterm|.
*xterm16-256cterm*
Terminals which support 256 colors: ~
Some terminal emulators like xterm, rxvt and mrxvt support 256 colors if
compiled in. A simple way to check if 256 colors are supported in your
terminal is to type the following the bash prompt: >
$ echo -e "\e[38;5;196mred\e[38;5;46mgreen\e[38;5;21mblue\e[0m"
< If you see the words red, green and blue in the correct colors, then
you've got 256 colors. If not, I recommend compiling 256 color support in
(use --enable-256-colors at compile time for xterm / mrxvt). If this is
not possible, try looking under |xterm16-16cterm|.
Once you know your terminal is 256 color capable, check to see if Vim is
aware of this. Start up vim in your terminal emulator and type >
:echo &t_Co
< If vim reports "256", then you need not make any modifications. If vim
reports 8 or 16, then add the following code snippet to your {.vimrc}: >
au VimEnter *
\ if &term == 'xterm' |
\ set t_Co=256 |
\ endif
< Replace 'xterm' above with the value of $TERM.
NOTE: You can also fix this by modifying the terminfo files on your
system. See the man pages of terminfo, infocmp and tic.
NOTE: rxvt users will need to set the variable |xterm16_termtype| and or
|xterm16_ccube| to get colors which are identical to those on the GUI.
NOTE: If in addition you want to adjust the default colors of your
terminal (for consistency with other applications) read the section on
|xterm16-modcolors|.
*xterm16-transparent*
Finally, if you use a terminal that supports pseudo transparency (like
mrxvt), and want your vim to appear transparent use: >
if $DISPLAY != '' && !has('gui_running') && $MRXVT_TABTITLE != ''
let xterm16bg_Normal = 'none'
endif
< This might not work on 16 color terms, but you're welcome to try :). This
definitely works on mrxvt versions 0.4.1 or later.
*xterm16-16cterm*
Terminals with only 8 or 16 color support: ~
If your terminal emulator does not support 256 colors, you will have to
manually modify the terminal palette to obtain the colors in this color
scheme. NOTE: You can only use the 'standard' colormap in such terminals.
See the section on |xterm16_colormap| for details.
First I suggest attempting to at least get 16 colors (and not settle for
only 8 colors). This looks a little nicer than using bold fonts. Read the
section on in the vim help under |xfree-xterm|, and hope that works.
*xterm16-modcolors*
Now to modify your terminal colors, the first thing you need to do is to
figure out the colors this color scheme is using. To do this, load this
color scheme in gvim, and adjust the brightness / contrast to your taste.
Don't forget to use the 'standard' colormap. Now the global variable
|xterm16_palette| contains all the colors that are currently being used.
If you use xterm, or some fork of rxvt (like mrxvt, aterm, wterm etc),
follow the instructions in |xterm16-xdefaults|. For konsole or
gnome-terminal see |xterm16-konsole| and |xterm16-gnome-terminal|
respectively. Finally for the Linux console, see |xterm16-ctheme|.
*xterm16-xdefaults*
For xterm or some fork of rxvt, do the following: Once the colors are
adjusted to your taste, edit the file ~/.Xdefaults or ~/.Xresources (or
~/.mrxvtrc for mrxvt). Paste in the contents of the vim variable
|xterm16_palette| (use <C-R>=xterm16_palette for instance). Now filter
those lines through the supplied perl script *cpalette.pl* by typing >
:'<,'>!perl -w /path/to/cpalette.pl -x --class trmname
< where trmname is the resource class of your terminal. Generally this is
the same as the terminal name. For xterm use "xterm.vt100" as the class,
and for mrxvt use "Mrxvt" as the class. (|cpalette.pl| can do a few other
things. Type "cpalette.pl -h" for options).
If your terminal gets it's resources via the X window system [using
XGetDefaults()], then you have to merge the above file with your current
resource using >
$ xrdb -merge ~/.Xresources
< If your terminal directly reads the resource file, then just restart the
terminal and you should be fine :). See the terminal version / man file to
figure out if you need to merge your resources or not.
*xterm16-konsole*
For konsole, the file *xterm16.schema* contains the colors of this color
scheme with 'standard' colormap, default brightness and CRTColors. If you
use a different colormap / brightness, get the palette from the variable
|xterm16_palette|, and modify the file appropriately. You'll need to
convert the palette from to decimal. The following few lines might help: >
" Brightness 134 (high), colormap standard
let palette = '#000000 #af0000 #00af00 #afaf00 #0000af #af00af #00afaf #9a9a9a #5f5f5f #d70000 #00d700 #d7d700 #0000d7 #d700d7 #00d7d7 #d7d7d7'
let i = 0
while i < 16
echo 'Color' i '0x'.strpart(palette,i*8+1,2)+0 ' '
\ '0x'.strpart(palette,i*8+3,2)+0 ' '
\ '0x'.strpart(palette,i*8+5,2)+0
let i = i + 1
endwhile
< To change the default colors on Konsole, add the file |xterm16.schema| to
~/.kde/share/apps/konsole. Select the "Xterm 16 Colors" schema from the
schema menu.
*xterm16-gnome-terminal*
For gnome-terminal you can change the colors by running gconf-editor and
selecting the apps - gnome-terminal - profiles - Default menu, and change
the palette option to the string (all in one line!) >
#000000:#af0000:#00af00:#afaf00:#0000af:#af00af:#00afaf:#9a9a9a:#5f5f5f:#d70000:#00d700:#d7d700:#0000d7:#d700d7:#00d7d7:#d7d7d7
< If you changed the brightness / colormap, you might want to replace the
above line with your current colormap (obtained from the variable
|xterm16_palette|).
*xterm16-ctheme*
ctheme can be used to change the colors on your Linux console (neat huh?).
Find more information about it at >
http://www.sourceforge.net/projects/ctheme/
< The file *xterm16.ct* contains the colors of this color scheme with
'standard' colormap, default brightness and CRTColors. If you use a
different colormap / brightness, get the palette from the variable
|xterm16_palette|, and modify the file appropriately.
If necessary, change the first line of |xterm16.ct| to point to the
correct location of ctheme, then run it with your ctheme. Thanks to
Juhapekka Tolvanen <juhtolv@iki.fi> (http://iki.fi/juhtolv) for providing
this theme, and informing me of the existence of ctheme!
------------------------------------------------------------------------------
COLOR SCHEME PALETTE *xterm16_palette*
The global variable |xterm16_palette| contains the 16 color palette
currently used by the color scheme. This is mainly so that you can easily
obtain the palette, and use it to change the colors on your favourite
terminal emulator.
CHANGING THE TERMINAL COLOR CUBE *xterm16_termtype* *xterm16_ccube*
The terminals that support 256 colors all have a 6x6x6 RGB color cube
between the colors 16 to 231. Unfortunately, not all of them have the same
color cube. Rxvt uses a uniform RGB color cube, but xterm and mrxvt do
not.
This color scheme tries to guess which terminal you're using, and use the
appropriate color cube. The guessing is done as follows:
1. If the environment variable MRXVT_TABTITLE is defined, then we
assume you're using mrxvt.
2. Otherwise, if your TERM variable is set to something beginning with
"rxvt", then we assume you're using rxvt.
3. Otherwise we assume you're using xterm.
If the above will lead to an incorrect guess, set the vim variable
|xterm16_termtype| to the terminal emulator you're using (currently only
'rxvt' and 'xterm' are supported).
If you use a different terminal with 256 colors, then you can get the
colors right by setting the variable |xterm16_ccube|. The value of
|xterm16_ccube| should be a 12 digit hex number (without the leading 0x).
The first two digits are the intensity of the term level 0 (generally this
is 00). The next two are the intensity of the term level 1, etc. The last
two correspond to the level 5. (Remember the terminal colors are a 6x6x6
RGB cube).
You will probably have to read the source of your terminal emulator to
figure out the intensities of the colors in the 6x6x6 color cube. However,
if your terminal supports setting colors 16 - 231 using .Xdefaults or
something, then you can use the supplied perl script |cpalette.pl| to
generate a color cube of your choice. For example: >
perl -w cpalette.pl --class xterm --ccube 002a557faad4 -g >> ~/.Xdefaults
< will make the xterm color cube the same as the rxvt color cube.
UNREADABLE CONSOLE COLORS *xterm16_NoRemap* *xterm16_TermRegexp*
On a Linux console (and some other 8 color terminals), the dark blue
(PreProc) is unreadable so we remap it. To disable this feature, set the
variable |xterm16_NoRemap| in your {.vimrc}
If this color gives you trouble on other terminals, and you want it
changed elsewhere too set the variable |xterm16_TermRegexp| to a regexp
matching all troublesome terminals.
NOTE: This is only true in the 'standard' colormap. The 'soft' colormap
does not use dark blue as a foreground, and hence no remapping is done.
------------------------------------------------------------------------------
>
Maintainer : Gautam Iyer <gautamATmathDOTuchicagoDOTedu>
Modified : Thu 18 May 2006 04:28:25 PM CDT
vim: ft=help:tw=78:iskeyword=!-~,^*,^|,^":ai: