Using Vim: Syntax Highlighting

In This Section

No programmer's text editor--in fact, no text editor--is truly complete without syntax highlighting, the coloring of special keywords and phrases within a program. Syntax highlighting emphasizes the structure of a document, helps catch typographical errors, aids in debugging purposes, and overall can make text editing easier and more productive. In this section we'll talk about the Vim syntax highlighting paradigm and how to set up and customize the coloring schemes.

The Vim Coloring Scheme

No, this section is not about which colors match best; it's about how Vim approaches the problem of syntax highlighting.

To decide how to color a file, Vim first breaks down the file into many structural groups. These are done through programmed syntax command files which are automatically sourced by Vim when you load a file, based on a complex series of rules. If Vim chooses an incorrect syntax command file, you can specify the correct one by entering the command:

:set syn=syntax-type
where syntax-type is the type of file. Generally these file types are named after the file extension for that file type, so, for example, to get PHP syntax highlighting, set it to "php".

There are nine primary highlighting groups which Vim uses:

Group NameDescription
Comment Comments within a program
Constant Program constants, such as numbers, quoted strings, or true/false
Identifier Variable identifier names
Statement A programming language statement, usually a keyword like "if" or "while"
PreProc A preprocessor, such as "#include" in C
Type A variable datatype, such as "int"
Special A special symbol, usually used for special characters like "\n" in strings
Underlined Text that should be underlined
Error Text which contains a programming language error

Additionally, there is a group named Normal which refers to normal text.

As you may have noticed, these highlighting groups are primarily for programming languages; this is because syntax highlighting is most useful for them. However, Vim has command files for highlighting much more than programming languages, including everything from HTML to e-mail messages!

Vim also deals with three kinds of output devices: the black-and-white terminal, the color terminal, and the GUI, or graphical user interface. Because each of these have different highlighting capabilities, Vim maintains three separate highlighting schemas, one for each type.

Setting Up Highlighting

The simplest way to get highlighting working is to get someone else's .vimrc file, like the one I have for download here. Most of the time this will work just fine. However, if it doesn't or if you would like to start from scratch, here's how.

The first line which you must put into your .vimrc file is:

syntax on
This will instruct Vim to start using syntax highlighting. If you don't want to change the file just yet, you can always just enter it as an Ex command in a Vim window.

If you're using a black-and-white terminal or the GUI interface, everything should be working just about right. If you're using a terminal which supports color, you may have to put the following line before the syntax on line:

set term=ansi
You could also try color_xterm rather than ansi.

Choosing Colors

By default Vim uses a set of colors which, in my opinion, are overly bright and confusing (comments are colored the same as variable names!); in any case, everyone has their own opinions on color, so you will probably want to know how to change them to your own tastes.

Colors are specified using the :highlight, or :hi, command. The :hi command is actually a multipurpose command that handles many highlighting routines; we will limit our use of it to color selection. It has the following syntax:

:hi Group key=value ...
Group is one of the group names listed in the table above.

The key-value pairs specify the highlighting for the various output devices Vim handles. There are three "base-names" for the keys (all of which are keys themselves): term, cterm, and gui, representing the black-and-white terminal, the color terminal, and the graphical interface. For each of these base names except for term, there exists two more keys, base-namefg and base-namebg, representing the foreground and background colors for that output device. The base-names themselves are keys for representing non-color attributes for highlighting, such as bold and underline.

Here is a list of the highlighting keys and the possible values they may take on.

KeyPossible Values
term bold, underline, reverse, italic, none
ctermfg red, yellow, green, blue, magenta, cyan, white, black, gray
guifg All of the above colors, plus many more; you may also use the #rrggbb format

So, for example, say I wanted to highlight all of my preprocessor statements bright magenta. Then I could say:

:hi PreProc ctermfg=magenta cterm=bold guifg=#FF00FF
Notice that I can put multiple key/value pairs on the same line; they will all apply to the same highlighting group.

Generally, once you come up with a scheme that you like, you can set it up in your .vimrc file, and it will load automatically.

Troubleshooting Syntax Highlighting

Occasionally there will be minor problems with syntax highlighting. I come across three of them the most often.

Colors are not showing up, only black-and-white terminal highlighting. This is most often caused because Vim cannot determine that the terminal has color capabilities. To fix it, first make sure that there is a line reading set term=ansi at the top of the .vimrc file, before the syntax on line. Also, try setting the TERM environment variable in the shell to "color_xterm" or "color-xterm".

Colors are showing up, but they're not mine. This tends to happen when you take someone else's .vimrc file and try to change the colors. Chances are, moving all of your color definition statements to the end of the file will fix it. If not, check for strange lines of code in the .vimrc file and comment them out (put a double-quote at the start of the line).

The colors get messed up when I scroll. Vim uses various heuristics to save time when determining the highlighting, and sometimes they cause problems. Look up :h syn-sync for a more detailed explanation. To fix this, you can try putting the line:

syn sync minlines=1000
or some other very large number, into the .vimrc file. In Vim 6.0 and up, you can use:
syn sync fromstart
to force the highlighting engine to start parsing from the top of the file; this is slow for large files, but it's always accurate.

At this point, if you feel comfortable using Vim and you've played around with its settings and found something you like, congratulations, you're a real Vim user! Of course, there's much more to this editor than I can provide in this tutorial--they wrote an entire book on the program--but hopefully you now have a basis for exploring further and learning more. Enjoy learning it; it's a skill that you won't regret having learned.