September 12, 2006
Although Vim’s help files have answers to all the questions, you need to know how to ask the questions, which is sometimes the problem.
A few years ago I spent a week looking for the little window that you can type ex commands in. I knew it existed because I had started it once by accident. Turns out I have to type “:help cmdline-window”. I tried all the obvious combinations of “command” and “window” and “ex” and so on. I ended up just going through the tags file of the help system and grepping for “window”. (I didn’t know at the time that you can type “:help window<Ctrl-D>” to get a list of all help topics that include the word “window”. That still depends on the word being in the topic, though.)
I’ve been using Vim for 13 years, so I’m not a newbie, but it’s still hard for me to find a particular option or feature just by its description. (Another one I had trouble with is the margin at the top and bottom of the window to stop the cursor from going too close to the edge. It’s 'scrolloff'. You want to tell me how to find that without knowing the word scrolloff?)
What I found very useful when I was first learning Unix was a “permuted index”, which basically means that you take each feature, describe it in a sentence using as many keywords as possible, and put it in the index under each word of the sentence. The formatting aligns the indexed word in the middle. This is easiest to explain with an example:
'tabline' custom format for the console tab pages line 'showtabline' tells when the tab pages line is displayed |:retab| change tab size |:tab| create new tab when opening new window 'smarttab' use 'shiftwidth' when inserting <Tab> 'list' show <Tab> and <EOL>
Notice that the word “tab” is vertically aligned so that your eye can scan down the list easily. Once you get to the word you’re interested in, you can quickly read each description to find the entry you want. If you wanted to show tabs, for example, it would be easy to find the 'list' option using the above index.
I wrote a Python program to generate a permuted index from Vim 7.0 help files. You can also just download the permuted index directly. Put it into your ~/.vim/doc/ directory, then from Vim run:
:helptags ~/.vim/doc
You can then see the index by typing:
:help permuted-index