Electrical and Computer Engineering, Carnegie Mellon University

TAB Completion for LaTeX References in Vim

As a grad student, I do all of my academic paper writing in LaTeX.

Using LaTeX rather than Microsoft Office or its open-source cousin LibreOffice allows me to write papers much more quickly using Vim, my text editor of choice. Like any good text editor, Vim is endlessly customizable with plugins, making editing almost any sort of text a breeze. Supertab is one of my favorite plugins, saving me keystrokes and helping me avoid errors through TAB completion.

However, one problem I frequently encountered while writing my most recent paper was in using Supertab to complete reference keys. Like many others, I use the common convention of using reference keys that have the reference type in the key itself (such as naming section labels in the form sec:foo and figures in the form fig:bar). In this case, though,  using TAB completion alone will open up a large list of options, almost all of which are from the dictionary word completion list.

It took me a while to figure out how to solve this problem, but the actual fix was quite simple. In fact, I stumbled onto it on a short help page for Vim-Latex (which I highly recommend for anyone who edits LaTeX in Vim). The help page is here, but it lacks a bit of explanation as to what’s actually happening under the hood.

The Vim command that does the trick is

set iskeyword+=:

This tells Vim that when using generic completion (which is what Supertab is actually doing when you hit TAB), it should consider the colon character as part of the keyword. This isn’t enabled by default, since the completion engine generally shouldn’t put colons when suggesting completions. As a somewhat contrived example, if you had already written

We need the following ingredients for our smoothie: oranges juice, berries, and
tartar sauce.

then if you later tried to TAB complete smooth, you would get smoothie: as a suggested completion. (You would almost certainly get this as the main suggestion if your auto-completion engine suggests the longest match, which most do.) However, when you type fig: and press TAB, you want to have your completion options show the various figure labels you’ve included in your document so far. By adding the colon character to the set of characters the completion engine should include in searching for completions, you can get the desired effect, making inserting references in LaTeX a breeze.

I further suggest adding the hyphen to the iskeyword variable. Personally, I often label my figures with keys such as “fig:design-diagram,” and thus I add the hyphen to allow completion for key names like this one. You can do this by changing the command to

set iskeyword+=:,-

A final note: the help page I referred to above suggests placing the line in ~/.vim/ftplugin/tex.vim, which only enables the option when editing .tex files. Unless you want colons and hyphen to be included in auto-completion for every file you edit, you should not put this in your .vimrc file. However, if you use Vundle (a plugin manager for Vim and perhaps the most useful plugin in my setup), your ftplugin/ directory will not be automatically loaded with Vim unless you configure it that way. For a cleaner setup, I recommend putting the following line in your .vimrc:

autocmd BufRead,BufNewFile *.tex set iskeyword+=:,-

This causes colon and hyphen to be added to the iskeyword variable only when editing .tex files, and does so in a way that plays very nicely with Vundle.

Tag Cloud