Nerdcore 4 Life

As much as I love Vim, it has some issues that I’ve pointed out before. Chief among them are the little ways that it proves to be inconsistent. The other day I found another one. Highlighting.
Vim has a very robust system for highlighting and coloring various categories of text, that’s one of the things that makes it a great editor. But finding out how to do it yourself was monstrously difficult for a couple of reasons:

• There are examples, but they are kept in 2 different files. The color scheme file(usually under $VIMRUNTIME/colors) holds some of the info and the syntax(automatically loaded from a syntax file in $VIMRUNTIME/syntax) holds the rest. And you’ll be looking for examples because
• The :help files are confusing. The same command is used 2 different ways to set up a highlighting scheme, so unless you read the entirety of the help files before you start then the example commands you are looking at are nothing like the description of those commands in :help. And the help files are huge. This is because there is so much you can do with syntax in Vim, but it makes it impossible to get started with a little tweak you want to make.

So with that in mind here is my goal. I want to present a quick, simple tutorial on how to alter the coloring and highlighting in Vim short of making your own syntax files. If you want to get that deep into you you’ll just have to wade through the whole country mile of :help pages.

First the theory. There are 2 commands you need to be concerned with, :hi and :syn. :syn is the syntax command. It has three ways to define a syntax group, and we’ll take a look at each in turn.

:hi is the highlight command. It allows you to set the coloring(foreground and background) of a syntax group. It’s simple really, but nothing in the :help explains this info :/

So why don’t we start our tutorial with a scenario:
Let’s say we have a weird text file that configures an obscure application. We only need to look at it every 6 months or so but it would be helpful if it was easier to read. It looks something like this:

  %% These files hold database information %%
  llv require("File1")
  llv require("File2")
  llv require("File3")
  %% This file holds user names %%
  llv require("File4")
  %% Output is written %%
  ${DUMP}("File5")

I’d advise you copy/paste this into Vim while you follow along

Basic Matching

It would be much easier to read if we could do a little coloring. Lets start with comments. You first need to set up a syntax group for comments using the syntax command. The simplest way of doing this is with something like this

  :syn match myComment "^%%.*%%$"

So we’re using the match type of syntax command. That will match a regular expression. Then we create a syntax group called myComment and we list, inside quotes, the regular expression we want to use to define myComment. In plain English it says to match if the line starts with 2 percent symbols, then has anything, then ends with 2 percent symbols.

And if you type all that in you get..nothing.
That’s because you haven’t told Vim to highlight that syntax group yet. If you type in

  :hi myComment term=bold ctermfg=DarkCyan guifg=#80a0ff

Then(assuming you’re on gVim) it should look like this

  %% These files hold database information %%
  llv require(”File1″)
  llv require(”File2″)
  llv require(”File3″)
  %% This file holds user names %%
  llv require(”File4″)
  %% Output is written %%
  ${DUMP}(”File5″)

This highlight command is pretty simple to break down. The first argument is the syntax group you want it applied to, in this case the myComment group we just created. The following arguments are for each of the Vim environments

guifg=#80a0ff

Says that if this is being displayed in gVim, set the foreground color of this group to the hex value 80a0ff(Dark Cyan).

  ctermfg=DarkCyan

Says that if this is being displayed by Vim running inside a color terminal, set the foreground color of this group to the named color DarkCyan.

  term=bold

And if this is Vim running inside a black and white terminal, set this syntax group to bold.

Region

Using the match argument with :syn is very powerful because of the flexibility with regular expressions. But sometimes we don’t want to add that much complexity but we still want to be able to identify whatever is between 2 markers. For that we can use :syn region.
We probably want to clearly identify the strings inside this file for easy reading, so we want to create a syntax group that concerns the region between quotes. We can use

:syn region myString start=+"+ end=+"+
:hi myString term=underline ctermfg=LightRed guifg=LightRed

And it should look like this

  %% These files hold database information %%
  llv require(“File1″)
  llv require(“File2″)
  llv require(“File3″)
  %% This file holds user names %%
  llv require(“File4″)
  %% Output is written %%
  ${DUMP}(“File5″)

So a region is similar to a match except we’re defining a start and end pattern each delimited by plus signs. Anything in between(and including) will be part of this syntax group. By the way you don’t have to use plus signs, you can use any single character at the begging and end, but you should avoid characters that are within the pattern(in this case double quotes). You could have also typed

:syn region myString start=|"| end=|"|

Keywords

There’s one other common syntax situation, the keyword. Luckily, :syn has the keyword option just for this(and it works pretty much as you’d expect).

  :syn keyword myKeywords llv
  :hi myKeywords ctermfg=Blue guifg=Blue

And your text should look like this

  %% These files hold database information %%
  llv require(“File1″)
  llv require(“File2″)
  llv require(“File3″)
  %% This file holds user names %%
  llv require(“File4″)
  %% Output is written %%
  ${DUMP}(“File5″)

The list of keywords being space separated.

Linking

Now there’s one more thing, let’s assume that ${DUMP} is a macro of some kind. Now let’s also assume that we always want it to look the same as myKeywords. Defining the syntax group is easy

  :syn region myMacro start=+${+ end=+}+

And we could highlight it with the following

  :hi myMacro ctermfg=Blue guifg=Blue

But what if we were on a computer where that color didn’t look good? Or if some other syntax group made that one hard to pick out? We would have to change myKeywords and myMacro separately. And if we have tens of syntax groups that we want to look alike this can get complicated.
An easier solution is to link them together like so

  :hi link myMacro myKeywords

And now the highlighting of the syntax group myMacro is linked to the highlighting of myKeywords.

  %% These files hold database information %%
  llv require(“File1″)
  llv require(“File2″)
  llv require(“File3″)
  %% This file holds user names %%
  llv require(“File4″)
  %% Output is written %%
  ${DUMP}(“File5″)

So that’s about everything you need to start tweaking your text colors in Vim.  Knowing this will make it a lot easier to go through and read the actual :help files now.

Remember that you can store a bunch of common commands into a file and load it using :source if that’s more convenient. Also remember that Vim commands without arguments give you a list of all current options. So if you type

  :syn

You’ll get

  myComment      xxx match /^%%.*%%/
  myString       xxx start=/”/ end=/”/
  myKeywords     xxx llv
  myMacro        xxx start=/${/ end=/}/
                     links to myKeywords

Which is very useful for debugging your highlighting.