pluginkiller.txt Plugin Killer Oct 16, 2012
Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2006-2012 by Charles E. Campbell pluginkiller-copyright
The VIM LICENSE applies to pluginkiller.vim
(see copyright) except use "pluginkiller instead of "Vim"
No warranty, express or implied. Use At-Your-Own-Risk.
==============================================================================
1. Contents pluginkiller pluginkiller-contents
>
<
1. Contents................................: pluginkiller-contents
2. Pluginkiller Manual.....................: pluginkiller-manual
3. Pluginkiller Usage......................: pluginkiller-usage
Discussion..............................: pluginkiller-discussion
Detailed Steps on using the Pluginkiller: pluginkiller-steps
4. Installing the PluginKiller.............: pluginkiller-install
5. History.................................: pluginkiller-history
==============================================================================
2. Pluginkiller Manual pluginkiller-manual
:PK pluginkiller-PK
:PK This command loads the pluginkiller's settings into the
window under test -- ie. initializes your plugin with the
pluginkiller's "nasty" vim option settings. It will also
start up the PLUGINKILLER server as required.
:PKnfm pluginkiller-PKnfm
:PKnfm This command is like :PK except that no function maps are
produced
(ie. no ctrl-f1 or ctrl-f2 maps, see pluginkiller-funcmap)
:PKr pluginkiller-PKr
:PKr Resets the pluginkiller so that all of its problematic
settings are enabled.
PKg pluginkiller-PKg
:PKg Used in the pluginkiller.vim window; you use this command
to indicate to the pluginkiller that the current settings
yielded good/expected/nominal behavior.
:PKb pluginkiller-PKb
:PKb Used in the pluginkiller.vim window; you use this command
to indicate to the pluginkiller that the current settings
yielded bad behavior.
:PKB pluginkiller-PKB
:PKB The pluginkiller backs up to the previous set of options.
PKR pluginkiller-PKR
:PKR [regname]
:PKR!
Provide a register (a-z, A-Z) to use after each binary
search. See @ and q; one may record a series of
keystrokes into a register using q and then every
:PKg, :PKb, and :PKB will cause the instructions in
that register to be executed.
pluginkiller-fm pluginkiller-funcmap
<c-f1> same as :PKg (makes normal mode and insert mode maps)
<c-f2> same as :PKb (makes normal mode and insert mode maps)
<c-f3> same as :PKB (makes normal mode and insert mode maps)
Also see g:pluginkiller_nofuncmap
g:pluginkiller_nofuncmap
g:pluginkiller_nofuncmap If this variable exists, then no
function maps will be made (ie. no ctrl-f1 or ctrl-f2 maps)
==============================================================================
3. Pluginkiller Usage pluginkiller-usage
pluginkiller-discussion
DISCUSSION
The PluginKiller helps Vim plugin writers determine which options that
their users might set that will cause problems with their plugin before
their users do!
To do this, the PluginKiller utilizes two instantiations of vim. The
first vim is your working vim; in it you normally startup and exercise
your plugin. The second one (see Step 1 below) is the pluginkiller
server; it keeps a copy of the current potential trouble-making
options.
Whenever your plugin works satisfactorily with the currently active
trouble-makers shown in the PluginKiller gvim, type :PKg (for
PluginKiller-good) (or <ctrl-f1> if function maps are available, see
pluginkiller-PKnfm). This tells the PluginKiller server about the
nice set of options it selected, and it responds with a new set.
On the other hand, whenever your plugin isn't performing up to your
exacting specifications, type :PKb (for PluginKiller-bad) (or
<ctrl-f2> if function maps are available). This command tells the
PluginKiller server about the trouble it caused, and the PluginKiller
responds with a smaller set of potential troublemakers.
Note that you may have to type ctrl-o :PKg and/or ctrl-o :PKb
because of one of the troublemaking options.
You'll need to repeat trying out your plugin and typing :PKg or :PKb
until the PluginKiller has found the culprit option. Its OK to quit
the first vim where you're exercising your plugin; if you do, use :PK
to resume working with the PluginKiller server -- whether you need to
quit and resume depends on how your plugin operates -- :PK just
reloads the current settings that the PluginKiller wants to have tried
out.
pluginkiller-steps
DETAILED STEPS ON USING THE PLUGINKILLER
Step 1: Bring up vim with a test file where you can exercise your
plugin with the pluginkiller. Type >
< The :PK command sets up the pluginkiller server window; it will
show >
< at the top of the screen in the server, followed by a number
of options that often cause problems with plugins.
Step 2: In the vim holding the test file (NOT the pluginkiller server):
UNTIL a message pops up about what option your plugin
is having a problem with:
Exercise/run your plugin
IF your plugin worked, type >
< Otherwise, type >
<
NOTE: you may have to type >
< -or- >
< to get commands to work if/when you seem to be stuck in insert
mode.
The :PKg (for good plugin behavior) and the :PKb (for bad
plugin behavior) commands implement a binary search technique
to determine which option is giving your plugin trouble. If,
as may sadly be the case, more than one such option is giving
your plugin fits, you may have to run through this process
several times.
What I usually do is create two functions that look something
like this: >
<
At the top of any function in my plugin that's being called, I
call the s:SaveUserSettings() function. This function saves
the user's current settings that caused my plugin difficulties
and then sets them to something that doesn't. Before any
return and the end of the function I call
s:RestoreUserFunctions(), which, of course, restores the
user's settings.
The l:optionname is the local version of the option, and the
setlocal means I only change the local option to support my
plugin.
==============================================================================
4. Installing the PluginKiller pluginkiller-install
First, you really _don't_ want to install the pluginkiller in your
normal .vim/plugin directory.
1. You will need vimball v18 or later; you can get it from
http://www.drchip.org/astronaut/vim/index.html#VimFuncs
as "Vimball Archiver", or from
http://vim.sourceforge.net/scripts/script.php?script_id=1502
Be sure to remove all vestiges of any earlier vimball versions
such as comes with vim 7.0: typically, that means, as superuser: >
<
2. vim pluginkiller.vba.gz
:so %
:q
This will create >
<
The directions under pluginkiller-steps give detailed information on
how to use the pluginkiller.
2. Enable the help: >
<
==============================================================================
5. PluginKiller History pluginkiller-history
v4 Apr 15, 2010 * Complete re-write, and new :PKB command
Now uses lists. The remote PLUGINKILLER
window now holds only the settings under
test, and is separate from the pluginkiller.vim
plugin itself.
* added "set bomb" to the pluginkiller settings
list (can adversely affect filtering)
Feb 22, 2011 * for menus, &go =~# used to insure correct case
v3 Oct 10, 2007 * added more options for pluginkiller checkout:
acd, insertmode, num, spell
v2 May 01, 2006 * the acd option is not always defined
Oct 19, 2006 * :PK will initialize the PLUGINKILLER
server automatically, as required.
v1 Mar 08, 2006 * initial release
vim: ts=8