Learning the vi Editor

en.wikibooks.org
December 29, 2013

On the 28th of April 2012 the contents of the English as well as German Wikibooks and Wikipedia
projects were licensed under Creative Commons Attribution-ShareAlike 3.0 Unported license. A
URI to this license is given in the list of figures on page 103. If this document is a derived work
from the contents of one of these projects and the content was still licensed by the project under
this license at the time of derivation this document has to be licensed under the same, a similar or a
compatible license, as stated in section 4b of the license. The list of contributors is included in chapter
Contributors on page 101. The licenses GPL, LGPL and GFDL are included in chapter Licenses on
page 107, since this book and/or parts of it may or may not be licensed under one or more of these
licenses, and thus require inclusion of these licenses. The licenses of the figures are given in the list of
figures on page 103. This PDF was generated by the LATEX typesetting software. The LATEX source
code is included as an attachment (source.7z.txt) in this PDF file. To extract the source from
the PDF file, you can use the pdfdetach tool including in the poppler suite, or the http://www.
pdflabs.com/tools/pdftk-the-pdf-toolkit/ utility. Some PDF viewers may also let you save
the attachment to a file. After extracting it from the PDF file you have to rename it to source.7z.
To uncompress the resulting archive we recommend the use of http://www.7-zip.org/. The LATEX
source itself was generated by a program written by Dirk Hünniger, which is freely available under
an open source license from http://de.wikibooks.org/wiki/Benutzer:Dirk_Huenniger/wb2pdf.
Contents
0.1 Learning the vi Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1 Getting acquainted 3
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Getting vi if you don't have it already . . . . . . . . . . . . . . . . . . . . . 5
1.3 Getting around vi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Basic tasks 9
2.1 Vi is a modal editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Entering text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Command mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Making your work easier 13

3.1 More on commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 Advanced tasks 15
4.1 Copying and Pasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Adjusting the Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Details 19
5.1 Command line invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2 Commands: Objects & Operators . . . . . . . . . . . . . . . . . . . . . . . 21
5.3 'Strange' lines on the screen . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.4 Indenting and shifting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.5 Modelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.6 .exrc Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.7 Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.8 EX commands in vi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.9 Shell escape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.10 Execute command from Buffer . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.11 vi for Programmers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.12 nroff/troff Typesetting Support . . . . . . . . . . . . . . . . . . . . . . . . . 44

6 Vi clones 47

7 Vim 49
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.2 External links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.3 Basic navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.4 Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.5 About this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

III
 Learning the vi Editor

7.6 Vim Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

7.7 Inserting Text From a File or Register . . . . . . . . . . . . . . . . . . . . . 60
7.8 Full Screen Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.9 Useful things for programmers to know . . . . . . . . . . . . . . . . . . . . 61
7.10 Enhancing VIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
7.11 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.12 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.13 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7.14 Subprograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.15 Object oriented programming . . . . . . . . . . . . . . . . . . . . . . . . . . 78

8 vile 81
8.1 Vile - vi like Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

9 BusyBox vi 83
9.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

10 vi Reference 85
10.1 Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
10.2 vi Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
10.3 vi Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
10.4 ex Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
10.5 External link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

11 Authors 99
11.1 List of major contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

12 Contributors 101

List of Figures 103

13 Licenses 107
13.1 GNU GENERAL PUBLIC LICENSE . . . . . . . . . . . . . . . . . . . . . 107
13.2 GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . 108
13.3 GNU Lesser General Public License . . . . . . . . . . . . . . . . . . . . . . 109

0.1 Learning the vi Editor

This book aims to teach you how to use the vi

editor, common to many Unix and Unix-like operating systems.
˜
˜
˜
˜
˜
"Learning_the_vi_editor" [New file].

The above text is a little example of how the vi editor's screen looks.

1
1 Getting acquainted

1.1 Introduction

1.1.1 Overview

vi is a powerful editor that is ubiquitous amongst Unix and Unix-like operating systems,
but is available on many other operating systems, even on MS-DOS, Windows and the
Macintosh. If not the original vi, there is usually at least a good clone available that
runs on your system. Even if you use another editor you must have a passing knowledge
of vi as an administrator. Sometimes vi is the only editor available when your computer
crashes leaving a minimal system for you to repair. vi, pronounced like 'vee eye', was
originally written by Bill Joy for BSD Unix in Berkeley in 1976 and became quickly part
of many vendor-specific versions of the (at that time) original AT&T Unix. It was later
directly added to AT&T's System V Unix, too. Bill Joy later went on to co-found Sun
Microsystems1 , and became the company's Chief Scientist at that time. vi stands for visual
and was an enormous improvement of the classic Unix editor called ed. ed is a line-editor.
If you are still familiar with MS-DOS, then you may know the MS-DOS edlin editor. ed
is similar, although more powerful than edlin, which doesn't mean much. vi also has a
line-mode, called ex. In fact, one can argue that the program is indeed two editors in one,
one editor called vi, another called ex. It is possible to switch between line and visual mode
during editing. It is also possible to choose the mode during startup. However, pure usage
of ex is rare. The visual mode is the prevailing mode. Although vi stands for visual, classic
vi is mainly operated via the character keys, and not via the mouse or the cursor keys. Once
you are used to this, it becomes extremely convenient, because there is less movement of the
hands to the cursor keys or mouse involved. vi also served as a kind of incubator for Unix's
terminal control capabilities. Because of vi's need to control the terminal and the many
different types of terminals at that time, the termcap (terminal-capabilities) database was
introduced (later replaced with the more flexible terminfo database). vi's internal high-level
screen control library was later separated, and became curses - the Unix standard library
for CRT screen handling.

1.1.2 Conventions

<c>
A single character, such as 'a' or '1'.
<ESC>, <Ctrl-[>

1 http://www.sun.com

3
Getting acquainted

Indicates that the Escape (Esc) key on your keyboard should be pressed, which is identical
to Control and '['.
<CR>
Indicates that the Return (Enter) key should be pressed.
<TAB>
Indicates that the Tabulator key should be pressed
<Ctrl-x>, <C-x>
Indicates that the Control key and the 'x' key should be pressed simultaneously. 'x' can
be almost any other key on your keyboard.
<Shift-x>, <S-x>, <X>
Indicates that the Shift key and the 'x' key should be pressed simultaneously
<Meta-x>, <M-x>
Indicates that the Meta or Alt key and the 'x' key should be pressed simultaneously.
:quit, :q
An Ex command. started with <:>, followed by the command and ends with <CR>. For
many Ex commands there is a long form (:quit) and a short form (:q).
:set nocompatible
represents a setting.
strlen ()
represents a function.
/pattern/, ?pattern?
A Search pattern. Search pattern in vi are regular expressions2 .
:ranges/search/replace/options, :global /pattern/ delete
A Search pattern combined with an Ex command.
All commands in vi are case sensitive.

unix-command(section)
Sometimes references to Unix commands are used in this book. On first occurrence such
a name of a command is written in the typical Unix style. This style consists of the
command's name followed by the section of the manual pages in which the command
description can be found, in brackets. E.g. sed(1) refers to Unix's sed command which is
usually documented in section 1 of the Unix manual pages (sed is the Unix stream editor;
a tool for manipulating text without user interaction).

2 http://en.wikibooks.org//en.wikipedia.org/wiki/regular_expression

4
 Getting vi if you don't have it already

1.2 Getting vi if you don't have it already

If you're running a Unix system, or a Unix-like system (for simplicity from now on we will
refer to both as a "Unix system"), such as a BSD or Linux distribution, or even Mac OS
X, you're sure to have vi or one of its variants on your system. If you're running Windows,
you can get a version of vi called "vim"3 or "elvis"4 . If you're on an older Mac OS (pre-OS
X) system, you can get MacVim Classic here5 .

1.2.1 Noted vi variants

As mentioned, vi has a number of variants. They have been created because vi was only
available on rather expensive Unix operating systems. Although vi itself, as well as nvi, was
created in Berkeley for the free BSD Unix variant, usage of BSD Unix required an original
AT&T Unix license (this has later changed, see below). Original vi, for example, used code
from AT&T's ed(1) editor. Over time, BSD replaced many of the original AT&T code up to
the point where today there is no such code any more in BSD, and an original Unix license
is no longer needed. As part of the effort to replace all AT&T code in BSD, Keith Bostic
undertook the work to create a clone of vi that was free of AT&T code, called nvi. nvi
then became BSD's standard vi instead of the original vi. Another vi clone is Elvis, which
was written by Steve Kirkendal. Over time, nvi was enhanced – for example, supporting
multiple windows – but originally it was not supposed to be an enhancement, 'just' a pure
clone. BSD's original vi (with the ed code inside) lives on as the vi which is distributed
with System V Unix, because AT&T decided a long time ago to take it from BSD and add
it to the official Unix. Of course AT&T didn't have a problem with an AT&T Unix license,
so they probably never replaced the ed code inside the original vi. Yet, some find nvi still
to be too minimal, and so vim was born. vim (vi-improved), is another effort to extend
vi's capabilities. Unlike nvi, vim goes even further to extend vi's capabilities. However
some find that vim is often too much. vim comes in two variants, a text-only version, and
a GUI version, the latter is called gvim. Other vi clones are the already mentioned elvis
and stevie. These clones were born in the CP/M and home computer area to bring the
editor to these platforms, too. Of course, they were later ported to MS-DOS and Windows.
These days, however, vim seems to be the prevailing vi-clone on free/open platforms and
proprietary platforms as well. You should choose the version you feel most comfortable with
– if you have an editor you feel displeased with, it will affect your productivity.

1.3 Getting around vi

1.3.1 Starting the editor

If you are running a Unix system, you can start up vi by typing

3 http://www.vim.org
4 http://elvis.the-little-red-haired-girl.org/whatiselvis/
5 http://macvim.swdev.org/MacClassic/

5
Getting acquainted

vi<CR>

at the command line. If you are running X, with a desktop like GNOME, KDE, CDE/Motif
or OpenLook you may have a launcher button handy to start the editor - if you have such a
setup, you can just click the icon. If you are running Windows or DOS with elvis, you can
start up the Windows editor by double-clicking "winelvis.exe", or in DOS, you can start the
editor by typing in "elvis" at the command line. You will be greeted with a screen similar
to:

˜
˜
˜
˜
˜
˜
"No File"

1.3.2 Quitting the editor

To quit for now, press the Escape key (the editor should beep), then enter the three char-
acters :q! and press Return:

<ESC>:q!<CR>

Just before you type the final <CR> the screen will look similar to

˜
˜
˜
˜
˜
˜
:q!

:q! is the short form of :quit! which quits the editor. You should be dropped back to your
operating system (or, rather, the shell from where you started). There are other ways to
quit, e.g. pressing <Z><Z> (<Shift-z><Shift-z>) will save any unsaved work and quit
the editor. Typing :wq will always save, even if there are no unsaved changes, and then
quit the editor. :x will write if there are no unsaved changes, and it will quit. :wq and
:x requires that you had previously provided a file name, so it will not work for the above
simple example. Typing :q will quit if there have been no changes made; if changes have
been made, vi will print a warning similar to "No write since last change".

1.3.3 Don't worry

Many first time vi users stop at this point, and never touch vi again. If you tried to enter
some text after you started, you will most likely have been greeted with a series of beeps

6
 Continue

and rather erratic behavior. Don't worry. This is perfectly normal for vi, and the editor is
not broken. You will soon see why this is normal vi behaviour.

1.4 Continue

Now that you know how to start the editor and quit it, let's move on to getting things
done in vi: see Learning the vi Editor/Basic tasks6

6 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Basic_tasks

7
2 Basic tasks

Now that we know how to invoke the editor and quit it, we can get acquainted with how to
use the editor. Alternatively, you can use the ViM tutor which comes with many modern
vim distributions. It contains, essentially the same information as the text below. You can
invoke the tutor by entering vimtutor at your shell.

2.1 Vi is a modal editor

The vi editor can do two things:

• accept a command, such as deleting a line
• accept text, written by you
In the vi editor, each of these tasks is achieved by putting the editor into a particular mode
of operation (normally just called a mode). When you wish to give vi a command, you enter
command mode, and when you want to enter text, you enter insert mode. We'll cover how
to do this below. It is important to set the correct mode before you begin writing, but this
is simple to do. When you first start vi, it is automatically in command mode.

2.2 Entering text

Entering text is the most basic task an editor can do! From command mode (in which the
editor starts), press i to enter insert mode, and you can begin typing. You can use the
backspace key to correct mistakes you make. If you make a mistake after a few sentences,
leave these errors for now, we will look at correcting them later. To leave insert mode once
you're done typing, and return to command mode, press the Escape key on your keyboard
(or type Control-[).

2.2.1 Exercise

Let's have an exercise:

1. Start the editor.
2. Enter insert mode.
3. Type some text
4. Return to command mode.
5. Quit the editor.

9
Basic tasks

2.2.2 Solution
1. We can start the editor as in the previous section.
2. Since the editor starts in command mode, we must press the <i> key before we can
start typing.
3. You can make some text up yourself!
4. Press the <Escape> key.
5. If you want to quit the editor, you need to be in command mode. Since pressing
Escape puts you in command mode, you can just use the method in the previous
section to exit: type :q!

2.3 Command mode

Command mode allows you to perform many useful tasks within vi.

2.3.1 Moving around

Say you have been writing for some time, and have forgotten something. Pressing
<Backspace>, erasing previous work is not the best solution! We would like to move
around the document freely, moving the cursor.

We can move around in the editor by first entering command mode, and then using the
<h>, <j>, <k>, and <l> keys.
Note
your arrow keys may be set up to work, and you can use them if you like, but for proficiency
and for advanced work later, you should learn to use the letter keys.
• The <h> key, in command mode, moves the cursor one character left.
• The <j> key, in command mode, moves the cursor one character down.
• The <k> key, in command mode, moves the cursor one character up.
• The <l> key, in command mode, moves the cursor one character right.
If you have trouble remembering this, keep in mind that <h> is leftmost, the letter
<j>goes down below the line, the letter <k>pokes up above the line, and the <l> key is
rightmost. (J also resembles an arrow pointing downward, if you squint a bit.) After you
have moved the cursor using those keys, you can enter insert mode again by pressing <i>.
When you do this, you insert text at the cursor, inserting text between the character to the
left of the cursor and the current position of the cursor. Let's practice this in an exercise.

Exercise

You can repeat this exercise with your own sentences. Make sure you are proficient doing
this before you continue.

10
 Command mode

1. Start the editor.

2. Enter the text: "The quick fox jumps over the dog"
3. Insert the word "brown" between "quick" and "fox".
4. Insert the word "lazy" between "the" and "dog".
5. Quit the editor.

Solution
1. Use the method in the previous section.
2. Press <i>, then enter The quick fox jumps over the dog normally.
3. Press <Escape>, then press <h> until the cursor is at the letter "f" of "fox". Press
<i>, and then type "brown ".
4. Press <Escape>, then press <l> until the cursor is at the letter "d". Press <i>, and
then type "lazy ".
5. Press <Escape> again, then type :quit!.

2.3.2 More on movement

Using h, j, k, and l is ok, but vi understands more than rows and columns. These are some
commands that move by text objects:
• w moves forward to the beginning of the next word.
• b moves backwards to the beginning of the previous word.
• ( and ) move by sentences, either backward or forward.
• { and } move by paragraphs.

2.3.3 Deleting things

If you have made a mistake after a few lines, for instance, pressing Backspace until you have
erased the mistake and starting again isn't always the best solution. We need a method of
deleting mistakes that happen in the normal course of editing. vi allows you several methods
of deleting text, based on how much you want to remove. Now that you are familiar with
moving around, once you've moved the cursor to where your error is:
• the x key deletes one character
• pressing dw deletes one word.
• pressing dd deletes one line

Exercise

From now on, we will omit the steps for you to start and quit the editor - you should be
already familiar with those.
1. Enter the following text: Sad I been here, I wouldnt ever ever leave.
2. Change the word "Sad" to "Had".
3. Add an apostrophe after "wouldn".
4. Delete the extra "ever".

11
Basic tasks

5. Delete the line.

Solution
1. Type the text normally. (You should already be familiar with entering insert mode
and leaving it.)
2. Enter command mode, use h to move to the start of the line, and then press x to
delete the "S". Press i to enter insert mode, insert the "H", then leave insert mode
by pressing Escape.
3. Now position the cursor on the t, and press i to enter insert mode, type the " ' ".
Leave insert mode by pressing escape.
4. Position the cursor over the first "e" in the word "ever" (choose whichever one you
like). Type dw to delete the word.
5. Type dd to remove the entire line.

12
3 Making your work easier

By now you should know the rudiments of using vi. However, to really make vi work for
you, it may be helpful to know the following to make your work easier for you.

3.1 More on commands

Say you are editing a document, and you wish to delete ten lines - as of now, the only way
to do this is to enter dd ten times. Or if you want to delete seven characters exactly - you
would have to enter x seven times. There must be a better way!

3.1.1 Repetition

Fortunately, vi lets you augment most of the commands in case you want to repeat that
command a certain number of times. This is done by typing in the number of times you
want that command repeated, followed by the command. So, if you want to delete ten
lines, you would type 10dd. Or if you want to delete seven characters, you would type 7x.
You can also repeat the last action done by typing . (this is a single period keystroke),
the single-repeat operation over the location you want to repeat the previous operation.
So if you wanted to repeat the deletion of ten lines as in the previous example, you could
repeatedly press . to perform this operation over and over again.

Exercise

1. Type the sentence Good morning Doctor, how are you today?. Delete "Good
morning". 2. Now using the single-repeat operation, delete "how are".

3.1.2 Motion

vi allows you greater flexibility over motion as well. There are a few commands to allow
you to quickly jump around your document, such as :
• 0 moves to the immediate beginning of the line
• $ moves to the immediate end of the line
• ˆ moves to the first non-whitespace character of the line
ˆ acts in the following way, if the line was

hello how are you

13
Making your work easier

and your cursor is on the u, if you would enter ˆ, the cursor would be upon the h. Further-
more, the / command allows you to jump directly to some pattern in the file. For example,
if you're looking for the next occurrence of the word "pomegranate" in your text, if you
hit /, then type in pomegranate (you need not enter insert mode) and hit enter, the cursor
will jump to the next occurrence of the word, if it exists. If you want to search backwards,
you would perform the same procedure, but use the ? command. To repeat either search,
enter //, ??, or alternatively, type / or ? and hit Enter. You can also press n to jump to
the next occurrence, and N to jump to the previous occurrence.

Commands and motion

We know now that vi lets you enter a number to specify how many times to do something.
Consider this example now: you want to delete everything after a certain point on a line
- you could enter dw for each word from the cursor position to the end of the line, or hold
down x, but these are cumbersome examples. vi thankfully lets you do something much
faster. With certain commands, vi allows you to specify a position, using the methods in
the previous sections. The position is specified after the command. For example, to delete
up to the end of the line, you would enter d$. Other examples:
• dt; will delete until the next semicolon (This is helpful in languages like C and perl that
use semicolons to finish statements).
• d2} to delete the next two paragraphs.
• d4b to delete the previous four words (alternatively, you could enter 4b4dw).

14
4 Advanced tasks

4.1 Copying and Pasting

Copying and pasting tasks are done with three keys, <y> (for "yank"), <d> (for "delete"),
and <p> (for "paste"). In general, you type <y> or <d> to tell vi that you're at the
position where you want to start yanking or deleting some text. Then you need to tell vi
where to stop, using cursor movement or other commands. You can also simply use key
<v> to enter a visual mode. Then you can highlight text by moving cursor keys. And
finally press <y> to copy text to clipboard. And <p> for paste.

4.1.1 A Word

To delete a single word, move your cursor to the first letter, then type <d><w>. To yank
a single word, move your cursor to the first letter, then type <y><w>.

Other Methods

Move to the character past the last letter and type <d> <b>. To delete a word like "can't",
which has an apostrophe, move to the first character and type <d><W>. Note the capital
W. This tells vi to go all the way to the first whitespace character after the word. Likewise,
try dB.

4.1.2 A Line

To delete a single line, type <d><d>.

4.1.3 Other Amounts

One of the great things about vi is that it lets you select a bunch of text without having to
move your hand to your mouse. Type <m><a>. This will mark the current position that
your cursor is at as mark a. You can go back to this position anytime you want from now
on by typing <`><a>. (`a means "move to the character that has been marked as a")
Now move to some other position. Type <d><`><a>. This will delete everything from
the current position to the position you marked as a. Note that you can use nearly any key
in place of the <a> used in this example. For instance, you might use <m><t> to mark
the top of a section, or <m><b> to mark the bottom. These mnemonics are strictly in the
user's head - vi doesn't care that t means top or b means bottom. Vi will remember all

15
Advanced tasks

unique bookmarks, allowing the user to easily and quickly jump between them. Some users
find using <m><m> to be a convenient temporary bookmark, because it can be typed so
quickly.

To the end or beginning of a line

<d><$> or <d><ˆ>

To the end or beginning of the file

<d><G> or <d><1><G>

To the next occurrence of a pattern

<d>/myPattern This is particularly useful when editing HTML files with d/<

4.2 Adjusting the Screen

vi, as a visual screen-oriented editor has a number of useful commands to redraw or adjust
the screen in case you find yourself somewhere where you don't want to be. If you run
in a Unix shell, it is possible that some background process writes to the same terminal.
This will disturb vi's screen layout. In order to force vi to redraw the complete screen,
press <Ctrl-L> or <Ctrl-R>. Both commands do the same. If you want to adjust what
is currently displayed, then the <z> command is rather useful. It's a kind of Swiss army
knife, and has a rather complex syntax:

[/pattern/][m]z[n](<CR>|.|-)

([ ... ] denotes optional items, (...|...) denotes alternatives) Before we explain the syntax in
detail, here are some common applications of the command: Scroll the screen so the current
line becomes the middle line of the screen. The cursor remains on that line:

<z><.>

Scroll the screen so the current line becomes the top line on the screen:

<z><CR>

Scroll the screen, so the current line becomes the bottom line of the screen

<z><->

16
 Adjusting the Screen

If a /pattern/ or a number m is given the cursor is moved further after the adjustment.
/pattern/ indicates to move the cursor to the first match of that pattern. m indicates to
move the cursor to the mth line on the screen. So, for example,

/while/z<CR>

would first scroll the screen so the current line becomes the top line on the screen, and
then move the cursor to the first 'while' in the text from that position on. The number
n is a rather obscure parameter. If provided, it tells vi to behave as if the screen is just
n lines high. The result is that only n number of lines are adjusted, and the rest of the
screen is either ignored or cleared, presumably useful on slow terminals to avoid redrawing
the screen unneccessarily.

17
5 Details

This section describes some of the details of the vi program itself (such as command line
features), and other advanced vi features for aspiring vi power users.

5.1 Command line invocation

Different vi clones of course have different ways of starting the program (invocation).
Usually, however, command-line versions of vi share a common basic set of command
line options. These following command line options and flags are typically available. In
addition, vi can be started under different names. Depending on the name used to start vi,
it may either behave slightly differently or load a different vi clone.

The common command line options and flags are

-
or
-s
Suppress. All interactive user feedback is suppressed (not written to the terminal). This
allows to pipe editing commands through the editor, and use it as a kind of stream editor.
There are probably better streaming editor tools on Unix, like sed(1), awk(1), or Perl(n).
Note, "-" is a common Unix notation to indicate standard input. It has been chosen as an
alternative to -s by the vi authors to provide a familiar look when piping commands. It
does not really mean 'read from standard input' since vi does that anyhow.
-C
Encryption. vi prompts the user for a key (a kind of password), and uses this key to
encrypt its files before writing. It also uses this key to decrypt any file opened with vi.
This feature is not supported by many clones, and the encryption algorithm is a very weak
one (it is based on a 256-element one-rotor algorithm). The algorithm is easy to crack. It
is compatible with the Unix crypt(1) command. See also -x.
-l
(lower-case letter L) Change some default settings so they are more useful for editing LISP
source code.
-L
(upper case letter L) Lists all files which have been saved during a crash. See -r, too.

19
Details

-r filename
Recover the file filename after a crash. Use -L to get a list of files which can be recovered.
-R
Readonly. Files can only be viewed, not written.
-S
Tags1 are not sorted. When a tag file is used, this flag tells vi that the tag file is not sorted,
therefore vi will use a slower algorithm to look up tags. See -t, too.
-t tag
Edit (open) that file which contains the given tag. This of course requires that a tag file
(called tags) is available.
-v
Start in visual mode. Only useful if the editor is started under the name ex and not vi.
-V
Verbose. Commands read via standard input are echoed to standard error. This is useful
for debugging when the editor is used as a streaming editor.
-wnumber
Window size. Set the editor's number of lines to number. vi behaves as if the terminal
has only number number of lines. This was used in the old days to speed up things when
connecting via a slow terminal or modem line.
-x
Encryption. Similar to -C. The difference is that vi tries to guess if a file that is opened
needs decryption or not. -C on the other hand always runs the decryption when a file is
opened.
+command
or
-c command
Execute the command command before allowing the user to enter own commands. The
most common usage is to use this to position the editor at some specific line in a file. E.g.

vi +10 list.txt

will open the file list.txt and position the cursor at line 10. Another common usage is
to specify a pattern:

vi +/END script.awk

1 #Tags

20
 Commands: Objects & Operators

This will open the file script.awk and position the cursor at the first occurrence of the
pattern 'END'.
As already mentioned, vi can be started using different names (all may not be available
depending on the particular clone):
vi
The usual way to start vi.
view
vi starts in read-only mode.
vedit
A few settings are changed to better suit beginners: magic is cleared, showmode and novice
are set, and report is set to 1.
ex -v
Same as just typing vi

5.2 Commands: Objects & Operators

5.2.1 General

Until now, this tutorial has just talked about commands, and that commands can be used
in conjunction with things like word counts. E.g. d2w has been explained as the operator
delete applied to two words. Note the 2w part. You have learned that this part specifies to
which text the operator should apply. And indeed, the 2w part specifies to which objects
of the text (words, lines, characters etc.) the operator is supposed to be applied. And you
have seen that the same object specifiers can be used with all types of operators - as long
as the combination makes sense. vi commands in fact follow a general schema. Commands
are made up from operators and objects:

[[count] operator] [[number] object]

This means the operator should be executed count times on number of objects. Almost all
parts are optional. Also, some operators don't take objects at all. This operator/operation
syntax is vi's heart. It is why people either love or hate vi. People love it, because it is such
a simple schema. Once one knows the few operators (not more than ten), and a few of the
objects one can be very productive in vi. People who hate vi simply can't get this schema,
and the fact that there is a difference between command and insert mode, into their heads.

5.2.2 Objects

We told you that things like the w command moves one word. We actually cheated a little bit
when telling you this. There is no such thing as a w command. w is an object specification,
not a command. The object specification was given without an explicit operator like d. In

21
Details

such a case vi uses the implicit default operator. And that operator is move. Whenever you
use an object specification without an operator, the operator move will be used. Therefore,
object specifiers degrade to move commands. The following is a list and summary of all
object specifier. Logically, you can use them in conjunction with operators, or to move
around if used stand-alone. You have seen a few of them already:

Paragraph, Section, Sentence Objects

}
Everything until next paragraph end.
{
Everything until previous paragraph end.
]]
[Everything until next section end.]
[[
[Everything until previous section end.]
)
Everything until next sentence end.
(
Everything until previous sentence end.

Line Objects

[number]G
Everything until line number. If number is omitted, last (not first) line in file. The first
line can be addressed as 1G instead.
[number]H
number of lines after the first line currently on screen. If number is not given, the first line
on the screen.
[number]L
number of lines before the last line currently on screen. If number is not given, the last
line on the screen.
M
The middle line of the screen.
j
One line down from current line.

22
 Commands: Objects & Operators

k
One line up from current line.
_
(underscore) The current line as a whole.

Positions within Lines

0
(Digit 0). Backward to first column of line. Same as 1| (not 0|).
ˆ
Backward to first non-whitespace character.
$
Forward to end of line.
[number]|
Column number of the current line. If number is not given, column 1 is used.
tchar
Before the next appearance of character char on the current line.
Tchar
Backwards after the next appearance of character char on the current line.
fchar
Next appearance of character char on the current line.
Fchar
Previous appearance of character char on the current line.
;
Repetition of the last t, T, f, or F command.
,
Repetition of the last t, T, f, or F command, but in opposite direction.
+
or
<CR>
To the first non-whitespace character on the next line.
-
To first non-whitespace character on the previous line.

23
Details

Word Objects

w
Forward to next begin of a word.
e
Forward to next end of a word.
b
Backwards to next begin of a word.

Character Object

h
or
<BS>
Left character.
l
or
<SPACE>
(lower-case letter L or space) Right character.

Pattern Matching Objects

/pattern/
Forward to the beginning of the first match of pattern pattern.
?pattern?
Backwards to the beginning of the first match of pattern pattern.
<n>
Repeat the last / or ?.
<N>
Repeat the last / or ? in opposite direction.

24
 Commands: Objects & Operators

<%>
To next matching (, {, or [.

5.2.3 Operators

The previously listed objects can be used as arguments to operators. If no operator is given,
the default move operator is used. The number of operators in vi is surprisingly small -
ten in total. Here is a list of the operators: needs better descriptions, a few of them are
separately described later in this module

Operators taking Objects

c
change - change the addressed objects. In fact, the text is replaced by what is typed in.
d
delete - delete the addressed objects. The deleted text is placed in the undo buffer.
y
yank - copy the text of the addressed objects into the buffer.
<
shift left - object arguments can only be objects which address lines Indenting and Shift-
ing2 .
>
shift right - object arguments can only be objects which address lines Indenting and
Shifting3 .
!
bang filter-through - filter lines through an external program. Objects can only be objects
addressing lines Filtering (stub)4 .

Operators not taking Objects

r, s,
x
Delete character. Use the d operator for deleting other objects than characters.
˜

2 #Indenting_and_shifting
3 #Indenting_and_shifting
4 #Filtering

25
Details

Flip case of character at cursor position. An uppercase letter becomes its lowercase equiv-
alent, and a lowercase letter becomes its uppercase equivalent.

Special Operator Forms

There are two special forms when typing an operator:

1. Typing the character in upper-case, instead of lower-case. E.g. Y instead of y , and
2. doubling the character. E.g. yy instead of y.

5.3 'Strange' lines on the screen

vi was written at a time when terminal or modem connections were slow. Therefore, vi
used several optimisation techniques to limit the need for redrawing the whole screen. In
such cases, vi used to display lines beginning with a special marker. Modern vi's seldom
have the need for such performance optimizations any more, but they still have the habit
to display such lines. There are two special markers used:

˜line

A leading '˜' indicates that the line is past the end of the file (non-existent). This can be
observed, for example, when vi is started on a new or empty file.

@line

The line is only on the screen, not in the file. This happens for deleted lines. If wrap is
enabled (the default), this also happens for lines that are too long to show on the screen all
at once.

5.4 Indenting and shifting

vi supports auto-indentation of text lines and also provides command for manual indenta-
tion. This is useful when editing program source code. It is a common convention in many
programming languages to use indentation to increase readability of the source code.

5.4.1 Options

The option shiftwidth (sw) determines how much space is used for indentation. E.g.

<ESC>:set shiftwidth=4<CR>

or

26
 Indenting and shifting

<ESC>:set sw=4<CR>

tells vi to use four spaces for indentation. The option [no]autoindent (ai) tells vi to use
auto identation or not. Auto indentation is turned on by

<ESC>:set autoindent<CR>

or

<ESC>:set ai<CR>

And it is turned off by

<ESC>:set noautoindent<CR>

or

<ESC>:set noai<CR>

5.4.2 Command Mode

Shifting lines is done with the < and > commands. < moves the text one shiftwidth
to the left (outdenting), while > moves the text one shiftwidth to the right (indenting).
The number of lines which can be affected are specified in vi's typical way. However, only
objects5 which identify lines, and not objects which identify words or individual characters
can be used. E.g.

>G

moves all lines from the current line until the end of the file to the right. Or

<}

moves all lines from the current line until the end of the paragraph to the left. Of course,
the shift commands can be used in conjunction with %, which indicates the next opening
bracket. E.g. to shift the lines encompassing the current cursor position up to the first line
with a matching (, {, or [ to the left one would type:

<%

Like with all commands it is also possible to specify a line count:

[number]<<

5 #Objects

27
Details

or
<[number]<
Moves number of lines, starting at the current line, one shiftwidth to the left (outdenting).
If number is not given, 1 is assumed - this leads to the shifting of the current line to the
left.
[number]>>
or
>[number]>
Moves number of lines, starting at the current line, one shiftwidth to the right (indenting).
If number is not given, 1 is assumed - this leads to the shifting of the current line to the
right.
The < and > commands can also be used with a marker. In this case, the reference to the
marker is placed between the two characters of the command:
<'m<
Shifts the lines from the marker m up and including the current line to the left.
>'m>
Shifts the lines from the marker m up and including the current line to the right.

5.4.3 Insert Mode

ˆt
Moves shiftwidth to the right. Note, it is a common mistake to use the <TAB> key instead
of ˆt. <TAB> inserts a Ctrl-I character and moves to the next multiple of tabstop, and
not to shiftwidth. So <TAB> only works if tabstop and shiftwidth are set to the same
value.
Since it is not a good idea to set tabstop to anything else than 8, <TAB> can only be used
instead of ˆt for indenting when shiftwidth is also set to 8.
ˆd
In autoindent mode, backtabs one shiftwidth. E.g. if autoindent is on, and one wants to
enter the follwing text:

if(true) {
printf("done"); // start sw indent
return;
} // bracket moved back to the left

one would type

if(true) {<CR>
ˆtprintf("done"); // start sw indent<CR>
return;<CR>

28
 Indenting and shifting

ˆd} // bracket moved back to the left<CR>

There are some special variants of ˆd, too:

ˆˆd

(the letter ˆ followed by Ctrl-D). When this is typed first on a new line, all autoindent
is killed (the insertion point is moved to the beginning of the line). Autoindent is then
continued on the next line.
E.g. to enter the following text when using autoindenting

an indented paragraph
another line in the indented paragraph
.F roff formating commands have to start at column one with a '.'
more text in the indented paragraph

one would type

ˆtan indented paragraph<CR>

another line in the indented paragraph<CR>
ˆˆd.F roff formating commands have to start at column one with a '.'<CR>
more text in the indented paragraph<CR>

0ˆd
(the digit 0 followed by Ctrl-D). Kills all autoindent (moves cursor to the beginning of the
line), and leaves autoindent off, until text is once manually indented (using ˆt).
E.g. to enter the following text when using autoindenting

INTEGER FUNCTION FAC(N)

FAC = 1
DO 100 I = 2, N
FAC = I * FAC
C
C PROVIDE LABEL TO END LOOP
C A HINT FOR THOSE GRASSHOPPERS: THIS IS FORTRAN CODE :-)
C
100 CONTINUE
RETURN
END

one would type

<ESC>:set sw=5<CR>
oˆtINTEGER FUNCTION FAC(N)<CR>
FAC = 1<CR>
DO 100 I = 2, N<CR>
ˆtFAC = I * FAC<CR>
0ˆdC<CR>
C PROVIDE LABEL TO END LOOP<CR>
C A HINT FOR THOSE GRASSHOPPERS: THIS IS FORTRAN CODE :-)<CR>
C<CR>
100 CONTINUE<CR>
ˆtRETURN<CR>

29
Details

END<CR>

5.5 Modelines

Modelines are lines in text files which are specially interpreted by vi when such a text file
is opened. When the modeline (ml) (in some version of vi also called modelines) option is
turned on (e.g. in the users .exrc file), vi scans the first and last five lines of each opened
file for text of the form

unrelated text vi:command: more unrelated text

or

unrelated text ex:command: more unrelated text

Each command from such lines is taken and executed as it would have been typed by the
user. Any text in front of the modeline-marker (vi: or ex:) or behind the closing : is
ignored for the modeline interpretation. This can be used to place modelines in comments
if they are used in some programming source code. Here is an example Java source code
file. It contains a modeline on the second and third line, in a Java comment:

/*
* vi:set sw=4 ai:
* vi:set showmatch:
*/
package gnu.freesoftware;
public class Interpreter {
public Interpreter() ...
...

When modelines are turned on, and this file is opened, shiftwidth (sw) is set to 4, au-
toindent (ai) is turned on, and the showmatch (sm) option is turned on, too. There is no
particular reason why two set commands on two modelines are used other than to demon-
strate that all modeline commands found in the first and last five lines are executed, and
not just the first. Modelines can be used to play some practical jokes. E.g., a file with the
modeline

vi:q!:

immediately closes the editor and makes it impossible to edit the file as long as modelines
are turned on. Modelines get outright dangerous if they mess with system files. E.g., if the
super user (administrator) of a Unix system has modelines turned on, and is tricked into
opening a file with the following modeline, the important Unix password file is overwritten
with the contents of the opened file:

vi:2,$w! /etc/passwd:
root:A shiny new root password:0:0:System Administrator:/:/bin/sh
anotheruser:Another shiny new password:1:0:Just another

30
 .exrc Configuration File

user:/home/anotheruser:/bin/sh

Therefore modelines should only be turned on in a controlled environment. This is sad, since
in principle it is a nice idea that files are able to provide the editor with a configuration best
suited to edit that file. There are some other problems with modelines. Classic vi versions
always set a file's status to modified if they find a modeline, even if no editing in the file
has taken place. This forces the user to leave the editor with :q! instead of just :q. If
instead ZZ is used to leave, the file is written. This causes tools like make to think the file
has changed if it in fact hasn't.

5.6 .exrc Configuration File

This module is a stub6 . You can help Wikibooks by fixing it7 . For a start: .exrc files are
files containing vi (and ex) configuration data. The format of the data in such a file is that
of ex commands, without the leading ':' (column). Typically, .exrc files are used to load
some default mappings (map and map! ex commands) or define particular defaults. E.g.
the following .exrc file would set autoindent and the shiftwidth when vi is started:

set ai
set sw=4

Normally, a .exrc file is placed in the user's home directory. Since the file name starts with
a '.', the file is hidden under Unix-like operating systems. It is possible to place .exrc files
in other directories, too. Vi can read the .exrc file in the current directory from which it
is started. However, this feature is considered a security risk and turned off by default. It
is considered a risk, because similar jokes can be played with .exrc files as with what has
been described for modelines. The .exrc file in a user's home directory is considered safe,
because on a correctly configured Unix system only the particular user should have write
access to it. There are three important things which should be observed when working with
a classic vi and .exrc files:
1. .exrc files must not contain empty lines. Classic vi chokes on these lines with all kinds
of cryptic error messages.
2. There is no official way to place a comment in .exrc files. However, since the beginning
of time the following hack is used and is known to work: A line which starts with a "
(quotation character) is ignored by vi.
3. Classic vi is very picky about map and map! commands. Definitions which by all
means should work can trigger strange error messages. This is due to classic vi's
limited parser and interpreter for such definitions. Spliting a map or map1 command
in several smaller ones can sometimes help.
Many clones have relaxed these rules by allowing empty lines in an .exrc file, and by officially
specifying the " as the comment character. Also, good clones should have no problem with
map or map! specifications.

6 #Power_Users
7 http://en.wikibooks.org/wiki/Wikibooks:Find_or_fix_a_stub

31
Details

"
" This is a comment in an .exrc file
" A .exrc file must not contain empty lines, so
" comment lines need to be used to separate entries
"
set sm
set sw=8
"
set wm=8
"
" map 'g' to go to begin of file
map g 1G
" rcs check-out (/co) and check-in (/ci)
map /co :w! %.co.bakˆM:!co -l %ˆM:e!
map /ci :wˆM:!ci -u %ˆM:e!ˆM
"
" Abbreviations
ab Lx Linux

5.7 Tags

5.7.1 Overview

Vi can use so called tag files (or tags) to allow for quick navigation (jump) to "interesting"
information in a set of files. The most common usage for this is to navigate within source
code files. E.g. to jump from the usage of a certain function to the function's definition,
possibly in another file. The mechanism is relatively simple. You tell vi to go to a particular
tag. vi looks up the file in which the tag can be found, opens that file and jumps to the
location of the tag in that file. In order to find the file and position of a tag, vi consults a tag
file. A tag file contains an index of tags. A tag is an item (e.g. some programming language
object) for which such an index entry can be found in a tag file. When vi is asked to jump
to a particular tag, vi looks up the index entry for that tag, and uses the information to
jump to the particular item. In order to use this feature one first has to create a tag file,
or a set of tag files, containing entries for all potentially interesting items. These tag file or
files then need to be made known to vi - if the default file name is not used. This can e.g.
be done by having appropriate commands in an .exrc file. Modern IDEs provide similar
navigation features, but without the need to build a tag file separately. IDEs build the
necessary index on-the-fly or use fast brute-force full-text search algorithms. The need for
the extra step of creating a tag file for vi is annoying by modern standards. Still, vi's tag
file system works and is usable.

5.7.2 Tag File Format, Creation & ctags(1)

The creation of a tag file typically requires to use a tool which analyses the input text files
(e.g. programming source code) and generates entries for each item of interest found in the
input text file. The most common tool is called ctags(1) and is a standard Unix program.
Several vi clones come with own versions of ctags, sometimes called differently. ctags knows
the syntax of a number of programming languages and generates index information for items
like function names, and macro definitions. In case ctags is not available, or the available

32
 Tags

version of ctags does not support the programming language in use it is also possible to
generate tag files with text processing tools like awk(1), sed(1) or perl(n) and some clever
scripts, because tag files are ASCII files. Typically an entry in a tag file looks like

tag-name<TAB>file-name<TAB>ex-command

tag-name
The name of the item. E.g. a function name or macro name.
file-name
The name of the file in which the tag-name item can be found
ex-command
An ex editor command indicating how to locate the item in the file. This can be any ex
command. But two types of ex commands make the most sense:
1. In the simple form ex-command is a line number, which is indeed a valid ex command.
2. Usually, however, it is a better idea to use a search pattern like /tag-name/. This
provides some flexibility if the file is edited later. It reduces the number of times the
tag file has to be re-build, because something moved inside a file. ctags also mostly
generates pattern search commands and not line numbers.
Typically vi clones allow for some extensions of this format. Check the particular docu-
mentation. A tag file should be sorted in alphabetic order to speed up operation. If this
can't be done, vi's -S8 command line option can be used. It is usually not a good idea to
generate tag files by manually running ctags or an own tool. Instead the building of tag
files is usually better integrated into the software build system. For Unix this means using
Makefiles. Typically, the make(1s) targets for generating tag files are called tags, because
that's the name of the to be created tag file:

# Makefile snippet
SRCS = ... # all source code
tags: $(SRCS)
ctags -dt $(SRCS)

5.7.3 Ex Commands

By default, vi looks in a file called tags for any tags. This file name can be changed with
the following ex command. In fact, more than one file name can be specified. They are all
loaded to find tags. The command is maybe best placed in a project-specific .exrc file.
:set tags=filename[\ filename ...]<CR>
Set name of files which contain tag information. The syntax of the command varies a
little bit from vi to vi version if more than one tag filename is supposed to be provided.
Filenames have either to be separated by "\ " (backslash space) or ";" (semicolon).

8 #Command_line_invocation

33
Details

Naviation to tags can be done via the following ex command. There is also a vi command
to do this.
:ta tag-name<CR>
or
:tag tag-name<CR>
Look up the tag-name in the tags file(s), open the file named in the index entry and execute
the ex-command from the index entry. This effectively positions the user at the file and
position where the symbol tag-name is defined. The command also remembers the current
file and position on the tag stack.

5.8 EX commands in vi

Ex is a line editor that serves as the foundation for the screen editor vi. Ex commands
work on the current line or on a range of lines in a file. Syntax of Ex commands
:[address] command [options]
':' specifies an Ex command. Address
The 'address' specifies the lines number or range of lines that are the object of command.If
no address is given,the current line is the object of the command.

Address Ranges can be specified by any of the following ways in Ex command syntax.

Syntax Range
:% All the lines in the file.
:1,$ All the lines in the file.
:ˆ,$ All the lines in the file.
:X,Y All the lines between Line number X to Line number Y.
:.,.+n All the lines between current line and next n lines.
:.,.-n All the lines between current line and previous n lines.
:X;Y Line number X to Line number Y with current line set as Line Number
X.
:X,+n All the lines between Line number X and next n lines from Current
Line.
:X,-n All the lines between Line number X and previous n lines from Current
Line.
:X The Line number X.
:. The Current Line.
:$ The Last line of File.
:0 The First line of file
:X-n The Line which is n lines before Line number X .
:X+n The Line which is n lines after Line number X .
:'b The Line which is marked by letter b.

34
 EX commands in vi

Syntax Range
:' The Line which is marked.
:/word Next Line containing pattern word
:?word Previous Line containing pattern word

Commands

Command Ex Syntax Operation

Substitute :%s/str1/str2/g Substitute str1 by str2 in the
Address range specified as
whole file.
Copy and Paste :t8 Copy current line and Paste
after Line number 8.
Copy and Paste :9t11 Copy line 9 and Paste after
Line number 11.
Copy and Paste :5,8t10 copy lines 5 through 8 and
Paste after Line number 5.
Copy and Paste :10,14co20 Copy lines 10 through 14 and
Paste after Line number 20.
Move and Paste :m8 Cut current line and Paste
after Line number 8.
Move and Paste :9m11 Cut line 9 and Paste after
Line number 11.
Move and Paste :5,8m10 Cut lines 5 through 8 and
Paste after Line number 5.
Yank/Copy in named :3,10y p Copy the text between line
buffer. number 3 and line number 10
in a buffer p (single lowercase
char)
Yank/Copy. :3,10y Copy the text between line
number 3 and line number 10
in a temporary buffer.
Paste/Put :10p Paste the text in temporary
buffer at line number 10.
Paste/Put :p Paste the text in temporary
buffer at Current line .
Paste/Put :+10p Paste the text in temporary
buffer at 10 lines after Cur-
rent line
Write/Save file :w! Save the current file.
Write/Save file :w fname Save the current file as
fname. Similar to "Save as"
in Windows Operating sys-
tem.

35
Details

Command Ex Syntax Operation

Write/Save file :15,30w fnew Saves the Lines between Line
number 15 to Line number
30 of current file in a new file
named fnew.
Write/Save file :15,30w >> fexist appends the Lines between
Line number 15 to Line num-
ber 30 of current file in a file
named fexist.
Write/Save file :x! Save & Quit current file
Forcefully.
Quit file :q Quit the current file.
Quit file :q! Quit current file Forcefully
without saving.
Edit/Refresh :e! Refresh- Discard changes not
saved.
Edit :e fname Edit file named fname with-
out leaving vi.
Edit :n Edit next file without leaving
vi.
Edit :p Edit previous file without
leaving vi.
Edit :rew Edit previous file without
leaving vi.
Insert file :r fname Inserts all the text in the file
named "fname" at the cur-
rent cursor location.
Read/Insert :r! command Inserts the output of com-
mand at the current cursor
location.
read/Insert 10:r! command Inserts the output of com-
mand at Line number 10.
Insert file :r fname Inserts all the text in the file
named "fname" at the cur-
rent cursor location.
Insert text :45i! Sets up insert mode at Line
number 45.
append text :45a! Sets up append mode at Line
number 45.
Delete Lines :d Deletes current line.
Delete Line :45d Delete Line number 45.
Delete Lines :.,.+15d Delete all the lines between
current line and next 15 lines
Delete Lines and put in :.,.+15d f Delete all the lines between
buffer current line and next 15 lines
and put them in a buffer
named f

36
 EX commands in vi

Command Ex Syntax Operation

mark a Line :10ma f Mark the Line number 10
with a single lowercase char
f.Return later to the mark by
'f.
Shell Command 10,15:! command Execute command in a shell.
Treat the text between Line
number 10 and Line numner
15 as standard input to com-
mand, and replace these lines
with the output.
View :10z Set up a view with Line num-
ber 10 at the Top of screen.
View :10z+ Set up a view with Line num-
ber 10 at the Top of screen.
View :10z- Set up a view with Line
number 10 at the bottom of
screen.
View :100z. Set up a view with Line
number 100 at the center of
screen.
View :100zˆ Set up a view with Line
number 100 at the center of
screen and set current line as
Line number 100.
View :10z+ 5 Set up a view with Line num-
ber 10 at the Top of screen
and display next 5 lines from
Line number 10.
Status :f Shows current position and
the file name at the bottom
of the screen.It also speci-
fies if any changes are made
to the file since it has been
opened.

Options

Option Operation
! Specifies the command has to be executed forcefully.
destination Specifies the Line number where the text is to be pasted.Used with
Copy and Move commands.
count Specifies the number of time command is to be repeated.This number
always succeed the command.
fname Specifies that the object is a file name "fname".

37
Details

5.8.1 Vi Commands

Navigation to tags can be done via the following vi command:

ˆ]
Take the tag-name at the cursor position, look it up in the tag file(s) and navigate to
it, similar to the :ta ex command. The command also remembers the current file and
position on the tag stack.
The following command uses the tag stack to go back to the previous position. Older vi's
don't have it implemented:
ˆT
Get the previous position and file from the tag stack and return to it. The data is removed
from the file.

5.8.2 Command Line

Vi can also be started with a tag name instead of a file name. See the -t9 command line
option.

5.9 Shell escape

While one is working in vi there might arise a need to run another operating system com-
mand. In these modern days this is not a big issue. One can open another terminal window
and do as pleased. However, this is not necessary when working with vi. Vi, like many
of the older interactive Unix tools, contains features to run operating system commands
or start a command line interpreter (shell) from within the editor. This dates back to the
times when there were no graphical user interfaces and an editor like vi would take up
the complete screen of the terminal (a real terminal of course, not a terminal emulation).
Being able to run commands from vi spares one the need to first quit the editor just to look
something up, e.g. in a manual page. In addition, vi provides features to insert the text
output of other commands directly into the text under editing.

5.9.1 Ex Commands

The editor commands to run another command from within vi are in fact implemented as
ex commands. That is, they start with the familiar ':' in command mode. To execute one
command from within vi, one would type

:!command<CR>
<CR>

9 #Command_line_invocation

38
 Shell escape

At the end of the command one has to hit Return (the second <CR> shown above) to go
back to vi. Vi then repaints the screen and continues where editing was left. In order to
repeat the last command, one can simply type

:!!<CR>
<CR>

It is possible to append to a previous command by using :!!, followed by whatever should

be appended. For example, the second of the following two commands

:!ls<CR>
<CR>
:!! | more<CR>
<CR>

is actually equal to

:!ls | more<CR>
<CR>

(Note, ls is the Unix command to list a directory, more is the Unix command to paginate
output, so it doesn't just scroll off the screen). Once something is appended to a command,
it becomes part of the last remembered command. So in the example above, another

:!!<CR>
<CR>

would be equal to

:!ls | more<CR>
<CR>

and not

:!ls<CR>
<CR>

Two placeholders can be used in shell escapes to denote the current file name or the name
of the previously edited file name:
%
is a placeholder for the current file name,
#
is a placeholder for the previously edited file name.
For example, if one is editing some shell script and wants to try it out, one could type
the following commands to save the file (:w), set the file's attributes to executable (!chmod
...), and run it (!%):

39
Details

:w<CR>
:!chmod 755 %<CR>
<CR>
:!%<CR>
<CR>

If the file's name is, e.g. script.sh, the above would be equal to typing

:w<CR>
:!chmod 755 script.sh<CR>
<CR>
:!script.sh<CR>
<CR>

Instead of running a command from within vi it is also possible to start the shell from
within vi. vi has an own command for this, which looks up the user's default shell (e.g.
the Bourne shell or the C shell) and starts it. It is important to note that a new shell is
started. The user is not returned to the shell from which vi was started. The command is
called :sh, and it can be used as it follows:

<ESC>:sh<CR>
$ #shell commands, when done exit shells:
$ exit<CR>

5.9.2 Vi Commands

It is possible to filter all or parts of a text currently under editing through an external
program. The original text is then replaced with the output of the external command.
The classic example for this feature is the usage of the Unix text formatter fmt. vi itself
doesn't have any specific formating capabilities, however, by running the text or parts of it
through an external formater from within vi, the desired formatting is easily achieved. The
vi command for filtering text is ! (note, as opposed to the ex shell escape command, there
is no leading :). ! follows the usual vi command format. So one can specify the scope to
which it should apply. E.g. !! means to filter the current line, or !} means to filter the
current paragraph. The ! vi command has to be followed by by the name of the external
program to be used for filtering. E.g. in order to format the current paragraph with the
already mentioned Unix text formatter fmt, one would type

!}fmt<CR>

! can also be used to just insert the output of some external command into the currently
edited text. To do so, one would first create a new empty line (e.g. with o), and then use
!! to replace the empty line with the output of a command. For example,

o<ESC>!!ls<CR>

40
 Execute command from Buffer

would include a listing of the files in the current directory into the text under Unix.

5.10 Execute command from Buffer

This module is a stub10 . You can help Wikibooks by fixing it11 .

@b
Execute command stored in buffer b.

5.11 vi for Programmers

Classic vi provides a number of features which are useful for programmers. Vi was made by
programmers for programmers -- but at a time when programming was different. Classic
vi's programming support is, by today's standards, not too great, but of course still usable.
And it is still more convenient to use vi for editing programming code than any of the
...pad editors like notepad (Windows) or dtpad (CDE/Motif). vi probably works best on
Unix systems due to the many text filters that come with Unix and the ease with which
additional special-purpose filters can be scripted. Useful features in vi for programmers are:

5.11.1 Autoindent and manual Shifting of Lines

See Indenting and shifting12

5.11.2 Modelines

Modelines to set per-language defaults - if security is not an issue (see Modelines13 )

5.11.3 Tags for Navigating

See Tags14

5.11.4 Shell Escapes

See Shell escape15

• One way to use shell escapes is to run a makefile or the compiler from within vi. It is in
general a good idea to first save the current file before trying to compile it:

10 #Power_Users
11 http://en.wikibooks.org/wiki/Wikibooks:Find_or_fix_a_stub
12 #Indenting_and_shifting
13 #Modelines
14 #Tags
15 #Shell_escape

41
Details

<ESC>:w<CR>
:!make<CR>
or
<ESC>:w<CR>
:!cc %<CR>
and afterwards
<ESC>:w<CR>
:!!<CR>

• Another way is filter source code through an external command, e.g. through a comment-
reformator for the specific language. For example, the following command will filter the
current paragraph through a external comment-reformator called recomment (not a
standard Unix program, but available as a separate script).

!}recomment

See [1]16 for the recomment script for Unix.

5.11.5 Editing multiple Files

vi can be started with a list of files:

vi file1 file2 file3 ...

Combined with other Unix features, like file matching, this can be a powerful feature. E.g.
to open all C source code, including header files in a directory (.h), the following command
can be used:

vi *.[ch]

Or to find all files which contain a certain keyword and open them, something like

vi `grep -l Keyword *.txt`

can be used. Once vi has been started with a list of files it is possible to navigate within
the list with the following commands:
:n
next - Move to the next file in the file list
:rew
rewind - rewind the file list and open the first file in the list.
vi clones like vim typically provide more commands, e.g. to go back one file in the file list.

16 http://examples.oreilly.com/upt3/split/recomment

42
 vi for Programmers

5.11.6 Flip between two Files

• Flip between two files using # as the name of the last file. E.g. to flip between a C source
file and the corresponding header file.

:e x.c<CR>
:e x.h<CR>
some changes to x.h, then going back to x.c
<ESC>:w<CR>
:e#<CR>

• Flipping between two files using CTRL-ˆ. This is one of the forgotten vi commands.

5.11.7 The error(1) Program

The error(1) program on Unix can be used to capture error messages from compilers and
later jump from error message to error message in the editor. error's way of working is
archaic. It parses error messages from the compiler and inserts them as comments into the
source file in which the compiler detected the error. Since error marks error messages with
### and %%% in the source file, navigation can be done with vi commands like / and n.
There are two common ways to use error with vi:
1. From outside vi and letting error start vi. error can start vi on all files which produced
an error during compilation, using the -v flag:

$ cc *.c 2>&1 | error -v

# Notes:
# cc - the C compiler
# *.c - all C files in the current directory
# 2>&1 - Standard error output is redirected to normal standard output
# | - the output is feed to error as input

2. From inside vi, on the current file. First the file is saved, then it is tried to compile it,
processing potential error messages with error, then the potentially changed source file is
re-read (:e!), and finally the first mark is searched with /###:

first time
<ESC>:w<CR>
:!cc % 2>&1 | error<CR>
:e!<CR>
/###<CR>
and afterwards
<ESC>:w<CR>
:!!<CR>
:e!<CR>
/###<CR>

Note:
error is a horrible kludge and can really mess up source code and a version control system!
We recommend you try it at least once and form your own opinion. Also have a look at
error's man page first. vi clones like vim provide a much more sensible system. Here the
editor executes the compiler (or make(1s)) and captures the output of the compiler. The

43
Details

information is recorded in an error message file by vim. vim then allows to navigate the
source code by extracting file names and line numbers from the error message and jump
to these positions. This is the same mechanism as provided by IDEs.

5.11.8 Macros & Shortcuts

vi's provides the :map and :map! commands to define useful shortcuts and macros, and ab
to provide abbreviations.
Todo: Provide a few such macros?

qqI//<Esc>jq
places a comment at the beginning of a line and moves down

Is this (above) what you mean by macro?

5.12 nroff/troff Typesetting Support

5.12.1 Overview

vi provides support for editing text files for the Unix typesetters nroff and troff. The
most "common" usage for this typesetter these days is probably to write manual (man)
pages for Unix applications. The support for writing nroff/troff input text files is always
active, there is no special vi mode or option which needs to be turned on. Already from
this it can be concluded that there aren't too many nroff/troff specific operations in vi. In
fact, vi just provides simple ways to navigate between nroff/troff paragraphs and sections.
Nevertheless, these features help when editing nroff/troff files. nroff's/troff's text file format
is simple. Normal text and macros are mixed, where macros indicate how the text should
be formatted. A macro starts with a '.' in column one, followed by a one or two letter
macro name followed by optional macro arguments. A typical nroff/troff text file with
some macros might look like:

.SH "A SECTION HEADER"

Some text making up the first paragraph in the section.
More text in the paragraph.
.PP
A new paragraph has been started.
More text in this second paragraph.
.PP
Yet another paragraph.
.\"
.\" A comment infront of the next section header
.\"
.SH "SECTION HEADER 2"
Paragraph text.

To simplify navigation in such a text file vi knows the common macro names for sections
(the .SH in the above example) and paragraphs (the .PP in the example) and provides
commands to move to the next/previous section. The list of macro names is configurable
in vi. Several of the common vi features also help when editing nroff/troff text. E.g. shell

44
 nroff/troff Typesetting Support

escapes to run the typesetter from within vi. The following will format the current file with
the manual page macros:

<ESC>:w<CR>
:!nroff -man % | more<CR>

5.12.2 Options

The following options are used to define the nroff/troff macro names as known by vi. Like
all options, one changes them by using the :set ex command:

:set option[=value]

sections
List of macro names which vi interprets as section delimiters. Two consecutive characters
in the list form one macro name. Typically, vi's default contains .SH, .NH, .H, and .HU.
So the sections option reads like

sections=SHNHH HU

paragraphs
or
para
List of macro names which vi interprets as paragraph delimiters. Two consecutive char-
acters in the list form one macro name. vi's default typically contains .IP, .LP, .PP, .QP,
.PL, .Ib, .p. So the paragraphs option reads like

paragraphs=IPLPPPQPPLIbp

5.12.3 Vi Commands

When in command mode, the following commands relate to working on nroff/troff text:
[[
Moves to the previous section.
]]
Moves to the next section.
{
Moves to the previous paragraph.
}

45
Details

Moves to the next paragraph.

And, for completeness:
(
Moves to the previous sentence.
)
Moves to the next sentence.

46
6 Vi clones

The following editors are derived from or share the spirit of the original vi editor, coupled
to an easier to learn user interface:
• Vim1
• Basic navigation2
• Modes3
• Tips and Tricks4
• Useful things for programmers to know5
• Enhancing Vim6
• VimL Script language7
• vile8
• vipe9
• BusyBox vi10

1 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim
2 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/Basic_navigation
3 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/Modes
4 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/Tips_and_Tricks
http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/Useful_things_for_
5
programmers_to_know
6 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/Enhancing_Vim
7 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/VimL_Script_language
8 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/vile
9 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/vipe
10 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/BusyBox_vi

47
7 Vim

Figure 2 Graphical Vim under GTK2

49
Vim

7.1 Overview
• Basic navigation1
• Modes2
• Tips and Tricks3
• Useful things for programmers to know4
• Enhancing Vim5
• External Scripts6
• VimL Script language7
• Vim on Windows8

7.2 External links

Wikipedia9 has related information at Vim (text editor)10

• vim.org11 - documentation and many tips and plugins

• vi-improved.org12 - Wiki dedicated to vim
• vim tutorial13
• zzapper's Best of Vim Tips14
• Vim Recipes15 - Free cookbook.

http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/Basic_
1
navigation&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/
2
Modes&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/Tips_
3
and_Tricks&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/
4
Useful_things_for_programmers_to_know&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/
5
Enhancing_Vim&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/
6
External_Scripts&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/VimL_
7
Script_language&amp;action=edit&amp;redlink=1
http://en.wikibooks.org/w/index.php?title=Learning_the_vi_Editor/Print_version/Vim_
8
on_Windows&amp;action=edit&amp;redlink=1
9 http://en.wikibooks.org//en.wikipedia.org/wiki/
10 http://en.wikibooks.org//en.wikipedia.org/wiki/Vim_(text_editor)
11 http://www.vim.org
12 http://www.vi-improved.org
13 http://www.yolinux.com/TUTORIALS/LinuxTutorialAdvanced_vi.html
14 http://www.rayninfo.co.uk/vimtips.html
15 http://vim.runpaint.org/

50
 Basic navigation

7.3 Basic navigation

Basic navigation in vim is covered below.

7.3.1 Moving around

We can move around in the editor by first entering command mode, and then using the
<h>, <j>, <k>, and <l> keys.
Note
your arrow keys may be set up to work, and you can use them if you like, but for proficiency
and for advanced work later, you should learn to use the letter keys.
• The <h> key, in command mode, moves the cursor one character left.
• The <j> key, in command mode, moves the cursor one character down.
• The <k> key, in command mode, moves the cursor one character up.
• The <l> key, in command mode, moves the cursor one character right.
If you have trouble remembering this, keep in mind that <h> is leftmost, the letter
<j>goes down below the line, the letter <k>pokes up above the line, and the <l> key is
rightmost. (J also resembles an arrow pointing downward, if you squint a bit.) After you
have moved the cursor using those keys, you can enter insert mode again by pressing <i>.
When you do this, you insert text at the cursor, inserting text between the character to the
left of the cursor and the current position of the cursor. Let's practice this in an exercise.

7.3.2 VIM Help system

vim is a very feature rich application. Unlike the 'vi' editor it includes a help system.
Because the help system will allow you to teach yourself much more than any book on vim
possibly could, you will benefit from the power of the vim editor much more if you learn to
use it. On a normal vim installation you should be able to start the online help by pressing
the <HELP> key . If your keyboard does not feature a <HELP> key then you can try
<F1> instead. (Some system administrators may have changed how vim behaves. If you
cannot get into vim's help system with these commands, perhaps your administrator can
help.)

:help

Start vim and enter command mode by pressing escape. To get help on any command
simply type :help command. For example, if you would like to learn all the different ways
the :x command can be used you could type :h x. To move around in the help files the
same keys work, <h>, <j>, <k>, <l>. To leave the help files type :quit. If you know you
want to do something, but you aren't sure what the command might be you can type partial
commands like this :help cut. To learn to switch text from upper case to lower case you
could type :help lowercase When you search for help on any subject, vim will (normally
by default) create a window (buffer) which you can navigate just like any window in vim.

51
Vim

You can close the help window by typing :quit or :q and pressing enter. The default help
file (shown when you type "help") explains basic navigation for vim and for vim's help files.

7.4 Modes

VIM offers more modes than vi (which offers only the "normal", "insert" and "command–
line" modes). Theses additional modes make VIM more powerful and easier to use; because
of this, vim users should at least be aware that they exist. (NOTE: If you ever enter a mode
you are unfamiliar with, you can usually press ESC to get back to normal mode.) Here a
short overview of each mode available in vim:
Name Description help page
normal For navigation and manipulation :help Normal-mode
of text. This is the mode that vim
will usually start in, which you can
usually get back to with ESC.
insert For inserting new text. The main :help Insert-mode
difference from vi is that many im-
portant "normal" commands are
also available in insert mode - pro-
vided you have a keyboard with
enough meta keys (such as Ctrl,
Alt, Windows-key, etc.).
visual For navigation and manipulation :help visual-mode
of text selections, this mode allows
you to perform most normal com-
mands, and a few extra commands,
on selected text.
select Similar to visual but with a more :help select-mode
MS-Window like behavior.
command-line For entering editor commands - :help Command-line-mode
like the help command in the 3rd
column.
Ex-mode Similar to the command-line mode :help Ex-mode
but optimized for batch processing.

Each mode is described below.

7.4.1 insert (and replace)

In insert mode you can type new text. In classic vi the insert mode was just that: insert
text and nothing else. Vim makes use of many meta keys on modern keyboards; with

52
 Modes

a correctly configured vim, cursor keys should work in insert mode. Insert mode can be
reached in several ways, but some of the most common ones are <a> (append after cursor),
<i> (insert before cursor), <A> (append at end of line), <I> (insert at beginning of line), <C>
(change to end of line), and <s> (substitute characters). If you wish to edit text by selecting
and replacing, as is common in many GUI-based editors, <C> does nicely. The selected
text is deleted before entering insert mode.

7.4.2 normal (command)

Unless you use the evim interface this is the standard mode for vim (vim starts in normal
mode). Everything the user types in normal mode is interpreted as commands (including
those which switch the user to other modes). If vim is started as evim (evim on the
command line), vim keeps the user in insert mode all the time. Normal mode can be
reached for individual commands by pressing <Ctrl-O> followed by the desired command.
After one command, the user is returned to insert mode. (Each normal command must be
started first by pressing <Ctrl-O>).

7.4.3 visual

There are three different types of highlighting in visual mode. Each allows the user to
highlight text in different ways. Commands that normally only affect one character, line,
or area will affect the highlighted text (such as changing text to uppercase (<Ctrl-˜>),
deleting text (<d>), indenting lines (>>, <<, and =), and so forth). There are three
(sub)types of the visual modes which are visual, block-visual , and linewise-visual

plain visual mode

The plain visual mode is started by pressing 'v' in normal mode. At any point, pressing
ESC or <v> will leave VISUAL mode without performing an operation. Movement com-
mands change the selection area, while other commands will generally perform the expected
operation on the text (there are some exceptions where the behavior will change or where
the command won't work, but if it doesn't do what you hoped you can always undo with
<u>).

block visual mode

block-visual is started by pressing <Ctrl-V> (or <Ctrl-Q> in some windows versions.

If neither of these works use ":help visual-block" to find out how). Visual blocks always
maintain a rectangular selection, highlighting only specific columns of characters over mul-
tiple lines. In this following example the user wants to put a dash in each phone number
between the second and third number fields: The user first moves the cursor to the top of
the column (you could start at the bottom if you want).

53
Vim

Figure 3

Next, press <Ctrl-V>. This puts you in block-visual mode (VISUAL BLOCK appears at
the bottom to tell you what visual mode you're in). Next, move down to the bottom desired
line. You can see a single column highlighted in this example, but you could move right or
left and highlight more columns.

Figure 4

In this case, the user wants to change the spaces to dashes. To change text, we press 'c'.
The spaces all disappear, and the changes are shown only in the current line while we type:

Figure 5

54
 Modes

when we press <ESC>, though, the change is duplicated on all the lines.

Figure 6

(Note: if you simply want to insert text rather than change it, you will need to use '<I>'
or '<A>' rather than '<i>' or '<a>'.)

linewise visual mode

In linewise-visual mode, enterd by <Shift-V>, entire lines are highlighted. Otherwise, it

generally works like the plain visual mode.

7.4.4 select

like the visual mode but with more CUA16 like behavior. This means that if you type a
single character it replaces the selection. Of course you lose all the one key operation on
selection like <U> to make a selection uppercase. This mode is usually activated by:

:behave mswin

which is default for MS-Windows installations. You can get the normal mode with

:behave xterm

7.4.5 command-line

Within the command-line you can run Ex17 commands, enter search patterns, and enter
filter commands. At the bottom a command line appears where you can enter the command.
Unlike vi - vim supports cursor keys which makes entering commands a lot easier. After one
command the editor returns into normal mode. You can enter an Ex command by typing
a : in normal mode. Some examples include:

16 http://en.wikibooks.org//en.wikipedia.org/wiki/Common_User_Access
17 http://en.wikibooks.org//en.wikipedia.org/wiki/Ex_(editor)

55
Vim

:set number
:substitute/search/replace/ig

You can enter a search pattern by typing / to search forward, or ? to search backward.
You can use vim's expanded regular expressions in these search patterns. For example,

/word

will jump to the next occurrence of "word" (even if it is "sword" or "wordlessly"), but

/\<word\>

will jump only to a complete word "word" (not "sword" or "wordless"). You can enter a
filter by typing ! followed by a motion command, then a shell command to run on the text
captured by the motion. For example, typing

!22jsort

in Linux will sort the current and 22 following lines with the sort system command. The
same thing can be done with

:.,.+22!sort

As a matter of fact, vim creates the above command for you if you follow the first example!

7.4.6 Ex-mode

The Ex mode is similar to the command line mode as it also allows you to enter Ex18
commands. Unlike the command-line mode you won't return to normal mode automatically.
You can enter an Ex command by typing a Q in normal mode and leave it again with the
:visual command. Note that the Ex mode is designed for Batch processing and as such
won't support mappings or command-line editing. For batch processing the Ex-mode is
normally started from outside by calling the editor with the "-E" option. Here is a real live
example from the RPM Package Manager19 specification:

vim -E -s Makefile <<-EOF

:%substitute/CFLAGS = -g$/CFLAGS =-fPIC -DPIC -g/
:%substitute/CFLAGS =$/CFLAGS =-fPIC -DPIC/
:%substitute/ADAFLAGS =$/ADAFLAGS =-fPIC -DPIC/
:update
:quit
EOF

18 http://en.wikibooks.org//en.wikipedia.org/wiki/Ex_(editor)
19 http://en.wikibooks.org//en.wikipedia.org/wiki/RPM_Package_Manager

56
 Modes

The RPM uses Bash20 as script language which make the example a little difficult to
understand as two different script languages are mixed in one file.
vim -E -s
starts vim in improved Ex mode which allows for more advanced commands than the vi
compatible Ex-mode (which is started with vim -e -s).
<<-EOF
tells bash to copy all lines that follow into the standard input of the external program just
started. The '-' tells the shell to strip the tab characters.
:
are lines with Ex commands which vim will execute. The : is optional but helpful when
two script languages are mixed in one file
:update
A beginners mistake is to forget to actually save the file after the change - falsely assuming
that this happens automatically.
:quit
Last not least: don't forget to actually exit vim again.
EOF
marks the end of the standard input redirection - from now on bash will execute the
command itself again.
If your shell does not allow such nifty redirection of standard input then you can always
use a more classic approach to I/O redirection using two files:

vim -E -s Makefile <Makefile-Fix1.vim

And if have no standard input redirection available then you can try the -c option in
combination with the source command:

vim -E -s -c "source Makefile-Fix1.vim" Makefile

With the improved Ex mode many tasks classically performed by awk21 or sed22 can be
done with vim and often better so:
• awk23 and sed24 are stream oriented - they only read the file forward from beginning to
end while vim is buffer oriented - you can move forward and backward in the file as you
like.

20 http://en.wikibooks.org//en.wikipedia.org/wiki/Bash
21 http://en.wikibooks.org//en.wikipedia.org/wiki/AWK_programming_language
22 http://en.wikibooks.org//en.wikipedia.org/wiki/sed
23 http://en.wikibooks.org//en.wikipedia.org/wiki/AWK_programming_language
24 http://en.wikibooks.org//en.wikipedia.org/wiki/sed

57
Vim

• vim's regular expressions25 are more powerful than awk26 's and sed27 's expressions -
for example vim can match over several lines and supports zero matches.

The Vim Tipbook is a collection of tips, hints and HowTos for using the Vim text editor28 .
It is an outgrowth of the Vim tips database29 in a more flexible format, and also includes
some helpful posts from the Vim mailing lists30 . For information on the general use of
Vim, please see the Learning the vi Editor/Vim31 .

7.5 About this Book

7.5.1 Tips for Editing

• Where possible, extensive personal configurations should be avoided. Keep suggestions
within the scope of a single tip. You may wish to link to several other tips that might
be used alongside, much in the same way a food cookbook would suggest dishes that go
well together.
• Always provide enough information so that a tip can be used from Vim's default com-
patible settings.

7.5.2 Conventions Used

<c>
A single character, such as 'a' or '1'.
<ESC>, <Ctrl-[>
Indicates that the Escape (Esc) key on your keyboard should be pressed, which is identical
to Control and '['.
<CR>
Indicates that the Return (Enter) key should be pressed.
<TAB>
Indicates that the Tabulator key should be pressed
<Ctrl-x>, <C-x>
Indicates that the Control key and the 'x' key should be pressed simultaneously. 'x' can
be almost any other key on your keyboard.

25 http://en.wikibooks.org//en.wikipedia.org/wiki/Regular_expression
26 http://en.wikibooks.org//en.wikipedia.org/wiki/AWK_programming_language
27 http://en.wikibooks.org//en.wikipedia.org/wiki/sed
28 http://www.vim.org/
29 http://vim.wikia.com/
30 http://www.vim.org/maillist.php
31 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim

58
 Vim Help

<Shift-x>, <S-x>, <X>

Indicates that the Shift key and the 'x' key should be pressed simultaneously
<Meta-x>, <M-x>
Indicates that the Meta or Alt key and the 'x' key should be pressed simultaneously.
:quit, :q
An Ex command. started with <:>, followed by the command and ends with <CR>. For
many Ex commands there is a long form (:quit) and a short form (:q).
:set nocompatible
represents a setting.
strlen ()
represents a function.
/pattern/, ?pattern?
A Search pattern. Search pattern in vi are regular expressions32 .
:ranges/search/replace/options, :global /pattern/ delete
A Search pattern combined with an Ex command.
All commands in vi are case sensitive.

Where a series of commands are required to be entered, these might be listed in a prefor-
matted block:

{{Vi/Ex|set}} {{Vi/set|number}}
{{Vi/Ex|set}} {{Vi/set|textwidth=70}}
{{Vi/Ex|set}} {{Vi/set|wrap}}

Which will produce the following formatted text:

set number
set textwidth=70
set wrap

7.6 Vim Help

If you are new to vi, try the vimtutor command. It's an excellent guide for the beginner.
Vim has an extensive help system. EVERYTHING is covered. This system is so extensive,
however, that finding the needed information is sometimes akin to finding one's own little
needle in a huge stack of hay. But even for that, there are Vim tools:

32 http://en.wikibooks.org//en.wikipedia.org/wiki/regular_expression

59
Vim

• (assuming 'nocompatible' is already set)

set wildmenu

• Help tag completion: if you think 'foo' is part of something which has a hyperlink in the
help system, use

help foo<Tab>

where <Tab> means "hit the Tab key", and if there is only one possible completion Vim
fills it in for you; if there is more than one the bottom status line is replaced by a menu
which can be navigated by hitting the <Left> and <Right> arrow keys; accept a selection
by hitting <Enter>, abort by hitting <Esc>.
• The :helpgrep function: if you think that some regular expression describe text you
want to search for in the text of all the help files, use

helpgrep <pattern>

where <pattern> is a Vim regular expression, like what you can use after / or ? . It may
take some time for Vim to look up all its help files, and it may or may not display interim
information which may require you to hit Enter to clear the |more-prompt| (q.v.) When
the blinking cursor reappears in your editfile, it means Vim has compiled the list of all
help locations where your regexp matches. See them by means of the following

cfirst or :cr
cnext or :cn
cprevious or :cprev or :cN
clast or :cla

7.7 Inserting Text From a File or Register

If your text is in a file on its own, you can use :r with a line number (the number of the
line after which to insert, or 0 for "before first line", or . for "after cursor line", or $ for
"after last line"; default is after cursor line) in the "range" position, i.e. just before the r.
The file name comes as an argument at the end. Example (after line 5):

5r ˜/template.txt

If your text is in a register, you can use :put with a line number (again) in the range
position and the register name (including ", which must be escaped as \", for the default
register; or + for the system clipboard) after the :put. Example (before cursor line):

.-1put \"

You can also insert a string directly using :put and direct assignment:

60
 Full Screen Mode

:put ='This is text to insert.'

See

:help :read
:help :put

7.8 Full Screen Mode

To achieve a full screen editing window on any version of gvim you can do:

:set go-=m go-=T go-=l go-=L go-=r go-=R go-=b go-=F

:set lines=999 columns=999

• 'guioptions': We remove the flags one-by-one to avoid problems if they appear in the
option in a different order, or if some of them do not appear at all. By choosing which
ones to remove (or not) you can customize your own flavour of "full-screen Vim".

m when present, menu bar is present

T when present, toolbar is present on versions which support it (W32, GTK1,
GTK2, Motif, Photon, kvim)
l when present, left scrollbar is always present
L when present, left scrollbar is present if there is a vertical split
r when present, right scrollbar is always present
R when present, right scrollbar is present if there is a vertical split
b when present, bottom scrollbar is present
F when present, gvim (Motif) will display a footer

• 'lines', 'columns': setting them to a large value will maximize the window.
For more, see:

:help 'guioptions'
:help 'lines'
:help 'columns'

7.9 Useful things for programmers to know

There are quite a few things programmers ought to know about vim that will make their
experience that much easier. Programmers can save hours and weeks of man-hours over the
long haul with effective editors. Here are some tricks and tools that vim provides. With the

61
Vim

time you save, you might speed up your work and have some extra time for a quick Quake
deathmatch or eventually increase your productivity to help justify a larger wage increase.

7.9.1 Word, variable, function, and line completion

Sometimes the word you're typing is really long. You shouldn't have to type it all out. If
it's in your dictionary, or in the current file, you can save a lot of time with <Ctrl-P> and
<Ctrl-N>. Let's take a closer look at how this works:
• Word/variable/function name Completion
Generally, any word in the current file, or any of the other files (buffers) you are editing in
the same instance of vim, will match for completion. This means once you've typed it once,
you can type the first couple letters next time, and press Ctrl-N (several times if you need
to cycle through several options) until you find the word you're looking for. Technically,
this isn't true. You can tell vim where to look for words in the complete function. In
Vim 7, the complete function will generally be set to figure out a lot about what you're
typing — drawing information from function libraries (As of the last update on this book,
the author knows C and C++ are supported by default). Keyword completion since Vim 7
will also show a popup menu. You can also define a dictionary of your own for completion.
For more detail, you might want to consult the vim help system ":help complete", ":help
complete-functions", and so forth. Example 1 As an example, you might edit a C program
file, "blah.c". You want a function that starts with "str", but you can't remember what it
is. You first type "str". It remains regular text until you press <Ctrl-P> or <Ctrl-N>. In
vim 7, you will see a menu appear, like this:

Figure 7

You can use <Ctrl-N> and <Ctrl-P> to cycle through the entries shown. In Vim versions 7
and higher, you can actually use the arrow keys to cycle through entries in the menu. There
might be too many to show on the screen at once (you will notice the black box on the right
represents a scroll position on a gray bar--not all the options are shown on-screen in this
example.) The files from which the options were drawn are shown, to help you decide if it's
what you're looking for. (You will also notice in this example that words show up from files

62
 Useful things for programmers to know

the author has recently edited, such as 'strict' from 'cgi-bin/ftplist.pl' -- we certainly don't
want that.) Example 2 Now, suppose you need the sine function, but you know it has an
odd name. You type sin and press <Ctrl-P>, and it doesn't show up:

Figure 8

You're not out of luck, you just haven't included the math library yet. All you have to do
is add the line

#include <math.h>

and try again. This time you see the function name you wanted (it wasn't easy to remember
since it has an odd name)

Figure 9

63
Vim

• Line Completion
You can complete entire lines if you need to, though this is less likely. <Ctrl-X>, <Ctrl-L>
will load the matching lines (white space matters!) into the menu, and from there you can
move forward and backward with arrows or <Ctrl-P> and <Ctrl-N> (for Previous and
Next)

7.9.2 Indentation

Vim can figure out how to indent most common filetypes. For most of the popular program-
ming languages, vim can detect the file type by the filename's extension, and from there it
will decide how to indent your files. If you don't see it automatically creating the proper
indentation for you, try

:filetype indent plugin on

In the GUI version, you might be able to turn it on at the same time you turn syntax
highlighting on for that file. Choose Syntax -> on/off for this file, or Syntax -> Show
Filetypes in menu, then go back into the syntax menu and choose the appropriate file type
from the list. You might want to put the above-mentioned ":filetype ..." line in your vimrc
file (discussed earlier) and open your program file again, though this really shouldn't be
necessary. If you still have problems, you might want to check that your runtimepath
variable is set properly (:help runtimepath). It's also possible (though unlikely) that your
programming language is rare enough that nobody has written an indent plugin for it yet.
The official site for vim, vim.org, may have an indent plugin file that meets your needs, even
if it didn't come with your default installation of vim. For those times when you've pasted
some text in and the indentation is wrong, (your indent plugin must be loaded), you can
use the = command. It's probably easiest to type '10=' to re-indent the next ten lines, or to
use visual mode and press <=>. If you want, you can indent lines with ">>" and unindent
them with "<<". If you are in insert mode, use <Ctrl-D> and <Ctrl-T> to change the
indentation of the line (<Ctrl-D> decreases indentation by one level and Ctrl-T increases
it by one level) If you can't manage to get filetype specific indentation working, you might
try setting one or more of the following options: smartindent, autoindent, cindent, and
copyindent. Chances are these won't work completely right, so <Ctrl-D> and <Ctrl-T>
will be more important. To turn autoindent on, type :set autoindent. To turn autoindent
off, type :set noautoindent

7.9.3 Repeating commands, or Performing the Same Command Many

Times

If you feel comfortable with vim, you might record your keystrokes to an invisible register
and repeat them later. It might be easier to write a vim script, or even filter your file with
another program (such as a perl script) for complex enough actions. That said, sometimes
it really is easier to record a command and reuse it, or even perform it on any matching
line. For more advanced execution patterns (e.g. executing one command on the whole
file), see below. You might also consider creating a mapping (discussed below) or running
a :global command (also discussed below).

64
 Useful things for programmers to know

Repeating the last single command

Suppose I want to put a semicolon on the end of a few lines, where I forgot:

cout << "Hello world\n"

i = j + k
cout << "i is " << i << endl

On the first line, I type A; followed by the ESC key. I move to the next line and press . (the
period tells vim to repeat the last command -- don't worry, it doesn't duplicate movement
commands).

Recording a command macro

Vim has a powerful form of command repetition available through the use of macros. A
user can record a series of commands into a register and run the register as a macro. Macros
can be recorded into any of 26 registers (a through z). To start recording a macro, press
q followed by a register name (any letter a through z -- Registers are defined by only one
letter of the alphabet, so only one character may be used as the storage buffer). After
performing a series of commands, finish recording the command macro by pressing q again.
For example to start recording into register z, press qz and press q again to finish recording.
To run a macro from a register, run it with @x where x is the register with the desired macro
recording. Register q is the default register for macro recordings, so if you have recorded
into register q you may simply type @@ to run the macro. (Note: Keep in mind that scripts
or mappings may sometimes use an arbitrary register--so if you have a conflict, especially
with a third party script or mapping, you should consider recording to a different register.
You can view the contents of a register with the :registers command.)

Example 1
As a simple example, suppose you have the following lines in the buffer, and you want each
line to repeat the last word on the line. Initially, the buffer looks like this:

The quick brown fox jumps over the lazy dog

The sly gray fox circles around the unsuspecting rabbit
The slow gray fox crawls under the rotting fence

And you want the buffer to look like this: (where additions are highlighted in bold)

The quick brown fox jumps over the lazy dog dog
The sly gray fox circles around the unsuspecting rabbit rabbit
The slow gray fox crawls under the rotting fence fence

To do this, start recording into the default register with qq, then append the line with A,
type a space, then Ctrl-P, then press the ESC key. To finish recording, press q again. Now
the macro has been recorded into register q. To repeat the command, move down one line,
and repeat the command by typing @@ or @q. You can use @@ to run this macro because q
is the default register for macros.

65
Vim

Example 2
In another example, suppose you have the following lines in the register:

The quick brown fox jumps over the lazy dog dog
The sly gray fox circles around the unsuspecting rabbit rabbit
The slow gray fox crawls under the rotting fence fence

and you want to put HTML tags around the animal names (fox, dog and rabbit) to make
them bold (eg, fox needs to become <b>fox </b>). Suppose you want to use register a
for the macro. To start, move the cursor onto the first animal name--fox. Place the cursor
somewhere on the word, such as on the 'o' in fox. Begin recording by typing qa. Next,
delete the word into register b by typing "bdaw (see :help awand :help dand :help "for
an explanation of this command). Next, enter insert mode by typing i and then type <b>
followed by Ctrl-O, then "bP (see :help i_CTRL-ofor an explanation of this command).
Next, type </b> and press ESC. Finally, stop the recording by typing q. To repeat the
command, move the cursor over the next word you wanted to surround with the HTML
tags and run the macro by typing @a. You can see what the macro looks like by examining
the register. To do so, you may run the command :registers a. In this case, vim will
show the following output:

--- Registers ---

"a "bdawi<b>ˆO"bP</b>ˆ[

Note that a recording remembers all your movement commands, so you will need to put
the cursor in the correct starting position before you begin recording.

Example 2b: fixing a macro

Suppose you made a minor mistake in your macro, but the macro is rather complex and
you don't want to repeat all those commands again. We would like to modify the contents
of a register. In order to do this, we use the feature that typing "x in the escape mode
uses the contents of register x for the next delete, yank, or put. Assume that we are using
register a,
• create a new line (this line will be eventually deleted) and put the register's contents
on the line with "ap in the escape mode. This command is pasting (note the p in the
command) the contents of register a (via "a) into the line.
• Make the modifications as needed, and
• put the modified line back into register a by moving to the start of the line (with |) and
typing "ad$ in the escape mode. (Do not use "aD because D will capture the newline
character in the buffer as well.)
• Test the macro to be sure it is working properly, then use it as needed.

Executing a command macro

To execute a macro stored in register q once, you can just press @q. But often, you would
not write a macro to execute it only once and here the full power of Vim kicks in. To apply
the command to the lines 23 through 42, use :23,42norm! @q, to apply it to all lines in your
document use you can use :%norm! @q. The same also works for single commands that you

66
 Enhancing VIM

can access with the dot. If you have forgotten semicolons on some lines in your document,
you would just execute A; followed by the ESC key. Then the command :23,42norm! .
will apply the same action to the lines 23 to 42 and insert a semicolon at the end of each
line.

Mapping a command

One of the advantages of mapping a new command is that you can put the mapping into
your vimrc file for use later. I have the following mapping

map <C-k> :!%:p<C-m>

What this does is maps the normal command Ctrl-K to run the current file as a script. You
could also perform the second "Recording a command" exercise from above (encase a word
in bold tags) with this mapping:

map <C-x>b "bdawi<b><C-o>"bp</b><ESC>

Note that in this case, I can get away with "<b>" because it doesn't match a special
character name. However, if I needed to avoid a conflict (if I wanted to map an insertion
of "<ESC>") I would use <lt> and <gt> for the less than and greater-than symbols.
(See ":help key-codes") If you want to map a command for insert mode, use imap instead
of map. If you want to prevent any of the commands in your map definitions from
being interpreted in other mappings, use noremap (or inoremap for insert mode inoremap
meaning insert mode nore-map)

7.10 Enhancing VIM

7.10.1 The .vimrc file

You can make a configuration-file called .vimrc in your home directory and save any partic-
ular settings. The existence of a vimrc has the side effect of making vim enable all of vim's
incompatible changes to vi, making it more user-friendly. The name of the file depends on
the operation system and userinterface used:

.vimrc Text-User-Interface on UNIX and VMS

_vimrc Text-User-Interface on MS-Windows and VMS
.gvimrc Graphical-User-Interface on UNIX and VMS
_gvimrc Graphical-User-Interface on MS-Windows and VMS

67
Vim

The alternatives with the underscore are for compatiblity with older filesystem. If you use
vim on several operating system and use a modern MS-Windows filesystem you don't have
to maintain two configurations files. it is perfectly Ok to set _vimrc to:

source ˜/.vimrc

and do all your configurations in .vimrc. This is an example .vimrc file here:

"Everything after a double quote is a comment.

"Wrap text after 72 characters

set textwidth=72

"Set tabs to 4 spaces

set tabstop=4
set shiftwidth=4
set stselect=4
set expandtab

"tell vim I use a dark background. Syntax highlighting (color coded text) will
adjust to more appropriate colors.
set background=dark

"misc overwrites of default color highlighting.

hi Comment ctermfg=DarkGreen
hi String ctermfg=DarkMagenta
hi pythonPreCondit ctermfg=Green

"make sure that bottom status bar is running.

set ruler
set laststatus=2

"make a mapping for "Q" which will reformat the current paragraph, comment,
"or code block according to the formatoptions setting:
map Q gqap

7.10.2 Syntax Highlighting

Syntax highighting is what allows you to highlight program code and other files for better
readability, using colorization, bold, and other font modifications. You may want to write
simple syntax highlighting statements for easily detected patterns in your file. That said,
if you are thinking you need syntax highlighting for html, don't worry: most users do not
need to define a syntax highlighting file for common filetypes--most of the file types common
developers are interested have already been given a default syntax highlighting definition
with vim. Even if it doesn't come with vim, you can usually find someone who has shared
their work on vim.org. However, if you need to write something simple, this section is for
you. (If you need a syntax highlighting definition that will correctly show perl code even
inside an HTML "pre" tag inside a perl print statement within a shell heredoc in a shell
script, you're probably out of luck and this section probably won't meet your needs--but
you might as well search vim.org, just in case someone has done it for you already). Syntax
Highlighting is one of the most powerful features of VIM. However, it can also be one of
the most difficult things to set up--if you don't know what you're doing (or if you just don't
have the patience, or if you're dealing with complex program language grammars). So lets
have a look at some easy highlighting definitions:

68
 Enhancing VIM

Lesson 1: Highlight Tabs

... or how to highlight a special characters

Say you need to know where in your file are tabs and where are spaces. With the following
highlight you make tabs visible:

:syntax match Special "\t"

syntax match matches a regular expression and applies the given color to it. In this case
it is the color "Special". You must make sure that the color "Special" has a non standard
background - otherwise you won't see a difference:

:highlight Special guifg=SlateBlue guibg=GhostWhite

You can also create a map in your .vimrc - so you can always activate the tab highlight:

:nnoremap <F12><Tab> :syntax match Special "\t"<CR>

:inoremap <F12><Tab> <C-O>:syntax match Special "\t"<CR>

Another approach is to use listchars. These would be tabs, trailing spaces and line ends.
Note the use of ">-" instead of the default "ˆI". That prevents the layout change when
showing/hidding listchars:

:set lcs=tab:>-,trail:%,eol:$ <CR>

:map <F12> :set list!<CR>

Lesson 2: Highlight Space errors

... or how to highlight spaces at the end of line

... or how to find spaces and/or tabs

:syntax match Error "\s\+$"

Lesson 3: Highlight Tab errors

... or how to not highlight characters serving as delimiter

Knowing where tabs are is good. But what about spaces before tabs? They just waste
space in your file. The following highlight will show them to you:

:syntax match Error " \+\t"me=e-1

The regular expression " \+\t" searches for one or more space followed by a tab. That
alone would solve the problem but would highlight the tab as error as well. Even better
would be if we could highlight only the spaces and leave the tab as it is. And indeed this is

69
Vim

possible and done by the me=e-1. Basically it says: End the highlight one character before
the last character found.

Lesson 4: Highlight Line length

... or how to highlight at a specific column

... or how to highlight inside other patterns
... or how to allow other pattern inside
The following match will highlight the column 78 when the line is 78 characters long. This
can serve as a warning when you have a line which is longer than you wish it to be. Of
course, such a highlight should not interfere with any other highlight you might use:

:syntax match Error "\(ˆ.\{79\}\)\@<=." contains=ALL containedin=ALL

Here is a description of how it works:

1. The regular expression \(ˆ.\{79}\) searches for exactly 79 characters from the be-
ginning of the line ˆ and group \( \) the result.
2. \@<= will now "zero match" the group from 1. "zero match" means the text must be
present, but is ignored once found.
3. with . one more character is matched. This character is highlighted using the Error
colour.
4. With contains=ALL we allow other highlight patterns to start inside our pattern.
5. containedin=ALL we allow our highlight pattern to start inside another pattern.
An alternative method is suggested by the vim help system. This pair of commands will
highlight all characters in virtual column 79 and more:

:highlight rightMargin ctermfg=lightblue

:match rightMargin /.\%>79v/

And this will highlight only column 79:

:highlight col79 ctermbg=red

:highlight col79 guibg=red
:match col79 /\%<80v.\%>79v/

Note the use of two items to also match a character that occupies more than one virtual
column, such as a TAB. In the last example, a separate ctermbg and guibg definition was
added so that col79 does something in both vim and gvim.

7.10.3 Omni Completion

From version 7 onwards vim supports omni completions. This form of completions should
work over several files and support all the twirks of a programming language. However, for
it to work you need an appropiate "*complete.vim" script in your "autoload/" directory.

70
 Enhancing VIM

This script must define a function called ...#Complete which does all the completion work
for the programming language at hand. However writing a useful complete function can be
a diffcult task. All the provided complete functions span several hundred lines of code. Here
a simple implementation used for the Ada programming language33 described in detail so
you can create your own. This implementation need a "tags" file which - for ada - you can
create with gnat xref -v. The full version can be download from the vim.org side34

Step by Step walkthrough

Set completion with <C-X> <C-O> to autoloaded function. This check is in place in case
this script is sourced directly instead of using the autoload feature.

if exists ('+omnifunc') && &omnifunc == ""

setlocal omnifunc=adacomplete#Complete
endif

Omnicompletion and autoload won't work with any vim less then 7.00.

if version < 700

finish
endif

All complete#Complete functions have to cover two options: a:findstart == 1 and

a:findstart != 1.

function adacomplete#Complete (findstart, base)

Findstart equals 1
When a:findstart == 1 then we have to find out how many characters left of the cursor
could be a part of an completion:

if a:findstart == 1

For our simple example finding the beginning of the word is pretty simple. We look left
until we find a character wich cannot be part of a word. For most languages searching for
“\i” should do the trick. However, for Ada we want to expand Attributes35 as well - hence
we add “'” to the list of word characters.

let line = getline ('.')

let start = col ('.') - 1
while start > 0 && line[start - 1] =˜ '\i\|'''
let start -= 1
endwhile

33 http://en.wikibooks.org/wiki/Ada_Programming
34 http://www.vim.org/scripts/script.php?script_id=1609
35 http://en.wikibooks.org/wiki/Ada_Programming/Attributes

71
Vim

return start

Findstart not equal 1

When a:findstart != 1 then we need to find possible completions for a:base. There are
two option open to return the found completions:
1. returning them all as a List with return.
2. calling complete_add for each completion found.
You can also use a combination of both - they will be merged then - so beware not to create
duplicates. A completion can either be a String or a Directory. In this example we use
complete_add.

else

The search pattern should look for a:base at the beginning of the text matched.

let l:Pattern = 'ˆ' . a:base . '.*$'

In a first step we add all known Ada Keywords36 , Pragmas37 , Attributes38 and Types39 .
They have been prepared as a List of Directorys by the Ada file-type plugin40 . All we
have to to is iterate over the list and add all where the Directory entry “word” matches the
pattern.

if exists ('g:Ada_Keywords')
for Tag_Item in g:Ada_Keywords
if l:Tag_Item['word'] =˜? l:Pattern

Add the value - incl. simple error handling.

if complete_add (l:Tag_Item) == 0
return []
endif
{{vi/Ex|if} complete_check ()
return []
endif
endif
endfor
endif

Searching for matches

Here the real work is done: We search for matches inside the tag file. Of course you need

36 http://en.wikibooks.org/wiki/Ada_Programming/Keywords
37 http://en.wikibooks.org/wiki/Ada_Programming/Pragmas
38 http://en.wikibooks.org/wiki/Ada_Programming/Attributes
39 http://en.wikibooks.org/wiki/Ada_Programming/Types
40 http://www.vim.org/scripts/script.php?script_id=1548

72
 Enhancing VIM

a tag file first. There are many tools to create vim compatible tag files. Just have a look
around for one.

let l:Tag_List = taglist (l:Pattern)

Again we need to iterate over all List elements found.

for Tag_Item in l:Tag_List

if l:Tag_Item['kind'] ==
let l:Tag_Item['kind'] = 's'
endif

Since the Directory structure for tags and completions are different the data needs to be
converted. The informations available inside the tag depend on the tag-file creation tool.
But the minimum is:
“name”
Name of the tag.
“filename”
Name of the file where the tag is defined.
“cmd”
Ex command used to locate the tag in the file.
“kind”
Type of the tag. The value for this entry depends on the language specific kind values
generated by the ctags tool.
The contest of the completion is fixed and contains the following:
“word”
The actual completion
“kind”
The type of completion, one character, i.E. “v” for variable.
“menu”
Short extra info displayed inside the completion menu.
“word”
Long extra info displayed inside an extra window.
“icase”
Ignore case
So for simple tags without any extras the conversion could look like this:

let l:Match_Item = {
\ 'word': l:Tag_Item['name'],

73
Vim

\ 'menu': l:Tag_Item['filename'],
\ 'info': "Symbol from file " . l:Tag_Item['filename'] . "
line " . l:Tag_Item['cmd'],
\ 'kind': l:Tag_Item['kind'],
\ 'icase': 1}
if complete_add (l:Match_Item) == 0
return []
endif
if complete_check ()
return []
endif
endfor

Please note
The current Ada plugin has been extended to also support ctags which gives more infor-
mation than gnat xref -v. However we have not updated the walkthrough as we want
to keep the example simple and easy to follow.
We already added all matches via complete_add so we only return an empty list.

return []
endif
endfunction adacomplete#Complete
finish
endif

One last advice: It your tag tool does not sort the entries then you should sort them
separately. Searches on sorted tag-files are significantly faster.

VimL (aka Vimscript, or Vim script41 ) is a full feature scripting language, meaning it can
solve almost any text processing problem.

7.11 Statements

The text in its current form is incomplete.

create a file to use do, while loop to key in person data

7.12 Data types

There are five datatypes:

7.12.1 Number

A 32 bit signed integer.

41 http://en.wikibooks.org//en.wikipedia.org/wiki/Vimscript

74
 Data types

7.12.2 String

A NULL terminated string of 8-bit unsigned characters (bytes). Strings can be created by
either ‘'’ or ‘"’ quotes. When using strings quoted with the double quote ‘"’ the text is
interpreted i.e. "\n" becomes a new line while strings quoted with a single quote ‘'’ are not
interpreted, i.e. '\n' means just that, a backslash and an n. The following two strings are
identical:

let String_1 = "C:\\WinNT"

let String_2 = 'C:\WinNT'

Any other datatype can be converted into a string using the string () function.

7.12.3 Funcref

A reference to a function. A Funcref can be created from a string by the use of the function
function.

let Function_1 = function ("MyFunc")

7.12.4 List

An ordered sequence of items.

let List_1 = [
\ "a",
\ "b",
\ "c"]

A list can be created from a string by the use of the split function.

let List_2 = split ("a b c")

7.12.5 Dictionary

An associative, unordered array: Each entry has a key and a value.

let Dictionary_1 = {
\ 1: 'one',
\ 2: 'two',
\ 3: 'three'}

75
Vim

7.12.6 Objects

VIM also supports object oriented programming by combining Funcref and Dictionary to
an Object:

let mydict = {
\'data': [0, 1, 2, 3]}

function mydict.len () dict

return len (self.data)
endfunction mydict.len

for more information see Object oriented programming42

7.13 Control Structures

The existence of control structures is the main difference between vi's ex commands and
vim's scripting language. They make the difference between a simple command set (vi) and
a full features script language (vim).

7.13.1 condition

if condition
operations
elseif condition
operations
else
operations
endif

7.13.2 loop

while

while condition
operations
endwhile

for

For loops are available from vim 7 onwards. They iterate over List or Directory structures.

for var in list

operations

42 #Object_oriented_programming

76
 Subprograms

endfor

7.13.3 exceptions

try
operations
catch /pattern/
error handling operations
finally
clean-up operations
endtry

7.14 Subprograms

7.14.1 Simple Subprograms

Like most Shell-Languages43 all subprograms are stored in separate files which you load
either with the source or runtime command. The difference lies in the use of a search path.
runtime uses a search path and allows wildcards to find the sub-program while source need
the full path. The following commands do the same - provided that "˜/vimfiles" is part of
your runtime search path:

runtime setup.vim
source ˜/vimfiles/setup.vim

For both commands need to add the .vim extension. Since runtime supports both a search
path and wildcards more than one match is possible. If you want runtime to load all the
matches - and not just the first hit - use runtime!.

7.14.2 Functions

function f ( parameter )
operations
endfunction

New with vim 7 is the autoload option for functions. If you name a function File-
name#Functionname or Directory#Filename#Functionname then the function will be
automatically loaded on first call. The file containing the function must be placed
in one of the "autoload" runtime directories and be named "Filename.vim" or "Direc-
tory/Filename.vim". This option is especially useful for functions which you don't always
need on in Object oriented programming44 .

43 http://en.wikibooks.org//en.wikipedia.org/wiki/Shell_(computing)
44 #Object_oriented_programming

77
Vim

7.14.3 Commands

command Command Command

Command are often used as shortcut for functions and subprograms:

command C -nargs=* call F ( <f-args> )

command C source ˜/vimfiles/s.vim

7.15 Object oriented programming

Vim 7 now allows object oriented programming45 . However, in order to make it real you
need to combine several features, namely Dictionaries46 , Funcrefs47 and the new function
autoload48 . The following example class is taken from the gnat compiler plugin for vim. The
actual functions implementations have been removed as they are not needed to understand
the concept. If you like to have a look at the full version you can download the plugin from
vim.org site49 .

7.15.1 Step by Step walk-through

We add our new class to a autoload script. That way the class is available when and only
when needed:

if exists ("g:loaded_gnat_autoload") || version < 700

finish
else
let g:loaded_gnat_autoload=1

Each function we define need to be defined with the "dict" attribute. Apart from that they
are just normal scripting functions.

function gnat#Make () dict

...
return
endfunction gnat#Make

function gnat#Pretty () dict

...
return
endfunction gnat#Make

function gnat#Find () dict

...
return

45 http://en.wikibooks.org/wiki/Object_Oriented_Programming
46 #Dictionary
47 #Funcref
48 #Functions
49 http://www.vim.org/scripts/script.php?script_id=1609

78
 Object oriented programming

endfunction gnat#Find

function gnat#Tags () dict

...
return
endfunction gnat#Tags

function gnat#Set_Project_File (...) dict

...
return
endfunction gnat#Set_Project_File

function gnat#Get_Command (Command) dict

...
return ...
endfunction gnat#Get_Command

The most important step is the composition of the object. In most OO languages this
happens automatically - But with vim we have to do this ourselves. For best flexibility the
use of a so called constructor function is suggested. The constructor is not marked with
"dict":

function gnat#New ()

The constructor creates a dictionary which assigns all the object functions to one element
of the dictionary:

let Retval = {
\ 'Make' : function ('gnat#Make'),
\ 'Pretty' : function ('gnat#Pretty'),
\ 'Find' : function ('gnat#Find'),
\ 'Tags' : function ('gnat#Tags'),
\ 'Set_Project_File' : function ('gnat#Set_Project_File'),
\ 'Get_Command' : function ('gnat#Get_Command'),
\ 'Project_File' :,

We optionally can now add data entries to our object:

\ 'Make_Command' : '"gnat make -P " . self.Project_File . " -F -gnatef

"',
\ 'Pretty_Command' : '"gnat pretty -P " . self.Project_File . " "',
\ 'Find_Program' : '"gnat find -P " . self.Project_File . " -F "',
\ 'Tags_Command' : '"gnat xref -P " . self.Project_File . " -v
*.AD*"',
\ 'Error_Format' : '%f:%l:%c: %trror: %m,' .
\ '%f:%l:%c: %tarning: %m,' .
\ '%f:%l:%c: (%ttyle) %m'}

If needed additional modifications to the object are also possible. At this stage you can
already use the OO-way:

if argc() == 1 && fnamemodify(argv (0), ':e') == 'gpr'

call Retval.Set_Project_File(argv(0))
elseif strlen(v:servername) > 0
call Retval.Set_Project_File(v:servername . '.gpr')
endif

79
Vim

The last operation of the constructor is the return of the newly created object.

return Retval
endfunction gnat#New

It is also possible to defined additional non dict functions. These functions are the equivalent
to the "static" or "class" methods of other OO languages.

function gnat#Insert_Tags_Header()
...
return
endfunction gnat#Insert_Tags_Header

finish
endif

80
8 vile

8.1 Vile - vi like Emacs

Wikipedia1 has related information at VILE2

8.1.1 Overview

vile is a vi clone which doesn't claim to be a vi clone. The idea behind vile is to have an
editor which works similar to vi but provides features for editing multiple files in multiple
window-areas like emacs. In fact, vile development started by using MicroEMACS as the
base, and not a vi clone, and also not full blown Emacs. MicroEMACS is an emacs-like
editor (MicroEMACS's author didn't like full-blown emacs, and the vile authors didn't
like (Micro)EMACS mode-less way of working). So vile was developed. vile provides the
most common vi commands (as used by their authors), but not all vi commands. The
implemented commands are supposed to work more or less like the original vi commands.
The window management and buffer management came from MicroEMACS. Much work
has gone into the vile documentation after the first versions were almost undocumented. It
is recommended to consult the documentation to find out the differences and extensions of
vile, compared to vi.

8.1.2 Resources
• vile3
• MicroEMACS4

1 http://en.wikibooks.org//en.wikipedia.org/wiki/
2 http://en.wikibooks.org//en.wikipedia.org/wiki/VILE
3 http://invisible-island.net/vile/
4 http://web.archive.org/20020207175546/uemacs.tripod.com/nojavasc.html

81
9 BusyBox vi

9.1 Overview

Wikipedia1 has related information at BusyBox2

BusyBox is a very popular program on many embedded Linux systems. In fact, someone
working on an embedded Linux system is very likely to encounter BusyBox. BusyBox com-
bines tiny versions of many common UNIX utilities into a single relatively small executable.
One of the included utilities is a vi clone. The BusyBox vi clone is limited. Among the
limits are:
• It does not support all common vi commands.
• It supports the '!' command to execute a child process, but does not capture process
output
• It also lacks the normal vi crash recovery feature.
• It always assumes a vt102 type terminal (emulator)
• Only very few settings are configurable via :set
• .exrc configuration and configuration via environment variables are not supported
• Line marks are not correctly adjusted if lines are inserted or deleted before the mark.
• Only whole-line undo (uppercase 'U'), no last-change undo (lowercase 'u') is supported.
• Searches ignore case by default, but can be case sensitive using :set noignorecase
• Command-counts need to prefix a command
• command counts for a, c, i, r, y and several other commands are not supported.
• A limited set of ex commands are supported.
In short, a lot of information in this vi tutorial is not applicable to BusyBox vi. However,
BusyBox vi also has some differences (considered by some to be enhancements) over classic
vi:
• Cursor navigation in insert and command mode
• <INSERT> key changes to insert mode
• No wrapping of long lines. Long lines are displayed via side-scrolling.

9.1.1 Weblinks
• BusyBox home page3

1 http://en.wikibooks.org//en.wikipedia.org/wiki/
2 http://en.wikibooks.org//en.wikipedia.org/wiki/BusyBox
3 http://busybox.net

83
BusyBox vi

• BusyBox vi source code4

4 http://git.busybox.net/busybox/plain/editors/vi.c

84
10 vi Reference

The following conventions are used in this reference.

<c>
A single character, such as 'a' or '1'.
<ESC>, <Ctrl-[>
Indicates that the Escape (Esc) key on your keyboard should be pressed, which is identical
to Control and '['.
<CR>
Indicates that the Return (Enter) key should be pressed.
<TAB>
Indicates that the Tabulator key should be pressed
<Ctrl-x>, <C-x>
Indicates that the Control key and the 'x' key should be pressed simultaneously. 'x' can
be almost any other key on your keyboard.
<Shift-x>, <S-x>, <X>
Indicates that the Shift key and the 'x' key should be pressed simultaneously
<Meta-x>, <M-x>
Indicates that the Meta or Alt key and the 'x' key should be pressed simultaneously.
:quit, :q
An Ex command. started with <:>, followed by the command and ends with <CR>. For
many Ex commands there is a long form (:quit) and a short form (:q).
:set nocompatible
represents a setting.
strlen ()
represents a function.
/pattern/, ?pattern?
A Search pattern. Search pattern in vi are regular expressions1 .

1 http://en.wikibooks.org//en.wikipedia.org/wiki/regular_expression

85
vi Reference

:ranges/search/replace/options, :global /pattern/ delete

A Search pattern combined with an Ex command.
All commands in vi are case sensitive.

c A single character, such as 'a' or '1'.

m A single lowercase letter, used to mark text.
string Several characters, such as 'abc bed'.
pattern A string used in searching, which may contain regular expressions. For
example 'abc' or 'ˆab[123]'.
myfile The name of a file to be edited.

10.1 Invocation

vi myfile Open the file myfile for editing. If it does not exist, a new
file is created. Multiple files can be opened at the same
time.
vi +line myfile Open the file myfile with the cursor positioned at the given
line.
• vi +5 myfile opens myfile at line 5.
• vi + myfile opens myfile at the last line.

vi +/string/ myfile Open the file myfile with the cursor positioned at the first
line containing the string. If the string has spaces it should
be enclosed in quotes.
• vi +/"search string"/ myfile opens myfile at the first
line containing search string.

vi -r Lists recovery copies of files. A recovery copy is taken if a

vi session is killed or the system crashes.
vi -r myfile Opens a recovery copy of the file myfile.
view myfile view is a read only version of vi. All vi commands, in-
clude those to change the file are allowed and act as in vi.
The difference is that normal attempts to save, ZZ or :wq
do not work. Instead :x! or :w need to be used.

10.2 vi Commands

10.2.1 Movement

vi can be set up on most systems to use the keyboard movement buttons, such as cursor
left, page up, home, delete, etc.

86
 vi Commands

<G> Move to the last line of the file. Can be preceded by a number indi-
cating the line to move to, <1><G> moves to the first line of the
file.
<h> Move left one character, or cursor left. Can be preceded by a num-
ber, <5><h> moves left 5 places.
<j> Move one line down, or cursor down. Can be preceded by a number,
<5><j> moves down 5 lines.
<k> Move one line up, or cursor up. Can be preceded by a number, 5k
moves up 5 lines.
<l> Move forward one character, or cursor right. Can be preceded by a
number, 5l moves right 5 places.
<H> Moves to the line at the top of the screen.
<M> Moves to the line in the middle of the screen.
<L> Moves to the line at the bottom of the screen.
<-> Moves to the first non-whitespace character of the line above. Can be
preceded by a number.
• 10- moves up 10 lines.

<+> Moves to the first non-whitespace character of the line below. Can be
preceded by a number.
• 10+ moves down 10 lines.

<CR> Same as <+>.

<> Must be preceded by a number. Moves to the specified column on the
current line.
• 10| moves to column 10.

<w> Moves to the start of the next word, which may be on the next line.
<W> As w but takes into account punctuation.
<e> Moves to the end of the current word or to the next word if between
words or at the end of a word.
<E> As e but takes into account punctuation.
<b> Moves backwards to the start of the current word or to the previous
word if between words or at the start of a word.
<B> As b but takes into account punctuation.
<f>c Find first occurrence of character c on the same line.This command
may be repeated using <;> or <,> (reverse direction).
• <3><f><x> moves forward on the third occurrence of x (if
present).
Same as <f><x><;><;>

<F>c Same as f but backward.

<t>c Find the character before the first occurrence of character c on the
same line.
<T>c Same as t but backward, placing the cursor after character c.
<0> Moves to the start of the current line.
<ˆ> Moves to the first non-whitespace character on the current line.
<$> Moves to the end of the current line.

87
vi Reference

<Ctrl-F> Move forwards one page.

• 5<Ctrl-F> moves forwards five pages.

<Ctrl-B> Move backwards one page.

• 5<Ctrl-B> moves backwards five pages.

<Ctrl-D> Move forwards by half a page.

<Ctrl-U> Move backwards by half a page.
<Ctrl-E> Display one more line at the bottom of the screen.
<Ctrl-Y> Display one more line at the top of the screen.

10.2.2 Inserting

All insert commands put vi into insert mode. Insert mode is terminated by the ESC key.

<i> Enters insert mode at the cursor position.

<I> Enters insert mode at the start of the current line.
<a> Enters insert mode after the cursor, or appends.
<A> Enters insert mode at the end of the current line, or append to the end of
the current line.
<o> Inserts a new line underneath the current line and then goes into insert
mode.
<O> Inserts a new line above the current line and then goes into insert mode.

10.2.3 Replacing

r Replaces the character underneath the cursor with the next character typed.
Can be preceded by a number, 5ra replaces 5 characters with the letter a.
R Enters replace mode. Each time a letter is typed it replaces the one under the
cursor and the cursor moves to the next character. Replace mode is termi-
nated by the ESC key. Can be preceded by a number, 5Rab followed by ESC
replaces the character under the cursor by a, the next character by b and then
inserts another 4 abs. The original line is placed into the buffer, replacing any
text already there.

10.2.4 Deleting

Each time a delete command is used, the deleted text is placed into the buffer, replacing
any text already in the buffer. Buffered text can be retrieved by p or P.

dd Deletes the current line. Can be preceded by a number.

• 5dd deletes five lines. d5d is the same as 5dd.

88
 vi Commands

de Deletes from the character underneath the cursor to the end of the
word. Can be preceded by a number.
• 5de deletes five words. d5e is the same as 5de.

dE As de but takes into account punctuation.

dw Deletes from the character underneath the cursor to the start of the
next word. Can be preceded by a number.
• 5dw deletes five words. d5w is the same as 5dw.

dW As dw but takes into account punctuation.

db Deletes from the left of the cursor to the start of the previous word.
Can be preceded by a number.
• 5db deletes five words to the left of the cursor.

dB As db but takes into account punctuation.

dtc Deletes from the cursor position to before the first instance of the char-
acter.
• dta deletes text up and to, but not including, the first letter 'a'.

dfc Deletes from the cursor position to the first instance of the character.
• dfa deletes text up and to, and including, the first letter 'a'.

dG Deletes the current line and everything to the end of the file.
d/string Deletes from the cursor to the string, either forwards or backwards.
D Deletes from the cursor to the end of the line.
d$ Same as D.
dˆ Deletes from the left of the cursor to the start of the line.
x Delete the character underneath the cursor. Can be preceded by a
number.
• 5x deletes the character underneath the cursor and the next 4 char-
acters.
• xp swaps the character underneath the cursor with the one to the
right of it.

X Delete the character to the left of the cursor, but will not delete the
end of line marker or any characters on the next line. Can be preceded
by a number.
• 5X deletes 5 characters to the left of the cursor.

10.2.5 Changing

The change commands all select text to be removed, the end of which is indicated by a
$. Insert mode is entered and new text overwrites or extends the text. When the <ESC>
key is pressed to terminate the insert, any remaining original text is deleted. Text deleted
during a change is placed into the buffer, replacing any text already there. Buffered text
can be retrieved by p or P.

89
vi Reference

C Change from the cursor position to the end of the line. Can be preceded by
a number.
• 5C changes 5 lines, the current line and the next 4 lines.

cM Generally the same as dMi, where M is any movement command.

cc Change the current line. Can be preceded by a number.
• 5cc changes 5 lines, the current line and the next 4 lines.

ce Change the current word. Can be preceded by a number.

• 5ce changes five words. c5e is the same as 5ce.

cw Exactly the same as ce.

This command is inconsistent with the usual vi moving: cw and ce is the
same as dei but dwi removes also the spaces until the next word.
ctc Changes from the cursor position to the first instance of the character.
• cta changes text up and to, but not including, the first letter 'a'.

cfc Changes from the cursor position to the first instance of the character (in-
cluding the character c).
cG Changes from the start of the current line to the end of the file.
s Change the character underneath the cursor. Can be preceded by a number.
• 5s changes 5 characters, the one under the cursor and the next 4.

S Change the entire line. Same as ddO (uppercase letter "O").

10.2.6 Cut and Paste

The yank commands copy text into the vi buffer. Text is also copied into the buffer by
delete and change commands. The put or place commands retrieve text from the buffer.

yy Yanks the current line into the buffer. Can be preceded by a number.
• 5yy yanks five lines.

Y Same as yy.
yw Yanks from the cursor to the start of the next word into the buffer. Can be
preceded by a number.
• 5yw yanks five words.

p If the buffer consists of whole lines, they are inserted after the current line.
If it consists of characters only, they are inserted after the cursor.
P If the buffer consists of whole lines, they are inserted before the current line.
If it consists of characters only, they are inserted before the cursor.

90
 vi Commands

10.2.7 Searching

Searching uses regular expressions2 .

/pattern/ Searches for the string, which could be a regular expression. Search-
ing is from the cursor position downwards, stopping at the first
match. If not found, it will continue from the start of the file to the
cursor position. The trailing slash character is optional.
• /abc/ seaches for the first occurrence of abc.

/pattern/+ Goes to the line after the one containing the search string.
• /abc/+3 goes to the third line after the one containing abc.

/pattern/e Leaves the cursor on the last character of the string that pattern
matched.* By adding +num or -num after e you can supply an offset
in characters to where the cursor gets left. For example: /foo/e+3
will leave the cursor 3 characters past the next occurrence of foo.*
By using b instead of e you can specify a character offset from the
beginning of the matched string.
/\cpattern/ Does a case insensitive search.
?pattern? As /pattern/ but searches upwards. The trailing question mark char-
acter is optional.
?pattern?- Goes to the line above the one containing the search string.
• ?abc?-3 goes to the third line above the one containing abc.

<n> Repeat last search.

<N> Repeat last search but in the opposite direction.
<f>char Search forward on the current line for the next occurrence of char.
<F>char Search backward on the current line for the next occurrence of char.
<t>char Search forward on the current line for the next occurrence of char
and leave the cursor on the character before char.
<T>char Search backward on the current line for the next occurrence of char
and leave the cursor on the character after char.
<;> Repeat the last f or F search.

2 http://en.wikibooks.org//en.wikipedia.org/wiki/regular_expression

91
vi Reference

10.2.8 Search and Replace

Search and replace uses regular expressions3 and the Ex command :substitute (short :s)
which has syntax similar to the sed4 utility - which is not surprising sed5 , Ex6 and w:Vi7
have common roots - the Ed8 editor.
:.s/pattern/replacement/ Replaces the first occurrence of pattern on the current
line with replacement.* If pattern contains \( and \)
they are used to remember what matched between
them instead of matching parenthesis characters. For
example :.s/\(\d*\)-\(\d*\)/\2:\1/ could match
the string 12345-6789 and substitute 6789:12345
for it.
:.s/pattern/replacement/g Replaces all occurrences of pattern on the current line
with replacement.
:%s/pattern/replacement/g Replaces all occurrences of pattern in the whole file
with replacement.
:x,ys/pattern/replacement/g Replaces all occurrences of pattern on lines x through
y with replacement.* For example: :14,18s/foo/bar/g
will replace all occurrences of foo with bar on lines 14
through 18.
• The character . can be used to indicate the current
line and the character $ can be used to indicate the
last line. For example: :.,$s/foo/bar/g will replace
all occurrences of foo with bar on the current line
through the end of the file.

The following meta-characters have special meaning in the replacement pattern:

& Replaced by the text that matched the search pattern.

\n Replaced by the text matching the search pattern between \( and \), where
n is in the range of 1 through 9 with \1 being replaced by the match from
the first set.
\u Capitalize the next character (if the character is a letter).
\l Lowercase the next character (if the character is a letter).
\U Turn on capitalization mode, where all of the following characters are capi-
talized.
\L Turn on lowercase mode, where all of the following characters are lowercased.
\E Turn off capitalization or lowercase mode.
\e Turn off capitalization or lowercase mode.

3 http://en.wikibooks.org//en.wikipedia.org/wiki/regular_expression
4 http://en.wikibooks.org//en.wikipedia.org/wiki/sed
5 http://en.wikibooks.org//en.wikipedia.org/wiki/sed
6 http://en.wikibooks.org//en.wikipedia.org/wiki/Ex_(text_editor)
7 http://en.wikibooks.org//en.wikipedia.org/wiki/Vi
8 http://en.wikibooks.org//en.wikipedia.org/wiki/Ed_(text_editor)

92
 vi Commands

For example .:s/\(foo\) \(bar\) \(baz\)/\u\1 \U\2\E \3/ could match the string
foo bar baz and substitute Foo BAR baz for it.

10.2.9 Mark Text

Marked lines can be used when changing or deleting text.

<m>m Mark the current line with the letter.

• <m><a> marks the current line with the letter a.

<'>m Move to the line marked by the letter.

• <'><a> moves to the line marked by a.

10.2.10 Screen Refresh

<Ctrl-L> Refresh the screen.

z<CR> Refreshes the screen so that the current line is at the top. Can be
preceded by a line number.
• 35z refreshes the screen so that line 35 is at the top.

/pattern/z Finds the line with the first occurrence of string and then refreshes
the screen so that it is at the top.
z. Refreshes the screen so that the current line is in the middle of the
screen. Can be preceded by a line number, in which case the line is
at the middle. The sequence zz also has the same effect.
• 35z. refreshes the screen so that line 35 is in the middle.

/string/z. Finds the line with the first occurrence of string and then refreshes
the screen so that it is in the middle.
z- Refreshes the screen so that the current line is at the bottom. Can
be preceded by a line number, in which case the line is at the bot-
tom.
• 35z- refreshes the screen so that line 35 is at the bottom.

/string/z- Finds the line with the first occurrence of string and then refreshes
the screen so that it is at the bottom.

10.2.11 Others

<˜> Changes the case of the character underneath the cursor and moves to
the next character. Can be preceded by a number, so that 5˜ changes
the case of 5 characters.

93
vi Reference

<.> Repeats the last insert or delete. Can be preceded by a number, dd

followed by 5. deletes a line and then deletes another 5 lines.
<%> Moves the cursor to the matching bracket, any of (), [] or {}.
<Ctrl-G> Temporarily displays a status line at the bottom of the screen.
:f Same as <Ctrl-G>.
<J> Joins the next line to the end of the current line. Can be preceded by
a number. Both 1J and 2J do the same as J.
• 3J joins three lines together, the current line and the next two lines.

<u> Undoes the last change.

<U> Undoes all changes to the current line.
<Ctrl-Z> Puts vi into the background, that is control is returned to the operat-
ing system. In UNIX, the vi session can be returned to the foreground
with fg.

10.2.12 Saving and Quitting

<Z><Z> Saves and quits. It is symbolic of sleep, indicating the

end of work.
:quit Quits, but only if no changes have been made.
:q
:quit! Quits without saving, regardless of any changes.
:q!
:write Saves the current file without quitting.
:w • {Vi/Ex|:write!}} myfile saves to the file called my-
file.

:write!filename Saves to the file, overwriting any existing contents.

:w!filename
:wq Saves and quits.
:write|quit
:exit Saves and quits.
:xit
:x
:exit! Used to save and quit in view.
:xit!
:x!

10.2.13 Files

:e filename Quits the current file and starts editing the named file.
:e + filename Quits the current file and starts editing the named file with the
cursor at the end of the file.
• :e +5 myfile quits the current file and begins editing myfile at
line 5.

94
 ex Commands

:e! The current file is closed, all unsaved changes discarded, and the
file is re-opened for editing.
:e# Quits the current file and starts editing the previous file.
:n When multiple files were quoted on the command line, start edit-
ing the next file.
:n files Resets the list of files for :n. The current file will be closed and
the first file in the list will be opened for editing.
:r filename Read a file, that is insert a file.
• :r myfile inserts the file named myfile after the cursor.
• :5r myfile inserts the file after line 5.

10.3 vi Options

All options are ex options, and so require an initial colon. Default options may be placed
into a file in the user's home directory called .exrc. Options in this file do not have the
initial colon, e.g.
set ic
:set all Displays all the current settings.

! Set on ! Set off ! Meaning

:set ignorecase :set noignorecase Ignore case. Makes search-
:set ic :set noic ing case insensitive.
:set list :set nolist Shows control characters.
<Ctrl-I> is tab, $ is line-
feed.
:set number :set nonumber Turns on line numbering.
:set nu :set nonu
:set term Displays the terminal
type.
:set autoindent :set noautoindent Automatically indents
:set ai :set noai lines while in insert mode
upon <CR>.
:set hlsearch :set nohlsearch Highlights searches
matched by /term/. It's
a visual aide.

10.4 ex Commands

ex commands start with :, which puts vi into last line mode, entered on the last line of the
screen. Spaces within the command are ignored.

95
vi Reference

:! command Executes the named operating system command and then returns
to vi.
• :! ls runs the UNIX ls command.

:sh Starts up a shell. exit returns to the vi session.

:vi Exit last line mode and return to normal command mode.

10.4.1 ex line commands

These commands edit lines and have the following syntax:

1. No line number, meaning work on the current line.
2. With %, meaning work on all lines.
3. A pair of line numbers, such as '3,5' meaning work on lines 3 to 5 inclusive. Either
number can be replaced with ., standing for the current line or $ standing for the last
line. So .,$ means from the current line to the end of the file and 1,$ means the same
as %. Additionally simple arithmetic may be used, so .+1 means the line after the
current line, or $-5 means 5 lines before the last line.

co Copy, followed by the line position to copy to.

• :co 5 copies the current line and places it after line 5.
• :1,3 co 4 copies lines 1 to 3 and places after line 4.

d Delete.
• :d deletes the current line.
• :.,.+5d delete the current line and the next 5 lines.
• :%d deletes all lines.

m Move, followed by the line position to move to.

• :m 10 moves the current line and places it after line 10.
• :1,3 m 4 moves lines 1 to 3 and places after line 4.

10.4.2 Mapping / Remapping vi Commands

:map Create new command or overwrite existing in vi command mode.

• :map v i--<Ctrl-[> new command v will insert -- and return to
command mode. <Ctrl-[> is the escape character typed as <CTRL-
V><ESC>.

96
 External link

:map! Create new command in both command and insert mode.

• :map! ;r <Ctrl-[> typing ;r in insert mode will return to command
mode.

10.5 External link

• vim Official Reference Manual9
• An introduction to the vi editor10
• Learning Unix in 10min11

9 http://vimdoc.sourceforge.net/htmldoc/ref_toc.html
10 http://planzero.org/tutorials/introduction_to_the_vi_editor.php
11 http://freeengineer.org/learnUNIXin10minutes.html

97
11 Authors

This book has many authors, including the public: it is open for anyone and everybody to
improve. Therefore, this is more properly a list of acknowledgements of contributors than
a list of authors. Whoever we are, this is where we get to brag about our accomplishments
in writing this book.

11.1 List of major contributors

• Dysprosia1 ( Contributions2 )
• Martin Krischik3 Learning the vi Editor/Vim4 ( Contributions5 )
• N.N.(anonymous): The advanced/Power User/Extra Details part ( Learning the vi Edi-
tor/Details6 ) - whatever it is currently called .
• Others (add your name and description if you made a major contribution)
• Various anonymous persons
Category7 :
• Learning the vi Editor8

1 http://en.wikibooks.org/wiki/User:Dysprosia
2 http://en.wikibooks.org/wiki/Special:Contributions/Dysprosia
3 http://en.wikibooks.org/wiki/User:Krischik
4 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim
5 http://en.wikibooks.org/wiki/Special:Contributions/Krischik
6 http://en.wikibooks.org/wiki/Learning_the_vi_Editor/Details
7 http://en.wikibooks.org/wiki/Special:Categories
8 http://en.wikibooks.org/wiki/Category:Learning_the_vi_Editor

99
12 Contributors

Edits User
69 Adrignola1
1 AlbertCahalan2
8 Andreas Ipp3
1 CarsracBot4
1 Chinasaur5
6 Darklama6
7 Dreftymac7
1 Eibwen8
2 Hagindaz9
4 Hannes Röst10
14 Jguk11
1 Jomegat12
78 Jonathan Webley13
2 Jusjih14
1 Kazkaskazkasako15
1 Kernigh16
359 Krischik17
1 LFaraone18
1 Lee J Haywood19
1 Liblamb20
3 Mahanga21

1 http://en.wikibooks.org/wiki/User:Adrignola
2 http://en.wikibooks.org/wiki/User:AlbertCahalan
3 http://en.wikibooks.org/wiki/User:Andreas_Ipp
4 http://en.wikibooks.org/wiki/User:CarsracBot
5 http://en.wikibooks.org/wiki/User:Chinasaur
6 http://en.wikibooks.org/wiki/User:Darklama
7 http://en.wikibooks.org/wiki/User:Dreftymac
8 http://en.wikibooks.org/wiki/User:Eibwen
9 http://en.wikibooks.org/wiki/User:Hagindaz
10 http://en.wikibooks.org/wiki/User:Hannes_R%25C3%25B6st
11 http://en.wikibooks.org/wiki/User:Jguk
12 http://en.wikibooks.org/wiki/User:Jomegat
13 http://en.wikibooks.org/wiki/User:Jonathan_Webley
14 http://en.wikibooks.org/wiki/User:Jusjih
15 http://en.wikibooks.org/wiki/User:Kazkaskazkasako
16 http://en.wikibooks.org/wiki/User:Kernigh
17 http://en.wikibooks.org/wiki/User:Krischik
18 http://en.wikibooks.org/wiki/User:LFaraone
19 http://en.wikibooks.org/wiki/User:Lee_J_Haywood
20 http://en.wikibooks.org/wiki/User:Liblamb
21 http://en.wikibooks.org/wiki/User:Mahanga

101
Contributors

1 Mercy22
3 Mga23
1 Mkn24
5 Nikai25
2 Njk26
2 Panic2k427
1 Polluks28
2 R3m0t29
1 Ramac30
2 Remi31
1 Robert Horning32
1 Thenub31433
2 Tompurl34
3 Van der Hoorn35
5 Waxmop36
1 Whiteknight37
1 Xania38

22 http://en.wikibooks.org/wiki/User:Mercy
23 http://en.wikibooks.org/wiki/User:Mga
24 http://en.wikibooks.org/wiki/User:Mkn
25 http://en.wikibooks.org/wiki/User:Nikai
26 http://en.wikibooks.org/wiki/User:Njk
27 http://en.wikibooks.org/wiki/User:Panic2k4
28 http://en.wikibooks.org/wiki/User:Polluks
29 http://en.wikibooks.org/wiki/User:R3m0t
30 http://en.wikibooks.org/wiki/User:Ramac
31 http://en.wikibooks.org/wiki/User:Remi
32 http://en.wikibooks.org/wiki/User:Robert_Horning
33 http://en.wikibooks.org/wiki/User:Thenub314
34 http://en.wikibooks.org/wiki/User:Tompurl
35 http://en.wikibooks.org/wiki/User:Van_der_Hoorn
36 http://en.wikibooks.org/wiki/User:Waxmop
37 http://en.wikibooks.org/wiki/User:Whiteknight
38 http://en.wikibooks.org/wiki/User:Xania

102
List of Figures

• GFDL: Gnu Free Documentation License. http://www.gnu.org/licenses/fdl.

html
• cc-by-sa-3.0: Creative Commons Attribution ShareAlike 3.0 License. http://
creativecommons.org/licenses/by-sa/3.0/
• cc-by-sa-2.5: Creative Commons Attribution ShareAlike 2.5 License. http://
creativecommons.org/licenses/by-sa/2.5/
• cc-by-sa-2.0: Creative Commons Attribution ShareAlike 2.0 License. http://
creativecommons.org/licenses/by-sa/2.0/
• cc-by-sa-1.0: Creative Commons Attribution ShareAlike 1.0 License. http://
creativecommons.org/licenses/by-sa/1.0/
• cc-by-2.0: Creative Commons Attribution 2.0 License. http://creativecommons.
org/licenses/by/2.0/
• cc-by-2.0: Creative Commons Attribution 2.0 License. http://creativecommons.
org/licenses/by/2.0/deed.en
• cc-by-2.5: Creative Commons Attribution 2.5 License. http://creativecommons.
org/licenses/by/2.5/deed.en
• cc-by-3.0: Creative Commons Attribution 3.0 License. http://creativecommons.
org/licenses/by/3.0/deed.en
• GPL: GNU General Public License. http://www.gnu.org/licenses/gpl-2.0.txt
• LGPL: GNU Lesser General Public License. http://www.gnu.org/licenses/lgpl.
html
• PD: This image is in the public domain.
• ATTR: The copyright holder of this file allows anyone to use it for any purpose,
provided that the copyright holder is properly attributed. Redistribution, derivative
work, commercial use, and all other use is permitted.
• EURO: This is the common (reverse) face of a euro coin. The copyright on the design
of the common face of the euro coins belongs to the European Commission. Authorised
is reproduction in a format without relief (drawings, paintings, films) provided they
are not detrimental to the image of the euro.
• LFK: Lizenz Freie Kunst. http://artlibre.org/licence/lal/de
• CFR: Copyright free use.

103
List of Figures

• EPL: Eclipse Public License. http://www.eclipse.org/org/documents/epl-v10.

php
Copies of the GPL, the LGPL as well as a GFDL are included in chapter Licenses39 . Please
note that images in the public domain do not require attribution. You may click on the
image numbers in the following table to open the webpage of the images in your webbrower.

39 Chapter 13 on page 107

104
 List of Figures

1 The people from the Tango! project40

2 Original uploader was Ehamberg41 at en.wikipedia42 Later GPL
version(s) were uploaded by Wapcaplet43 , AzaToth44 , Hep-
tite45 , Mineralè46 , Procus the Mad47 , Byondlimits48 ,
Jvihavainen49 at en.wikipedia50 .
3 Krischik
4
5
6
7
8
9 HDBot

40 http://tango.freedesktop.org/The_People
41 http:////en.wikipedia.org/wiki/User:Ehamberg
42 http://en.wikipedia.org
43 http:////en.wikipedia.org/wiki/User:Wapcaplet
44 http:////en.wikipedia.org/wiki/User:AzaToth
45 http:////en.wikipedia.org/wiki/User:Heptite
46 http:////en.wikipedia.org/wiki/User:Mineral%C3%83%C2%A8
47 http:////en.wikipedia.org/wiki/User:Procus_the_Mad
48 http:////en.wikipedia.org/wiki/User:Byondlimits
49 http:////en.wikipedia.org/wiki/User:Jvihavainen
50 http://en.wikipedia.org

105
13 Licenses

13.1 GNU GENERAL PUBLIC LICENSE

Version 3, 29 June 2007 The “Corresponding Source” for a work in object code form means all different server (operated by you or a third party) that supports equiv- your license, and (b) permanently, if the copyright holder fails to no-
the source code needed to generate, install, and (for an executable alent copying facilities, provided you maintain clear directions next to tify you of the violation by some reasonable means prior to 60 days
Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/> work) run the object code and to modify the work, including scripts the object code saying where to find the Corresponding Source. Re- after the cessation.
to control those activities. However, it does not include the work's gardless of what server hosts the Corresponding Source, you remain
System Libraries, or general-purpose tools or generally available free obligated to ensure that it is available for as long as needed to satisfy Moreover, your license from a particular copyright holder is reinstated
Everyone is permitted to copy and distribute verbatim copies of this
programs which are used unmodified in performing those activities but these requirements. * e) Convey the object code using peer-to-peer permanently if the copyright holder notifies you of the violation by
license document, but changing it is not allowed. Preamble
which are not part of the work. For example, Corresponding Source transmission, provided you inform other peers where the object code some reasonable means, this is the first time you have received notice
includes interface definition files associated with source files for the and Corresponding Source of the work are being offered to the general of violation of this License (for any work) from that copyright holder,
The GNU General Public License is a free, copyleft license for software work, and the source code for shared libraries and dynamically linked public at no charge under subsection 6d. and you cure the violation prior to 30 days after your receipt of the
and other kinds of works. subprograms that the work is specifically designed to require, such as notice.
by intimate data communication or control flow between those sub- A separable portion of the object code, whose source code is excluded
The licenses for most software and other practical works are designed programs and other parts of the work. from the Corresponding Source as a System Library, need not be in- Termination of your rights under this section does not terminate the
to take away your freedom to share and change the works. By con- cluded in conveying the object code work. licenses of parties who have received copies or rights from you under
trast, the GNU General Public License is intended to guarantee your The Corresponding Source need not include anything that users can re- this License. If your rights have been terminated and not permanently
freedom to share and change all versions of a program--to make sure generate automatically from other parts of the Corresponding Source.
A “User Product” is either (1) a “consumer product”, which means any reinstated, you do not qualify to receive new licenses for the same
it remains free software for all its users. We, the Free Software Foun-
tangible personal property which is normally used for personal, family, material under section 10. 9. Acceptance Not Required for Having
dation, use the GNU General Public License for most of our software;
The Corresponding Source for a work in source code form is that same or household purposes, or (2) anything designed or sold for incorpora- Copies.
it applies also to any other work released this way by its authors. You
work. 2. Basic Permissions. tion into a dwelling. In determining whether a product is a consumer
can apply it to your programs, too.
product, doubtful cases shall be resolved in favor of coverage. For a You are not required to accept this License in order to receive or run
All rights granted under this License are granted for the term of copy- particular product received by a particular user, “normally used” refers a copy of the Program. Ancillary propagation of a covered work oc-
When we speak of free software, we are referring to freedom, not price.
right on the Program, and are irrevocable provided the stated con- to a typical or common use of that class of product, regardless of the curring solely as a consequence of using peer-to-peer transmission to
Our General Public Licenses are designed to make sure that you have
ditions are met. This License explicitly affirms your unlimited per- status of the particular user or of the way in which the particular receive a copy likewise does not require acceptance. However, nothing
the freedom to distribute copies of free software (and charge for them
mission to run the unmodified Program. The output from running a user actually uses, or expects or is expected to use, the product. A other than this License grants you permission to propagate or modify
if you wish), that you receive source code or can get it if you want
covered work is covered by this License only if the output, given its product is a consumer product regardless of whether the product has any covered work. These actions infringe copyright if you do not accept
it, that you can change the software or use pieces of it in new free
content, constitutes a covered work. This License acknowledges your substantial commercial, industrial or non-consumer uses, unless such this License. Therefore, by modifying or propagating a covered work,
programs, and that you know you can do these things.
rights of fair use or other equivalent, as provided by copyright law. uses represent the only significant mode of use of the product. you indicate your acceptance of this License to do so. 10. Automatic
Licensing of Downstream Recipients.
To protect your rights, we need to prevent others from denying you
You may make, run and propagate covered works that you do not con- “Installation Information” for a User Product means any methods, pro-
these rights or asking you to surrender the rights. Therefore, you have
vey, without conditions so long as your license otherwise remains in cedures, authorization keys, or other information required to install Each time you convey a covered work, the recipient automatically re-
certain responsibilities if you distribute copies of the software, or if you
force. You may convey covered works to others for the sole purpose and execute modified versions of a covered work in that User Product ceives a license from the original licensors, to run, modify and prop-
modify it: responsibilities to respect the freedom of others.
of having them make modifications exclusively for you, or provide you from a modified version of its Corresponding Source. The information agate that work, subject to this License. You are not responsible for
with facilities for running those works, provided that you comply with must suffice to ensure that the continued functioning of the modified enforcing compliance by third parties with this License.
For example, if you distribute copies of such a program, whether gratis the terms of this License in conveying all material for which you do not object code is in no case prevented or interfered with solely because
or for a fee, you must pass on to the recipients the same freedoms that control copyright. Those thus making or running the covered works modification has been made. An “entity transaction” is a transaction transferring control of an or-
you received. You must make sure that they, too, receive or can get for you must do so exclusively on your behalf, under your direction ganization, or substantially all assets of one, or subdividing an orga-
the source code. And you must show them these terms so they know and control, on terms that prohibit them from making any copies of
If you convey an object code work under this section in, or with, or nization, or merging organizations. If propagation of a covered work
their rights. your copyrighted material outside their relationship with you.
specifically for use in, a User Product, and the conveying occurs as results from an entity transaction, each party to that transaction who
part of a transaction in which the right of possession and use of the receives a copy of the work also receives whatever licenses to the work
Developers that use the GNU GPL protect your rights with two steps: Conveying under any other circumstances is permitted solely under the party's predecessor in interest had or could give under the previous
User Product is transferred to the recipient in perpetuity or for a fixed
(1) assert copyright on the software, and (2) offer you this License the conditions stated below. Sublicensing is not allowed; section 10 paragraph, plus a right to possession of the Corresponding Source of
term (regardless of how the transaction is characterized), the Corre-
giving you legal permission to copy, distribute and/or modify it. makes it unnecessary. 3. Protecting Users' Legal Rights From Anti- the work from the predecessor in interest, if the predecessor has it or
sponding Source conveyed under this section must be accompanied by
Circumvention Law. the Installation Information. But this requirement does not apply if can get it with reasonable efforts.
For the developers' and authors' protection, the GPL clearly explains neither you nor any third party retains the ability to install modi-
that there is no warranty for this free software. For both users' and No covered work shall be deemed part of an effective technological fied object code on the User Product (for example, the work has been You may not impose any further restrictions on the exercise of the
authors' sake, the GPL requires that modified versions be marked as measure under any applicable law fulfilling obligations under article installed in ROM). rights granted or affirmed under this License. For example, you may
changed, so that their problems will not be attributed erroneously to 11 of the WIPO copyright treaty adopted on 20 December 1996, or not impose a license fee, royalty, or other charge for exercise of rights
authors of previous versions. similar laws prohibiting or restricting circumvention of such measures. granted under this License, and you may not initiate litigation (in-
The requirement to provide Installation Information does not include
a requirement to continue to provide support service, warranty, or up- cluding a cross-claim or counterclaim in a lawsuit) alleging that any
Some devices are designed to deny users access to install or run mod- dates for a work that has been modified or installed by the recipient, patent claim is infringed by making, using, selling, offering for sale, or
When you convey a covered work, you waive any legal power to forbid
ified versions of the software inside them, although the manufacturer or for the User Product in which it has been modified or installed. importing the Program or any portion of it. 11. Patents.
circumvention of technological measures to the extent such circum-
can do so. This is fundamentally incompatible with the aim of protect- vention is effected by exercising rights under this License with respect Access to a network may be denied when the modification itself ma-
ing users' freedom to change the software. The systematic pattern of to the covered work, and you disclaim any intention to limit opera- terially and adversely affects the operation of the network or violates A “contributor” is a copyright holder who authorizes use under this
such abuse occurs in the area of products for individuals to use, which tion or modification of the work as a means of enforcing, against the the rules and protocols for communication across the network. License of the Program or a work on which the Program is based. The
is precisely where it is most unacceptable. Therefore, we have designed work's users, your or third parties' legal rights to forbid circumvention work thus licensed is called the contributor's “contributor version”.
this version of the GPL to prohibit the practice for those products. If of technological measures. 4. Conveying Verbatim Copies.
such problems arise substantially in other domains, we stand ready to Corresponding Source conveyed, and Installation Information pro-
vided, in accord with this section must be in a format that is publicly A contributor's “essential patent claims” are all patent claims owned
extend this provision to those domains in future versions of the GPL,
You may convey verbatim copies of the Program's source code as you documented (and with an implementation available to the public in or controlled by the contributor, whether already acquired or hereafter
as needed to protect the freedom of users.
receive it, in any medium, provided that you conspicuously and appro- source code form), and must require no special password or key for acquired, that would be infringed by some manner, permitted by this
priately publish on each copy an appropriate copyright notice; keep in- unpacking, reading or copying. 7. Additional Terms. License, of making, using, or selling its contributor version, but do
Finally, every program is threatened constantly by software patents. not include claims that would be infringed only as a consequence of
tact all notices stating that this License and any non-permissive terms
States should not allow patents to restrict development and use of soft- further modification of the contributor version. For purposes of this
added in accord with section 7 apply to the code; keep intact all no-
ware on general-purpose computers, but in those that do, we wish to “Additional permissions” are terms that supplement the terms of this definition, “control” includes the right to grant patent sublicenses in a
tices of the absence of any warranty; and give all recipients a copy of
avoid the special danger that patents applied to a free program could License by making exceptions from one or more of its conditions. Ad- manner consistent with the requirements of this License.
this License along with the Program.
make it effectively proprietary. To prevent this, the GPL assures that ditional permissions that are applicable to the entire Program shall be
patents cannot be used to render the program non-free. treated as though they were included in this License, to the extent that
You may charge any price or no price for each copy that you con- they are valid under applicable law. If additional permissions apply Each contributor grants you a non-exclusive, worldwide, royalty-free
vey, and you may offer support or warranty protection for a fee. 5. only to part of the Program, that part may be used separately under patent license under the contributor's essential patent claims, to make,
The precise terms and conditions for copying, distribution and modi- use, sell, offer for sale, import and otherwise run, modify and propa-
Conveying Modified Source Versions. those permissions, but the entire Program remains governed by this
fication follow. TERMS AND CONDITIONS 0. Definitions. gate the contents of its contributor version.
License without regard to the additional permissions.
You may convey a work based on the Program, or the modifications
“This License” refers to version 3 of the GNU General Public License. In the following three paragraphs, a “patent license” is any express
to produce it from the Program, in the form of source code under the When you convey a copy of a covered work, you may at your option
terms of section 4, provided that you also meet all of these conditions: agreement or commitment, however denominated, not to enforce a
remove any additional permissions from that copy, or from any part
“Copyright” also means copyright-like laws that apply to other kinds patent (such as an express permission to practice a patent or covenant
of it. (Additional permissions may be written to require their own
of works, such as semiconductor masks. not to sue for patent infringement). To “grant” such a patent license
* a) The work must carry prominent notices stating that you modified removal in certain cases when you modify the work.) You may place
to a party means to make such an agreement or commitment not to
it, and giving a relevant date. * b) The work must carry prominent additional permissions on material, added by you to a covered work,
“The Program” refers to any copyrightable work licensed under this Li- enforce a patent against the party.
notices stating that it is released under this License and any conditions for which you have or can give appropriate copyright permission.
cense. Each licensee is addressed as “you”. “Licensees” and “recipients” added under section 7. This requirement modifies the requirement in
may be individuals or organizations. section 4 to “keep intact all notices”. * c) You must license the entire If you convey a covered work, knowingly relying on a patent license,
Notwithstanding any other provision of this License, for material you and the Corresponding Source of the work is not available for anyone
work, as a whole, under this License to anyone who comes into pos-
add to a covered work, you may (if authorized by the copyright holders to copy, free of charge and under the terms of this License, through
To “modify” a work means to copy from or adapt all or part of the work session of a copy. This License will therefore apply, along with any
of that material) supplement the terms of this License with terms: a publicly available network server or other readily accessible means,
in a fashion requiring copyright permission, other than the making of applicable section 7 additional terms, to the whole of the work, and
an exact copy. The resulting work is called a “modified version” of the all its parts, regardless of how they are packaged. This License gives then you must either (1) cause the Corresponding Source to be so
earlier work or a work “based on” the earlier work. no permission to license the work in any other way, but it does not * a) Disclaiming warranty or limiting liability differently from the available, or (2) arrange to deprive yourself of the benefit of the patent
invalidate such permission if you have separately received it. * d) If terms of sections 15 and 16 of this License; or * b) Requiring preser- license for this particular work, or (3) arrange, in a manner consistent
the work has interactive user interfaces, each must display Appropriate vation of specified reasonable legal notices or author attributions in with the requirements of this License, to extend the patent license to
A “covered work” means either the unmodified Program or a work
Legal Notices; however, if the Program has interactive interfaces that that material or in the Appropriate Legal Notices displayed by works downstream recipients. “Knowingly relying” means you have actual
based on the Program.
do not display Appropriate Legal Notices, your work need not make containing it; or * c) Prohibiting misrepresentation of the origin of knowledge that, but for the patent license, your conveying the cov-
them do so. that material, or requiring that modified versions of such material be ered work in a country, or your recipient's use of the covered work
To “propagate” a work means to do anything with it that, without per- marked in reasonable ways as different from the original version; or * in a country, would infringe one or more identifiable patents in that
mission, would make you directly or secondarily liable for infringement d) Limiting the use for publicity purposes of names of licensors or au- country that you have reason to believe are valid.
under applicable copyright law, except executing it on a computer or A compilation of a covered work with other separate and independent
thors of the material; or * e) Declining to grant rights under trademark
modifying a private copy. Propagation includes copying, distribution works, which are not by their nature extensions of the covered work,
law for use of some trade names, trademarks, or service marks; or * If, pursuant to or in connection with a single transaction or arrange-
(with or without modification), making available to the public, and in and which are not combined with it such as to form a larger program,
f) Requiring indemnification of licensors and authors of that material ment, you convey, or propagate by procuring conveyance of, a covered
some countries other activities as well. in or on a volume of a storage or distribution medium, is called an
by anyone who conveys the material (or modified versions of it) with work, and grant a patent license to some of the parties receiving the
“aggregate” if the compilation and its resulting copyright are not used
contractual assumptions of liability to the recipient, for any liability covered work authorizing them to use, propagate, modify or convey a
to limit the access or legal rights of the compilation's users beyond
To “convey” a work means any kind of propagation that enables other that these contractual assumptions directly impose on those licensors specific copy of the covered work, then the patent license you grant is
what the individual works permit. Inclusion of a covered work in an
parties to make or receive copies. Mere interaction with a user through and authors. automatically extended to all recipients of the covered work and works
aggregate does not cause this License to apply to the other parts of
a computer network, with no transfer of a copy, is not conveying. based on it.
the aggregate. 6. Conveying Non-Source Forms.
All other non-permissive additional terms are considered “further re-
An interactive user interface displays “Appropriate Legal Notices” to strictions” within the meaning of section 10. If the Program as you A patent license is “discriminatory” if it does not include within the
You may convey a covered work in object code form under the terms of
the extent that it includes a convenient and prominently visible fea- received it, or any part of it, contains a notice stating that it is gov- scope of its coverage, prohibits the exercise of, or is conditioned on the
sections 4 and 5, provided that you also convey the machine-readable
ture that (1) displays an appropriate copyright notice, and (2) tells the erned by this License along with a term that is a further restriction, non-exercise of one or more of the rights that are specifically granted
Corresponding Source under the terms of this License, in one of these
user that there is no warranty for the work (except to the extent that you may remove that term. If a license document contains a further under this License. You may not convey a covered work if you are
ways:
warranties are provided), that licensees may convey the work under restriction but permits relicensing or conveying under this License, you a party to an arrangement with a third party that is in the business
this License, and how to view a copy of this License. If the inter- may add to a covered work material governed by the terms of that li- of distributing software, under which you make payment to the third
face presents a list of user commands or options, such as a menu, a * a) Convey the object code in, or embodied in, a physical product (in- cense document, provided that the further restriction does not survive party based on the extent of your activity of conveying the work, and
prominent item in the list meets this criterion. 1. Source Code. cluding a physical distribution medium), accompanied by the Corre- such relicensing or conveying. under which the third party grants, to any of the parties who would
sponding Source fixed on a durable physical medium customarily used
receive the covered work from you, a discriminatory patent license (a)
for software interchange. * b) Convey the object code in, or embodied
The “source code” for a work means the preferred form of the work for If you add terms to a covered work in accord with this section, you in connection with copies of the covered work conveyed by you (or
in, a physical product (including a physical distribution medium), ac-
making modifications to it. “Object code” means any non-source form must place, in the relevant source files, a statement of the additional copies made from those copies), or (b) primarily for and in connection
companied by a written offer, valid for at least three years and valid
of a work. terms that apply to those files, or a notice indicating where to find the with specific products or compilations that contain the covered work,
for as long as you offer spare parts or customer support for that prod-
applicable terms. unless you entered into that arrangement, or that patent license was
uct model, to give anyone who possesses the object code either (1) a
A “Standard Interface” means an interface that either is an official granted, prior to 28 March 2007.
copy of the Corresponding Source for all the software in the product
standard defined by a recognized standards body, or, in the case of that is covered by this License, on a durable physical medium cus- Additional terms, permissive or non-permissive, may be stated in the
interfaces specified for a particular programming language, one that is tomarily used for software interchange, for a price no more than your Nothing in this License shall be construed as excluding or limiting any
form of a separately written license, or stated as exceptions; the above
widely used among developers working in that language. reasonable cost of physically performing this conveying of source, or implied license or other defenses to infringement that may otherwise
requirements apply either way. 8. Termination.
(2) access to copy the Corresponding Source from a network server at be available to you under applicable patent law. 12. No Surrender of
The “System Libraries” of an executable work include anything, other no charge. * c) Convey individual copies of the object code with a Others' Freedom.
than the work as a whole, that (a) is included in the normal form of copy of the written offer to provide the Corresponding Source. This You may not propagate or modify a covered work except as expressly
packaging a Major Component, but which is not part of that Major alternative is allowed only occasionally and noncommercially, and only provided under this License. Any attempt otherwise to propagate or If conditions are imposed on you (whether by court order, agreement
Component, and (b) serves only to enable use of the work with that if you received the object code with such an offer, in accord with sub- modify it is void, and will automatically terminate your rights under or otherwise) that contradict the conditions of this License, they do
Major Component, or to implement a Standard Interface for which an section 6b. * d) Convey the object code by offering access from a this License (including any patent licenses granted under the third not excuse you from the conditions of this License. If you cannot con-
implementation is available to the public in source code form. A “Ma- designated place (gratis or for a charge), and offer equivalent access to paragraph of section 11). vey a covered work so as to satisfy simultaneously your obligations
jor Component”, in this context, means a major essential component the Corresponding Source in the same way through the same place at under this License and any other pertinent obligations, then as a con-
(kernel, window system, and so on) of the specific operating system (if no further charge. You need not require recipients to copy the Corre- However, if you cease all violation of this License, then your license sequence you may not convey it at all. For example, if you agree to
any) on which the executable work runs, or a compiler used to produce sponding Source along with the object code. If the place to copy the from a particular copyright holder is reinstated (a) provisionally, un- terms that obligate you to collect a royalty for further conveying from
the work, or an object code interpreter used to run it. object code is a network server, the Corresponding Source may be on a less and until the copyright holder explicitly and finally terminates those to whom you convey the Program, the only way you could satisfy
both those terms and this License would be to refrain entirely from Later license versions may give you additional or different permissions. If the disclaimer of warranty and limitation of liability provided above You should have received a copy of the GNU General Public License
conveying the Program. 13. Use with the GNU Affero General Public However, no additional obligations are imposed on any author or copy- cannot be given local legal effect according to their terms, reviewing along with this program. If not, see <http://www.gnu.org/licenses/>.
License. right holder as a result of your choosing to follow a later version. 15. courts shall apply local law that most closely approximates an abso-
Disclaimer of Warranty. lute waiver of all civil liability in connection with the Program, unless a
warranty or assumption of liability accompanies a copy of the Program Also add information on how to contact you by electronic and paper
Notwithstanding any other provision of this License, you have permis- in return for a fee. mail.
sion to link or combine any covered work with a work licensed under
version 3 of the GNU Affero General Public License into a single com- THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EX-
TENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN END OF TERMS AND CONDITIONS How to Apply These Terms If the program does terminal interaction, make it output a short notice
bined work, and to convey the resulting work. The terms of this Li-
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLD- to Your New Programs like this when it starts in an interactive mode:
cense will continue to apply to the part which is the covered work, but
the special requirements of the GNU Affero General Public License, ERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM
section 13, concerning interaction through a network will apply to the “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EX- If you develop a new program, and you want it to be of the greatest <program> Copyright (C) <year> <name of author> This program
combination as such. 14. Revised Versions of this License. PRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, possible use to the public, the best way to achieve this is to make it comes with ABSOLUTELY NO WARRANTY; for details type `show
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND free software which everyone can redistribute and change under these w'. This is free software, and you are welcome to redistribute it under
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK terms. certain conditions; type `show c' for details.
The Free Software Foundation may publish revised and/or new ver- AS TO THE QUALITY AND PERFORMANCE OF THE PRO-
sions of the GNU General Public License from time to time. Such new GRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DE-
To do so, attach the following notices to the program. It is safest to
versions will be similar in spirit to the present version, but may differ FECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SER- The hypothetical commands `show w' and `show c' should show the
attach them to the start of each source file to most effectively state the
in detail to address new problems or concerns. VICING, REPAIR OR CORRECTION. 16. Limitation of Liability. appropriate parts of the General Public License. Of course, your pro-
exclusion of warranty; and each file should have at least the “copyright”
line and a pointer to where the full notice is found. gram's commands might be different; for a GUI interface, you would
use an “about box”.
Each version is given a distinguishing version number. If the Program
specifies that a certain numbered version of the GNU General Pub- IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
<one line to give the program's name and a brief idea of what it does.>
lic License “or any later version” applies to it, you have the option of AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, You should also get your employer (if you work as a programmer) or
Copyright (C) <year> <name of author>
following the terms and conditions either of that numbered version or OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS school, if any, to sign a “copyright disclaimer” for the program, if nec-
of any later version published by the Free Software Foundation. If THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU essary. For more information on this, and how to apply and follow the
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCI- This program is free software: you can redistribute it and/or modify
the Program does not specify a version number of the GNU General it under the terms of the GNU General Public License as published by GNU GPL, see <http://www.gnu.org/licenses/>.
Public License, you may choose any version ever published by the Free DENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING the Free Software Foundation, either version 3 of the License, or (at
Software Foundation. your option) any later version.
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING REN- The GNU General Public License does not permit incorporating your
DERED INACCURATE OR LOSSES SUSTAINED BY YOU OR program into proprietary programs. If your program is a subroutine
If the Program specifies that a proxy can decide which future versions THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPER- This program is distributed in the hope that it will be useful, but library, you may consider it more useful to permit linking proprietary
of the GNU General Public License can be used, that proxy's public ATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER WITHOUT ANY WARRANTY; without even the implied warranty applications with the library. If this is what you want to do, use the
statement of acceptance of a version permanently authorizes you to OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY of MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR- GNU Lesser General Public License instead of this License. But first,
choose that version for the Program. OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. POSE. See the GNU General Public License for more details. please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.

13.2 GNU Free Documentation License

Version 1.3, 3 November 2008 following text that translates XYZ in another language. (Here XYZ the Invariant Sections of the Document, unaltered in their text and Title (section 1) will typically require changing the actual title. 9.
stands for a specific section name mentioned below, such as "Acknowl- in their titles. Section numbers or the equivalent are not considered TERMINATION
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, edgements", "Dedications", "Endorsements", or "History".) To "Pre- part of the section titles. * M. Delete any section Entitled "Endorse-
Inc. <http://fsf.org/> serve the Title" of such a section when you modify the Document ments". Such a section may not be included in the Modified Version. You may not copy, modify, sublicense, or distribute the Document
means that it remains a section "Entitled XYZ" according to this def- * N. Do not retitle any existing section to be Entitled "Endorsements" except as expressly provided under this License. Any attempt oth-
inition. or to conflict in title with any Invariant Section. * O. Preserve any erwise to copy, modify, sublicense, or distribute it is void, and will
Everyone is permitted to copy and distribute verbatim copies of this Warranty Disclaimers.
license document, but changing it is not allowed. 0. PREAMBLE automatically terminate your rights under this License.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These War- If the Modified Version includes new front-matter sections or appen- However, if you cease all violation of this License, then your license
The purpose of this License is to make a manual, textbook, or other ranty Disclaimers are considered to be included by reference in this dices that qualify as Secondary Sections and contain no material copied
functional and useful document "free" in the sense of freedom: to as- from a particular copyright holder is reinstated (a) provisionally, un-
License, but only as regards disclaiming warranties: any other impli- from the Document, you may at your option designate some or all of less and until the copyright holder explicitly and finally terminates
sure everyone the effective freedom to copy and redistribute it, with or cation that these Warranty Disclaimers may have is void and has no these sections as invariant. To do this, add their titles to the list of
without modifying it, either commercially or noncommercially. Sec- your license, and (b) permanently, if the copyright holder fails to no-
effect on the meaning of this License. 2. VERBATIM COPYING Invariant Sections in the Modified Version's license notice. These titles tify you of the violation by some reasonable means prior to 60 days
ondarily, this License preserves for the author and publisher a way to must be distinct from any other section titles.
get credit for their work, while not being considered responsible for after the cessation.
modifications made by others. You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the You may add a section Entitled "Endorsements", provided it con-
Moreover, your license from a particular copyright holder is reinstated
copyright notices, and the license notice saying this License applies tains nothing but endorsements of your Modified Version by various
This License is a kind of "copyleft", which means that derivative works permanently if the copyright holder notifies you of the violation by
to the Document are reproduced in all copies, and that you add no parties—for example, statements of peer review or that the text has
of the document must themselves be free in the same sense. It com- some reasonable means, this is the first time you have received notice
other conditions whatsoever to those of this License. You may not use been approved by an organization as the authoritative definition of a
plements the GNU General Public License, which is a copyleft license of violation of this License (for any work) from that copyright holder,
technical measures to obstruct or control the reading or further copy- standard.
designed for free software. and you cure the violation prior to 30 days after your receipt of the
ing of the copies you make or distribute. However, you may accept notice.
compensation in exchange for copies. If you distribute a large enough You may add a passage of up to five words as a Front-Cover Text,
We have designed this License in order to use it for manuals for free number of copies you must also follow the conditions in section 3. and a passage of up to 25 words as a Back-Cover Text, to the end
software, because free software needs free documentation: a free pro- Termination of your rights under this section does not terminate the
of the list of Cover Texts in the Modified Version. Only one passage
gram should come with manuals providing the same freedoms that the licenses of parties who have received copies or rights from you under
You may also lend copies, under the same conditions stated above, and of Front-Cover Text and one of Back-Cover Text may be added by
software does. But this License is not limited to software manuals; this License. If your rights have been terminated and not permanently
you may publicly display copies. 3. COPYING IN QUANTITY (or through arrangements made by) any one entity. If the Document
it can be used for any textual work, regardless of subject matter or reinstated, receipt of a copy of some or all of the same material does
already includes a cover text for the same cover, previously added by
whether it is published as a printed book. We recommend this Li- not give you any rights to use it. 10. FUTURE REVISIONS OF THIS
If you publish printed copies (or copies in media that commonly have you or by arrangement made by the same entity you are acting on
cense principally for works whose purpose is instruction or reference. LICENSE
printed covers) of the Document, numbering more than 100, and the behalf of, you may not add another; but you may replace the old one,
1. APPLICABILITY AND DEFINITIONS on explicit permission from the previous publisher that added the old
Document's license notice requires Cover Texts, you must enclose the
one. The Free Software Foundation may publish new, revised versions
copies in covers that carry, clearly and legibly, all these Cover Texts:
This License applies to any manual or other work, in any medium, of the GNU Free Documentation License from time to time. Such
Front-Cover Texts on the front cover, and Back-Cover Texts on the
that contains a notice placed by the copyright holder saying it can new versions will be similar in spirit to the present version, but
back cover. Both covers must also clearly and legibly identify you as The author(s) and publisher(s) of the Document do not by this Li-
be distributed under the terms of this License. Such a notice grants a may differ in detail to address new problems or concerns. See
the publisher of these copies. The front cover must present the full title cense give permission to use their names for publicity for or to as-
world-wide, royalty-free license, unlimited in duration, to use that work http://www.gnu.org/copyleft/.
with all words of the title equally prominent and visible. You may add sert or imply endorsement of any Modified Version. 5. COMBINING
under the conditions stated herein. The "Document", below, refers to other material on the covers in addition. Copying with changes limited DOCUMENTS
any such manual or work. Any member of the public is a licensee, and to the covers, as long as they preserve the title of the Document and Each version of the License is given a distinguishing version number.
is addressed as "you". You accept the license if you copy, modify or satisfy these conditions, can be treated as verbatim copying in other If the Document specifies that a particular numbered version of this
You may combine the Document with other documents released under
distribute the work in a way requiring permission under copyright law. respects. License "or any later version" applies to it, you have the option of
this License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the In- following the terms and conditions either of that specified version or
A "Modified Version" of the Document means any work containing the variant Sections of all of the original documents, unmodified, and list of any later version that has been published (not as a draft) by the
If the required texts for either cover are too voluminous to fit legibly,
Document or a portion of it, either copied verbatim, or with modifica- them all as Invariant Sections of your combined work in its license Free Software Foundation. If the Document does not specify a version
you should put the first ones listed (as many as fit reasonably) on the
tions and/or translated into another language. notice, and that you preserve all their Warranty Disclaimers. number of this License, you may choose any version ever published
actual cover, and continue the rest onto adjacent pages.
(not as a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of this License
A "Secondary Section" is a named appendix or a front-matter sec- If you publish or distribute Opaque copies of the Document numbering The combined work need only contain one copy of this License, and can be used, that proxy's public statement of acceptance of a version
tion of the Document that deals exclusively with the relationship of more than 100, you must either include a machine-readable Transpar- multiple identical Invariant Sections may be replaced with a single permanently authorizes you to choose that version for the Document.
the publishers or authors of the Document to the Document's overall ent copy along with each Opaque copy, or state in or with each Opaque copy. If there are multiple Invariant Sections with the same name 11. RELICENSING
subject (or to related matters) and contains nothing that could fall copy a computer-network location from which the general network- but different contents, make the title of each such section unique by
directly within that overall subject. (Thus, if the Document is in part using public has access to download using public-standard network adding at the end of it, in parentheses, the name of the original au-
a textbook of mathematics, a Secondary Section may not explain any protocols a complete Transparent copy of the Document, free of added thor or publisher of that section if known, or else a unique number. "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
mathematics.) The relationship could be a matter of historical connec- material. If you use the latter option, you must take reasonably pru- Make the same adjustment to the section titles in the list of Invariant World Wide Web server that publishes copyrightable works and also
tion with the subject or with related matters, or of legal, commercial, dent steps, when you begin distribution of Opaque copies in quantity, Sections in the license notice of the combined work. provides prominent facilities for anybody to edit those works. A public
philosophical, ethical or political position regarding them. to ensure that this Transparent copy will remain thus accessible at the wiki that anybody can edit is an example of such a server. A "Massive
stated location until at least one year after the last time you distribute Multiauthor Collaboration" (or "MMC") contained in the site means
In the combination, you must combine any sections Entitled "History" any set of copyrightable works thus published on the MMC site.
The "Invariant Sections" are certain Secondary Sections whose titles an Opaque copy (directly or through your agents or retailers) of that in the various original documents, forming one section Entitled "His-
are designated, as being those of Invariant Sections, in the notice that edition to the public. tory"; likewise combine any sections Entitled "Acknowledgements",
says that the Document is released under this License. If a section does and any sections Entitled "Dedications". You must delete all sections "CC-BY-SA" means the Creative Commons Attribution-Share Alike
not fit the above definition of Secondary then it is not allowed to be It is requested, but not required, that you contact the authors of the Entitled "Endorsements". 6. COLLECTIONS OF DOCUMENTS 3.0 license published by Creative Commons Corporation, a not-for-
designated as Invariant. The Document may contain zero Invariant Document well before redistributing any large number of copies, to profit corporation with a principal place of business in San Francisco,
Sections. If the Document does not identify any Invariant Sections give them a chance to provide you with an updated version of the California, as well as future copyleft versions of that license published
You may make a collection consisting of the Document and other doc-
then there are none. Document. 4. MODIFICATIONS by that same organization.
uments released under this License, and replace the individual copies
of this License in the various documents with a single copy that is
The "Cover Texts" are certain short passages of text that are listed, You may copy and distribute a Modified Version of the Document un- included in the collection, provided that you follow the rules of this "Incorporate" means to publish or republish a Document, in whole or
as Front-Cover Texts or Back-Cover Texts, in the notice that says that der the conditions of sections 2 and 3 above, provided that you release License for verbatim copying of each of the documents in all other in part, as part of another Document.
the Document is released under this License. A Front-Cover Text may the Modified Version under precisely this License, with the Modified respects.
be at most 5 words, and a Back-Cover Text may be at most 25 words. Version filling the role of the Document, thus licensing distribution An MMC is "eligible for relicensing" if it is licensed under this License,
and modification of the Modified Version to whoever possesses a copy You may extract a single document from such a collection, and dis- and if all works that were first published under this License somewhere
A "Transparent" copy of the Document means a machine-readable of it. In addition, you must do these things in the Modified Version: tribute it individually under this License, provided you insert a copy other than this MMC, and subsequently incorporated in whole or in
copy, represented in a format whose specification is available to the of this License into the extracted document, and follow this License part into the MMC, (1) had no cover texts or invariant sections, and
general public, that is suitable for revising the document straightfor- * A. Use in the Title Page (and on the covers, if any) a title distinct in all other respects regarding verbatim copying of that document. 7. (2) were thus incorporated prior to November 1, 2008.
wardly with generic text editors or (for images composed of pixels) from that of the Document, and from those of previous versions (which AGGREGATION WITH INDEPENDENT WORKS
generic paint programs or (for drawings) some widely available drawing should, if there were any, be listed in the History section of the Docu- The operator of an MMC Site may republish an MMC contained in
editor, and that is suitable for input to text formatters or for automatic ment). You may use the same title as a previous version if the original A compilation of the Document or its derivatives with other separate the site under CC-BY-SA on the same site at any time before August
translation to a variety of formats suitable for input to text formatters. publisher of that version gives permission. * B. List on the Title Page, and independent documents or works, in or on a volume of a storage or 1, 2009, provided the MMC is eligible for relicensing. ADDENDUM:
A copy made in an otherwise Transparent file format whose markup, as authors, one or more persons or entities responsible for authorship distribution medium, is called an "aggregate" if the copyright resulting How to use this License for your documents
or absence of markup, has been arranged to thwart or discourage sub- of the modifications in the Modified Version, together with at least five from the compilation is not used to limit the legal rights of the com-
sequent modification by readers is not Transparent. An image format of the principal authors of the Document (all of its principal authors, pilation's users beyond what the individual works permit. When the
is not Transparent if used for any substantial amount of text. A copy To use this License in a document you have written, include a copy
if it has fewer than five), unless they release you from this require- Document is included in an aggregate, this License does not apply to of the License in the document and put the following copyright and
that is not "Transparent" is called "Opaque". ment. * C. State on the Title page the name of the publisher of the the other works in the aggregate which are not themselves derivative license notices just after the title page:
Modified Version, as the publisher. * D. Preserve all the copyright works of the Document.
Examples of suitable formats for Transparent copies include plain notices of the Document. * E. Add an appropriate copyright notice
ASCII without markup, Texinfo input format, LaTeX input for- for your modifications adjacent to the other copyright notices. * F. In- Copyright (C) YEAR YOUR NAME. Permission is granted to copy,
If the Cover Text requirement of section 3 is applicable to these copies distribute and/or modify this document under the terms of the GNU
mat, SGML or XML using a publicly available DTD, and standard- clude, immediately after the copyright notices, a license notice giving
of the Document, then if the Document is less than one half of the Free Documentation License, Version 1.3 or any later version pub-
conforming simple HTML, PostScript or PDF designed for human the public permission to use the Modified Version under the terms of
entire aggregate, the Document's Cover Texts may be placed on cov- lished by the Free Software Foundation; with no Invariant Sections,
modification. Examples of transparent image formats include PNG, this License, in the form shown in the Addendum below. * G. Preserve
ers that bracket the Document within the aggregate, or the electronic no Front-Cover Texts, and no Back-Cover Texts. A copy of the license
XCF and JPG. Opaque formats include proprietary formats that can in that license notice the full lists of Invariant Sections and required
equivalent of covers if the Document is in electronic form. Otherwise is included in the section entitled "GNU Free Documentation License".
be read and edited only by proprietary word processors, SGML or Cover Texts given in the Document's license notice. * H. Include an
they must appear on printed covers that bracket the whole aggregate.
XML for which the DTD and/or processing tools are not generally unaltered copy of this License. * I. Preserve the section Entitled "His-
8. TRANSLATION
available, and the machine-generated HTML, PostScript or PDF pro- tory", Preserve its Title, and add to it an item stating at least the title, If you have Invariant Sections, Front-Cover Texts and Back-Cover
duced by some word processors for output purposes only. year, new authors, and publisher of the Modified Version as given on Texts, replace the "with … Texts." line with this:
the Title Page. If there is no section Entitled "History" in the Docu- Translation is considered a kind of modification, so you may distribute
ment, create one stating the title, year, authors, and publisher of the translations of the Document under the terms of section 4. Replacing
The "Title Page" means, for a printed book, the title page itself, plus Invariant Sections with translations requires special permission from with the Invariant Sections being LIST THEIR TITLES, with the
such following pages as are needed to hold, legibly, the material this Document as given on its Title Page, then add an item describing the Front-Cover Texts being LIST, and with the Back-Cover Texts being
Modified Version as stated in the previous sentence. * J. Preserve the their copyright holders, but you may include translations of some or all
License requires to appear in the title page. For works in formats Invariant Sections in addition to the original versions of these Invari- LIST.
which do not have any title page as such, "Title Page" means the text network location, if any, given in the Document for public access to a
Transparent copy of the Document, and likewise the network locations ant Sections. You may include a translation of this License, and all the
near the most prominent appearance of the work's title, preceding the license notices in the Document, and any Warranty Disclaimers, pro- If you have Invariant Sections without Cover Texts, or some other
beginning of the body of the text. given in the Document for previous versions it was based on. These
may be placed in the "History" section. You may omit a network vided that you also include the original English version of this License combination of the three, merge those two alternatives to suit the sit-
location for a work that was published at least four years before the and the original versions of those notices and disclaimers. In case of a uation.
The "publisher" means any person or entity that distributes copies of Document itself, or if the original publisher of the version it refers to disagreement between the translation and the original version of this
the Document to the public. gives permission. * K. For any section Entitled "Acknowledgements" License or a notice or disclaimer, the original version will prevail. If your document contains nontrivial examples of program code, we
or "Dedications", Preserve the Title of the section, and preserve in recommend releasing these examples in parallel under your choice of
A section "Entitled XYZ" means a named subunit of the Document the section all the substance and tone of each of the contributor ac- If a section in the Document is Entitled "Acknowledgements", "Ded- free software license, such as the GNU General Public License, to per-
whose title either is precisely XYZ or contains XYZ in parentheses knowledgements and/or dedications given therein. * L. Preserve all ications", or "History", the requirement (section 4) to Preserve its mit their use in free software.
13.3 GNU Lesser General Public License
GNU LESSER GENERAL PUBLIC LICENSE The “Corresponding Application Code” for a Combined Work means You may convey a Combined Work under terms of your choice that, You may place library facilities that are a work based on the Library
the object code and/or source code for the Application, including any taken together, effectively do not restrict modification of the portions side by side in a single library together with other library facilities that
Version 3, 29 June 2007 data and utility programs needed for reproducing the Combined Work of the Library contained in the Combined Work and reverse engineer- are not Applications and are not covered by this License, and convey
from the Application, but excluding the System Libraries of the Com- ing for debugging such modifications, if you also do each of the follow- such a combined library under terms of your choice, if you do both of
bined Work. 1. Exception to Section 3 of the GNU GPL. ing: the following:
Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/>
You may convey a covered work under sections 3 and 4 of this License * a) Accompany the combined library with a copy of the same work
Everyone is permitted to copy and distribute verbatim copies of this without being bound by section 3 of the GNU GPL. 2. Conveying * a) Give prominent notice with each copy of the Combined Work
license document, but changing it is not allowed. that the Library is used in it and that the Library and its use are based on the Library, uncombined with any other library facilities,
Modified Versions. conveyed under the terms of this License. * b) Give prominent no-
covered by this License. * b) Accompany the Combined Work with a
copy of the GNU GPL and this license document. * c) For a Com- tice with the combined library that part of it is a work based on the
This version of the GNU Lesser General Public License incorporates If you modify a copy of the Library, and, in your modifications, a fa- Library, and explaining where to find the accompanying uncombined
the terms and conditions of version 3 of the GNU General Public Li- bined Work that displays copyright notices during execution, include
cility refers to a function or data to be supplied by an Application that the copyright notice for the Library among these notices, as well as a form of the same work.
cense, supplemented by the additional permissions listed below. 0. uses the facility (other than as an argument passed when the facility
Additional Definitions. reference directing the user to the copies of the GNU GPL and this
is invoked), then you may convey a copy of the modified version: license document. * d) Do one of the following: o 0) Convey the 6. Revised Versions of the GNU Lesser General Public License.
Minimal Corresponding Source under the terms of this License, and
As used herein, “this License” refers to version 3 of the GNU Lesser * a) under this License, provided that you make a good faith effort to the Corresponding Application Code in a form suitable for, and under
General Public License, and the “GNU GPL” refers to version 3 of the ensure that, in the event an Application does not supply the function terms that permit, the user to recombine or relink the Application The Free Software Foundation may publish revised and/or new ver-
GNU General Public License. or data, the facility still operates, and performs whatever part of its with a modified version of the Linked Version to produce a modified sions of the GNU Lesser General Public License from time to time.
purpose remains meaningful, or * b) under the GNU GPL, with none Combined Work, in the manner specified by section 6 of the GNU Such new versions will be similar in spirit to the present version, but
“The Library” refers to a covered work governed by this License, other of the additional permissions of this License applicable to that copy. GPL for conveying Corresponding Source. o 1) Use a suitable shared may differ in detail to address new problems or concerns.
than an Application or a Combined Work as defined below. library mechanism for linking with the Library. A suitable mechanism
3. Object Code Incorporating Material from Library Header Files. is one that (a) uses at run time a copy of the Library already present Each version is given a distinguishing version number. If the Library
An “Application” is any work that makes use of an interface provided on the user's computer system, and (b) will operate properly with a as you received it specifies that a certain numbered version of the GNU
by the Library, but which is not otherwise based on the Library. Defin- The object code form of an Application may incorporate material from modified version of the Library that is interface-compatible with the Lesser General Public License “or any later version” applies to it, you
ing a subclass of a class defined by the Library is deemed a mode of a header file that is part of the Library. You may convey such object Linked Version. * e) Provide Installation Information, but only if you have the option of following the terms and conditions either of that
using an interface provided by the Library. code under terms of your choice, provided that, if the incorporated ma- would otherwise be required to provide such information under section published version or of any later version published by the Free Software
terial is not limited to numerical parameters, data structure layouts 6 of the GNU GPL, and only to the extent that such information is Foundation. If the Library as you received it does not specify a version
and accessors, or small macros, inline functions and templates (ten or necessary to install and execute a modified version of the Combined number of the GNU Lesser General Public License, you may choose
A “Combined Work” is a work produced by combining or linking an Work produced by recombining or relinking the Application with a
Application with the Library. The particular version of the Library fewer lines in length), you do both of the following: any version of the GNU Lesser General Public License ever published
modified version of the Linked Version. (If you use option 4d0, the by the Free Software Foundation.
with which the Combined Work was made is also called the “Linked Installation Information must accompany the Minimal Corresponding
Version”. * a) Give prominent notice with each copy of the object code that the Source and Corresponding Application Code. If you use option 4d1,
Library is used in it and that the Library and its use are covered by you must provide the Installation Information in the manner specified If the Library as you received it specifies that a proxy can decide
The “Minimal Corresponding Source” for a Combined Work means the this License. * b) Accompany the object code with a copy of the GNU by section 6 of the GNU GPL for conveying Corresponding Source.) whether future versions of the GNU Lesser General Public License
Corresponding Source for the Combined Work, excluding any source GPL and this license document. shall apply, that proxy's public statement of acceptance of any ver-
code for portions of the Combined Work that, considered in isolation, sion is permanent authorization for you to choose that version for the
are based on the Application, and not on the Linked Version. 4. Combined Works. 5. Combined Libraries. Library.