Distribution
************

Copyright © 1991 Aamod Sane.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the same conditions as for modified versions.

VIP
***

VIP is a VI emulation package for GNU Emacs. VIP implements most VI and EX commands. VIP gives you the best of both worlds: VI keystrokes for editing combined with the GNU Emacs environment. VIP also fixes some common complaints with VI commands. This manual describes VIP, concentrating on the differences from VI and new features of VIP.

VIP is intended to be usable without reading this manual --- the defaults are set to make VIP as close to VI as possible. The VIP startup message attempts to tell you the basic GNU Emacs window management commands to help you start immediately. The full VI/EX macro language is not yet implemented. You need to know some emacs lisp to customize VIP.

It is recommended that you read the Overview node. The other nodes may be visited as needed.

Comments and bug reports are welcome. sane@cs.uiuc.edu is the current address for VIP reports.

Overview of VIP
***************

VIP is a VI emulation on top of Emacs. We wish to give access to Emacs facilities through VIP. Perfect compatibility with VI is possible but not desirable. This chapter tells you about the Emacs ideas that you should know about, how to use VIP within emacs and some incompatibilities.

Emacs Preliminaries
===================

Emacs can edit several files at once. A file in Emacs is placed in a buffer that has the same name as the file. Buffers are also used for other purposes, such as shell interfaces, directory editing etc. See Directory Editor (The Gnu Emacs Manual), for an example.

A buffer has a distinguished position called the point. A point is always between 2 characters, and is looking at the right hand character. The cursor is positioned on the right hand character. Thus, when the point is looking at the end-of-line, the cursor is on the end-of-line character, i.e. beyond the last character on the line. This is the default Emacs behavior.

The default settings of VIP try to mimic the behavior of VI, preventing the cursor from going beyond the last character on the line. However, under some circumstances it is possible for the cursor to get beyond the end-of-line, so do not be surprised if this happens.

In addition to the point, there is another distinguished buffer position called the mark. See Mark (The GNU Emacs manual), for more info on the mark. The text between the point and the mark is called the region of the buffer. For the VIP user, this simply means that in addition to the VI textmarkers a--z, there is another marker called mark. VIP provides access to the region in most text manipulation commands as r and R suffix to commands that operate on text regions. e.g. dr to delete region etc. See Basics, for more info.

Emacs divides the screen into tiled windows. You can see the contents of a buffer through the window associated with the buffer.  The cursor of the screen is positioned on the character after point. Every window has a mode line that displays information about the buffer. You can change the format of the mode line, but normally if you see ** at the beginning of a mode line it means that the buffer is modified.  If you write out the contents of the buffer to a file, then the buffer will become not modified.  Also if you see %% at the beginning of the mode line, it means that the file associated with the buffer is write protected. The mode line will also show the buffer name and current major and minor modes (See below). A special buffer called Minibuffer is displayed as the last line in a Minibuffer window. The Minibuffer window is used for command input output. VIP uses the Minibuffer window for / and some other commands.

An Emacs buffer can have a major mode that customizes Emacs for editing text of a particular sort by changing the functionality of the keys. Keys are defined using a keymap that records the bindings between keystrokes and functions. The global keymap common to all the buffers.  Additionally, each buffer has its local keymap that determines the mode of the buffer.  If a function is bound to some key in the local keymap then that function will be executed when you type the key. If no function is bound to a key in the local map, however, the function bound to the key in the global map will be executed. See Major Modes (The GNU Emacs Manual), for more information.

A buffer can also have a minor mode. Minor modes are options that you can use or not. A buffer in text-mode can have auto-fill-mode as minor mode, which can be turned off or on at any time. A minor mode changes the local keymap when turned on, and changes it back to original when turned off. For more information, see Minor Modes (The GNU Emacs Manual).

VIP is implemented as a minor mode. This means that you can turn VIP on or off at any time in any major mode. See Modes in VIP for more information.

Emacs uses Control and Meta modifiers. These are denoted as C and M, e.g. ^Z as C-z and Meta-x as M-x. For keyboards that do not have a Meta key, the ESC is used as Meta. Thus M-x is typed as ESC x. VIP uses ESC to switch from Insert mode to Vi mode. Therefore VIP defines _ as its Meta key in Vi mode. See Vi Mode, for more info.

Emacs is structured as a lisp interpreter around a C core. Emacs keys cause lisp functions to be called. It is possible to call these functions directly typing M-x function-name.

Loading VIP
===========

The most common way to load VIP automatically is to include the line:

     (load "vip")

in your .emacs file.  The .emacs file is placed in your home directory and it will be executed every time you invoke Emacs.  If you wish to be in Vi mode whenever Emacs starts up, you can include the following line in your .emacs file instead of the above line:

     (setq term-setup-hook 'vip-mode)

(see Vi Mode, for the explanation of vi mode.)

Once invoked, VIP will arrange to bring up most buffers in Vi mode.

Even if your .emacs file does not contain any of the above lines, you can load VIP and enter vi mode by typing the following from within Emacs.

     M-x vip-mode

Ask your local Emacs administrator if this fails to work.

When Emacs first comes up, if you have not specified a file on the command line, it will show up the *scratch* buffer, in the Lisp Interaction mode. After you invoke VIP, you can start editing files by using :e.

VIP also has its own startup file, called .vip. Most VIP customization commands can be put in .vip except (load "vip"), which must be in the Emacs startup, .emacs.

Modes in VIP
============

VIP has 4 modes, Emacs, Vi, Insert, Replace.

Emacs mode
     This is the mode Emacs is normally in. After you have loaded vip, C-z will take you to Vi mode. Another C-z will take you back to Emacs mode. This toggle key can be changed, see Customization. You can also type M-x vip-mode to change to Vi mode.

Vi mode
     This is the VI command mode. Any of the VI i, o, a ... etc. commands will take you to Insert mode. All VI commands may be used in this mode. Most EX commands can also be used.

Insert mode
     Insert mode is the VI insertion mode. ESC will take you back to Vi mode. Insert mode editing can be done, including autoindentation. By default, VIP disables Emacs keybindings in Insert mode.

Replace mode
     Commands like cw invoke the Replace mode. When you cross the $ sign, or when you type ESC, it will automatically change to Insert mode. You do not have to worry about it. The key bindings remain the same as Insert mode. It is invoked for internal use, and serves as a reminder to the user.

The modes are indicated on the mode line, so that the multiple modes do not confuse you. Most of your editing can be done in Vi and Insert modes. VIP will try to make all new buffers be in Vi mode, but sometimes they will come up either in Emacs mode, or their own major modes. C-z will take you to Vi mode in such a case.

Modes in VIP are orthogonal to Emacs major modes, such as C mode or Dired mode. You can turn VIP on and off for any Emacs mode. When VIP is turned on, Vi mode can be used to move around. In Insert mode, the bindings for these modes can be accessed. By default, these bindings are suppressed in Insert mode, so that a new user is not confused by the Emacs modes. Note that unless you turn the bindings on in Insert mode, you cannot do interesting things like language sensitive editing. See Customization, to find out how to do this.

Now for the details of these modes.

Emacs Mode
----------

You will be in this mode only by accident (hopefully). This is the mode Emacs is normally in (imagine!!). Now leave it as soon as possible by typing C-z. The you will be in Vi mode (sigh of relief) :-).

Emacs mode is actually a VIP'ism to denote all the major and minor modes (see Emacs Preliminaries.) other than VIP that Emacs can be in. Emacs can have several modes, such as C mode for C editing, Dired for directory editing etc. These are major modes, each with a different set of key-bindings. VIP modes are orthogonal to these Emacs major modes. The presence of these language sensitive and other modes is a major win over VI. See Improvements over VI for more.

The bindings for these modes can be made available in the VIP Insert mode as well as in Emacs mode. It is even possible to bind some keys in the manner of VI, and keep the rest according to the major mode. This means that you can use specialized behavior in Insert mode, and then jump back to Vi mode for any movement, deletion etc.

See Customization, to find out how to do this.

Vi Mode
-------

This is the Vi command mode. Most keys will work as in Vi. The notable exceptions are:

C-x
     C-x is used to invoke Emacs commands, mainly those that do window management. C-x 2 will split a window, C-x 0 will close a window. C-x 1 will close all other windows. C-xb is used to switch buffers in a window, and C-xo to move through windows. These are about the only necessary keystrokes. For the rest see GNU Emacs Manual.

C-g and C-]
     These are the Emacs quit keys. I have tried to make VIP use C-c as the quit key, but these keys are harcoded in some places in Emacs for all but the most recent versions. There will be cases where you will have to use C-g to quit. Similarly, C-] is used to exit Recursive Edits in Emacs for which there is no comparable VI functionality and no key-binding. Recursive edits are indicated by [] brackets framing the modes on the mode line. See Recursive Edit (The GNU Emacs Manual).

     Besides, C-c is used in Emacs as a general user binding key. Many packages will define key sequences that use C-c. After a little experience, you should either free up C-c, or swap the C-g and C-c keys. See Keyboard Translate Table (GNU Emacs Lisp Reference Manual), to find out how to do this.

Underscore
     VIP uses ESC as switch between Insert and Vi modes. Emacs uses ESC for Meta. We need a Meta key to call the Meta key functions such as M-x function name. _ key was chosen, since it is the only reasonable free VI key left. Thus, in Vi mode, to get M-x, you should type _x. It is possible to use ESC as Meta, but then you cannot press ESC multiple times in Vi mode. See Customization, to find out how to rebind ESC to be Meta.

Other differences are mostly improvements. The ones you should know about are:

Undo
     u will undo. Undo can be repeated by the . key. Undo itself can be undone. Another u will change the direction. The presence of repeatable undo means that U, undoing lines, is not very important. Therefore, U also calls vip-undo.

Counts
     Most commands, ~, [[, p, /, ... etc. take counts.

Regexps
     VIP uses Emacs Regular Expressions for searches. These are a superset of VI regular expressions, excepting the change-of-case escapes \u, \L, ... etc. See Regular Expressions (The GNU Emacs Manual), for details. Files specified to :e use csh regular expressions (globbing, wildcards, what have you).

Ex commands
     The directory of a file is automatically prepended to any :e non-absolute-pathname done from the corresponding buffer. Absolute filenames are required less often in VIP. :cd will change the default directory for the buffer the :cd is issued from. :e will interpret the filename argument by default in csh. See Customization if you want to change this.:next takes counts from :args, so that :rew is obsolete. Also, :args will show only the undisplayed files. The current file should be visible on the mode line.

See Improvements over VI for more information.

Insert Mode
-----------

By default, VIP makes the standard VI keys available in Insert mode. But this also means that Emacs major modes cannot be used in Insert mode. It is strongly recommended that as soon as you are comfortable, make the Emacs mode bindings visible. See Customization, to see how to do this.

Once this is done, it is possible to do quite a bit of editing in the Insert mode, and also use Shell, Dired and other modes of Emacs.

You can call Meta functions from Insert mode. The Vi to Emacs toggle key, normally C-z, can now be used as Meta. Thus M-x is typed as C-zx. _ will now insert itself.

Replace Mode
------------

As a user, you should not be concerned about this mode. However, if you start doing Insert mode editing, then remember that if you move beyond the line that the $ sign is in, Replace will get confused, and not remove the $ after you are done. Otherwise you can use nice Emacs features like dynamic abbreviations. See Dynamic Abbreviations (The GNU Emacs Manual), for details.

The Minibuffer
==============

The minibuffer is where commands are entered in. Editing can be done by commands from Insert mode, namely:

C-h
     Backspace

C-w
     Delete Word

C-u
     Erase line

C-c
     Quit

C-v
     Quote the following character

ESC
     Leave minibuffer

RET
     Execute command

C-g and C-]
     Emacs quit and abort keys. These may be necessary. See Vi Mode for an explanation.

The Emacs keys are functional in the minibuffer. It is possible to turn them off, but this version does not do so. There are some issues to be resolved before this happens.

Multiple Files in VIP
=====================

VIP can edit multiple files. This means, for example that you never need to suffer through No write since last change errors. Some VIP elements are common over all the files.

Textmarkers
     Textmarkers remember files and positions. If you set marker a in file foo, start editing file bar and type 'a, then YOU WILL SWITCH TO FILE foo. You can see the contents of a textmarker using the VIP command [<a-z> where <a-z> are the textmarkers, e.g. [a to view marker a .

Repeated Commands
     Command repetitions are common over files. !! will repeat the last ! command whichever file it was issued from. . repetition will repeat the last command from any file, and searches will repeat the last search. Ex commands are also common.

Registers
     Registers are common to files. Also, y yanked text can be p put back into any file. The VIP command ]<a-z>, where <a-z> are the registers, can be used to look at the contents of a register e.g. ]a to view register a.

Absolute Filenames
     The directory name for a file is automatically prepended to any :e done from the corresponding buffer. Absolute filenames are required less often in VIP. :cd will change the default directory for the buffer the :cd is issued from. :e will interpret the filename argument by default in csh. See Customization if you want to change this.

Currently undisplayed files can be listed using the :ar command. :n can be given counts from the :ar list to switch to other files.

RSN Features
============

Real Soon Now, i.e. Not Yet Implemented features include:

  * :map and :map! do not yet take strings, and the timeout expansion. I have a version of timeout expansion and string maps for the next VIP. :map , i.e. list all mapped keys. is not implemented.

  * :ab and :una are not implemented.

  * :set option? and :set are not implemented. The current :set can also be used to set Emacs variables.

  * :se list requires modification of the display code for Emacs, so it is not implemented. A useful alternative is cat -t -e file. Unfortunately, it cannot be used directly inside Emacs, since Emacs will obdurately change ^I back to normal tabs.

Improvements over VI
********************

Some common problems with VI and EX have been solved in VIP. This includes better implementation of existing commands, new commands, and the facilities provided by Emacs.

Basics
======

The VI command set is based on the idea of combining motion commands with other commands. The motion command is used as a text region specifier for other commands. We classify motion commands into point commands and line commands.

The point commands are:

     h, l, 0,  $, w, W, b, B, e, E, (, ), /, ?, `, f, F, t, T, %, ;, ,, ^

The line commands are:

     j, k, +, -, H, M, L, {, }, G, ',  [[, ]], []

If a point command is given as an argument to a modifying command, the region determined by the point command will be affected by the modifying command. On the other hand, if a line command is given as an argument to a modifying command, the region determined by the line command will be enlarged so that it will become the smallest region properly containing the region and consisting of whole lines (we call this process expanding the region), and then the enlarged region will be affected by the modifying command. Text Deletion Commands (see Deleting Text.), Change commands (see Changing Text.), even Shell Commands (see Shell Commands) use these commands to describe a region of text to operate on. Thus dw to delete a word, >} to shift a paragraph, or !'afmt to format a region from point to textmarker a.

VIP adds the region specifiers r and R. Emacs has a special marker called mark. The text-area between the current cursor position point and the mark is called the region. r specifies the raw region and R is the expanded region. dr will now delete the region, >r will shift it etc. r,R are not motion commands, however. The special mark is set by m. and other commands. See Marking, for more info.

VIP also adds counts to most commands for which it would make sense.

In the Overview chapter, some Multiple File issues were discussed (see Multiple Files in VIP). In addition to the files, Emacs has buffers. These can be seen in the :args list and switched using :next if you type :set ex-cycle-through-non-files t, or specify (setq ex-cycle-through-non-files t) in your .emacs file. See Customization for details.

Undo and Backups
================

VIP provides multiple undo. The number of undo's and the size is limited by the machine. The VIP command u does and undo. Undo can be repeated by .. Another u will undo the undo, and further . will repeat it. u does the first undo, and changes the direction.

Since the undo size is limited, VIP can create backup files and auto-save files. It will normally do this automatically. It is possible to have numbered backups etc. For details, see Backup and Auto-Save (The GNU Emacs Manual).

The results of the 9 previous changes are available in the 9 numeric registers as in VI. The extra goody is the ability to view these registers, in addition to being able to access them through p. The VIP command ] register will display the contents of any register, numeric or alphabetical. The related command [ textmarker will show the text around the textmarker. register and textmarker can be any letters from a through z.

History
=======

History is provided for Ex commands and Vi searches. It is especially useful to fix those small typos that screw up searches and :s//. At the : or /, you can do

C-p C-n
     To move to previous and next history items. This causes the history items to appear on the command line, where you can edit them, or simply type Return to execute.

C-r C-s
     To search backward and forward through the history.

C-t C-l
     To go to the top and bottom of the history.

C-o
     To display the history in a buffer

RET
     Simple RET to return the current history item. The current history item is displayed in brackets.

History is provided using the gmhist package. History is not turned on by default. You have to explicitly call

     (vip-get-history)

in your .emacs file.

In normal use, a few C-p an C-n strokes suffice. For further details, refer to the gmhist package in the distribution.

Macros and Registers
====================

VIP provides keyboard macros. @# will start a macro definition. As you type, the commands will be executed, and remembered (This is called learn mode in some editors). @register will complete the macro, putting it into register, where register is any character from a through z. Then you can execute this macro using @register. It is, of course, possible to yank some text into a register and execute it using @register. @@, @RET, @LF will execute the last macro that was executed using @register.

VIP will automatically lowercase the register, so that pressing the SHIFT key for @ will not create problems. This is for @ macros and "p only. In the case of y, "Ayy will append to register a. For [,],',`, it is an error to use a Uppercase register name.

The contents of a register can be seen by ]register. ([textmarker will show the contents of a textmarker).

The last keyboard macro can also be executed using *, and it can be yanked into a register using @!register. This is useful for Emacs style keyboard macros defined using C-x( and C-x). Emacs keyboard macros have more capabilities. See Keyboard Macros (The GNU Emacs Manual), for details.

Keyboard Macros allow an interesting form of Query-Replace. /pattern and n to go to the next pattern (the query), followed by a Keyboard Macro execution @@ (the replace).

Completion
==========

VIP can complete filenames for Ex file commands. Filename completion must be turned on by calling

     (setq vip-filename-completion t)

in your .emacs file before turning history on. The completion is base on completer.el package. This completer recognizes partial filename patterns. You must get this file from the Emacs archives to get completion (see Useful Packages for archive locations). It will be in Emacs 19 distribution.

Completion is done when you type TAB. The completer does not grok wildcards in filenames. Once you type a wildcard, the completer will no longer work for that path.

Improved Search
===============

VIP provides buffer search, the ability to search the buffer for a region under the cursor. You have to turn this on by calling

     (vip-get-buffer-search)

Then, the key g will take movement commands like w,/ etc. to find a region and search for the contents of this region. This command is very useful to search for variable names etc. in a program. The search can be repeated by n, or reversed by N.

Emacs provides incremental search. As you type the string in, the cursor will move to the next match. You can snarf words from the buffer as you go along. Incremental Search is normally bound to C-s and C-r. See Customization, to find out how to change the bindings of C-r or C-s. :map cannot be used, since it creates macros bound to keys, not lisp functions. For details, see Incremental Search (The GNU Emacs Manual)

VIP also provides a query replace function that prompts through the minibuffers. It is invoked by the Q key in Vi mode.

Improved Abbrevs
================

It is possible in Emacs to define abbrevs based on the contents of the buffer. See Abbreviations (The GNU Emacs Manual), for details.

Sophisticated templates can be defined using the Emacs abbreviation facilities. Check out the templates.el from the Emacs archives.

Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs will search the buffer to find an extension for this word. For instance, I typed Abbreviations by typing A, followed by a keystroke that completed the A to Abbreviations. Repeated typing will search further, so that I get Abbrevs by repeating the keystroke, which appears earlier in the text. Emacs binds this to ESC /, so you will have to find a key and bind the function dabbrev-expand to that key. I use C-o for this. By using simple keys for commands, VIP frees up a lot of other keys and key sequences. I no longer venture outside the basic keyboard for anything.

Movement and Markers
====================

VIP can be free from the line--limited movements in VI, such as l refusing to move beyond the line, ESC moving one character back etc. These derive from Ex, which is a line editor. If your .emacs contains

     (setq vip-ex-style-motion nil)

the motion will be a true screen editor motion. One thing you must then watch out for is that it is possible to be on the end-of-line character. x and % will still work correctly, i.e as if they were on the last character.

Textmarkers in VIP remember the file and the position, so that you can switch files by simply doing 'a. If you set up a regimen for using Textmarkers, this is very useful. Contents of textmarkers can be viewed by [marker. (Contents of registers can be viewed by ]register).

New Commands
============

These commands have no VI analogs.

C-x
     C-x will exit from Vi mode and return to Emacs mode temporarily. If you hit one of these keys, Emacs will be in emacs mode and will believe that you hit that key in Emacs mode. For example, if you hit C-x followed by 2, then the current window will be split into 2 and you will be in Vi mode again. It is possible to make C-c to do the same, to use keybindings from packages. ESC can do the same, if you configure ESC as Meta.See Customization. C-z in Insert mode will make Emacs think Meta has been hit.

Q
     Q is for query replace.  By default, string to be replaced are treated as regular expressions. You can use (setq vip-re-query-replace nil) in your .emacs file to turn this off. (For normal searches, :se nomagic will work. Note that :se nomagic turns Regexps off completely unlike VI).

v
V
     These keys are used to Visit files.  v will switch to a buffer visiting file whose name can be entered in the minibuffer. V is similar, but will use window different from the current window.

#
     If followed by a certain character CH, it becomes an operator whose argument is the region determined by the motion command that follows (indicated as <move>). Currently, CH can be one of c, C, g, q and s.

# c
     Change upper case characters in the region to lower case (downcase-region).

# C
     Change lower case characters in the region to upper case. For instance, # C 3 w will capitalize 3 words from the current point (upcase-region).

# g
     Execute last keyboard macro for each line in the region (vip-global-execute).

# q
     Insert specified string at the beginning of each line in the region (vip-quote-region).

# s
     Check spelling of words in the region (spell-region).

*
     Call last keyboard macro.

m .
     Set mark at point and push old mark off the ring

m< m>
     Set mark at beginning and end of buffer resp.

m,
     Jump to mark and pop mark off the ring. See Mark (The GNU Emacs Manual), for more info.

] register
     View contents of register

[ textmarker
     View filename and position of textmarker

@#, @register, @!
     Begin keyboard macro. @register has a different meaning when used after a @#. See Macros and Registers for details

[]
     Go to end of heading.

g movement command
     Search buffer for text delimited by movement command. The canonical example is gw to search for word under cursor.See Improved Search for details.

_
     Meta key when in Vi mode.See Vi Mode for an explanation.

C-g and C-]
     Quit and Abort Recursive edit. These may be necessary on occasion. See Vi Mode for a reason.

Ex commands
     :args, :next, :pre behave differently. :pwd exists to get current directory.

Useful Packages
===============

Some Emacs packages are mentioned here as an aid to the new VIP user, to indicate what VIP is capable of. These are Emacs packages that I use. A vast number exists on the net and on the archives.

I also mention some Emacs features I think a new user should know about. The details for these will be found in the GNU Emacs Manual.

The features first. For details, look up the Emacs Manual.

Make
     Makes and Compiles can be done from the editor. Error messages will be parsed and you can move to the error lines.

Shell
     You can talk to Shells from inside the editor. Your entire shell session can be treated as a file.

Mail
     Mail can be read from and sent within the editor. Several sophisticated packages exist. I use my own 300 line interface to Berkeley Mail.

Language Sensitive Editing
     Editing modes are written for most languages in existence. By controlling indentation, they catch punctuation errors.

The packages:

Transparent FTP
     ange-ftp.el can ftp from the editor to files on other machines transparent to the user.

RCS Interfaces
     rcs-cks.el for doing RCS commands from inside the editor

Directory Editor
     dired.el for editing contents of directories.

Navigator - Director Tree Manager
     navigator.el - Navigate a directory tree, pop up shells on directories etc. Like Norton Commander or PCTools for the IBM PC. Do not ever use absolute long paths again!!!.

Emacs lisp code archives exist on archive.cis.ohio-state.edu (128.146.8.52)

 and wuarchive.wustl.edu (128.252.135.4)

And finally, until Emacs 19 arrives, there is Epoch, which can have multiple X-windows for editing. The next version of VIP will support Epoch, in that the :e file will bring the file up in a new X-window etc.

VIP supports Epoch. If you are running epoch, :e will bring up files in a new screen, and :q will kill the buffer and screen.

Customization
*************

Customization can be done in 3 ways.

  * Elisp code in a .vip file in your home directory. VIP loads .vip itself just before it does the binding for mode hooks. This is the recommended method for new users.

  * Elisp code in your .emacs file before and after loading vip using (load "vip").

  * Put a file called vip.el in your load-path, and then arrange to call the real vip.el from inside. This is useful for heavy duty customization.

Emacs customization is done in elisp. For the common cases, I have provided examples that you can use directly.

Rudimentary Changes
===================

An easy way to customize VIP is to change the values of constants used in VIP.  Here is the list of the constants used in VIP and their default values. The corresponding :se command is also indicated. (t and nil are true and false in elisp).

vip-auto-indent nil
:se ai
     If t then enable auto indentation. by o or O command.

vip-case-fold-search nil
:se ic
     If t search ignores cases.

vip-re-search nil
:se magic
     If t then search is reg-exp search, if nil then vanilla search.

buffer-read-only
:se ro
     Set current buffer to read only. To change globally put (setq-default buffer-read-only t) in your .emacs file.

blink-matching-paren t
:se sm
     Show matching parens by blinking cursor.

vip-shift-width 8
:se sw=value
     The number of columns shifted by > and < command.

vip-search-wrap-around t
:se ws
     If t, search wraps around the buffer.

vip-tags-file-name "TAGS"
     The name of the file used as the tag table.

vip-re-query-replace nil
     If t then do reg-exp replace in query replace.

vip-help-in-insert-mode nil
     If t then C-h is bound to help-command in insert mode, if nil then it is bound to delete-backward-char.

vip-no-multiple-ESC t
     If you reset this, you can use ESC as Meta in Vi mode.

vip-ex-style-motion t
     Reset this to get ESC that does not move back, l to cross lines etc.See Movement and Markers for more info.

vip-filename-completion nil
     Set to t to get filename completion.See Completion for details.

vip-always t
     Whether you want VIP mode in for all new buffers. This option must be set before VIP is loaded or in the .vip file.

vip-custom-file-name "~/.vip"
     Change this if you want. Must be set before vip is loaded. Note that you have to set it as a string inside double quotes.

ex-find-file-shell "csh"
     Shell used to interpret filenames. If you have problems with csh,change to something else. Note that you have to set it as a string inside double quotes.

ex-cycle-other-window t
     :n will cycle through files in another window if one exists.

ex-cycle-through-non-files nil
     :n does not normally cycle through buffers. Set this to get buffers also.

You can reset these constants in VIP by the Ex command set.  Or you can include a line like this in your .vip file:

     (setq vip-case-fold-search t)

Keybindings
===========

VIP uses 2 main keymaps: vip-mode-map for Vi mode commands, and vip-insert-mode-map for Insert mode commands. By default, vip-insert-mode-map makes non VI keys insert themselves. VIP also suppresses Emacs control keys in vip-mode-map.

To unsuppress emacs bindings in Vi and Insert modes, put the line

     	(vip-make-emacs-keys-visible)

in your .vip file. To unsuppress bindings in just Insert mode, put

     (setq-default vip-insert-mode-vi-map nil)

in your .vip file. This unsuppresses Emacs bindings for all buffers. To do that selectively, you will have to

     (setq vip-insert-mode-vi-map nil)

in just those buffers. This is usually accomplished in customization hooks for major modes. See Mode Hooks (The GNU Emacs Manual), and see Hooks (GNU Emacs Lisp Reference Manual), for details.

You can also alter the vip-insert-mode-map to change the bindings. Note that changing to a VI compatible insert mode also requires undefining some bindings. This is done in the function vip-insert-mode-bindings. To make a substantial change, you have to redefine this function. The vip-insert-mode-map was defined primararily so that :map! could be implemented.

That was about VIP bindings. For normal Emacs bindings, read the following. See Customization (The GNU Emacs Manual), and the Emacs quick reference card for more info.

To bind a function to a key, say C-s for incremental search

     (define-key vip-mode-map "\C-s" 'isearch-forward)

To set a key globally,

     (global-set-key "\C-s" 'isearch-forward)

Note that local mode maps override the global keymap.

Each Emacs command key calls some lisp function. If you have enabled the Help, (see Rudimentary Changes) C-h k will show you the function.

:map and :map! defined Vi/Ex macros, and cannot be used to define bindings for Emacs functions. See VI Macros, for details.

Packages that change keymaps
----------------------------

If you use other packages that change keymaps, remember that these packages will assume native Emacs. So let the other packages alter the keymaps, and then change to VIP mode, usually by calling (vip-mode) from the hooks for those packages.

VIP is designed as a minor mode --- a feature you can turn on or off. Therefore, mode keymap changes must be made to the underlying major modes, not VIP itself.

This question usually arises in the context of C-c bindings. In Emacs, C-c is reserved for users and packages as a general key. Normally, VIP binds C-c in Insert and Vi mode to keyboard-quit, to be compatible with VI. vip-make-emacs-keys-visible will bind C-c to vip-ctl-c, making C-c act like a Emacs key. (you might want to change the bindings in the vip-insert-mode-map and vip-mode-map yourself, if you want other VI bindings to remain) Any C-c binding from the current buffer major mode will be accessible now under either Vi or Insert mode.

VIP Specials
============

(vip-redefine-toggle-key "\C-w")
     Redefine the toggle key C-z from Emacs to Vi to say C-w.

(vip-get-history)
     Enable history for Ex and Vi commands.

(vip-buffer-search-enable)
     Enable buffer search. The key binding can also be changed by redefining vip-buffer-search-char.

vip-heading-start and vip-heading-end
     Regular Expressions for [[ and ]]. Note that Emacs defines to Regexps for paragraphs and sentences. See Paragraphs and Sentences (The GNU Emacs Manual), for details.

(vip-become-vi)
     This function is intended to be an ultimate compatibility test, mostly as a joke.

VI Macros
=========

The function vip-ex can be called with a string to evaluate. This string must be an Ex command without the :. Thus (vip-ex "se ai") is the same as :se ai when running vip, or (setq vip-ai t). The VI & and C-^ commands (see Commands) are implemented by calling the corresponding Ex commands in this fashion.

In principle, it s straightforward to parse an external environment variable or file and pass it to vip-ex to get VI macro programming.

However, this feature is not yet been implemented and vip-ex has not been tested in this fashion. I welcome the adventurous to try and report bugs and/or fixes to improve VIP.

Note also that :map and :map! can map only single characters, not strings, and :ab and :una are not implemented.

:map and :map! cannot be used to bind lisp functions to keys. See Keybindings, to see how to do that.

     [file vip-cmd.texinfo not included]

Acknowledgments
***************

The original author of VIP was Masahiko Sato. The Manual and VIP 4.3 is based on his VIP 3.5 Manual and Code.

Jean-Jacques Moreau contributed code to get small changes with the $ sign instead of through the minibuffer. He also put in the completer hooks, and ex commands :pwd, :cd, and :recover.

Jeff Lewis contributed code to make Ex style motion possible.

Many contributors on the net pointed out bugs.

Finally, my advisor Roy Campbell at Illinois did not mind my spending inordinate amounts of time on VIP.