Sunday, March 3, 2013

VIM Plugins

I use MacVIM with Austin Taylor's VIM configuration tilde, and recently replaced it with Yehuda Katz and Carl Lerche's Janus VIM configuration on my MacBook. Both add plenty of bells and whistles plugins: keyboard mappings, commands, syntax highlighting, etc. The two motivating factors is that (a) Janus is documented whereas tilde is not and (b) tilde does a few things that mismatch my preferred defaults, such as setting very magic regex mode and altering the meaning of keys that normally do navigation.

The big brick wall that I hit with any of these configurations is that unless you are a vim plugin writer,  the morass of code is an incomprehensibly ugly mess. Note: I can read the code, but VIM script is usually so ugly that the skin on my eyeballs starts peeling from gazing upon it.

The size of these VIM config bundles exacerbates the obfuscation. There are simple means of showing the key mappings in vim. (Incidentally, this wikia is a good read for learning about key mappings in vim.) Type map (or imap/nmap/vmap for insert mode/command mode/visual mode mappings):

:map

...and you'll get a list of the key mappings. Now, with proper grouping a few dozen mappings can be readily accessible to the working memory. It is not unusual for vim configs to have upward of hundreds of key mappings. When you type :map all those mappings get dumped to a pager in the window, without any meaningful grouping. Not so nice for reading. This bloat is perhaps the best reason of all not to simply reuse someone else's VIM config bundle.

Try verbose:

:verbose map

This shows the file responsible for last setting a given mapping. This is nice for debugging why your expected mappings fail miserably and for identifying which mappings belong to a particular plugin (frequently undocumented).

Another problem with VIM mappings is that they are very often convoluted but only very rarely commented. Carlhuda's VIM bundle is an exception. Is a user really expected to read a mapping like this in a listing meant as a quick reference?

ai * :<C-u>cal <Sid>HandleTextObjectMapping(0, 0, 0, [line("."), line("."), col("."), col(".")])<CR>
What is the intention of the mapping? Idunno. Something about text indentation? Idunno. Should I even care? Idunno. The source file for this mapping had a few sparse comments. None of them were especially meaningful, but then again comments in vim mappings don't help the :map output. Ideally, the map command would allow a descriptive label to be attached, but that's not the way it works.