Learn Vimscript the Hard Way

Section Movement Theory

If you've never used Vim's section movement commands ([[, ]], [] and ][) take a second and read the help for them now. Go ahead and read :help section as well.

Confused yet? That's okay, so was I the first time I read that stuff. We're going to take a quick detour from writing code to learn about how these movements work, and then in the next chapter we'll make our Potion plugin support them.

Nroff Files

The four "section movement" commands are conceptually meant to move around between "sections" of a file.

All of these commands are designed to work with nroff files by default. Nroff is a language like LaTeX or Markdown -- it's used to write text that will be reformatted later (it's actually the format used by UNIX man pages).

Nroff files use a certain set of "macros" to define "section headings". For example, here's an excerpt from the awk man page:

.SH NAME                                                     ***
awk \- pattern-directed scanning and processing language
.SH SYNOPSIS                                                 ***
.B awk
.BI \-F
.I fs
.BI \-v
.I var=value
.I 'prog'
.BI \-f
.I progfile
.I file ...
.SH DESCRIPTION                                              ***
.I Awk
scans each input
.I file
for lines that match ...

The lines starting with .SH are section headings. I've marked them with ***. The four section movement commands will move your cursor between these section heading lines.

Vim considers any line starting with . and one of the nroff heading macros to be a section header, even when you're not editing an nroff file!

You can change the macros by changing the sections setting, but Vim still requires a period at the beginning of the line, and the macros must be pairs of characters, so that setting doesn't add enough flexibility for Potion files.


Section movement commands also look for one more thing: an opening or closing curly brace ({ or }) as the first character on a line.

[[ and ]] look for opening braces, while [] and ][ look for closing braces.

This extra "hack" allows you to move between sections of C-like languages easily. However, these rules are always the same no matter what type of file you're in!

Put the following into a buffer:

Test           A B

.SH Hello      A B


{              A
}                B


.H World       A B

Test           A B

Now run :set filetype=basic to tell Vim that this is a BASIC file, and try the section movement comments.

The [[ and ]] commands will move between the lines marked A, while [] and ][ move between the lines marked B.

This shows us that Vim always uses these same two rules for section movement, even for languages where neither one makes sense (like BASIC)!


Read :help section again, now that you know the story of section movement.

Read :help sections just for the fun of it.