*1* Installing VIP

Suppose that you have a copy of VIP (which you can find in Part 2) in the
file vi.el and its full path name is .../vi.el.  Then include the line

	(load ".../vi.el")

in your .emacs file.  In this way, VIP will be loaded whenever you enter
Emacs.  Or, after you entered Emacs, you can load vi.el by the "load"
command.  Another way is to define the function "change-mode-to-vi" to
autoload from the file vi.el.

You can also compile vi.el and use vi.elc instead of vi.el.

*2* Modes in VIP

(From now on I assume that vi.el has been loaded.)  Loading vi.el has the
effect of globally binding "^Z" (control-Z) to the function 
"change-mode-to-vi". The default binding of "^Z" in GNU Emacs is 
"suspend-emacs", but, you can also call "suspend-emacs" by hitting "^X^Z".
Other than this, all the key bindings of Emacs remain the same after loading 
vi.el.

Now, if you hit "^Z" the function "change-mode-to-vi" will be called, and
you will be in vi-mode.  (Some major modes like shell-mode locally bind
"^Z" to some special functions.  In such cases, you can call 
"change-mode-to-vi" by the "execute-extended-command" which is invoked by
"ESC x".)

You can observe the change of mode by looking at the mode line.  For instance,
if the mode line was:

-----Emacs: *scratch*              (Lisp Interaction)----All------------------

Then it will change to:

-----Vi:    *scratch*              (Lisp Interaction)----All------------------

Thus the word "Emacs" in the mode line will change to "Vi".  This assumes
that the initial mode line contains the string "Emacs:".  (If the mode line
does not contain the string "Emacs:", which I think is rather rare, VIP
will use its own mode line to replace the mode line.)

You can go back to the original emacs-mode by hitting "^Z" in vi-mode.  Thus
"^Z" toggles between these two modes.

Note that modes in VIP exist orthogonally to modes in Emacs.  This means
that you can be in vi-mode and at the same time, say, shell-mode.  You can
then bind a function which is useful in shell-mode to some key in VIP's
vi-mode.

Vi-mode corresponds to vi's command mode.  You can change from vi-mode to
insert-mode (which corresponds to vi's insert mode) by usual vi command
keys like "i", "a", "o" ... etc.

In insert-mode, the mode line will look like this:

-----Insert *scratch*              (Lisp Interaction)----All------------------

You can exit from insert-mode by hitting "ESC" key as you do in vi.

That VIP has three modes may seem very complicated, but in fact it is not
so, since VIP is implemented so that you can do most editing remaining only
in the two modes for vi (that is vi-mode and insert-mode).

The figure below shows the transition of three modes in VIP.

		   ==== ^Z ==>		== i,o ... ==>
	emacs-mode		vi-mode			insert-mode
		   <=== ^Z ===		<=== ESC ====
		   
*3* Emacs-mode

You will be in this mode just after you loaded vi.el.  You can do all normal 
Emacs editing in this mode.  Note that the key "^Z" is globally bound to 
"change-mode-to-vi".

*4* Vi-mode

This mode corresponds to vi's command mode.  Most vi commands work as they
do in vi.  I explain the major differences from vi below.

-- limitations --

Ex commands are not supported.  The key ":" is used for other purpose.
(See below.)

-- modifications --

- Undoing.  You can repeat undoing by the "." key.  So, "u" will undo
a single change, while "u...", for instance, will undo 4 previous
changes.  Undo is undoable as in vi.  So the content of the buffer will
be the same before and after "uu".

- Some commands which change a small number of characters are executed
slightly differently.  Thus, if the point is at the beginning of a word
"foo" and you wished to change it to "bar" by hitting "cw", then VIP
will prompt you for a new word in the mini buffer by the prompt
"foo => ".  You can then enter "bar" followed by a <return> to complete
the command.  Before you enter a <return> you can abort the command by
hitting "^G".  In general, you can abort a partially formed command by
hitting "^G".

- Searching by "/" and "?".  Search string must be terminated by a <return>,
and not by a "ESC".  The string will be searched literally by default.  To
invoke a regular expression search, first execute the search command "/"
(or "?") with empty search string.  (I.e, do "/" followed by a <return>.)
A search for empty string will toggle the search mode between vanilla
search and regular expression search.  You cannot give an offset to the
search string.  (It is a limitation.)  By default, search will wrap around
the buffer as in vi.  You can change this by rebinding the varialbe
"vi-search-wrap-around".  See *6* for how to do this.

- ":" key is now used to do a pseudo incremental search.  Assume for instance
that your last search was "/foo", but you wanted to search "fox" forward
instead of "foo".  Then hitting ":" will give you "/foo" in the mini buffer.
You can change the last "o" to "x" and then give a <return> to search
"fox" forward.

- For those of you who cannot remember which of "z" followed by <return>,
"." and "-" do what.  You can also use "z" followed by "H", "M" and "L" to
place the current line in the Home (Middle, and Last) line of the window.

-- additions --

- Some vi commands which do not accept counts now accept counts.

"p" and "P".  Given counts, text will be yanked (in vi's sense) that many
times.  Thus "3p" is the same as "ppp".

"o" and "O".  Given counts, that many copies of text will be inserted.
Thus "oabc" followed by "ESC" will insert 3 lines of "abc" below the
current line.

"/" and "?".  Given a count n, n-th occurrence will be searched.

- Marking.  "m" followed by a lower case <char> marks the point to the
register named <char> as in vi.  In addition to these, we have following
key bindings for marking.

"m<"  Set mark at the beginning of buffer.
"m>"  Set mark at the end of buffer.
"m."  Set mark at the point (and push old mark on mark ring).
"m,"  Jump to mark (and pop mark off the mark ring).

- Region commands.  Vi operators like "d", "c" etc. are usually used in
combination with motion commands.  It is now possible to use current
region as the argument to these operators.  (A region is a part of buffer
delimited by point and mark.)  The key "r" is used for this purpose.
Thus "dr" will delete the current region.  If "R" is used instead of "r"
the region will first be enlarged so that it will become the smallest
region containing the original region and consisting of whole lines.
Thus "m.dR" will have the same effect as "dd".

- New commands added to vi.  Note that the keys below are not used in vi.

"^A"  Move point to the beginning of line.

"^N"  If you have two or more windows in the screen, this key will move
point to the next window.

"^O"  Insert a newline and leave point before it, and then you will be
in insert-mode.

"^S"  Suspend emacs.

"^C", "^X" and "ESC"  These keys 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 "^X" followed by "2", then the current window will 
be splitted into 2 and you will be in vi-mode again.

- "\"  Escape to emacs-mode.  Hitting a "\" will take you to emacs-mode,
and you can execute a single Emacs command.  After executing a single
Emacs command you will be in vi-mode again.  You can give a count before
hitting "\".  Thus "5\+", as well as "\^U5+", will insert "+++++" before
the point.  Similarly "10\^P" will move the point 10 lines above the current
line.

- "K"  Kill current buffer if it is not modified.  Useful when you selected
a buffer which you did not want.

- "Q" and "R"  "Q" is for query replace and "R" is for replace.  By default,
string to be replaced are treated literally.  If you wish to do a regular
expression replace, first do replace with empty string as the string to
be replaced.  In this way, you can toggle between vanilla and regular
expression replacement.

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

- "#"  If followed by a certain <char>, it becomes a operator whose
argument is the region determined by the motion command that follows.
Currently, <char> 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.
	      (upcase-region)
	"#g"  execute last keyboard macro for each line in the region.
	      (global-execute)
	"#q"  insert specified string at the beginning of each line in the
	      region. (quote-region)
	"#s"  check spelling of words in the region. (spell-region)

For instance, "#C3w" will capitalize 3 words from the current point.

- "*"  Call last keyboard macro.

*5* Insert-mode

The key bindings in this mode is the same as in the emacs-mode except for
the following 3 keys.  So, you can move around in the buffer and change
its content while you are in insert mode.

- "ESC"  This key will take you back to vi-mode.

- "^H"  Delete previous character.

- "^W"  Delete previous word.

*6*  Customization

If you have a file called .vip in your home directory, then it will also
be loaded when vi.el is loaded.  This file is thus useful for customizing
VIP.  You will find an example of .vip in Part 3.