*** empty log message ***
[emacs.git] / man / viper.texi
blob572a3296d529660a8d22c606f1624bb7aed67ca1
1 % -*-texinfo-*-
2 \input texinfo
4 @comment Using viper.info instead of viper in setfilename breaks DOS.
5 @comment @setfilename viper
6 @comment @setfilename viper.info
7 @setfilename ../info/viper
9 @copying
10 Copyright @copyright{} 1995, 1996, 1997, 2001, 2002, 2003, 2004,
11    2005 Free Software Foundation, Inc.
13 @quotation
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with the Front-Cover texts being ``A GNU
18 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
19 license is included in the section entitled ``GNU Free Documentation
20 License'' in the Emacs manual.
22 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
23 this GNU Manual, like GNU software.  Copies published by the Free
24 Software Foundation raise funds for GNU development.''
26 This document is part of a collection distributed under the GNU Free
27 Documentation License.  If you want to distribute this document
28 separately from the collection, you can do so by adding a copy of the
29 license to the document, as described in section 6 of the license.
30 @end quotation
31 @end copying
33 @dircategory Emacs
34 @direntry
35 * VIPER: (viper).       The newest Emacs VI-emulation mode.
36                           (also, A VI Plan for Emacs Rescue
37                            or the VI PERil.)
38 @end direntry
40 @finalout
42 @titlepage
43 @title Viper Is a Package for Emacs Rebels
44 @subtitle a Vi emulator for Emacs
45 @subtitle January 2002, Viper Version 3.11.2
47 @author Michael Kifer (Viper)
48 @author Aamod Sane (VIP 4.4)
49 @author Masahiko Sato (VIP 3.5)
51 @page
52 @vskip 0pt plus 1filll
53 @insertcopying
54 @end titlepage
56 @ifnottex
57 @node Top, Overview,, (DIR)
59 @unnumbered Viper
61 We believe that one or more of the following statements are adequate
62 descriptions of Viper:
64 @example
65 Viper Is a Package for Emacs Rebels;
66 it is a VI Plan for Emacs Rescue
67 and/or a venomous VI PERil.
68 @end example
70 Technically speaking, Viper is a Vi emulation package for Emacs.  It
71 implements all Vi and Ex commands, occasionally improving on them and
72 adding many new features.  It gives the user the best of both worlds: Vi
73 keystrokes for editing combined with the power of the Emacs environment.
75 Viper emulates Vi at several levels, from the one that closely follows Vi
76 conventions to the one that departs from many of them.  It has many
77 customizable options, which can be used to tailor Viper to the work habits
78 of various users.
79 This manual describes Viper, concentrating on the differences from Vi and
80 new features of Viper.
82 Viper, formerly known as VIP-19, was written by Michael Kifer.  It is based
83 on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane.
84 About 15% of the code still comes from those older packages.
86 Viper is intended to be usable without reading this manual --- the defaults
87 are set to make Viper as close to Vi as possible.  At startup, Viper will
88 try to set the most appropriate default environment for you, based on
89 your familiarity with Emacs.  It will also tell you the basic GNU Emacs window
90 management commands to help you start immediately.
92 Although this manual explains how to customize Viper, some basic
93 familiarity with Emacs Lisp is a plus.
95 It is recommended that you read the Overview node.  The other nodes may
96 be visited as needed.
98 Comments and bug reports are welcome.
99 @code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports.
100 Please use the Ex command @kbd{:submitReport} for this purpose.@refill
102 @end ifnottex
104 @menu
105 * Overview::                    Read for a smoother start
106 * Improvements over Vi::        New features, Improvements
107 * Customization::               How to customize Viper
108 * Commands::                    Vi and Ex Commands
110 * Key Index::                   Index of Vi and Ex Commands
111 * Function Index::              Index of Viper Functions
112 * Variable Index::              Index of Viper Variables
113 * Package Index::               Index of Packages Mentioned in this Document
114 * Concept Index::               Vi, Ex and Emacs concepts
116 * Acknowledgments::
117 @end menu
118 @iftex
119 @unnumbered Introduction
121 We believe that one or more of the following statements are adequate
122 descriptions of Viper:
124 @example
125 Viper Is a Package for Emacs Rebels;
126 it is a VI Plan for Emacs Rescue
127 and/or a venomous VI PERil.
128 @end example
130 Viper is a Vi emulation package for Emacs.  Viper contains virtually all
131 of Vi and Ex functionality and much more.  It gives you the best of both
132 worlds: Vi keystrokes for editing combined with the GNU Emacs
133 environment.  Viper also fixes some common complaints with Vi commands.
134 This manual describes Viper, concentrating on the differences from Vi
135 and on the new features of Viper.
137 Viper was written by Michael Kifer.  It is based on VIP version 3.5 by
138 Masahiko Sato and VIP version 4.4 by Aamod Sane.  About 15% of the code
139 still comes from those older packages.
141 Viper is intended to be usable out of the box, without reading this manual
142 --- the defaults are set to make Viper as close to Vi as possible.  At
143 startup, Viper will attempt to set the most appropriate default environment
144 for you, based on your familiarity with Emacs.  It will also tell you the
145 basic GNU Emacs window management commands to help you start immediately.
147 Although this manual explains how to customize Viper, some basic
148 familiarity with Emacs Lisp is a plus.
150 It is recommended that you read the chapter Overview.  The other chapters
151 will be useful for customization and advanced usage.
153 You should also learn to use the Info on-line hypertext manual system that
154 comes with Emacs.  This manual can be read as an Info file.  Try the command
155 @kbd{@key{ESC} x info} with vanilla Emacs sometime.
157 Comments and bug reports are welcome.
158 @code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports.
159 Please use the Ex command @kbd{:submitReport} for this purpose.@refill
161 @end iftex
163 @node Overview,Improvements over Vi,Top,Top
164 @chapter Overview of Viper
166 Viper is a Vi emulation on top of Emacs.  At the same time, Viper provides a
167 virtually unrestricted access to Emacs facilities.  Perfect compatibility
168 with Vi is possible but not desirable.  This chapter tells you about the
169 Emacs ideas that you should know about, how to use Viper within Emacs and
170 some incompatibilities.
172 This manual is written with the assumption that you are an experienced Vi
173 user who wants to switch to Emacs while retaining the ability to edit files
174 Vi style. Incredible as it might seem, there are experienced Emacs users
175 who use Viper as a backdoor into the superior (as every Vi user already knows)
176 world of Vi! These users are well familiar with Emacs bindings and prefer them
177 in some cases, especially in the Vi Insert state. John Hawkins
178 <jshawkin@@eecs.umich.edu> has provided a set of customizations, which
179 enables additional Emacs bindings under Viper.  These customizations can be
180 included in your @file{~/.viper} file and are found at the following URL:
181 @file{http://www.eecs.umich.edu/~jshawkin/viper-sample}.
183 @menu
184 * Emacs Preliminaries::         Basic concepts in Emacs.
185 * Loading Viper::               Loading and Preliminary Configuration.
186 * States in Viper::             Viper has four states orthogonal to Emacs
187                                 modes.
188 * The Minibuffer::              Command line in Emacs.
189 * Multiple Files in Viper::     True multiple file handling.
190 * Unimplemented Features::      That are unlikely to be implemented.
191 @end menu
193 @node Emacs Preliminaries, Loading Viper, Overview, Overview
194 @section Emacs Preliminaries
196 @cindex buffer
197 @cindex point
198 @cindex mark
199 @cindex text
200 @cindex looking at
201 @cindex end (of buffer)
202 @cindex end (of line)
203 @cindex region
205 Emacs can edit several files at once.  A file in Emacs is placed in a
206 @dfn{buffer} that usually has the same name as the file.  Buffers are also used
207 for other purposes, such as shell interfaces, directory editing, etc.
208 @xref{Dired,,Directory Editor,emacs,The
209 GNU Emacs Manual}, for an example.@refill
211 A buffer has a distinguished position called the @dfn{point}.
212 A @dfn{point} is always between 2 characters, and is @dfn{looking at}
213 the right hand character.  The cursor is positioned on the right hand
214 character.  Thus, when the @dfn{point} is looking at the end-of-line,
215 the cursor is on the end-of-line character, i.e.@: beyond the last
216 character on the line.  This is the default Emacs behavior.@refill
218 The default settings of Viper try to mimic the behavior of Vi, preventing
219 the cursor from going beyond the last character on the line.  By using
220 Emacs commands directly (such as those bound to arrow keys), it is possible
221 to get the cursor beyond the end-of-line.  However, this won't (or
222 shouldn't) happen if you restrict yourself to standard Vi keys, unless you
223 modify the default editing style.  @xref{Customization}.@refill
225 In addition to the @dfn{point}, there is another distinguished buffer
226 position called the @dfn{mark}.  @xref{Mark,,Mark,emacs,The GNU Emacs
227 manual}, for more info on the mark.  The text between the @dfn{point} and
228 the @dfn{mark} is called the @dfn{region} of the buffer.  For the Viper
229 user, this simply means that in addition to the Vi textmarkers a--z, there
230 is another marker called @dfn{mark}.  This is similar to the unnamed Vi
231 marker used by the jump commands @kbd{``} and @kbd{''}, which move the
232 cursor to the position of the last absolute jump.  Viper provides access to
233 the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix
234 to commands that operate on text regions, e.g., @kbd{dr} to delete region,
235 etc.
237 Furthermore, Viper lets Ex-style commands to work on the current region.
238 This is done by typing a digit argument before @kbd{:}.  For instance,
239 typing @kbd{1:} will propmt you with something like @emph{:123,135},
240 assuming that the current region starts at line 123 and ends at line
241 135.  There is no need to type the line numbers, since Viper inserts them
242 automatically in front of the Ex command.
244 @xref{Basics}, for more info.@refill
246 @cindex window
247 @cindex mode line
248 @cindex buffer information
249 @cindex Minibuffer
250 @cindex command line
251 @cindex buffer (modified)
253 Emacs divides the screen into tiled @dfn{windows}.  You can see the
254 contents of a buffer through the window associated with the buffer.  The
255 cursor of the screen is positioned on the character after @dfn{point}.
256 Every window has a @dfn{mode line} that displays information about the buffer.
257 You can change the format of the mode
258 line, but normally if you see @samp{**} at the beginning of a mode line it
259 means that the buffer is @dfn{modified}.  If you write out the contents of
260 a buffer to a file, then the buffer will become not modified.  Also if
261 you see @samp{%%} at the beginning of the mode line, it means that the file
262 associated with the buffer is write protected.  The mode line will also
263 show the buffer name and current major and minor modes (see below).
264 A special buffer called @dfn{Minibuffer} is displayed as the last line
265 in a Minibuffer window.  The Minibuffer window is used for command input
266 output.  Viper uses Minibuffer window for @kbd{/} and @kbd{:}
267 commands.@refill
269 @cindex mode
270 @cindex keymap
271 @cindex local keymap
272 @cindex global keymap
273 @cindex major mode
274 @cindex minor mode
276 An Emacs buffer can have a @dfn{major mode} that customizes Emacs for
277 editing text of a particular sort by changing the functionality of the keys.
278 Keys are defined using a @dfn{keymap} that records the bindings between
279 keystrokes and
280 functions.  The @dfn{global keymap} is common to all the
281 buffers.  Additionally, each buffer has its @dfn{local keymap} that determines the
282 @dfn{mode} of the buffer.  If a function is bound to some key in the local
283 keymap then that function will be executed when you type the key.
284 If no function is bound to a key in the
285 local map, however, the function bound to the key in the global map
286 will be executed.  @xref{Major Modes,Major Modes,Major Modes,emacs,The
287 GNU Emacs Manual}, for more information.@refill
289 A buffer can also have a @dfn{minor mode}.  Minor modes are options that
290 you can use or not.  A buffer in @code{text-mode} can have
291 @code{auto-fill-mode} as minor mode, which can be turned off or on at
292 any time.  In Emacs, a minor mode may have it own keymap,
293 which overrides the local keymap when the minor mode is turned on.  For
294 more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The
295 GNU Emacs Manual} @refill
297 @cindex Viper as minor mode
298 @cindex Control keys
299 @cindex Meta key
301 Viper is implemented as a collection of minor modes.  Different minor modes
302 are involved when Viper emulates Vi command mode, Vi insert mode, etc.
303 You can also turn Viper on and off at any time while in Vi command mode.
304 @xref{States in Viper}, for
305 more information.@refill
307 Emacs uses Control and Meta modifiers.  These are denoted as C and M,
308 e.g.@: @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}.  The Meta key is
309 usually located on each side of the Space bar; it is used in a manner
310 similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while
311 holding the Meta key down.  For keyboards that do not have a Meta key,
312 @key{ESC} is used as Meta.  Thus @kbd{M-x} is typed as @kbd{@key{ESC}
313 x}.  Viper uses @key{ESC} to switch from Insert state to Vi state.  Therefore
314 Viper defines @kbd{C-\} as its Meta key in Vi state.  @xref{Vi State}, for
315 more info.@refill
317 Emacs is structured as a Lisp interpreter around a C core.  Emacs keys
318 cause Lisp functions to be called.  It is possible to call these
319 functions directly, by typing @kbd{M-x function-name}.
321 @node Loading Viper, States in Viper, Emacs Preliminaries, Overview
322 @section Loading Viper
324 The most common way to load it automatically is to include the following
325 lines (in the given order!):
327 @lisp
328 (setq viper-mode t)
329 (require 'viper)
330 @end lisp
332 @noindent
333 in your @file{~/.emacs} file.  The @file{.emacs} file is placed in your
334 home directory and it is be executed every time you invoke Emacs.  This is
335 the place where all general Emacs customization takes place.  Beginning with
336 version 20.0, Emacsen have an interactive interface, which simplifies the
337 job of customization significantly.
339 Viper also uses the file @file{~/.viper} for Viper-specific customization.
340 The location of Viper customization file can be changed by setting the
341 variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading
342 Viper.
344 The latest versions of Emacs have an interactive customization facility,
345 which allows you to (mostly) bypass the use of the @file{.emacs} and
346 @file{.viper} files. You can reach this customization
347 facility from within Viper's VI state by executing the Ex command
348 @kbd{:customize}.
350 Once invoked, Viper will arrange to bring up Emacs buffers in Vi state
351 whenever this makes sense.
352 @xref{Packages that Change Keymaps}, to find out when forcing Vi command state
353 on a buffer may be counter-productive.
355 Even if your @file{.emacs} file does not invoke Viper automatically,
356 you can still load Viper and enter the Vi command state by typing the
357 following from within Emacs:
359 @lisp
360 M-x viper-mode
361 @end lisp
363 When Emacs first comes up, if you have not specified a file on the
364 command line, it will show the @samp{*scratch*} buffer, in the
365 @samp{Lisp Interaction} mode.  After you invoke Viper, you can start
366 editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands.
367 (@xref{File and Buffer Handling}, for more information on @kbd{v} and other
368 new commands that, in many cases, are more convenient than @kbd{:e},
369 @kbd{:vi}, and similar old-style Vi commands.)@refill
371 Finally, if at some point you would want to de-Viperize your running
372 copy of Emacs after Viper has been loaded, the command @kbd{M-x
373 viper-go-away} will do it for you.  The function @code{toggle-viper-mode}
374 toggles Viperization of Emacs on and off.
376 @node States in Viper, The Minibuffer, Loading Viper,Overview
377 @section States in Viper
379 @kindex @kbd{C-z}
380 @kindex @key{ESC}
381 @kindex @kbd{i}
382 @cindex Emacs state
383 @cindex Vi state
384 @cindex Insert state
385 @cindex Replace state
386 @cindex Ex commands
387 @findex @code{viper-go-away}
388 @findex @code{toggle-viper-mode}
390 Viper has four states, Emacs, Vi, Insert, and Replace.
392 @table @samp
393 @item Emacs state
394 This is the state plain vanilla Emacs is normally in.  After you have loaded
395 Viper, @kbd{C-z} will normally take you to Vi command state.  Another
396 @kbd{C-z} will take you back to Emacs state.  This toggle key can be
397 changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to
398 change to Vi state.@refill
401 For users who chose to set their user level to 1 at Viper setup time,
402 switching to Emacs state is deliberately made harder in order to not
403 confuse the novice user.  In this case, @kbd{C-z} will either iconify Emacs
404 (if Emacs runs as an application under X) or it will stop Emacs (if
405 Emacs runs on a dumb terminal or in an Xterm window).
407 @item Vi state
408 This is the Vi command mode.  Any of the Vi commands, such as @kbd{i, o, a},
409 @dots{}, will take you to Insert state.  All Vi commands may
410 be used in this mode.  Most Ex commands can also be used.
411 For a full list of Ex commands supported by Viper, type
412 @kbd{:} and then @key{TAB}.  To get help on any issue, including the Ex
413 commands, type @kbd{:help}.  This will invoke Viper Info
414 (if it is installed).  Then typing @kbd{i} will prompt you for a topic to
415 search in the index.  Note: to search for Ex commands in the index, you
416 should start them with a @kbd{:}, e.g., @kbd{:WW}.
418 In Viper, Ex commands can be made to work on the current Emacs region.
419 This is done by typing a digit argument before @kbd{:}.
420 For instance, typing @kbd{1:} will propmt you with something like
421 @emph{:123,135}, assuming that the current region starts at line 123 and
422 ends at line 135.  There is no need to type the line numbers, since Viper
423 inserts them automatically in front of the Ex command.
425 @item Insert state
426 Insert state is the Vi insertion mode.  @key{ESC} will take you back to
427 Vi state.  Insert state editing can be done, including auto-indentation.  By
428 default, Viper disables Emacs key bindings in Insert state.
430 @item Replace state
431 Commands like @kbd{cw} invoke the Replace state.  When you cross the
432 boundary of a replacement region (usually designated via a @samp{$} sign),
433 it will automatically change to Insert state.  You do not have to worry
434 about it.  The key bindings remain practically the same as in Insert
435 state.  If you type @key{ESC}, Viper will switch to Vi command mode, terminating the
436 replacement state.@refill
437 @end table
439 @cindex mode line
441 The modes are indicated on the @dfn{mode line} as <E>, <I>, <V>, and <R>,
442 so that the multiple modes do not confuse you.  Most of your editing can be
443 done in Vi and Insert states.  Viper will try to make all new buffers be in Vi
444 state, but sometimes they may come up in Emacs state.  @kbd{C-z}
445 will take you to Vi state in such a case.  In some major modes, like Dired,
446 Info, Gnus, etc., you should not switch to Vi state (and Viper will not
447 attempt to do so) because these modes are not intended for text editing and
448 many of the Vi keys have special meaning there.  If you plan to read news,
449 browse directories, read mail, etc., from Emacs (which you should start
450 doing soon!), you should learn about the meaning of the various keys in
451 those special modes (typing @kbd{C-h m} in a buffer provides
452 help with key bindings for the major mode of that buffer).
454 If you switch to Vi in Dired or similar modes---no harm is done.  It is just
455 that the special key bindings provided by those modes will be temporarily
456 overshadowed by Viper's bindings.  Switching back to Viper's Emacs state
457 will revive the environment provided by the current major mode.
459 States in Viper are orthogonal to Emacs major modes, such as C mode or Dired
460 mode.  You can turn Viper on and off for any Emacs state.  When Viper is turned
461 on, Vi state can be used to move around.  In Insert state, the bindings for
462 these modes can be accessed.  For beginners (users at Viper levels 1 and 2),
463 these bindings are suppressed in Insert state, so that new users are not
464 confused by the Emacs states.  Note that unless you allow Emacs bindings in
465 Insert state, you cannot do many interesting things, like language
466 sensitive editing.  For the novice user (at Viper level 1), all major mode
467 bindings are turned off in Vi state as well.  This includes the bindings for
468 key sequences that start with @kbd{C-c}, which practically means that all
469 major mode bindings are unsupported.  @xref{Customization}, to find out how
470 to allow Emacs keys in Insert state.
472 @menu
473 * Emacs State::         This is the state you should learn more about when
474                         you get up to speed with Viper.
475 * Vi State::            Vi commands are executed in this state.
476 * Insert State::        You can enter text, and also can do sophisticated
477                         editing if you know enough Emacs commands.
478 * Replace State::       Like Insert mode, but it is invoked via the
479                         replacement commands, such as cw, C, R, etc.
480 @end menu
482 @node Emacs State, Vi State, States in Viper, States in Viper
483 @subsection Emacs State
485 @kindex @kbd{C-z}
486 @cindex Emacs state
489 You will be in this mode only by accident (hopefully).  This is the state
490 Emacs is normally in (imagine!!).  Now leave it as soon as possible by
491 typing @kbd{C-z}.  Then you will be in Vi state (sigh of relief) :-).
493 Emacs state is actually a Viperism to denote all the major and minor modes
494 (@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in.  Emacs
495 can have several modes, such as C mode for editing C programs, LaTeX mode
496 for editing LaTeX documents, Dired for directory editing, etc.  These are
497 major modes, each with a different set of key-bindings.  Viper states are
498 orthogonal to these Emacs major modes.  The presence of these language
499 sensitive and other modes is a major win over Vi.  @xref{Improvements over
500 Vi}, for more.@refill
502 The bindings for these modes can be made available in the Viper Insert state
503 as well as in Emacs state.  Unless you specify your user level as 1 (a
504 novice), all major mode key sequences that start with @kbd{C-x} and
505 @kbd{C-c} are also available in Vi state.  This is important because major
506 modes designed for editing files, such as cc-mode or latex-mode, use key
507 sequences that begin with @kbd{C-x} and @kbd{C-c}.
509 There is also a key that lets you temporarily escape to Vi command state
510 from the Insert state: typing @kbd{C-z} will let you execute a
511 single Vi command while staying in Viper's Insert state.
514 @node Vi State, Insert State, Emacs State, States in Viper
515 @subsection Vi State
517 @cindex Vi state
519 This is the Vi command mode.  When Viper is in Vi state, you will see the sign
520 <V> in the mode line.  Most keys will work as in Vi.  The notable
521 exceptions are:
523 @table @kbd
524 @item C-x
525 @kindex @kbd{C-x}
526 @kbd{C-x} is used to invoke Emacs commands, mainly those that do window
527 management.  @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a
528 window.  @kbd{C-x 1} will close all other windows.  @kbd{C-xb} is used to
529 switch buffers in a window, and @kbd{C-xo} to move through windows.
530 These are about the only necessary keystrokes.
531 For the rest, see the GNU Emacs Manual.
533 @item C-c
534 @kindex @kbd{C-c}
535 For user levels 2 and higher, this key serves as a prefix key for the key
536 sequences used by various major modes.  For users at Viper level 1, @kbd{C-c}
537 simply beeps.
539 @item C-g and C-]
540 @kindex @kbd{C-g}
541 @kindex @kbd{C-]}
543 These are the Emacs @samp{quit} keys.
544 There will be cases where you will have to
545 use @kbd{C-g} to quit.  Similarly, @kbd{C-]} is used to exit
546 @samp{Recursive Edits} in Emacs for which there is no comparable Vi
547 functionality and no key-binding.  Recursive edits are indicated by
548 @samp{[]} brackets framing the modes on the mode line.
549 @xref{Recursive Edit,Recursive
550 Edit,Recursive Edit,emacs,The GNU Emacs Manual}.
551 At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file}
552 function instead.
553 @refill
554 @item C-\
555 @kindex @kbd{C-\}
556 @cindex Meta key
558 Viper uses @key{ESC} as a switch between Insert and Vi states.  Emacs uses
559 @key{ESC} for Meta.  The Meta key is very important in Emacs since many
560 functions are accessible only via that key as @kbd{M-x function-name}.
561 Therefore, we need to simulate it somehow.  In Viper's Vi, Insert, and
562 Replace states, the meta key is set to be @kbd{C-\}.  Thus, to get
563 @kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key,
564 which is rare these days).
565 This works both in the Vi command state and in the Insert and Replace
566 states.  In Vi command state, you can also use @kbd{\ @key{ESC}} as the
567 meta key.
569 Note: Emacs binds @kbd{C-\} to a function that offers to change the
570 keyboard input method in the multilingual environment.  Viper overrides this
571 binding.  However, it is still possible to switch the input method by typing
572 @kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state.
573 Or you can use the MULE menu in the menubar.
574 @end table
575 @noindent
576 Other differences are mostly improvements.  The ones you should know
577 about are:
579 @table @samp
580 @item Undo
581 @kindex @kbd{u}
582 @kbd{u} will undo.  Undo can be repeated by the @kbd{.} key.  Undo itself
583 can be undone.  Another @kbd{u} will change the direction.  The presence
584 of repeatable undo means that @kbd{U}, undoing lines, is not very
585 important.  Therefore, @kbd{U} also calls @code{viper-undo}.
586 @cindex multiple undo
587 @cindex undo
590 @item Counts
591 Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts.
593 @comment ]] Just to balance parens
594 @item Regexps
595 Viper uses Emacs Regular Expressions for searches.  These are a superset of
596 Vi regular
597 expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L},
598 @dots{}, etc.  @xref{Regexps,,Syntax of Regular Expressions,emacs,The
599 GNU Emacs Manual}, for details.
600 Files specified to @kbd{:e} use @code{csh} regular expressions
601 (globbing, wildcards, what have you).
602 However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /},
603 lets the user switch from search with regular expressions to plain vanilla
604 search and vice versa.  It also lets one switch from case-sensitive search
605 to case-insensitive and back.
606 @xref{Viper Specials}, for more details.
607 @cindex regular expressions
608 @cindex vanilla search
609 @cindex case-sensitive search
610 @cindex case-insensitive search
611 @kindex @kbd{C-c /}
613 @item Ex commands
614 @cindex Ex commands
615 The current working directory of a buffer is automatically inserted in the
616 minibuffer if you type @kbd{:e} then space.  Absolute filenames are
617 required less often in Viper.  For file names, Emacs uses a convention that
618 is slightly different from other programs.  It is designed to minimize the
619 need for deleting file names that Emacs provides in its prompts.  (This is
620 usually convenient, but occasionally the prompt may suggest a wrong file
621 name for you.)  If you see a prompt @kbd{/usr/foo/} and you wish to edit the
622 file @kbd{~/.viper}, you don't have to erase the prompt.  Instead, simply
623 continue typing what you need.  Emacs will interpret @kbd{/usr/foo/~/.viper}
624 correctly.  Similarly, if the prompt is @kbd{~/foo/} and you need to get to
625 @kbd{/bar/file}, keep typing.  Emacs interprets @kbd{~/foo//bar/} as
626 @kbd{/bar/file}, since when it sees @samp{//}, it understands that
627 @kbd{~/foo/} is to be discarded.
629 The command @kbd{:cd} will change the default directory for the
630 current buffer.  The command @kbd{:e} will interpret the
631 filename argument in @code{csh}.  @xref{Customization}, if you
632 want to change the default shell.
633 The command @kbd{:next} takes counts from
634 @kbd{:args}, so that @kbd{:rew} is obsolete.  Also, @kbd{:args} will show only
635 the invisible files (i.e., those that are not currently seen in Emacs
636 windows).
638 When applicable, Ex commands support file completion and history.  This
639 means that by typing a partial file name and then @key{TAB}, Emacs will try
640 to complete the name or it will offer a menu of possible completions.
641 This works similarly to Tcsh and extends the behavior of Csh.  While Emacs
642 is waiting for a file name, you can type @kbd{M-p} to get the previous file
643 name you typed.  Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you
644 browse through the file history.
646 Like file names, partially typed Ex commands can be completed by typing
647 @key{TAB}, and Viper keeps the history of Ex commands.  After typing
648 @kbd{:}, you can browse through the previously entered Ex commands by
649 typing @kbd{M-p} and @kbd{M-n}.  Viper tries to rationalize when it puts Ex
650 commands on the history list.  For instance, if you typed @kbd{:w!@: foo},
651 only @kbd{:w!} will be placed on the history list.  This is because the
652 last history element is the default that can be invoked simply by typing
653 @kbd{: @key{RET}}.  If @kbd{:w!@: foo} were placed on the list, it would be all to
654 easy to override valuable data in another file.  Reconstructing the full
655 command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper
656 has a separate history for file names.  By typing @kbd{: M-p}, you will get
657 @kbd{:w!} in the Minibuffer.  Then, repeated @kbd{M-p} will get you through
658 the file history, inserting one file name after another.
660 In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire
661 command will appear in the history list.  This is because having @kbd{:r}
662 alone as a default is meaningless, since this command requires a file
663 argument.
664 @refill
665 @end table
666 @noindent
667 As Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'.
668 However, in addition, Viper keeps track of the history of such commands.  This
669 history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}.
670 Having found the appropriate command, it can be then executed by typing
671 `@kbd{.}'.
672 @xref{Improvements over Vi}, for more information.
674 @node Insert State, Replace State, Vi State, States in Viper
675 @subsection Insert State
677 @cindex Insert state
679 To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the
680 standard Vi keys available in Insert state.  The implication is that
681 Emacs major modes cannot be used in Insert state.
682 It is strongly recommended that as soon as you are comfortable, make the
683 Emacs state bindings visible (by changing your user level to 3 or higher).
684 @xref{Customization},
685 to see how to do this.@refill
687 Once this is done, it is possible to do quite a bit of editing in
688 Insert state.  For instance, Emacs has a @dfn{yank} command, @kbd{C-y},
689 which is similar to Vi's @kbd{p}.  However, unlike @kbd{p}, @kbd{C-y} can be
690 used in Insert state of Viper.  Emacs also has a kill ring where it keeps
691 pieces of text you deleted while editing buffers.  The command @kbd{M-y} is
692 used to delete the text previously put back by Emacs' @kbd{C-y} or by Vi's
693 @kbd{p} command and reinsert text that was placed on the kill-ring earlier.
695 This works both in Vi and Insert states.
696 In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way
697 of recovering the 10 previously deleted chunks of text.  In Insert state,
698 you can
699 use this as follows.  Suppose you deleted a piece of text and now you need
700 to re-insert it while editing in Insert mode.  The key @kbd{C-y} will put
701 back the most recently deleted chunk.  If this is not what you want, type
702 @kbd{M-y} repeatedly and, hopefully, you will find the chunk you want.
704 Finally, in Insert and Replace states, Viper provides the history of
705 pieces of text inserted in previous insert or replace commands.  These
706 strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or
707 @kbd{C-c M-n} while in Insert or Replace state.  (This feature is disabled
708 in the minibuffer: the above keys are usually bound to other histories,
709 which are more appropriate in the minibuffer.)
712 @cindex Meta key
714 You can call Meta functions from Insert state.  As in Vi state, the Meta key
715 is @kbd{C-\}.  Thus @kbd{M-x} is typed as @kbd{C-\ x}.
717 Other Emacs commands that are useful in Insert state are @kbd{C-e}
718 and @kbd{C-a}, which move the cursor to the end and the beginning of the
719 current line, respectively.  You can also use @kbd{M-f} and @kbd{M-b},
720 which move the cursor forward (or backward) one word.
721 If your display has a Meta key, these functions are invoked by holding the
722 Meta key and then typing @kbd{f} and @kbd{b}, respectively.  On displays
723 without the Meta key, these functions are invoked by typing
724 @kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert
725 state, as explained above).
727 The key @kbd{C-z} is sometimes also useful in Insert state: it allows you
728 to execute a single command in Vi state without leaving the Insert state!
729 For instance, @kbd{C-z d2w} will delete the next two words without leaving
730 the Insert state.
732 When Viper is in Insert state, you will see <I> in the mode line.
734 @node Replace State,, Insert State, States in Viper
735 @subsection Replace State
737 @cindex Replace state
739 This state is entered through Vi replacement commands, such as @kbd{C},
740 @kbd{cw}, etc., or by typing @kbd{R}.  In Replace state, Viper puts <R> in
741 the mode line to let you know which state is in effect.  If Replace state is
742 entered through @kbd{R}, Viper stays in that state until the user hits
743 @key{ESC}.  If this state is entered via the other replacement commands,
744 then Replace state is in effect until you hit @key{ESC} or until you cross
745 the rightmost boundary of the replacement region.  In the latter case, Viper
746 changes its state from Replace to Insert (which you will notice by the
747 change in the mode line).
749 Since Viper runs under Emacs, it is possible to switch between buffers
750 while in Replace state.  You can also move the cursor using the arrow keys
751 (even on dumb terminals!)@: and the mouse.  Because of this freedom (which is
752 unattainable in regular Vi), it is possible to take the cursor outside the
753 replacement region.  (This may be necessary for several reasons, including
754 the need to enable text selection and region-setting with the mouse.)
756 The issue then arises as to what to do when the user
757 hits the @key{ESC} key.  In Vi, this would cause the text between cursor and
758 the end of the replacement region to be deleted.  But what if, as is
759 possible in Viper, the cursor is not inside the replacement region?
761 To solve the problem, Viper keeps track of the last cursor position while it
762 was still inside the replacement region.  So, in the above situation, Viper
763 would delete text between this position and the end of the replacement
764 region.
766 @node The Minibuffer,Multiple Files in Viper, States in Viper, Overview
767 @section The Minibuffer
769 @cindex Minibuffer
771 The Minibuffer is where commands are entered in.  Editing can be done
772 by commands from Insert state, namely:
774 @table @kbd
775 @item C-h
776 Backspace
777 @item C-w
778 Delete Word
779 @item C-u
780 Erase line
781 @item C-v
782 Quote the following character
783 @item @key{RET}
784 Execute command
785 @item C-g and C-]
786 Emacs quit and abort keys.  These may be necessary.  @xref{Vi State}, for an
787 explanation.
788 @item M-p and M-n
789 These keys are bound to functions that peruse minibuffer history.  The
790 precise history to be perused depends on the context.  It may be the history
791 of search strings, Ex commands, file names, etc.
792 @end table
794 Most of the Emacs keys are functional in the Minibuffer.  While in the
795 Minibuffer, Viper tries to make editing resemble Vi's behavior when the
796 latter is waiting for the user to type an Ex command.  In particular, you
797 can use the regular Vi commands to edit the Minibuffer.  You can switch
798 between the Vi state and Insert state at will, and even use the replace mode.
799 Initially, the Minibuffer comes up in Insert state.
801 Some users prefer plain Emacs bindings in the Minibuffer.  To this end, set
802 @code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}.
803 @xref{Customization}, to learn how to do this.
805 When the Minibuffer changes Viper states, you will notice that the appearance
806 of the text there changes as well.  This is useful because the Minibuffer
807 has no mode line to tell which Vi state it is in.
808 The appearance of the text in the Minibuffer can be changed.
809 @xref{Viper Specials}, for more details.
811 @node Multiple Files in Viper,Unimplemented Features,The Minibuffer,Overview
812 @section Multiple Files in Viper
814 @cindex multiple files
815 @cindex managing multiple files
817 Viper can edit multiple files.  This means, for example that you never need
818 to suffer through @code{No write since last change} errors.
819 Some Viper elements are common over all the files.
821 @table @samp
822 @item Textmarkers
823 @cindex markers
824 @cindex textmarkers
825 Textmarkers remember @emph{files and positions}.
826 If you set marker @samp{a} in
827 file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then
828 @emph{YOU WILL SWITCH TO FILE @file{foo}}.  You can see the contents of a
829 textmarker using the Viper command @kbd{[<a-z>} where <a-z> are the
830 textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill
831 @item Repeated Commands
832 Command repetitions are common over files.  Typing @kbd{!!} will repeat the
833 last @kbd{!} command whichever file it was issued from.
834 Typing @kbd{.} will repeat the last command from any file, and
835 searches will repeat the last search.  Ex commands can be repeated by typing
836 @kbd{: @key{RET}}.@refill
837 Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous.
838 However, usually its effect can be undone by typing @kbd{u}.
839 @item Registers
840 @cindex registers
841 Registers are common to files.  Also, text yanked with @kbd{y} can be
842 put back (@kbd{p}) into any file.  The Viper command @kbd{]<a-z>}, where <a-z> are
843 the registers, can be used to look at the contents of a register, e.g.,
844 type @kbd{]a} to view register @samp{a}.
846 There is one difference in text deletion that you should be
847 aware of.  This difference comes from Emacs and was adopted in Viper
848 because we find it very useful.  In Vi, if you delete a line, say, and then
849 another line, these two deletions are separated and are put back
850 separately if you use the @samp{p} command.  In Emacs (and Viper), successive
851 series of deletions that are @emph{not interrupted} by other commands are
852 lumped together, so the deleted text gets accumulated and can be put back
853 as one chunk.  If you want to break a sequence of deletions so that the
854 newly deleted text could be put back separately from the previously deleted
855 text, you should perform a non-deleting action, e.g., move the cursor one
856 character in any direction.
857 @item Absolute Filenames
858 @cindex absolute file names
859 The current directory name for a file is automatically prepended to the
860 file name in any
861 @kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a
862 current directory).
863 This directory is inserted in the Minibuffer once you type space after
864 @kbd{:e, r}, etc.  Viper also supports completion of file names and Ex
865 commands (@key{TAB}), and it keeps track of
866 command and file history (@kbd{M-p}, @kbd{M-n}).
867 Absolute filenames are required less
868 often in Viper.
870 You should be aware that Emacs interprets @kbd{/foo/bar//bla} as
871 @kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}.  This is designed to
872 minimize the need for erasing file names that Emacs suggests in its
873 prompts, if a suggested file name is not what you wanted.
875 The command @kbd{:cd} will change the default directory for the
876 current Emacs buffer.  The Ex command @kbd{:e} will interpret the
877 filename argument in @samp{csh}, by default.  @xref{Customization}, if you
878 want to change this.
879 @end table
881 @noindent
882 Currently undisplayed files can be listed using the @kbd{:ar} command.  The
883 command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to
884 other files. For example, use `:n3' to move to the third file in that list.
886 @node Unimplemented Features,,Multiple Files in Viper,Overview
887 @section Unimplemented Features
889 Unimplemented features include:
891 @itemize @bullet
892 @item
893 @kbd{:ab} and @kbd{:una} are not implemented, since
894 @kbd{:ab} is considered obsolete, since Emacs has much
895 more powerful facilities for defining abbreviations.
896 @item
897 @kbd{:set option?} is not implemented.  The current
898 @kbd{:set} can also be used to set Emacs variables.
899 @item
900 @kbd{:se list} requires modification of the display code for Emacs, so
901 it is not implemented.
902 A useful alternative is @code{cat -t -e file}.  Unfortunately, it cannot
903 be used directly inside Emacs, since Emacs will obdurately change @samp{^I}
904 back to normal tabs.@refill
905 @end itemize
907 @comment  node-name,  next,  previous,  up
908 @node Improvements over Vi, Customization, Overview, Top
909 @chapter Improvements over Vi
911 Some common problems with Vi and Ex have been solved in Viper.  This
912 includes better implementation of existing commands, new commands, and
913 the facilities provided by Emacs.
915 @menu
916 * Basics::                  Basic Viper differences, Multi-file effects.
917 * Undo and Backups::        Multiple undo, auto-save, backups and changes
918 * History::                 History for Ex and Vi commands.
919 * Macros and Registers::    Keyboard Macros (extended ".")@: @@reg execution.
920 * Completion::              Filename and Command Completion for Ex.
921 * Improved Search::         Incremental Search and Buffer Content Search.
922 * Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs.
923 * Movement and Markers::    Screen Editor movements, viewing textmarkers.
924 * New Commands::            Commands that do not exist in Vi.
925 * Useful Packages::         A Sampling of some Emacs packages, and things
926                             you should know about.
927 @end menu
929 @node Basics, Undo and Backups, Improvements over Vi, Improvements over Vi
930 @section Basics
932 The Vi command set is based on the idea of combining motion commands
933 with other commands.  The motion command is used as a text region
934 specifier for other commands.
935 We classify motion commands into @dfn{point commands} and
936 @dfn{line commands}.@refill
938 @cindex point commands
940 The point commands are:
942 @quotation
943 @kbd{h}, @kbd{l}, @kbd{0},  @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B},
944 @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f},
945 @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^}
946 @end quotation
948 @cindex line commands
950 The line commands are:
952 @quotation
953 @kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{},
954 @kbd{@}}, @kbd{G}, @kbd{'},  @kbd{[[}, @kbd{]]}, @kbd{[]}
955 @end quotation
957 @cindex region
958 @cindex region specification
959 @cindex expanding (region)
960 @cindex describing regions
961 @cindex movement commands
963 @noindent
964 If a point command is given as an argument to a modifying command, the
965 region determined by the point command will be affected by the modifying
966 command.  On the other hand, if a line command is given as an argument to a
967 modifying command, the region determined by the line command will be
968 enlarged so that it will become the smallest region properly containing the
969 region and consisting of whole lines (we call this process @dfn{expanding
970 the region}), and then the enlarged region will be affected by the modifying
971 command.
972 Text Deletion Commands (@pxref{Deleting Text}), Change commands
973 (@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands})
974 use these commands to describe a region of text to operate on.
975 Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or
976 @kbd{!'afmt} to format a region from @samp{point} to textmarker
977 @samp{a}.
979 @cindex r and R region specifiers
981 Viper adds the region specifiers @samp{r} and @samp{R}.  Emacs has a
982 special marker called @dfn{mark}.  The text-area between the current cursor
983 position @dfn{point} and the @dfn{mark} is called the @dfn{region}.
984 @samp{r} specifies the raw region and @samp{R} is the expanded region
985 (i.e., the minimal contiguous chunk of full lines that contains the raw
986 region).
987 @kbd{dr} will now delete the region, @kbd{>r} will shift it, etc.
988 @kbd{r,R} are not motion commands, however.  The special mark is set by
989 @kbd{m.} and other commands.  @xref{Marking}, for more info.
991 Viper also adds counts to most commands for which it would make sense.
993 In the Overview chapter, some Multiple File issues were discussed
994 (@pxref{Multiple Files in Viper}).  In addition to the files, Emacs has
995 buffers.  These can be seen in the @kbd{:args} list and switched using
996 @kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or
997 specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper}
998 file.  @xref{Customization}, for details.
1000 @node Undo and Backups, History, Basics, Improvements over Vi
1001 @section Undo and Backups
1003 @cindex undo
1005 Viper provides multiple undo.  The number of undo's and the size is limited
1006 by the machine.  The Viper command @kbd{u} does an undo.  Undo can be
1007 repeated by typing @kbd{.} (a period).  Another @kbd{u} will undo the undo,
1008 and further
1009 @kbd{.} will repeat it.  Typing @kbd{u} does the first undo, and changes the
1010 direction.
1012 @cindex backup files
1013 @cindex auto save
1015 Since the undo size is limited, Viper can create backup files and
1016 auto-save files.  It will normally do this automatically.  It is possible
1017 to have numbered backups, etc.  For details, @pxref{Backup,,Backup and
1018 Auto-Save,emacs,The GNU Emacs Manual} @refill
1020 @comment [ balance parens
1021 @cindex viewing registers and markers
1022 @cindex registers
1023 @cindex markers
1024 @cindex textmarkers
1026 The results of the 9 previous changes are available in the 9 numeric
1027 registers, as in Vi.  The extra goody is the ability to @emph{view} these
1028 registers, in addition to being able to access them through @kbd{p} and
1029 @kbd{M-y} (@xref{Insert State}, for details.)
1030 The Viper command @kbd{] register} will display the contents of any
1031 register, numeric or alphabetical.  The related command @kbd{[ textmarker}
1032 will show the text around the textmarker.  @samp{register} and @samp{textmarker}
1033 can be any letters from a through z.
1034 @comment ] balance parens
1036 @node History,  Macros and Registers, Undo and Backups,Improvements over Vi
1037 @section History
1039 @cindex history
1040 @cindex Minibuffer
1042 History is provided for Ex commands, Vi searches, file names, pieces of
1043 text inserted in earlier commands that use Insert or Replace state, and for
1044 destructive commands in Vi state.  These are
1045 useful for fixing those small typos that screw up searches and @kbd{:s},
1046 and for eliminating routine associated with repeated typing of file names
1047 or pieces of text that need to be inserted frequently.
1048 At the @kbd{:} or @kbd{/} prompts in the Minibuffer, you can do the following:
1050 @table @kbd
1051 @item M-p and M-n
1052 To move to previous and next history items.  This causes the history
1053 items to appear on the command line, where you can edit them, or
1054 simply type Return to execute.
1055 @item M-r and M-s
1056 To search backward and forward through the history.
1057 @item @key{RET}
1058 Type @key{RET} to accept a default (which is displayed in the prompt).
1059 @end table
1061 The history of insertions  can be perused by
1062 typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state.
1063 The history of destructive Vi commands can be perused via the same keys
1064 when Viper is in Vi state.  @xref{Viper Specials}, for details.
1066 All Ex commands have a file history.  For instance, typing @kbd{:e}, space
1067 and then @kbd{M-p} will bring up the name of the previously typed file
1068 name.  Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse
1069 through the file history.
1071 Similarly, commands that have to do with switching buffers
1072 have a buffer history, and commands that expect strings or regular
1073 expressions keep a history on those items.
1075 @node Macros and Registers,Completion,History,Improvements over Vi
1076 @section Macros and Registers
1078 @cindex keyboard macros
1079 @cindex macros
1080 @cindex registers
1081 @cindex register execution
1083 Viper facilitates the use of Emacs-style keyboard macros.  @kbd{@@#} will
1084 start a macro definition.  As you type, the commands will be executed, and
1085 remembered (This is called ``learn mode'' in some editors.)
1086 @kbd{@@register} will complete the macro, putting it into @samp{register},
1087 where @samp{register} is any character from @samp{a} through @samp{z}.  Then
1088 you can execute this macro using @kbd{@@register}.  It is, of course,
1089 possible to yank some text into a register and execute it using
1090 @kbd{@@register}.  Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will
1091 execute the last macro that was executed using @kbd{@@register}.@refill
1093 Viper will automatically lowercase the register, so that pressing the
1094 @kbd{SHIFT} key for @kbd{@@} will not create problems.  This is for
1095 @kbd{@@} macros and @kbd{"p} @emph{only}.  In the case of @kbd{y},
1096 @kbd{"Ayy} will append to @emph{register a}.  For @kbd{[,],',`}, it
1097 is an error to use a Uppercase register name.
1099 @comment [ balance parens
1100 @cindex viewing registers and markers
1102 The contents of a register can be seen by @kbd{]register}.  (@kbd{[textmarker}
1103 will show the contents of a textmarker).
1104 @comment ] balance parens
1106 @cindex last keyboard macro
1108 The last keyboard macro can also be executed using
1109 @kbd{*}, and it can be yanked into a register using @kbd{@@!register}.
1110 This is useful for Emacs style keyboard macros defined using @kbd{C-x(}
1111 and @kbd{C-x)}.  Emacs keyboard macros have more capabilities.
1112 @xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for
1113 details.@refill
1115 Keyboard Macros allow an interesting form of Query-Replace:
1116 @kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a
1117 Keyboard Macro execution @kbd{@@@@} (the replace).
1119 Viper also provides Vi-style macros.  @xref{Vi Macros}, for details.
1122 @node Completion, Improved Search, Macros and Registers, Improvements over Vi
1123 @section Completion
1125 @cindex completion
1127 Completion is done when you type @key{TAB}.  The Emacs completer does not
1128 grok wildcards in file names.  Once you type a wildcard, the completer will
1129 no longer work for that file name.  Remember that Emacs interprets a file name
1130 of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as
1131 @kbd{~/bar}.
1133 @node Improved Search, Abbreviation Facilities, Completion, Improvements over Vi
1134 @section Improved Search
1136 @cindex buffer search
1137 @cindex word search
1139 Viper provides buffer search, the ability to search the buffer for a region
1140 under the cursor.  You have to turn this on in @file{.viper} either by calling
1142 @example
1143 (viper-buffer-search-enable)
1144 @end example
1146 @noindent
1147 or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}:
1148 @example
1149 (setq viper-buffer-search-char ?g)
1150 @end example
1152 @noindent
1153 If the user calls @code{viper-buffer-search-enable} explicitly (the first
1154 method), then @code{viper-buffer-search-char} will be set to @kbd{g}.
1155 Regardless of how this feature is enabled, the key
1156 @code{viper-buffer-search-char} will take movement commands, like
1157 @kbd{w,/,e}, to find a region and then search for the contents of that
1158 region.  This command is very useful for searching for variable names, etc.,
1159 in a program.  The search can be repeated by @kbd{n} or reversed by @kbd{N}.
1161 @cindex incremental search
1163 Emacs provides incremental search.  As you type the string in, the
1164 cursor will move to the next match.  You can snarf words from the buffer
1165 as you go along.  Incremental Search is normally bound to @kbd{C-s} and
1166 @kbd{C-r}.  @xref{Customization}, to find out how to change the bindings
1167 of @kbd{C-r or C-s}.
1168 For details, @pxref{Incremental Search,,Incremental
1169 Search,emacs,The GNU Emacs Manual} @refill
1171 @cindex query replace
1173 Viper also provides a query replace function that prompts through the
1174 Minibuffer.  It is invoked by the @kbd{Q} key in Vi state.
1176 @cindex mouse search
1178 On a window display, Viper supports mouse search, i.e., you can search for a
1179 word by clicking on it.  @xref{Viper Specials}, for details.
1181 Finally, on a window display, Viper highlights search patterns as it finds
1182 them.  This is done through what is known as @emph{faces} in Emacs.  The
1183 variable that controls how search patterns are highlighted is
1184 @code{viper-search-face}.  If you don't want any highlighting at all, put
1185 @example
1186 (copy-face 'default 'viper-search-face)
1187 @end example
1188 @vindex @code{viper-search-face}
1189 @noindent
1190 in @file{~/.viper}.  If you want to change how patterns are highlighted, you
1191 will have to change @code{viper-search-face} to your liking.  The easiest
1192 way to do this is to use Emacs customization widget, which is accessible
1193 from the menubar.  Viper customization group is located under the
1194 @emph{Emulations} customization group, which in turn is under the
1195 @emph{Editing} group (or simply by typing @kbd{:customize}).  All Viper
1196 faces are grouped together under Viper's
1197 @emph{Highlighting} group.
1199 Try it: it is really simple!
1201 @node Abbreviation Facilities,Movement and Markers,Improved Search,Improvements over Vi
1202 @section Abbreviation Facilities
1204 @cindex abbrevs
1206 It is possible in Emacs to define abbrevs based on the contents of the
1207 buffer.
1208 Sophisticated templates can be defined using the Emacs abbreviation
1209 facilities.  @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for
1210 details.
1212 @cindex dynamic abbrevs
1214 Emacs also provides Dynamic Abbreviations.  Given a partial word, Emacs
1215 will search the buffer to find an extension for this word.  For instance,
1216 one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke
1217 that completed the @samp{A} to @samp{Abbreviations}.  Repeated typing
1218 will search further back in the buffer, so that one could get
1219 @samp{Abbrevs} by repeating the
1220 keystroke, which appears earlier in the text.  Emacs binds this to
1221 @kbd{@key{ESC} /}, so you will have to find a key and bind the function
1222 @code{dabbrev-expand} to that key.
1223 Facilities like this make Vi's @kbd{:ab} command obsolete.
1225 @node Movement and Markers, New Commands, Abbreviation Facilities, Improvements over Vi
1226 @section Movement and Markers
1228 @cindex Ex style motion
1229 @cindex line editor motion
1231 Viper can be set free from the line--limited movements in Vi, such as @kbd{l}
1232 refusing to move beyond the line, @key{ESC} moving one character back,
1233 etc.  These derive from Ex, which is a line editor.  If your @file{.viper}
1234 contains
1236 @example
1237 @code{(setq viper-ex-style-motion nil)}
1238 @end example
1240 @noindent
1241 the motion will be a true screen editor motion.  One thing you must then
1242 watch out for is that it is possible to be on the end-of-line character.
1243 The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they
1244 were on the last character.
1246 @vindex @code{viper-syntax-preference}
1247 @cindex syntax table
1249 The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated
1250 deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to
1251 understand Emacs syntax tables.  If the variable
1252 @code{viper-syntax-preference} is set to @code{strict-vi} then
1253 the meaning of @emph{word} is the same as in
1254 Vi.  However, if the value is @code{reformed-vi} (the default) then the
1255 alphanumeric symbols will be those specified by the current Emacs syntax
1256 table (which may be different for different major modes) plus the
1257 underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc.
1258 Both @code{strict-vi} and @code{reformed-vi} work close to Vi in
1259 traditional cases, but @code{reformed-vi} does a better job when editing
1260 text in non-Latin alphabets.
1262 The user can also specify the value @code{emacs}, which would
1263 make Viper use exactly the Emacs notion of word.  In particular, the
1264 underscore may not be part of a word.  Finally, if
1265 @code{viper-syntax-preference} is set to @code{extended}, Viper words would
1266 consist of characters that are classified as alphanumeric @emph{or} as
1267 parts of symbols.  This is convenient for writing programs and in many other
1268 situations.
1270 @code{viper-syntax-preference} is a local variable, so it can have different
1271 values for different major modes.  For instance, in programming modes it can
1272 have the value @code{extended}.  In text modes where words contain special
1273 characters, such as European (non-English) letters, Cyrillic letters, etc.,
1274 the value can be @code{reformed-vi} or @code{emacs}.
1276 Changes to @code{viper-syntax-preference} should be done in the hooks to
1277 various major modes by executing @code{viper-set-syntax-preference} as in
1278 the following example:
1280 @example
1281 (viper-set-syntax-preference nil "emacs")
1282 @end example
1284 @findex @code{viper-set-syntax-preference}
1286 The above discussion of the meaning of Viper's words concerns only Viper's
1287 movement commands.  In regular expressions, words remain the same as in
1288 Emacs.  That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use
1289 Emacs' idea of what is a word, and they don't look into the value of
1290 variable @code{viper-syntax-preference}.  This is because Viper doesn't change
1291 syntax tables in fear of upsetting the various major modes that set these
1292 tables.
1294 @cindex textmarkers
1296 Textmarkers in Viper remember the file and the position, so that you can
1297 switch files by simply doing @kbd{'a}.  If you set up a regimen for using
1298 Textmarkers, this is very useful.  Contents of textmarkers can be viewed
1299 by @kbd{[marker}.  (Contents of registers can be viewed by @kbd{]register}).
1301 @node New Commands, Useful Packages, Movement and Markers, Improvements over Vi
1302 @section New Commands
1304 These commands have no Vi analogs.
1306 @table @kbd
1307 @item C-x, C-c
1308 @kindex @kbd{C-x}
1309 @kindex @kbd{C-c}
1310 These two keys invoke many important Emacs functions.  For example, if you
1311 hit @kbd{C-x} followed by @kbd{2}, then the current window will be split
1312 into 2.  Except for novice users, @kbd{C-c} is also set to execute an Emacs
1313 command from the current major mode.  @key{ESC} will do the same, if you
1314 configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to @code{nil}
1315 in @file{.viper}.  @xref{Customization}.  @kbd{C-\} in Insert, Replace, or Vi
1316 states will make Emacs think @kbd{Meta} has been hit.@refill
1317 @item \
1318 @kindex @kbd{\}
1319 Escape to Emacs to execute a single Emacs command.  For instance,
1320 @kbd{\ @key{ESC}} will act like a Meta key.
1321 @item Q
1322 @kindex @kbd{Q}
1323 @cindex query replace
1324 @kbd{Q} is for query replace.  By default,
1325 each string to be replaced is treated as a regular expression.  You can use
1326 @code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to
1327 turn this off.  (For normal searches, @kbd{:se nomagic} will work.  Note
1328 that @kbd{:se nomagic} turns Regexps off completely, unlike Vi).
1329 @item v
1330 @itemx V
1331 @itemx C-v
1332 @kindex @kbd{v}
1333 @kindex @kbd{V}
1334 @kindex @kbd{C-v}
1335 These keys are used to visit files.  @kbd{v} will switch to a buffer
1336 visiting file whose name can be entered in the Minibuffer.  @kbd{V} is
1337 similar, but will use a window different from the current window.
1338 @kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used
1339 instead of a new Emacs window.
1340 @item #
1341 @kindex @kbd{#}
1342 If followed by a certain character @var{ch}, it becomes an operator whose
1343 argument is the region determined by the motion command that follows
1344 (indicated as <move>).
1345 Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and
1346 @kbd{s}.  For instance, @kbd{#qr} will prompt you for a string and then
1347 prepend this string to each line in the buffer.@refill
1348 @item # c
1349 @kindex @kbd{#c<move>}
1350 @cindex changing case
1351 Change upper-case characters in the region to lower-case
1352 (@code{downcase-region}).
1353 Emacs command @kbd{M-l} does the same for words.
1354 @item # C
1355 @kindex @kbd{#C<move>}
1356 Change lower-case characters in the region to upper-case.  For instance,
1357 @kbd{# C 3 w} will capitalize 3 words from the current point
1358 (@code{upcase-region}).
1359 Emacs command @kbd{M-u} does the same for words.
1360 @item # g
1361 @kindex @kbd{#g<move>}
1362 Execute last keyboard macro for each line in the region
1363 (@code{viper-global-execute}).@refill
1364 @item # q
1365 @kindex @kbd{#q<move>}
1366 Insert specified string at the beginning of each line in the region
1367 (@code{viper-quote-region}).  The default string is composed of the comment
1368 character(s) appropriate for the current major mode.
1369 @item # s
1370 @kindex @kbd{#s<move>}
1371 Check spelling of words in the region (@code{spell-region}).
1372 The function used for spelling is determined from the variable
1373 @code{viper-spell-function}.
1374 @vindex @code{viper-spell-function}
1375 @item *
1376 @kindex @kbd{*}
1377 Call last keyboard macro.
1378 @item m .
1379 Set mark at point and push old mark off the ring
1380 @item m<
1381 @item m>
1382 Set mark at beginning and end of buffer, respectively.
1383 @item m,
1384 Jump to mark and pop mark off the ring.  @xref{Mark,,Mark,emacs,The GNU
1385 Emacs Manual}, for more info.
1386 @item ] register
1387 @kindex @kbd{]<a-z>}
1388 View contents of register
1389 @item [ textmarker
1390 @kindex @kbd{[<a-z>}
1391 View filename and position of textmarker
1392 @item @@#
1393 @item @@register
1394 @item @@!
1395 @kindex @kbd{@@#}
1396 @kindex @kbd{@@<a-z>}
1397 @kindex @kbd{@@!}
1398 @cindex keyboard macros
1399 @cindex register execution
1401 Begin/end keyboard macro.  @@register has a different meaning when used after
1402 a @kbd{@@#}.  @xref{Macros and Registers}, for details
1403 @item []
1404 @kindex @kbd{[]}
1405 Go to end of heading.
1406 @item g <@emph{movement command}>
1407 Search buffer for text delimited by movement command.  The canonical
1408 example is @kbd{gw} to search for the word under the cursor.
1409 @xref{Improved Search}, for details.@refill
1410 @item C-g and C-]
1411 @kindex @kbd{C-g}
1412 @kindex @kbd{C-]}
1413 Quit and Abort Recursive edit.  These may be necessary on occasion.
1414 @xref{Vi State}, for a reason.
1415 @item C-c C-g
1416 @kindex @kbd{C-c C-g}
1417 Hitting @kbd{C-c} followed by @kbd{C-g} will display the information on the
1418 current buffer.  This is the same as hitting @kbd{C-g} in Vi, but, as
1419 explained above, @kbd{C-g} is needed for other purposes in Emacs.
1420 @item C-c /
1421 @kindex @kbd{C-c /}
1422 Without a prefix argument, this command toggles
1423 case-sensitive/case-insensitive search modes and plain vanilla/regular
1424 expression search.  With the prefix argument 1, i.e.,
1425 @kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2,
1426 toggles plain vanilla search and search using
1427 regular expressions.  @xref{Viper Specials}, for alternative ways to invoke
1428 this function.
1429 @cindex vanilla search
1430 @cindex case-sensitive search
1431 @cindex case-insensitive search
1433 @item M-p and M-n
1434 @kindex @kbd{M-p}
1435 @kindex @kbd{M-n}
1436 In the Minibuffer, these commands navigate through the minibuffer
1437 histories, such as the history of search strings, Ex commands, etc.
1439 @item C-c M-p and C-c M-n
1440 @kindex @kbd{C-c M-p}
1441 @kindex @kbd{C-c M-n}
1442 @cindex Insertion history
1443 @cindex Insertion ring
1444 @cindex Command history
1445 @cindex Command ring
1447 In Insert or Replace state, these commands let  the user
1448 peruse the history of insertion strings used in previous insert or replace
1449 commands.  Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what
1450 happens.  @xref{Viper Specials}, for more.
1452 In Vi state, these commands let the user peruse the history of Vi-style
1453 destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc.
1454 By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper
1455 through the recent history of Vi commands, displaying the commands one by
1456 one.  Once
1457 an appropriate command is found, it can be executed by typing `@kbd{.}'.
1459 Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an
1460 appropriate function to a function key on the keyboard and use that key.
1461 @xref{Viper Specials}, for details.
1463 @item Ex commands
1464 @findex  @kbd{:args}
1465 @findex  @kbd{:n}
1466 @findex  @kbd{:pwd}
1467 @findex  @kbd{:pre}
1468 The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave
1469 differently.  @kbd{:pwd} exists to get current directory.
1470 The commands @kbd{:b} and @kbd{:B} switch buffers around.  @xref{File and
1471 Buffer Handling}, for details.
1472 There are also the new commands @kbd{:RelatedFile} and
1473 @kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P},
1474 respectively.  @xref{Viper Specials}, for details.
1475 @findex @kbd{:RelatedFile}
1476 @findex @kbd{:PreviousRelatedFile}
1477 @end table
1479 Apart from the new commands, many old commands have been enhanced.  Most
1480 notably, Vi style macros are much more powerful in Viper than in Vi.  @xref{Vi
1481 Macros}, for details.
1483 @node Useful Packages, ,New Commands, Improvements over Vi
1484 @section Useful Packages
1486 Some Emacs packages are mentioned here as an aid to the new Viper user, to
1487 indicate what Viper is capable of.
1488 A vast number comes with the standard Emacs distribution, and many more exist
1489 on the net and on the archives.
1491 This manual also mentions some Emacs features a new user
1492 should know about.  The details of these are found in the GNU Emacs
1493 Manual.
1495 The features first.  For details, look up the Emacs Manual.
1497 @table @samp
1498 @item Make
1499 @cindex make
1500 @cindex compiling
1502 Makes and Compiles can be done from the editor.  Error messages will be
1503 parsed and you can move to the error lines.
1504 @item Shell
1505 @cindex shell
1506 @cindex interactive shell
1507 You can talk to Shells from inside the editor.  Your entire shell session
1508 can be treated as a file.
1509 @item Mail
1510 @cindex email
1511 @cindex mail
1512 Mail can be read from and sent within the editor.  Several sophisticated
1513 packages exist.
1514 @item Language Sensitive Editing
1515 Editing modes are written for most computer languages in existence.  By
1516 controlling indentation, they catch punctuation errors.
1517 @end table
1519 The packages, below, represents a drop in the sea of special-purpose
1520 packages that come with standard distribution of Emacs.
1522 @table @samp
1523 @item Transparent FTP
1524 @cindex transparent ftp
1525 @pindex ange-ftp.el
1526 @code{ange-ftp.el} can ftp from the editor to files on other machines
1527 transparent to the user.
1528 @item RCS Interfaces
1529 @cindex version maintenance
1530 @cindex RCS
1531 @pindex vc.el
1532 @code{vc.el} for doing RCS commands from inside the editor
1533 @item Directory Editor
1534 @cindex dired
1535 @pindex dired.el
1536 @code{dired.el} for editing contents of directories and for navigating in
1537 the file system.
1538 @item Syntactic Highlighting
1539 @cindex font-lock
1540 @pindex font-lock.el
1541 @code{font-lock.el} for automatic highlighting various parts of a buffer
1542 using different fonts and colors.
1543 @item Saving Emacs Configuration
1544 @cindex desktop
1545 @pindex desktop.el
1546 @code{desktop.el} for saving/restoring configuration on Emacs exit/startup.
1547 @item Spell Checker
1548 @cindex ispell
1549 @pindex ispell.el
1550 @code{ispell.el} for spell checking the buffer, words, regions, etc.
1551 @item File and Buffer Comparison
1552 @cindex ediff
1553 @pindex ediff.el
1554 @code{ediff.el} for finding differences between files and for applying
1555 patches.
1556 @end table
1558 @noindent
1559 Emacs Lisp archives exist on
1560 @samp{archive.cis.ohio-state.edu}
1561 and @samp{wuarchive.wustl.edu}@refill
1564 @node Customization,Commands,Improvements over Vi,Top
1565 @chapter Customization
1567 @cindex customization
1569 Customization can be done in 2 ways.
1571 @itemize @bullet
1572 @item
1573 @cindex initialization
1574 @cindex .viper
1575 Elisp code in a @file{.viper} file in your home directory.  Viper
1576 loads @file{.viper} just before it does the binding for mode
1577 hooks.  This is recommended for experts only.
1578 @item
1579 @cindex .emacs
1580 Elisp code in your @file{.emacs} file before and after the @code{(require
1581 'viper)} line.  This method is @emph{not} recommended, unless you know what
1582 you are doing.  Only two variables, @code{viper-mode} and
1583 @code{viper-custom-file-name}, are supposed to be customized in @file{.emacs},
1584 prior to loading Viper (i.e., prior to @code{(require 'viper)} command.@refill
1585 @item
1586 @cindex :customize
1587 By executing the @kbd{:customize} Ex command. This takes you to the Emacs
1588 customization widget, which lets you change the values of Viper
1589 customizable variables easily. This method is good for novice and
1590 experts alike. The customization code in the form of Lisp commands will be
1591 placed in @file{~/.emacs} or some other customization file depending on the
1592 version of Emacs that you use. Still, it is recommended to separate
1593 Viper-related customization produced by the Emacs customization widget
1594 and keep it in the @file{.viper} file.
1596 Some advanced customization cannot be accomplished this way, however, and
1597 has to be done in Emacs Lisp in the @file{.viper} file.  For the common
1598 cases, examples are provided that you can use directly.
1599 @end itemize
1602 @menu
1603 * Rudimentary Changes::          Simple constant definitions.
1604 * Key Bindings::                 Enabling Emacs Keys, Rebinding keys, etc.
1605 * Packages that Change Keymaps:: How to deal with such beasts.
1606 * Viper Specials::               Special Viper commands.
1607 * Vi Macros::                    How to do Vi style macros.
1608 @end menu
1610 @node Rudimentary Changes,Key Bindings,Customization,Customization
1611 @section Rudimentary Changes
1613 @cindex setting variables
1614 @cindex variables for customization
1615 @findex @kbd{:set}
1617 An easy way to customize Viper is to change the values of constants used in
1618 Viper.  Here is the list of the constants used in Viper and their default
1619 values.  The corresponding :se command is also indicated.  (The symbols
1620 @code{t} and @code{nil} represent ``true'' and ``false'' in Lisp).
1622 Viper supports both the abbreviated Vi variable names and their full
1623 names.  Variable completion is done on full names only.  @key{TAB} and
1624 @key{SPC} complete
1625 variable names.  Typing `=' will complete the name and then will prompt for
1626 a value, if applicable.  For instance, @kbd{:se au @key{SPC}} will complete the
1627 command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command
1628 and prompt further like this: @kbd{:set tabstop = }.
1629 However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message
1630 because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports
1631 completion on full names only.  However, you can still hit @key{RET}
1632 or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and
1633 Viper will be waiting for you to type a value for the tabstop variable.
1634 To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}.
1636 @table @code
1637 @item viper-auto-indent nil
1638 @itemx :se ai (:se autoindent)
1639 @itemx :se ai-g (:se autoindent-global)
1640 If @code{t}, enable auto indentation.
1641 by @key{RET}, @kbd{o} or @kbd{O} command.
1643 @code{viper-auto-indent} is a local variable.  To change the value globally, use
1644 @code{setq-default}.  It may be useful for certain major modes to have their
1645 own values of @code{viper-auto-indent}.  This can be achieved by using
1646 @code{setq} to change the local value of this variable in the hooks to the
1647 appropriate major modes.
1649 @kbd{:se ai} changes the value of @code{viper-auto-indent} in the current
1650 buffer only; @kbd{:se ai-g} does the same globally.
1651 @item viper-electric-mode t
1652 If not @code{nil}, auto-indentation becomes electric, which means that
1653 @key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current
1654 major mode.  In the future, this variable may control additional electric
1655 features.
1657 This is a local variable: @code{setq} changes the value of this variable
1658 in the current buffer only.  Use @code{setq-default} to change the value in
1659 all buffers.
1660 @item viper-case-fold-search nil
1661 @itemx :se ic (:se ignorecase)
1662 If not @code{nil}, search ignores cases.
1663 This can also be toggled by quickly hitting @kbd{/} twice.
1664 @item viper-re-search nil
1665 @itemx :se magic
1666 If not @code{nil}, search will use regular expressions; if @code{nil} then
1667 use vanilla search.
1668 This behavior can also be toggled by quickly hitting @kbd{/} trice.
1669 @item buffer-read-only
1670 @itemx :se ro (:se readonly)
1671 Set current buffer to read only.  To change globally put
1672 @code{(setq-default buffer-read-only t)} in your @file{.emacs} file.
1673 @item blink-matching-paren t
1674 @itemx :se sm (:se showmatch)
1675 Show matching parens by blinking cursor.
1676 @item tab-width t (default setting via @code{setq-default})
1677 @itemx :se ts=value (:se tabstop=value)
1678 @itemx :se ts-g=value (:se tabstop-global=value)
1679 @code{tab-width} is a local variable that controls the width of the tab stops.
1680 To change the value globally, use @code{setq-default}; for local settings,
1681 use @code{setq}.
1683 The command @kbd{:se ts}
1684 sets the tab width in the current
1685 buffer only; it has no effect on other buffers.
1687 The command @kbd{:se ts-g} sets tab width globally,
1688 for all buffers where the tab is not yet set locally,
1689 including the new buffers.
1691 Note that typing @key{TAB} normally
1692 doesn't insert the tab, since this key is usually bound to
1693 a text-formatting function, @code{indent-for-tab-command} (which facilitates
1694 programming and document writing).  Instead, the tab is inserted via the
1695 command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab).
1697 On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so
1698 @kbd{S-tab} behaves as if it were @key{TAB}.  In such a case, you will have
1699 to bind @code{viper-insert-tab} to some other convenient key.
1701 @item viper-shift-width 8
1702 @itemx :se sw=value  (:se shiftwidth=value)
1703 The number of columns shifted by @kbd{>} and @kbd{<} commands.
1704 @item viper-search-wrap-around t
1705 @itemx :se ws (:se wrapscan)
1706 If not @code{nil}, search wraps around the end/beginning of buffer.
1707 @item viper-search-scroll-threshold 2
1708 If search lands within this many lines of the window top or bottom, the
1709 window will be scrolled up or down by about 1/7-th of its size, to reveal
1710 the context.  If the value is negative---don't scroll.
1711 @item viper-tags-file-name "TAGS"
1712 The name of the file used as the tag table.
1713 @item viper-re-query-replace nil
1714 If not @code{nil}, use reg-exp replace in query replace.
1715 @item viper-want-ctl-h-help nil
1716 If not @code{nil}, @kbd{C-h} is bound to @code{help-command};
1717 otherwise, @kbd{C-h} is bound as usual in Vi.
1718 @item viper-vi-style-in-minibuffer t
1719 If not @code{nil}, Viper provides a high degree of compatibility with Vi
1720 insert mode when you type text in the Minibuffer; if @code{nil}, typing in
1721 the Minibuffer feels like plain Emacs.
1722 @item viper-no-multiple-ESC t
1723 If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state.
1724 Normally, this is not necessary, since graphical displays have separate
1725 Meta keys (usually on each side of the space bar).  On a dumb terminal, Viper
1726 sets this variable to @code{twice}, which is almost like @code{nil}, except
1727 that double @key{ESC} beeps.  This, too, lets @key{ESC} to be used as a Meta.
1728 @item viper-ESC-keyseq-timeout 200 on tty, 0 on windowing display
1729 Escape key sequences separated by this much delay (in milliseconds) are
1730 interpreted as command, ignoring the special meaning of @key{ESC} in
1731 VI.  The default is suitable for most terminals.  However, if your terminal
1732 is extremely slow, you might want to increase this slightly.  You will know
1733 if your terminal is slow if the @key{ESC} key sequences emitted by the
1734 arrow keys are interpreted as separately typed characters (and thus the
1735 arrow keys won't work).  Making this value too large will slow you down, so
1736 exercise restraint.
1737 @item viper-fast-keyseq-timeout 200
1738 Key sequences separated by this many milliseconds are treated as Vi-style
1739 keyboard macros.  If the key sequence is defined as such a macro, it will be
1740 executed.  Otherwise, it is processed as an ordinary sequence of typed keys.
1742 Setting this variable too high may slow down your typing.  Setting it too
1743 low may make it hard to type macros quickly enough.
1744 @item viper-translate-all-ESC-keysequences @code{t} on tty, @code{nil} on windowing display
1745 Normally, Viper lets Emacs translate only those ESC key sequences that are
1746 defined in the low-level key-translation-map or function-key-map, such as those
1747 emitted by the arrow and function keys. Other sequences, e.g., @kbd{\\e/}, are
1748 treated as @kbd{ESC} command followed by a @kbd{/}. This is good for people
1749 who type fast and tend to hit other characters right after they hit
1750 ESC. Other people like Emacs to translate @kbd{ESC} sequences all the time.
1751 The default is to translate all sequences only when using a dumb terminal.
1752 This permits you to use @kbd{ESC} as a meta key in insert mode. For instance,
1753 hitting @kbd{ESC x} fast would have the effect of typing @kbd{M-x}.
1754 If your dumb terminal is not so dumb and understands the meta key, then you
1755 probably will be better off setting this variable to @code{nil}. Try and see which
1756 way suits you best.
1757 @item viper-ex-style-motion t
1758 Set this to @code{nil}, if you want @kbd{l,h} to cross
1759 lines, etc.  @xref{Movement and Markers}, for more info.
1760 @item viper-ex-style-editing t
1761 Set this to @code{nil}, if you want
1762 @kbd{C-h} and @key{DEL} to not stop
1763 at the beginning of a line in Insert state, @key{X} and @key{x} to delete
1764 characters across lines in Vi command state, etc.
1765 @item viper-ESC-moves-cursor-back t
1766 It @code{t}, cursor moves back 1 character when switching from insert state to vi
1767 state.  If @code{nil}, the cursor stays where it was before the switch.
1768 @item viper-always t
1769 @code{t} means: leave it to Viper to decide when a buffer must be brought
1770 up in Vi state,
1771 Insert state, or Emacs state.  This heuristics works well in virtually all
1772 cases.  @code{nil} means you either has to invoke @code{viper-mode} manually
1773 for each buffer (or you can add @code{viper-mode} to the appropriate major mode
1774 hooks using @code{viper-load-hook}).
1776 This option must be set in the file @file{~/.viper}.
1777 @item viper-custom-file-name "~/.viper"
1778 File used for Viper-specific customization.
1779 Change this setting, if you want.  Must be set in @file{.emacs} (not @file{.viper}!)
1780 before Viper is loaded.  Note that you
1781 have to set it as a string inside double quotes.
1782 @item viper-spell-function 'ispell-region
1783 Function used by the command @kbd{#c<move>} to spell.
1784 @item viper-glob-function
1785 The value of this variable is the function symbol used to expand wildcard
1786 symbols. This is platform-dependent. The default tries to set this variable
1787 to work with most shells, MS Windows, OS/2, etc. However, if it
1788 doesn't work the way you expect, you should write your own.
1789 Use @code{viper-glob-unix-files} and @code{viper-glob-mswindows-files} in
1790 @file{viper-util.el} as examples.
1792 This feature is used to expand wildcards in the Ex command @kbd{:e}.
1793 Note that Viper doesn't support wildcards in the @kbd{:r} and @kbd{:w}
1794 commands, because file completion is a better mechanism.
1795 @findex @code{viper-glob-function}
1797 @item ex-cycle-other-window t
1798 If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another
1799 window, if one exists.
1800 @item ex-cycle-through-non-files nil
1801 @kbd{:n} does not normally cycle through buffers.  Set this to get
1802 buffers also.
1803 @item viper-want-emacs-keys-in-insert
1804 This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user
1805 levels 3 and 4.  Users who specify level 5 are allowed to set this variable
1806 as they please (the default for this level is @code{t}).  If set to
1807 @code{nil}, complete Vi compatibility is provided in Insert state.  This is
1808 really not recommended, as this precludes you from using language-specific
1809 features provided by the major modes.
1810 @item viper-want-emacs-keys-in-vi
1811 This is set to @code{nil} for user
1812 level 1 and to @code{t} for user levels 2--4.
1813 At level 5, users are allowed to set this variable as they please (the
1814 default for this level is @code{t}).
1815 If set to @code{nil}, complete Vi compatibility is provided
1816 in Vi command state.  Setting this to @code{nil} is really a bad idea,
1817 unless you are a novice, as this precludes the use
1818 of language-specific features provided by the major modes.
1819 @item viper-keep-point-on-repeat t
1820 If not @code{nil}, point is not moved when the user repeats the previous
1821 command by typing `.'  This is very useful for doing repeated changes with
1822 the @kbd{.} key.
1823 @item viper-repeat-from-history-key 'f12
1824 Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat
1825 the second-last and the third-last destructive command.
1826 Both these macros are bound (as Viper macros) to
1827 @code{viper-repeat-from-history},
1828 which checks the second key by which it is invoked to see which of the
1829 previous commands to invoke.  Viper binds @kbd{f12 1} and @kbd{f12 2} only,
1830 but the user can bind more in @file{~/.viper}.  @xref{Vi Macros}, for how to do
1831 this.
1832 @item viper-keep-point-on-undo nil
1833 If not @code{nil}, Viper tries to not move point when undoing commands.
1834 Instead, it will briefly move the cursor to the place where change has
1835 taken place.  However, if the undone piece of text is not seen in window,
1836 then point will be moved to the place where the change took place.
1837 Set it to @code{t} and see if you like it better.
1838 @item viper-delete-backwards-in-replace nil
1839 If not @code{nil}, @key{DEL} key will delete characters while moving the cursor
1840 backwards.  If @code{nil}, the cursor will move backwards without deleting
1841 anything.
1842 @item viper-replace-overlay-face 'viper-replace-overlay-face
1843 On a graphical display, Viper highlights replacement regions instead of
1844 putting a @samp{$} at the end.  This variable controls the so called
1845 @dfn{face} used to highlight the region.
1847 By default, @code{viper-replace-overlay-face} underlines the replacement on
1848 monochrome displays and also lays a stipple over them.  On color displays,
1849 replacement regions are highlighted with color.
1851 If you know something about Emacs faces and don't like how Viper highlights
1852 replacement regions, you can change @code{viper-replace-overlay-face} by
1853 specifying a new face.  (Emacs faces are described in the Emacs Lisp
1854 reference.)  On a color display, the following customization method is
1855 usually most effective:
1856 @example
1857 (set-face-foreground viper-replace-overlay-face "DarkSlateBlue")
1858 (set-face-background viper-replace-overlay-face "yellow")
1859 @end example
1860 For a complete list of colors available to you, evaluate the expression
1861 @code{(x-defined-colors)}.  (Type it in the buffer @code{*scratch*} and then
1862 hit the @kbd{C-j} key.
1864 @item viper-replace-overlay-cursor-color  "Red"
1865 @vindex @code{viper-replace-overlay-cursor-color}
1866 Cursor color when it is inside the replacement region.
1867 This has effect only on color displays and only when Emacs runs as an X
1868 application.
1869 @item viper-insert-state-cursor-color nil
1870 @vindex @code{viper-insert-state-cursor-color}
1871 If set to a valid color, this will be the cursor color when Viper is in
1872 insert state.
1873 @item viper-replace-region-end-delimiter "$"
1874 A string used to mark the end of replacement regions.  It is used only on
1875 TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}.
1876 @item viper-replace-region-start-delimiter  ""
1877 A string used to mark the beginning of replacement regions.  It is used
1878 only on TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}.
1879 @item viper-use-replace-region-delimiters
1880 If non-@code{nil}, Viper will always use @code{viper-replace-region-end-delimiter} and
1881 @code{viper-replace-region-start-delimiter} to delimit replacement regions,
1882 even on color displays (where this is unnecessary).  By default, this
1883 variable is non-@code{nil} only on TTYs or monochrome displays.
1884 @item viper-allow-multiline-replace-regions t
1885 If non-@code{nil}, multi-line text replacement regions, such as those produced by
1886 commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits
1887 the replacement mode.  In this variable is set to @code{nil}, Viper will
1888 emulate the standard Vi behavior, which supports only intra-line
1889 replacement regions (and multi-line replacement regions are deleted).
1890 @item viper-toggle-key "\C-z"
1891 Specifies the key used to switch from Emacs to Vi and back.
1892 Must be set in @file{.viper}.  This variable can't be
1893 changed interactively after Viper is loaded.
1895 In Insert state, this key acts as a temporary escape to Vi state, i.e., it
1896 will set Viper up so that the very next command will be executed as if it
1897 were typed in Vi state.
1898 @item viper-ESC-key "\e"
1899 Specifies the key used to escape from Insert/Replace states to Vi.
1900 Must be set in @file{.viper}.  This variable cannot be
1901 changed interactively after Viper is loaded.
1902 @item viper-buffer-search-char nil
1903 Key used for buffer search.  @xref{Viper Specials}, for details.
1904 @item viper-surrounding-word-function 'viper-surrounding-word
1905 The value of this variable is a function name that is used to determine
1906 what constitutes a word clicked upon by the mouse.  This is used by mouse
1907 search and insert.
1908 @item viper-search-face 'viper-search-face
1909 Variable that controls how search patterns are highlighted when they are
1910 found.
1911 @item viper-vi-state-hook nil
1912 List of parameterless functions to be run just after entering the Vi
1913 command state.
1914 @item viper-insert-state-hook nil
1915 Same for Insert state.  This hook is also run after entering Replace state.
1916 @item viper-replace-state-hook  nil
1917 List of (parameterless) functions called just after entering Replace state
1918 (and after all @code{viper-insert-state-hook}).
1919 @item viper-emacs-state-hook nil
1920 List of (parameterless) functions called just after switching from Vi state
1921 to Emacs state.
1922 @item viper-load-hook nil
1923 List of (parameterless) functions called just after loading Viper.  This is
1924 the last chance to do customization before Viper is up and running.
1925 @end table
1926 @noindent
1927 You can reset some of these constants in Viper with the Ex command @kbd{:set}
1928 (when so indicated in the table).  Or you
1929 can include a line like this in your @file{.viper} file:
1930 @example
1931 (setq viper-case-fold-search t)
1932 @end example
1933 @vindex @code{viper-auto-indent}
1934 @vindex @code{viper-electric-mode}
1935 @vindex @code{viper-case-fold-search}
1936 @vindex @code{viper-re-search}
1937 @vindex @code{viper-shift-width}
1938 @vindex @code{buffer-read-only}
1939 @vindex @code{viper-search-wrap-around}
1940 @vindex @code{viper-search-scroll-threshold}
1941 @vindex @code{viper-search-face}
1942 @vindex @code{viper-tags-file-name}
1943 @vindex @code{viper-re-query-replace}
1944 @vindex @code{viper-want-ctl-h-help}
1945 @vindex @code{viper-vi-style-in-minibuffer}
1946 @vindex @code{viper-no-multiple-ESC}
1947 @vindex @code{viper-always}
1948 @vindex @code{viper-ESC-keyseq-timeout}
1949 @vindex @code{viper-fast-keyseq-timeout}
1950 @vindex @code{viper-ex-style-motion}
1951 @vindex @code{viper-ex-style-editing}
1952 @vindex @code{viper-ESC-moves-cursor-back}
1953 @vindex @code{viper-custom-file-name}
1954 @vindex @code{viper-spell-function}
1955 @vindex @code{ex-cycle-other-window}
1956 @vindex @code{ex-cycle-through-non-files}
1957 @vindex @code{viper-want-emacs-keys-in-insert}
1958 @vindex @code{viper-want-emacs-keys-in-vi}
1959 @vindex @code{viper-keep-point-on-repeat}
1960 @vindex @code{viper-keep-point-on-undo}
1961 @vindex @code{viper-delete-backwards-in-replace}
1962 @vindex @code{viper-replace-overlay-face}
1963 @vindex @code{viper-replace-region-end-symbol}
1964 @vindex @code{viper-replace-region-start-symbol}
1965 @vindex @code{viper-allow-multiline-replace-regions}
1966 @vindex @code{viper-toggle-key}
1967 @vindex @code{viper-ESC-key}
1968 @vindex @code{viper-buffer-search-char}
1969 @vindex @code{viper-surrounding-word-function}
1970 @vindex @code{viper-vi-state-hook}
1971 @vindex @code{viper-insert-state-hook}
1972 @vindex @code{viper-replace-state-hook}
1973 @vindex @code{viper-emacs-state-hook}
1975 @node Key Bindings, Packages that Change Keymaps, Rudimentary Changes,Customization
1976 @section Key Bindings
1978 @cindex key bindings
1979 @cindex keymaps
1981 Viper lets you define hot keys, i.e., you can associate keyboard keys
1982 such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already
1983 exist or that you will write).  Each key has a "preferred form" in
1984 Emacs.  For instance, the Up key's preferred form is [up], the Help key's
1985 preferred form is [help], and the Undo key has the preferred form [f14].
1986 You can find out the preferred form of a key by typing @kbd{M-x
1987 describe-key-briefly} and then typing the key you want to know about.
1989 Under the X Window System, every keyboard key emits its preferred form,
1990 so you can just type
1992 @lisp
1993 (global-set-key [f11] 'calendar)                        ; L1, Stop
1994 (global-set-key [f14] 'undo)                            ; L4, Undo
1995 @end lisp
1997 @noindent
1998 to bind L1 (a key that exists on some SUN workstations) so it will invoke
1999 the Emacs Calendar and to bind L4 so it will undo changes.
2000 However, on a dumb terminal or in an Xterm window, even the standard arrow
2001 keys may
2002 not emit the right signals for Emacs to understand.  To let Emacs know about
2003 those keys, you will have to find out which key sequences they emit
2004 by typing @kbd{C-q} and then the key (you should switch to Emacs state
2005 first).  Then you can bind those sequences to their preferred forms using
2006 @code{function-key-map} as follows:
2008 @lisp
2009 (cond ((string= (getenv "TERM") "xterm")
2010 (define-key function-key-map "\e[192z" [f11])    ; L1
2011 (define-key function-key-map "\e[195z" [f14])    ; L4, Undo
2012 @end lisp
2014 The above illustrates how to do this for Xterm.  On VT100, you would have to
2015 replace "xterm" with "vt100" and also change the key sequences (the same
2016 key may emit different sequences on different types of terminals).
2018 The above keys are global, so they are overwritten by the local maps
2019 defined by the major modes and by Viper itself.  Therefore, if you wish to
2020 change a binding set by a major mode or by Viper, read this.
2022 Viper users who wish to specify their own key bindings should be concerned
2023 only with the following three keymaps:
2024 @code{viper-vi-global-user-map} for Vi state commands,
2025 @code{viper-insert-global-user-map} for Insert state commands,
2026 and @code{viper-emacs-global-user-map} for Emacs state commands (note:
2027 customized bindings for Emacs state made to @code{viper-emacs-global-user-map}
2028 are @emph{not} inherited by Insert state).
2030 For more information on Viper keymaps, see the header of the file
2031 @file{viper.el}.
2032 If you wish to change a Viper binding, you can use the
2033 @code{define-key} command, to modify @code{viper-vi-global-user-map},
2034 @code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as
2035 explained below.  Each of these key maps affects the corresponding Viper state.
2036 The keymap @code{viper-insert-global-user-map} also affects Viper's Replace
2037 state.
2039 @noindent
2040 If you want to
2041 bind a key, say @kbd{C-v}, to the function that scrolls
2042 page down and to make @kbd{0} display information on the current buffer,
2043 putting this in @file{.viper} will do the trick in Vi state:
2044 @example
2045 (define-key viper-vi-global-user-map "\C-v" 'scroll-down)
2046 @end example
2047 @noindent
2048 To set a key globally,
2049 @example
2050 (define-key viper-emacs-global-user-map "\C-c m" 'smail)
2051 (define-key viper-vi-global-user-map "0" 'viper-info-on-file)
2052 @end example
2053 @noindent
2054 Note, however, that this binding may be overwritten by other keymaps, since
2055 the global keymap has the lowest priority.
2056 To make sure that nothing will override a binding in Emacs state, you
2057 can write this:
2058 @example
2059 (define-key viper-emacs-global-user-map "\C-c m" 'smail)
2060 @end example
2061 @noindent
2062 To customize the binding for @kbd{C-h} in Insert state:
2063 @example
2064 (define-key viper-insert-global-user-map "\C-h" 'my-del-backwards-function)
2065 @end example
2066 @noindent
2068 Each Emacs command key calls some Lisp function.  If you have enabled the
2069 Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function
2070 for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m}
2071 will provide information on the major mode in effect.  If Help is not
2072 enabled, you can still get help in Vi state by prefixing the above commands
2073 with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the
2074 menu bar, if Emacs runs under X).
2076 Viper users can also change bindings on a per major mode basis.  As with
2077 global bindings, this can be done separately for each of the three main Viper
2078 states.  To this end, Viper provides the function
2079 @code{viper-modify-major-mode}.
2080 @findex @code{viper-modify-major-mode}
2082 To modify keys in Emacs state for @code{my-favorite-major-mode}, the user
2083 needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever
2084 keys necessary in that keymap, and put
2086 @example
2087 (viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map)
2088 @end example
2090 @noindent
2091 in @file{~/.viper}.  To do the same in Vi and Insert states, you should use
2092 @code{vi-state} and @code{insert-state}.  Changes in Insert state are also
2093 in effect in Replace state.  For instance, suppose that the user wants to
2094 use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark
2095 files, etc.  The following code in @file{~/.viper} will then do the job:
2097 @example
2098 (setq my-dired-modifier-map (make-sparse-keymap))
2099 (define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion)
2100 (define-key my-dired-modifier-map "u" 'dired-unmark)
2101 (viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map)
2102 @end example
2104 A Vi purist may want to modify Emacs state under Dired mode so that
2105 @kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in
2106 Vi.  Although this is not recommended, as these keys are bound to useful
2107 Dired functions, the trick can be accomplished via the following code:
2109 @example
2110 (setq my-dired-vi-purist-map (make-sparse-keymap))
2111 (define-key my-dired-vi-purist-map "k" 'viper-previous-line)
2112 (define-key my-dired-vi-purist-map "l" 'viper-forward-char)
2113 (viper-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map)
2114 @end example
2116 Yet another way to customize key bindings in a major mode is to edit the
2117 list @code{viper-major-mode-modifier-list} using the customization widget.
2118 @vindex @code{viper-major-mode-modifier-list}
2119 (This variable is in the Viper-misc customization group.)
2120 The elements of this list are triples of the form: (major-mode viper-state
2121 keymap), where the keymap contains bindings that are supposed to be active
2122 in the given major mode and the given viper-state.
2124 Effects similar to key binding changes can be achieved by defining Vi
2125 keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}.  The
2126 difference is that multi-key Vi macros do not override the keys they are
2127 bound to, unless these keys are typed in quick succession.  So, with macros,
2128 one can use the normal keys alongside with the macros.  If per-mode
2129 modifications are needed, the user can try both ways and see which one is
2130 more convenient.
2131 @findex @kbd{:map}
2132 @xref{Vi Macros}, for details.
2134 Note: in major modes that come up in @emph{Emacs state} by default, the
2135 aforesaid modifications may not take place immediately (but only after the
2136 buffer switches to some other Viper state and then back to Emacs state).  To
2137 avoid this, one should add @code{viper-change-state-to-emacs} to an
2138 appropriate hook of that major mode.  (Check the function
2139 @code{viper-set-hooks} in @file{viper.el} for examples.)  However, if you
2140 did not set @code{viper-always} to @code{nil}, chances are that you won't
2141 need to perform the above procedure, because Viper will take care of most
2142 useful defaults.
2145 Finally, Viper has a facility that lets the user define per-buffer
2146 bindings, i.e., bindings that are in effect in some specific buffers
2147 only.  Unlike per-mode bindings described above, per-buffer bindings can be
2148 defined based on considerations other than the major mode.  This is done
2149 via the function @code{viper-add-local-keys}, which lets one specify bindings
2150 that should be in effect in the current buffer only and for a specific Viper
2151 state.  For instance,
2152 @lisp
2153 (viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master)
2154                                  ("ZQ" .@: viper-save-kill-buffer)))
2155 @end lisp
2156 @noindent
2157 redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state}
2158 and @kbd{ZQ} to save-then-kill the current buffer.  These bindings take
2159 effect only in the buffer where this command is executed.  The typical use
2160 of this function is to execute the above expression from within a function
2161 that is included in a hook to some major mode.  For instance, the above
2162 expression
2163 could be called from a function, @code{my-tex-init}, which may be added to
2164 @code{tex-mode-hook} as follows:
2165 @lisp
2166 (add-hook 'tex-mode-hook 'my-tex-init)
2167 @end lisp
2168 @noindent
2169 When TeX mode starts, the hook is executed and the above Lisp expression is
2170 evaluated.  Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi
2171 command mode for all buffers in TeX mode.
2173 Another useful application is to bind @kbd{ZZ} to @code{send-mail}
2174 in the Mail mode buffers (the specifics of this depend on which mail
2175 package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc.
2176 For instance, here is how to do this for @code{mh-e}, the Emacs interface
2177 to MH:
2178 @lisp
2179 (defun mh-add-vi-keys ()
2180   "Set up ZZ for MH-e and XMH."
2181   (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter))))
2182 (add-hook 'mh-letter-mode-hook 'mh-add-vi-keys)
2183 @end lisp
2185 You can also use @code{viper-add-local-keys} to set per buffer
2186 bindings in Insert state and Emacs state by passing as a parameter the
2187 symbols @code{insert-state} and @code{emacs-state}, respectively.
2188 As with global bindings, customized local bindings done to Emacs state
2189 are not inherited by Insert state.
2191 On rare occasions, local keys may be added by mistake.  Usually this is done
2192 indirectly, by invoking a major mode that adds local keys (e.g.,
2193 @code{shell-mode} redefines @key{RET}).  In such a case, exiting the wrong
2194 major mode won't rid you from unwanted local keys, since these keys are
2195 local to Viper state and the current buffer, not to the major mode.
2196 In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}.
2198 So much about Viper-specific bindings.
2199 @xref{Customization,,Customization,emacs,The GNU Emacs
2200 Manual}, and the Emacs quick reference card for the general info on key
2201 bindings in Emacs.
2203 @vindex @code{function-key-map}
2204 @vindex @code{viper-vi-global-user-map}
2205 @vindex @code{viper-insert-global-user-map}
2206 @vindex @code{viper-emacs-global-user-map}
2207 @findex @code{viper-add-local-keys}
2208 @findex @code{viper-zap-local-keys}
2210 @node Packages that Change Keymaps,Viper Specials,Key Bindings,Customization
2211 @subsection Packages that Change Keymaps
2212 @cindex C-c and Viper
2213 @cindex Viper and C-c
2215 Viper is designed to coexist with all major and minor modes of Emacs.  This
2216 means that bindings set by those modes are generally available with Viper
2217 (unless you explicitly prohibit them by setting
2218 @code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to
2219 @code{nil}).
2220 If @code{viper-always} is set to @code{t} (which is the default), Viper
2221 will try to bring each buffer
2222 in the Viper state that is most appropriate for that buffer.
2223 Usually, this would be the Vi state, but sometimes it could be the Insert
2224 state or the Emacs state.
2226 Some major mode bindings will necessarily be overwritten by Viper.  Indeed, in
2227 Vi state, most of the 1-character keys are used for Vi-style editing.  This
2228 usually causes no problems because most packages designed for editing files
2229 typically do not bind such keys.  Instead, they use key sequences that start
2230 with @kbd{C-x} and @kbd{C-c}.  This is why it was so important for us to
2231 free up @kbd{C-x} and @kbd{C-c}.
2232 It is common for language-specific major modes to bind @key{TAB} and
2233 @kbd{C-j} (the line feed) keys to various formatting functions.  This is
2234 extremely useful, but may require some getting used to for a Vi user.  If you
2235 decide that this feature is not for you, you can re-bind these keys as
2236 explained earlier (@pxref{Customization}).
2238 Binding for @key{TAB} is one of the most unusual aspects of Viper for many
2239 novice users.  In Emacs, @key{TAB} is used to format text and programs, and
2240 is extremely useful.  For instance, hitting @key{TAB} causes the current
2241 line to be re-indented in accordance with the context.  In programming,
2242 this is very important, since improper automatic indentation would
2243 immediately alert the programmer to a possible error.  For instance, if a
2244 @kbd{)} or a @kbd{"} is missing somewhere above the current
2245 line, @key{TAB} is likely to mis-indent the line.
2247 For this reason, Viper doesn't change the standard Emacs binding of
2248 @key{TAB}, thereby sacrificing Vi compatibility
2249 (except for users at level 1).  Instead, in Viper, the key
2250 @kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}.
2252 We should note that on some non-windowing terminals, Shift doesn't modify
2253 the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}.  In such
2254 a case, you will have to bind @code{viper-insert-tab} to some other
2255 convenient key.
2257 Some packages, notably Dired, Gnus, Info, etc., attach special meaning to
2258 common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others.  This
2259 means that Vi command state is inappropriate for working with these
2260 packages.  Fortunately, these modes operate on read-only buffers and are
2261 designed not for editing files, but for special-purpose browsing, reading
2262 news, mail, etc., and Vi commands are meaningless in these situations.  For
2263 this reason, Viper doesn't force Vi state on such major modes---it
2264 brings them in Emacs state.  You can switch to Vi state by typing @kbd{C-z}
2265 if, for instance, you want to do Vi-style search in a buffer (although,
2266 usually, incremental search, which is bound to @kbd{C-s}, is sufficient in
2267 these situations).  But you should then switch back to Emacs state if you
2268 plan to continue using these major modes productively.  You can also switch
2269 to Vi temporarily, to execute just one command.  This is done by typing
2270 @kbd{C-c \}.  (In some of these modes, @kbd{/} and @kbd{:} are bound
2271 Vi-style, unless these keys perform essential duties.)
2273 If you would like certain major modes to come up in Emacs state rather than
2274 Vi state (but Viper thinks otherwise), you should put these major modes
2275 on the @code{viper-emacs-state-mode-list} list and delete them from
2276 @code{viper-vi-state-mode-list}.
2277 Likewise, you can force Viper's Insert state on a major mode by putting it
2278 in @code{viper-insert-state-mode-list}.
2279 @vindex @code{viper-emacs-state-mode-list}
2280 @vindex @code{viper-insert-state-mode-list}
2281 @vindex @code{viper-vi-state-mode-list}
2283 It is also possible to impose Vi on some major modes, even though they may
2284 bind common keys to specialized commands.  This might make sense for modes
2285 that bind only a small number of common keys.  For instance, Viper subverts
2286 the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using
2287 @code{viper-add-local-keys} described in the section on customization
2288 (@pxref{Customization}).
2290 In some cases, some @emph{minor} modes might override certain essential
2291 bindings in Vi command state.  This is not a big priblem because this
2292 can happen only in the beginning, when the minor mode kicks in.  Typing
2293 @code{M-x viper-mode} will correct the situation.  Viper knows about
2294 several such minor modes and takes care of them, so the above trick
2295 is usually not necessary.  If you find that some minor mode, e.g.,
2296 @code{nasty-mode} interferes with Viper, putting the following in
2297 @file{.viper} should fix the problem:
2298 @lisp
2299 (viper-harness-minor-mode "nasty-mode")
2300 @end lisp
2301 @noindent
2302 The argument to @code{viper-harness-minor-mode} is the name of the file for the
2303 offending minor mode with the suffixes @file{.el} and @file{.elc} removed.
2305 It may not be always obvious which minor mode is at fault.  The only
2306 guidance here is to look into the file that defines the minor mode you are
2307 suspecting, say @file{nasty-mode.el}, and see if it has a variable called
2308 @code{nasty-mode-map}.  Then check if there is a statement of the form
2309 @lisp
2310 (define-key nasty-mode-map key function)
2311 @end lisp
2312 @noindent
2313 that binds the misbehaving
2314 keys.  If so, use the above line to harness @code{nasty-mode}.  If your
2315 suspicion is wrong, no harm is done if you harness a minor mode that
2316 doesn't need to be harnessed.
2318 It is recommended to harness even those minor modes that don't override
2319 Viper keys, but still have their own keymaps. A general way to
2320 make a minor mode, @code{my-mode},
2321 compatible with Viper is to have the file @file{my-mode.el} include the following code:
2323 @lisp
2324 (when (fboundp 'viper-harness-minor-mode)
2325   (let ((lib (file-name-sans-extension
2326                (file-name-nondirectory load-file-name))))
2327     (viper-harness-minor-mode lib)))
2328 @end lisp
2330 @vindex @code{viper-want-emacs-keys-in-vi}
2331 @vindex @code{viper-want-emacs-keys-in-insert}
2332 @vindex @code{viper-always}
2333 @findex @code{viper-set-hooks}
2334 @findex @code{viper-mode}
2335 @findex @code{viper-harness-minor-mode}
2336 @findex @code{remove-hook}
2337 @findex @code{add-hook}
2339 @node Viper Specials,Vi Macros,Packages that Change Keymaps,Customization
2340 @section Viper Specials
2342 Viper extends Vi with a number of useful features.  This includes various
2343 search functions, histories of search strings, Ex commands, insertions, and
2344 Vi's destructive commands.  In addition, Viper supports file name completion
2345 and history, completion of Ex commands and variables, and many other
2346 features.  Some of these features are explained in detail elsewhere in this
2347 document.  Other features are explained here.
2349 @table @code
2350 @item (viper-buffer-search-enable)
2351 @item viper-buffer-search-char nil
2352 Enable buffer search.  Explicit call to @code{viper-buffer-search-enable}
2353 sets @code{viper-buffer-search-char} to @kbd{g}.  Alternatively, the user can
2354 set @code{viper-buffer-search-char} in @file{.viper} to a key sequence
2355 to be used for buffer search.  There is no need to call
2356 @code{viper-buffer-search-enable} in that case.
2357 @findex @code{viper-buffer-search-enable}
2358 @vindex @code{viper-buffer-search-char}
2359 @item viper-toggle-search-style
2360 This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and
2361 case-insensitive search, and also switch between plain vanilla search and
2362 search via regular expressions.  Without the prefix argument, the user is
2363 asked which mode to toggle.  With prefix argument 1, this toggles
2364 case-sensitivity.  With prefix argument 2, regular expression/vanilla search
2365 will be toggled.
2367 However, we found that the most convenient way to toggle
2368 these options is to bind a Vi macro to
2369 bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles
2370 vanilla search.  Thus, quickly hitting @kbd{/} twice will switch Viper from
2371 case sensitive search to case-insensitive.  Repeating this once again will
2372 restore the original state.  Likewise, quickly hitting @kbd{/} three times
2373 will switch you from vanilla-style search to search via regular expressions.
2374 If you hit something other than @kbd{/} after the first @kbd{/} or if the
2375 second @kbd{/} doesn't follow quickly enough, then Viper will issue the
2376 usual prompt @kbd{/} and will wait for input, as usual in Vi.
2377 If you don't like this behavior, you can ``unrecord'' these macros in your
2378 @file{~/.viper} file.  For instance, if you don't like the above feature, put
2379 this in @file{~/.viper}:
2380 @example
2381 (viper-set-searchstyle-toggling-macros 'undefine)
2382 @end example
2383 @findex @code{viper-set-searchstyle-toggling-macros}
2385 If you don't like this feature as a default, but would still like to have
2386 it in some major modes, you can do so by first unsetting it globally, as
2387 shown above, and then setting it in the desired major modes as follows:
2388 @example
2389 (viper-set-searchstyle-toggling-macros nil 'c-mode)
2390 (viper-set-searchstyle-toggling-macros nil 'lisp-mode)
2391 @end example
2393 @item Vi-isms in Emacs state
2394 Some people find it useful to use the Vi-style search key, `/', to invoke
2395 search in modes which Viper leaves in emacs-state.  These modes are:
2396 @code{dired-mode}, @code{mh-folder-mode},
2397 @code{Info-mode}, and @code{Buffer-menu-mode}
2398 (more may be added in the future).  So, in the above modes, Viper binds `/'
2399 so that it will behave Vi-style.  Furthermore, in those major modes, Viper
2400 binds `:' to invoke ex-style commands, like in vi-state.  And, as described
2401 above, `//' and `///' get bound to Vi-style macros that toggle
2402 case-insensitivity and regexp-search.
2404 If you don't like these features---which I don't really understand---you
2405 can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in
2406 @code{viper-slash-and-colon-map}, for other modes.
2407 @vindex @code{viper-slash-and-colon-map}
2408 @vindex @code{viper-dired-modifier-map}
2410 To unbind the macros `//' and `///' for a major mode where you feel they
2411 are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a
2412 non-@code{nil} argument.  This can be done either interactively, by supplying a
2413 prefix argument, or by placing
2414 @example
2415 (viper-set-emacs-state-searchstyle-macros 'undefine)
2416 @end example
2417 @findex @code{viper-set-emacs-state-searchstyle-macros}
2418 in the hook to the major mode (e.g., @code{dired-mode-hook}).
2419 @xref{Vi Macros}, for more information on Vi macros.
2421 @item viper-heading-start
2422 @item viper-heading-end
2423 @cindex headings
2424 @cindex sections
2425 @cindex paragraphs
2426 @cindex sentences
2427 Regular Expressions for @kbd{[[} and @kbd{]]}.  Note that Emacs defines
2428 Regexps for paragraphs and sentences.  @xref{Paragraphs,,Paragraphs and
2429 Sentences,emacs,The GNU Emacs Manual}, for details.
2430 @item M-x viper-set-expert-level
2431 @findex @code{viper-set-expert-level}
2432 Change your user level interactively.
2433 @item viper-smart-suffix-list  '("" "tex" "c" "cc" "el" "p")
2434 @vindex @code{viper-smart-suffix-list}
2435 Viper supports Emacs-style file completion when it prompts the user for a
2436 file name.  However, in many cases, the same directory may contain files
2437 with identical prefix but different suffixes, e.g., prog.c, prog.o,
2438 paper.tex, paper.dvi.  In such cases, completion will stop at the `.'.
2439 If the above variable is a list of strings representing suffixes, Viper will
2440 try these suffixes
2441 in the order listed and will check if the corresponding file exists.
2443 For instance, if completion stopped at `paper.'@: and the user typed
2444 @key{RET},
2445 then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist.
2446 It will take the first such file.  If no file exists, Viper will give a chance
2447 to complete the file name by typing the appropriate suffix.  If `paper.'@: was
2448 the intended file name, hitting return will accept it.
2450 To turn this feature off, set the above variable to @code{nil}.
2452 @item viper-insertion-ring-size  14
2453 @vindex @code{viper-insertion-ring-size}
2454 @cindex Insertion ring
2455 Viper remembers what was previously inserted in Insert and Replace states.
2456 Several such recent insertions are kept in a special ring of strings of size
2457 @code{viper-insertion-ring-size}.
2458 If you enter Insert or Replace state you can reinsert strings from this
2459 ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}.  The former will search the
2460 ring in
2461 the direction of older insertions, and the latter will search in
2462 the direction of newer insertions.  Hitting @kbd{C-c M-p} or @kbd{C-c M-n}
2463 in succession
2464 will undo the previous insertion from the ring and insert the next item on
2465 the ring.  If a larger ring size is needed, change the value of the above
2466 variable in the @file{~/.viper} file.
2468 Since typing these sequences of keys may be tedious, it is suggested that the
2469 user should bind a function key, such as @kbd{f31}, as follows:
2470 @example
2471 (define-key viper-insert-global-user-map [f31]
2472             'viper-insert-prev-from-insertion-ring)
2473 @end example
2474 This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation)
2475 to the function that inserts the previous string in the insertion history.
2476 To rotate the history in the opposite
2477 direction, you can either bind an unused key to
2478 @code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then
2479 @kbd{f31}.
2481 One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since
2482 this will interfere with the Minibuffer histories and, possibly, other
2483 major modes.
2485 @item viper-command-ring-size  14
2486 @vindex @code{viper-command-ring-size}
2487 @cindex Destructive command ring
2488 @cindex Destructive command history
2489 Viper keeps track of the recent history of destructive
2490 commands, such as @kbd{dw}, @kbd{i}, etc.
2491 In Vi state,
2492 the most recent command can be re-executed by hitting `@kbd{.}', as in Vi.
2493 However, repeated typing @kbd{C-c M-p} will cause Viper to show the
2494 previous destructive commands in the minibuffer.  Subsequent hitting `@kbd{.}'
2495 will execute the command that was displayed last.
2496 The key @kbd{C-c M-n} will cycle through the command history in the
2497 opposite direction.
2498 Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an
2499 appropriate function to an unused function key on the keyboard and use that
2500 key.  For instance, the following
2501 @example
2502 (define-key viper-vi-global-user-map [f31]
2503             'viper-prev-destructive-command)
2504 @end example
2505 binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation)
2506 to the function that searches the command history in the direction of older
2507 commands.  To search in the opposite
2508 direction, you can either bind an unused key to
2509 @code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}.
2511 One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since
2512 this will interfere with the Minibuffer histories and, possibly, other
2513 major modes.
2515 @item viper-minibuffer-vi-face  'viper-minibuffer-vi-face
2516 @item viper-minibuffer-insert-face  'viper-minibuffer-insert-face
2517 @item viper-minibuffer-emacs-face  'viper-minibuffer-emacs-face
2518 These faces control the appearance of the minibuffer text in the
2519 corresponding Viper states.  You can change the appearance of these faces
2520 through Emacs' customization widget, which is accessible through the
2521 menubar.
2523 Viper is located in this widget under the @emph{Emulations} customization
2524 subgroup of the @emph{Editing} group.  All Viper faces are grouped together
2525 in Viper's @emph{Highlighting} customization subgroup.
2527 Note that only the text you type in is affected by the above faces.
2528 Prompts and Minibuffer messages are not affected.
2530 Purists who do not like adornments in the minibuffer can always zap them by
2531 putting
2532 @example
2533 (copy-face 'default 'viper-minibuffer-vi-face)
2534 (copy-face 'default 'viper-minibuffer-insert-face)
2535 (copy-face 'default 'viper-minibuffer-emacs-face)
2536 @end example
2537 in the @file{~/.viper} file or through the customization widget, as
2538 described above.  However, in that case, the user will not have any
2539 indication of the current Viper state in the minibuffer.  (This is important
2540 if the user accidentally switches to another Viper state by typing @key{ESC} or
2541 @kbd{C-z}).
2542 @item M-x viper-go-away
2543 @findex @code{viper-go-away}
2544 Make Viper disappear from the face of your running Emacs instance.  If your
2545 fingers start aching again, @kbd{M-x viper-mode} might save your day.
2546 @item M-x toggle-viper-mode
2547 @findex @code{toggle-viper-mode}
2548 Toggle Viperization of Emacs on and off.
2549 @end table
2551 @cindex Multifile documents and programs
2553 Viper provides some support for multi-file documents and programs.
2554 If a document consists of several files we can designate one of them as a
2555 master and put the following at the end of that file:
2556 @lisp
2557 ;;; Local Variables:
2558 ;;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file4")
2559 ;;; End:
2560 @end lisp
2561 @noindent
2562 where @code{file1} to @code{file4} are names of files related to the master
2563 file.  Next time, when the master file is visited, the command
2564 @code{viper-setup-master-buffer} will be evaluated and the above files will
2565 be associated with the master file.  Then, the new Ex command
2566 @kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 4 one after
2567 another, so you can edit them.  If a file is not in any Emacs buffer, it
2568 will be visited.  The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P})
2569 goes through the file list in the opposite direction.
2570 @findex @kbd{:RelatedFile}
2571 @findex @kbd{:PreviousRelatedFile}
2573 These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to
2574 focus on relevant files only.
2576 Note that only the master file needs to have the aforementioned block of
2577 commands.  Also, ";;;" above can be replaced by some other
2578 markers.  Semicolon is good for Lisp programs, since it is considered a
2579 comment designator there.  For LaTeX, this could be "%%%", and for C the
2580 above block should be commented out.
2582 Even though these commands are sometimes useful, they are no substitute for
2583 the powerful @emph{tag table} facility of Emacs.  Viper's @kbd{:tag} command
2584 in a primitive interface to Emacs tags.  @xref{Tags,Tags,Tags,emacs,
2585 The GNU Emacs Manual}, for more information on tags.
2587 The following two commands are normally bound to a mouse click and are part
2588 of Viper.  They work only if Emacs runs as an application under X
2589 Windows (or under some other window system for which a port of GNU Emacs 20
2590 is available).  Clicking the mouse when Emacs is invoked in an Xterm window
2591 (using @code{emacs -nw}) will do no good.
2593 @table @code
2594 @cindex mouse
2595 @cindex mouse-search
2596 @item viper-mouse-search-key  (meta shift 1)
2597 @vindex @code{viper-mouse-insert-key}
2598 This variable controls the @emph{mouse-search} feature of Viper.  The
2599 default value
2600 states that holding Meta and Shift keys while clicking mouse button 1
2601 should initiate search for a region under the mouse pointer (defined
2602 below).  This command can take a prefix argument, which indicates the
2603 occurrence of the pattern to search for.
2605 Note: while loading initially, Viper binds this mouse action only if it is
2606 not already bound to something else.  If you want to use the mouse-search
2607 feature, and the @kbd{Meta-Shift-Mouse-1} mouse action is already bound to
2608 something else, you can rebind the mouse-search feature by setting
2609 @code{viper-mouse-search-key} to something else in your @code{~/.viper}
2610 file:
2611 @lisp
2612 (setq viper-mouse-search-key '(meta 1))
2613 @end lisp
2614 This would bind mouse search to the action invoked by pressing the
2615 Meta key and clicking mouse button 1.  The allowed values of
2616 @code{viper-mouse-search-key} are lists that contain a mouse-button number
2617 (1,2, or 3) and any combination of the words `control', `meta', and
2618 `shift'.
2620 If the requested mouse action (e.g., (meta 1)) is already taken for other
2621 purposes then you have to confirm your intention by placing the following
2622 command in @code{~/.viper} after setting @code{viper-mouse-search-key}:
2623 @lisp
2624 (viper-bind-mouse-search-key 'force)
2625 @end lisp
2627 You can also change this setting interactively, through the customization
2628 widget of Emacs (type @kbd{:customize}).
2630 The region that is chosen as a pattern to search for is determined as
2631 follows.  If search is invoked via a single click, Viper chooses the region
2632 that lies between the beginning of the ``word'' under the pointer (``word''
2633 is understood in Vi sense) and the end of that word.  The only difference
2634 with Vi's words is that in Lisp major modes `-' is considered an
2635 alphanumeric symbol.  This is done for the convenience of working with Lisp
2636 symbols, which often have an `-' in them.  Also, if you click on a
2637 non-alphanumeric character that is not a word separator (in Vi sense) then
2638 this character will also be considered alphanumeric, provided that it is
2639 adjacent (from either side) to an alphanumeric character.  This useful
2640 feature gives added control over the patterns selected by the mouse click.
2642 On a double-click, the region is determined by the beginning of the current
2643 Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End
2644 of that ``Word'' (as determined by the @kbd{E} command).
2646 On a triple-click, the region consists of the entire line where the click
2647 occurred with all leading and trailing spaces and tabs removed.
2649 @cindex mouse-insert
2650 @item viper-mouse-insert-key (meta shift 2)
2651 @vindex @code{viper-mouse-insert-key}
2652 This variable controls the @emph{mouse-insert} feature of Viper.
2653 The above default value states that
2654 holding Meta and Shift keys while clicking mouse button 2
2655 should insert the region surrounding the
2656 mouse pointer.  The rules defining this region are the same as for
2657 mouse-search.  This command takes an optional prefix argument, which
2658 indicates how many such regions to snarf from the buffer and insert.  (In
2659 case of a triple-click, the prefix argument is ignored.)
2661 Note: while loading initially, Viper binds this mouse action only if it not
2662 already bound to something else.  If you want to use this feature and the
2663 default mouse action is already bound, you can rebind mouse-insert by
2664 placing this command in @code{~/.viper}:
2665 @lisp
2666 (setq viper-mouse-insert-key '(meta 2))
2667 @end lisp
2668 If you want to bind mouse-insert to an action even if this action is
2669 already taked for other purposes in Emacs, then you should add this command
2670 to @code{~/.viper}, after setting @code{viper-mouse-insert-key}:
2671 @lisp
2672 (viper-bind-mouse-insert-key 'force)
2673 @end lisp
2675 This value can also be changed via the Emacs customization widget at the
2676 menubar.
2678 @item viper-multiclick-timeout
2679 This variable controls the rate at which double-clicking must occur for the
2680 purpose of mouse search and mouse insert.  By default, this is set to
2681 @code{double-click-time} in Emacs and to
2682 @code{mouse-track-multi-click-time} milliseconds in XEmacs.
2683 @end table
2684 @kindex @kbd{S-Mouse-1}
2685 @kindex @kbd{S-Mouse-2}
2686 @kindex @kbd{meta shift button1up}
2687 @kindex @kbd{meta shift button2up}
2688 @vindex @code{viper-multiclick-timeout}
2689 @findex @code{viper-mouse-click-insert-word}
2690 @findex @code{viper-mouse-click-search-word}
2692 Note: The above functions search and insert in the selected window of
2693 the latest active frame.  This means that you can click in another window or
2694 another frame and have search or insertion done in the frame and window you
2695 just left.  This lets one use these functions in a multi-frame
2696 configuration.  However, this may require some getting used to.  For
2697 instance, if you are typing in a frame, A, and then move the mouse to frame
2698 B and click to invoke mouse search, search (or insertion) will be performed
2699 in frame A.  To perform search/insertion in frame B, you will first have to
2700 shift focus there, which doesn't happen until you type a character or
2701 perform some other action in frame B---mouse search doesn't shift focus.
2703 If you decide that you don't like the above feature and always want
2704 search/insertion be performed in the frame where the click occurs, don't
2705 bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from
2706 the mouse event it is bound to.
2708 Mouse search is integrated with Vi-style search, so you can
2709 repeat it with @kbd{n} and @kbd{N}.  It should be also noted that, while
2710 case-sensitivity of search in Viper is controlled by the variable
2711 @code{viper-case-fold-search}, the case of mouse search is
2712 controlled by the Emacs variable @code{case-fold-search}, which may be set
2713 differently from @code{viper-case-fold-search}.  Therefore, case-sensitivity
2714 of mouse search may be different from that of the usual Vi-style search.
2716 Finally, if the way Viper determines the word to be searched for or to be
2717 inserted is not what you want, there is a variable,
2718 @code{viper-surrounding-word-function}, which can be changed to indicate
2719 another function for snarfing words out of the buffer.  The catch is that
2720 you will then have to write such a function and make it known to your
2721 Emacs.  The function @code{viper-surrounding-word} in @file{viper.el} can be
2722 used as a guiding example.
2724 @node Vi Macros, ,Viper Specials,Customization
2725 @section Vi Macros
2727 @cindex Vi macros
2729 Viper supports much enhanced Vi-style macros and also facilitates the use
2730 of Emacs-style macros.  To define a temporary macro, it is generally more
2731 convenient to use Emacs keyboard macro facility.  Emacs keyboard macros are
2732 usually defined anonymously, and the latest macro can be executed by typing
2733 @kbd{C-x e} (or @kbd{*}, if Viper is in Vi state).  If you need to use several
2734 temporary macros, Viper lets you save them to a
2735 register (a lowercase letter); such macros can then be executed by typing
2736 @kbd{@@a} in Vi state (if a macro was previously saved in register
2737 @kbd{a}).
2738 @xref{Macros and Registers}, for details.
2740 If, however, you need to use a macro regularly, it must be given a
2741 permanent name and saved.  Emacs manual explains how to do this, but
2742 invocation of named Emacs macros is quite different from Vi's.  First,
2743 invocation of permanent Emacs macros takes time because it requires typing
2744 too many keys (to  a Vi user's taste, anyway).
2745 Second, binding such macros to function keys, for
2746 fast access, hogs valuable real estate on the keyboard.
2748 Vi-style macros are better in that respect, since Vi lets the user overload
2749 the meaning of key sequences: keys typed in fast succession are treated
2750 specially, if this key sequence is bound to a macro.
2752 Viper provides Vi-style keyboard macros through the usual Ex commands,
2753 @kbd{:map} and
2754 @kbd{:map!}.  These macros are much more powerful in Viper than
2755 they are in the original Vi and in other emulators.  This is because Viper
2756 implements an enhanced vi-style
2757 interface to the powerful Emacs keyboard macro facility.
2759 First, any Emacs
2760 command can be executed while defining a macro, not just the Vi
2761 commands.  In particular, the user can invoke Emacs commands via @kbd{M-x
2762 command-name} or by pressing various function keys on the keyboard.  One
2763 can even use the mouse, although this is usually not useful and is not
2764 recommended (and macros defined with the use of the mouse cannot be saved in
2765 command history and in the startup file, for future use).
2767 Macros defined by mixing Vi and Emacs commands are represented as
2768 vectors.  So, don't be confused when you see one (usually through the
2769 history of Ex commands).  For instance, if @kbd{gg} is defined by typing
2770 @kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look
2771 as follows in Emacs:
2773 @example
2774 [l up (meta x) n e x t - l i n e return]
2775 @end example
2777 Second, Viper macros are defined in a WYSIWYG style.  This means that
2778 commands are executed as you type them, so you can see precisely what is
2779 being defined.  Third, macros can be bound to arbitrary sequences of keys,
2780 not just to printable keys.  For instance, one can define a macro that will
2781 be invoked by hitting @kbd{f3} then @kbd{f2} function keys.  (The keys
2782 @kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation
2783 sequence can't start with @key{ESC}.  Some other keys, such as @kbd{f1} and
2784 @kbd{help}, can't be bound to macros under Emacs, since they
2785 are bound in @code{key-translation-map}, which overrides any other binding
2786 the user gives to keys.  In general, keys that have a binding in
2787 @code{key-translation-map} can't be bound to a macro.)
2789 Fourth, in Viper, one can define macros that are specific to a given
2790 buffer, a given major mode, or macros that are defined for all buffers.  In
2791 fact, the same macro name can have several different definitions: one
2792 global, several definitions for various major modes, and
2793 definitions for various specific buffers.  Buffer-specific definitions
2794 override mode-specific definitions, which, in turn, override global
2795 definitions.
2797 As if all that is not enough, Viper (through its interface to Emacs
2798 macros) lets the user define keyboard macros that ask for confirmation or
2799 even prompt the user for input and then continue.  To do this, one should
2800 type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt).
2801 For details, @pxref{Keyboard Macro Query,,Customization,emacs,The GNU Emacs
2802 Manual} @refill
2804 When the user finishes defining a macro (which is done by typing @kbd{C-x)} ---
2805 a departure from Vi), you will be asked whether you want this
2806 macro to be global, mode-specific, or buffer-specific.  You will also be
2807 given a chance to save the macro in your @file{~/.viper} file.
2808 This is the easiest way to save a macro and make
2809 it permanently available.  If you work your startup files with bare hands,
2810 here is how Viper saves the above macro so that it will be
2811 available in Viper's Insert state (and Replace state) in buffer @code{my-buf}
2812 only:
2814 @example
2815 (viper-record-kbd-macro "gg" 'insert-state
2816        [l up (meta x) n e x t - l i n e return]
2817        "my-buf")
2818 @end example
2820 @noindent
2821 To do the same for Vi state and all buffers with the major mode
2822 @code{cc-mode}, use:
2824 @example
2825 (viper-record-kbd-macro "gg" 'vi-state
2826        [l up (meta x) n e x t - l i n e return]
2827        'cc-mode)
2828 @end example
2830 @noindent
2831 Both macro names and macro definitions are vectors of symbols that denote
2832 keys on the keyboard.  Some keys, like @kbd{\}, @kbd{ }, or digit-keys must
2833 be escaped with a backslash.  Modified keys are represented as lists.  For
2834 instance, holding Meta and Control and pressing @kbd{f4} is represented as
2835 @kbd{(control meta f4)}.
2836 If all members of a vectors are printable characters (or sequences, such as
2837 @kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as
2838 strings:
2840 @example
2841 (viper-record-kbd-macro "aa" 'vi-state  "aaa\e"  "my-buffer")
2842 @end example
2844 @noindent
2845 Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state
2846 (due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi
2847 state.  All this will take effect only in the buffer named @code{my-buffer}.
2849 Note that the last argument to @code{viper-record-kbd-macro} must be either a
2850 string (a buffer name), a symbol representing a major mode, or @code{t};
2851 the latter says that the macro is to be defined for all buffers
2852 (which is how macros are defined in original Vi).
2854 For convenience, Viper also lets you define Vi-style macros in its Emacs
2855 state.  There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing
2856 this, but the user can include such a macro in the @file{~/.viper} file.  The
2857 only thing is that the @code{viper-record-kbd-macro} command should specify
2858 @code{emacs-state} instead of @code{vi-state} or @code{insert-state}.
2860 The user can get rid of a macro either by using the Ex commands @kbd{:unmap}
2861 and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}.
2862 The latter is more powerful, since it can delete macros even in
2863 @code{emacs-state}.  However, @code{viper-unrecord-kbd-macro} is usually
2864 needed only when the user needs to get rid of the macros that are already
2865 predefined in Viper.
2866 The syntax is:
2867 @findex @code{viper-unrecord-kbd-macro}
2868 @example
2869 (viper-unrecord-kbd-macro macro state)
2870 @end example
2871 @noindent
2872 The second argument must be @code{vi-state}, @code{insert-state}, or
2873 @code{emacs-state}.  The first argument is a name of a macro.  To avoid
2874 mistakes in specifying names of existing macros, type @kbd{M-x
2875 viper-describe-kbd-macros} and use a name from the list displayed by this
2876 command.
2878 If an error occurs during macro definition, Emacs
2879 aborts the process, and it must be repeated.  This is analogous to Vi,
2880 except that in Vi the user doesn't know there is an error until the macro is
2881 actually run.  All that means that in order for a definition to be
2882 successful, the user must do some simple planning of the process in
2883 advance, to avoid errors.  For instance, if you want to map @kbd{gg} to
2884 @kbd{llll} in Vi state, you must make sure that there is enough room on the
2885 current line.  Since @kbd{l} moves the cursor forward, it may signal an
2886 error on reaching the end of line, which will abort the definition.
2888 These precautions are necessary only when defining macros; they will help
2889 avoid the need to redo the job.  When macros are actually run, an error
2890 during the execution will simply terminate the current execution
2891 (but the macro will remain mapped).
2893 A macro name can be a string of characters or a vector of keys.
2894 The latter makes it possible to define macros bound to, say, double-hits
2895 on a function key, such as @kbd{up} or @kbd{f13}.
2896 This is very useful if you run out of function keys on your keyboard; it
2897 makes Viper macro facility a @emph{keyboard doubler}, so to speak.
2899 Elsewhere (@xref{Key Bindings}, for details), we review
2900 the standard Emacs mechanism for binding function keys to commands.
2901 For instance,
2903 @example
2904 (global-set-key [f13] 'repeat-complex-command)
2905 @end example
2907 @noindent
2908 binds the key f13 to the Emacs function that repeats the last minibuffer
2909 command.  Under Viper, however, you may still use this key for additional
2910 purposes, if you bind, say, a double-hitting action for that key to some
2911 other function.  Emacs doesn't allow the user to do that, but Viper does
2912 this through its keyboard macro facility.  To do this, type @kbd{:map }
2913 first.  When you are asked to enter a macro name, hit f13 twice, followed by
2914 @key{RET} or @key{SPC}.
2916 Emacs will now start the mapping process by actually executing
2917 Vi and Emacs commands, so that you could see what will happen each time the
2918 macro is executed.  Suppose now we wanted to bind the key sequence
2919 @kbd{f13 f13} to the command @code{eval-last-sexp}.  To accomplish this, we
2920 can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}.
2921 If you answer positively to Viper's offer to save this macro in @file{~/.viper}
2922 for future uses, the following will be inserted in that file:
2924 @example
2925 (viper-record-kbd-macro [f16 f16] 'vi-state
2926          [(meta x) e v a l - l a s t - s e x p]
2927          'lisp-interaction-mode)
2928 @end example
2930 To illustrate the above point, Viper provides two canned macros, which, by
2931 default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing
2932 @kbd{f12} then @kbd{1} and @kbd{2}, respectively).  These macros are useful
2933 shortcuts to Viper's command ring history.  The first macro will execute the
2934 second-last destructive command (the last one is executed by @kbd{.}, as
2935 usual).  The second macro executes the third-last command.
2937 If you need to go deeper into the command history, you will have to use
2938 other commands, as described earlier in this section; or you can bind,
2939 say, @kbd{f12 \3} like this:
2941 @example
2942 (viper-record-kbd-macro [f12 \3] 'vi-state
2943                       [(meta x) r e p e a t - f r o m - h i s t o r y]
2944                       t)
2945 @end example
2948 Note that even though the macro uses the function key @kbd{f12}, the key is
2949 actually free and can still be bound to some Emacs function via
2950 @code{define-key} or @code{global-set-key}.
2953 Viper allows the user to define macro names that are prefixes of other macros.
2954 For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros.
2955 If you type the exact sequence of such keys and then pause, Viper will
2956 execute the right macro.  However, if you don't pause and, say, type
2957 @kbd{[[[[text} then the conflict is resolved as follows.  If only one of the
2958 key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the
2959 current buffer, then, in fact, there is no conflict and the right macro
2960 will be chosen.  If both have applicable definitions, then the first one
2961 found will be executed.  Usually this is the macro with a shorter name.  So,
2962 in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed
2963 twice and then the remaining keys, @kbd{t e x t}, will be processed.
2965 When defining macros using @kbd{:map} or @kbd{:map!}, the user enters
2966 the actually keys to be used to invoke the macro.  For instance, you
2967 should hit the actual key @kbd{f6} if it is to be part of a macro
2968 name; you do @emph{not} write @kbd{f 6}.  When entering keys, Viper
2969 displays them as strings or vectors (e.g., @code{"abc"} or @code{[f6
2970 f7 a]}).  The same holds for unmapping.  Hitting @key{TAB} while
2971 typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command will
2972 cause name completion.  Completions are displayed as strings or
2973 vectors.  However, as before, you don't actually type @samp{"},
2974 @samp{[}, or @samp{]} that appear in the completions.  These are
2975 meta-symbols that indicate whether the corresponding macro name is a
2976 vector or a string.
2978 One last difference from Vi: Vi-style keyboard macros cannot be defined in
2979 terms of other Vi-style keyboard macros (but named Emacs macros are OK).
2980 More precisely, while defining or executing a macro, the special meaning
2981 of key sequences (as Vi macros) is ignored.
2982 This is because it is all too easy to create an infinite loop in this way.
2983 Since Viper macros are much more powerful than Vi's it is impossible to
2984 detect such loops.  In practice, this is not really a limitation but,
2985 rather, a feature.
2987 We should also note that Vi macros are disabled in the Minibuffer, which
2988 helps keep some potential troubles away.
2990 The rate at which the user must type keys in order for them to be
2991 recognized as a timeout macro is controlled by the variable
2992 @code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds.
2994 For the most part, Viper macros defined in @file{~/.viper} can be shared
2995 between X and TTY modes.
2996 The problem with TTY may be that the function keys there generate sequences
2997 of events instead of a single event (as under a window system).
2998 Emacs maps some of these sequences back to the logical keys
2999 (e.g., the sequences generated by the arrow keys are mapped to @kbd{up},
3000 @kbd{left}, etc.).  However, not all function keys are mapped in this way.
3001 Macros that are bound to key sequences that contain such unmapped function
3002 keys have to be redefined for TTY's (and possibly for every type of TTY you
3003 may be using).  To do this, start Emacs on an appropriate TTY device and
3004 define the macro using @kbd{:map}, as usual.
3006 @findex @code{viper-describe-kbd-macros}
3007 Finally, Viper provides a function that conveniently displays all macros
3008 currently defined.  To see all macros along with their definitions, type
3009 @kbd{M-x viper-describe-kbd-macros}.
3011 @node Commands,,Customization,Top
3012 @chapter Commands
3014 This section is a semi-automatically bowdlerized version of the Vi
3015 reference created by @* @samp{maart@@cs.vu.nl} and others.  It can be
3016 found on the Vi archives.  This reference has been adapted for Viper.@refill
3018 @menu
3019 * Groundwork::                  Textual Conventions and Viper basics
3020 * Text Handling::               Moving, Editing, Undoing.
3021 * Display::                     Scrolling.
3022 * File and Buffer Handling::    Editing, Writing and Quitting.
3023 * Mapping::                     Mapping Keys, Keyboard Macros
3024 * Shell Commands::              Accessing Shell Commands, Processing Text
3025 * Options::                     Ex options, the @kbd{:set} commands
3026 * Emacs Related Commands::      Meta Keys, Windows
3027 * Mouse-bound Commands::        Search and insertion of text
3028 @end menu
3030 @node Groundwork, Text Handling, Commands, Commands
3031 @comment  node-name,  next,  previous,  up
3032 @section Groundwork
3034 The VI command set is based on the idea of combining motion commands
3035 with other commands.  The motion command is used as a text region
3036 specifier for other commands.
3037 We classify motion commands into @dfn{point commands} and
3038 @dfn{line commands}.@refill
3040 @cindex point commands
3042 The point commands are:
3044 @quotation
3045 @kbd{h}, @kbd{l}, @kbd{0},  @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B},
3046 @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f},
3047 @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^}
3048 @end quotation
3050 @cindex line commands
3052 The line commands are:
3054 @quotation
3055 @kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{},
3056 @kbd{@}}, @kbd{G}, @kbd{'},  @kbd{[[}, @kbd{]]}, @kbd{[]}
3057 @end quotation
3058 @noindent
3060 Text Deletion Commands (@pxref{Deleting Text}), Change commands
3061 (@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands})
3062 use these commands to describe a region of text to operate on.
3064 @cindex r and R region specifiers
3066 Viper adds two region descriptors, @kbd{r} and @kbd{R}.  These describe
3067 the Emacs regions (@pxref{Basics}), but they are not movement commands.
3069 The command description uses angle brackets @samp{<>} to indicate
3070 metasyntactic variables, since the normal conventions of using simple
3071 text can be confusing with Viper where the commands themselves are
3072 characters.  Watch out where @kbd{<} shift commands and @kbd{<count>} are
3073 mentioned together!!!
3075 @kindex <move>
3076 @kindex <a-z>
3077 @kindex <address>
3078 @cindex <move>
3079 @cindex <a-z>
3080 @cindex <address>
3081 @cindex movements
3083 @samp{<move>} refers to the above movement commands, and @samp{<a-z>}
3084 refers to registers or textmarkers from @samp{a} to @samp{z}.  Note
3085 that the @samp{<move>}  is described by full move commands, that is to
3086 say they will take counts, and otherwise behave like normal move commands.
3087 @cindex Ex addresses
3088 @samp{<address>} refers to Ex line addresses, which include
3090 @table @kbd
3091 @item .@: <No address>
3092 Current line
3093 @item .+n .-n
3094 Add or subtract for current line
3095 @item number
3096 Actual line number, use @kbd{.=} to get the line number
3097 @item '<a-z>
3098 Textmarker
3099 @item $
3100 Last line
3101 @item x,y
3102 Where x and y are one of the above
3103 @item %
3104 @cindex % (Ex address)
3105 For the whole file, same as (1,$).
3106 @item /<pat>/
3107 @itemx ?<pat>?
3108 Next or previous line with pattern <pat>.
3110 Note that the pattern is allowed to contain newline character (inserted as
3111 @kbd{C-qC-j}).  Therefore, one can search for patterns that span several
3112 lines.
3113 @end table
3115 @cindex % (Current file)
3116 Note that @samp{%} is used in Ex commands @kbd{:e} and @kbd{:r <shell-cmd>}
3117 to mean current file.  If you want a @samp{%} in your command, it must be
3118 escaped as @samp{\%}. Note that @kbd{:w} and the regular @kbd{:r <file>}
3119 command doesn't support the meta symbols @samp{%} and @samp{#}, because
3120 file history is a better mechanism.
3121 @cindex # (Previous file)
3122 Similarly, @samp{#} expands to the previous file.  The previous file is
3123 the first file in @kbd{:args} listing.  This defaults to previous window
3124 in the VI sense if you have one window only.
3126 @kindex <args>
3127 @kindex <cmd>
3128 @cindex <args>
3129 @cindex <cmd>
3130 @noindent
3131 Others like @samp{<args> -- arguments}, @samp{<cmd> -- command} etc.
3132 should be fairly obvious.
3134 @noindent
3135 Common characters referred to include:
3137 @table @kbd
3138 @item <sp>
3139 Space
3140 @item <ht>
3142 @item <lf>
3143 Linefeed
3144 @item <esc>
3145 Escape
3146 @item <cr>
3147 Return, Enter
3148 @end table
3149 @cindex <cr>
3150 @cindex <esc>
3151 @cindex <lf>
3152 @cindex <ht>
3153 @cindex <sp>
3155 @cindex words
3156 @cindex WORDS
3157 @cindex char
3158 @cindex CHAR
3160 We also use @samp{word} for alphanumeric/non-alphanumeric words, and
3161 @samp{WORD} for whitespace delimited words.  @samp{char} refers to any
3162 @acronym{ASCII} character, @samp{CHAR} to non-whitespace character.
3163 Brackets @samp{[]} indicate optional parameters; @samp{<count>} also
3164 optional, usually defaulting to 1.  Brackets are elided for
3165 @samp{<count>} to eschew obfuscation.
3167 Viper's idea of Vi's words is slightly different from Vi.  First, Viper
3168 words understand Emacs symbol tables.  Therefore, all symbols declared to be
3169 alphanumeric in a symbol table can automatically be made part of the Viper
3170 word.  This is useful when, for instance, editing text containing European,
3171 Cyrillic, Japanese, etc., texts.
3173 Second, Viper lets you depart from Vi's idea of a word by changing the a
3174 syntax preference via the customization widget (the variable
3175 @code{viper-syntax-preference}) or by executing
3176 @code{viper-set-syntax-preference} interactively.
3178 By default, Viper syntax preference is @code{reformed-vi}, which means that
3179 Viper considers only those symbols to be part of a word that are specified
3180 as word-symbols by the current Emacs syntax table (which may be different
3181 for different major modes) plus the underscore symbol @kbd{_}, minus the
3182 symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be
3183 considered as word-symbols by various Emacs major modes.  Reformed-Vi works
3184 very close to Vi, and it also recognizes words in other
3185 alphabets.  Therefore, this is the most appropriate mode for editing text
3186 and is likely to fit all your needs.
3188 You can also set Viper syntax preference to @code{strict-vi}, which would
3189 cause Viper to view all non-English letters as non-word-symbols.
3191 You can also specify @code{emacs} as your preference, which would
3192 make Viper use exactly the same notion of a word as Emacs does.  In
3193 particular, the underscore may not be part of a word in some major modes.
3195 Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper
3196 words would consist of characters that are classified as alphanumeric
3197 @emph{or} as parts of symbols.  This is convenient for editing programs.
3199 @code{viper-syntax-preference} is a local variable, so it can have different
3200 values for different major modes.  For instance, in programming modes it can
3201 have the value @code{extended}.  In text modes where words contain special
3202 characters, such as European (non-English) letters, Cyrillic letters, etc.,
3203 the value can be @code{reformed-vi} or @code{emacs}.
3204 If you consider using different syntactic preferences for different major
3205 modes, you should execute, for example,
3207 @example
3208 (viper-set-syntax-preference nil "extended")
3209 @end example
3211 in the appropriate major mode hooks.
3213 @vindex @code{viper-syntax-preference}
3214 @findex @code{viper-set-syntax-preference}
3215 @cindex syntax table
3219 The above discussion concerns only the movement commands.  In regular
3220 expressions, words remain the same as in Emacs.  That is, the expressions
3221 @code{\w}, @code{\>}, @code{\<}, etc., use Emacs' idea of what is a word,
3222 and they don't look into the value of variable
3223 @code{viper-syntax-preference}.  This is because Viper avoids changing
3224 syntax tables in order to not thwart the various major modes that set these
3225 tables.
3227 The usual Emacs convention is used to indicate Control Characters, i.e
3228 C-h for Control-h.  @emph{Do not confuse this with a sequence of separate
3229 characters
3230 C, -, h!!!} The @kbd{^} is itself, never used to indicate a
3231 Control character.
3233 Finally, we note that Viper's Ex-style commands can be made to work on the
3234 current Emacs region.  This is done by typing a digit argument before
3235 @kbd{:}.  For instance, typing @kbd{1:} will propmt you with something like
3236 @emph{:123,135}, assuming that the current region starts at line 123 and
3237 ends at line 135.  There is no need to type the line numbers, since Viper
3238 inserts them automatically in front of the Ex command.
3239 @cindex Ex commands
3241 @node Text Handling, Display, Groundwork, Commands
3242 @section Text Handling
3244 @menu
3245 * Move Commands::               Moving, Searching
3246 * Marking::                     Textmarkers in Viper and the Emacs Mark.
3247 * Appending Text::              Text insertion, Shifting, Putting
3248 * Editing in Insert State::     Autoindent, Quoting etc.
3249 * Deleting Text::               Deleting
3250 * Changing Text::               Changing, Replacement, Joining
3251 * Search and Replace::          Searches, Query Replace, Pattern Commands
3252 * Yanking::                     Yanking, Viewing Registers
3253 * Undoing::                     Multiple Undo, Backups
3254 @end menu
3256 @node Move Commands,Marking,,Text Handling
3257 @subsection Move Commands
3259 @cindex movement commands
3260 @cindex searching
3261 @cindex textmarkers
3262 @cindex markers
3263 @cindex column movement
3264 @cindex paragraphs
3265 @cindex headings
3266 @cindex sections
3267 @cindex sentences
3268 @cindex matching parens
3269 @cindex paren matching
3271 @table @kbd
3272 @item <count>  h  C-h
3273 <count> chars to the left.
3274 @item <count>  j  <lf> C-n
3275 <count> lines downward.
3276 @item <count>  l  <sp>
3277 <count> chars to the right.
3278 @item <count>  k  C-p
3279 <count> lines upward.
3280 @item <count>  $
3281 To the end of line <count> from the cursor.
3282 @item <count>  ^
3283 To the first CHAR <count> - 1 lines lower.
3284 @item <count>  -
3285 To the first CHAR <count> lines higher.
3286 @item <count>  +  <cr>
3287 To the first CHAR <count> lines lower.
3288 @item  0
3289 To the first char of the line.
3290 @item <count> |
3291 To column <count>
3292 @item <count>  f<char>
3293 <count> <char>s to the right (find).
3294 @item <count>  t<char>
3295 Till before <count> <char>s to the right.
3296 @item <count>  F<char>
3297 <count> <char>s to the left.
3298 @item <count>  T<char>
3299 Till after <count> <char>s to the left.
3300 @item <count>  ;
3301 Repeat latest @kbd{f t F T} <count> times.
3302 @item <count>  ,
3303 Repeat latest @kbd{f t F T}
3304 <count> times in opposite direction.
3305 @item <count>  w
3306 <count> words forward.
3307 @item <count>  W
3308 <count> WORDS forward.
3309 @item <count>  b
3310 <count> words backward.
3311 @item <count>  B
3312 <count> WORDS backward.
3313 @item <count>  e
3314 To the end of word <count> forward.
3315 @item <count>  E
3316 To the end of WORD <count> forward.
3317 @item <count>  G
3318 Go to line <count> (default end-of-file).
3319 @item <count>  H
3320 To line <count> from top of the screen (home).
3321 @item <count>  L
3322 To line <count> from bottom of the screen (last).
3323 @item  M
3324 To the middle line of the screen.
3325 @item <count>  )
3326 <count> sentences forward.
3327 @item <count>  (
3328 <count> sentences backward.
3329 @item <count>  @}
3330 <count> paragraphs forward.
3331 @item <count>  @{
3332 <count> paragraphs backward.
3333 @item <count>  ]]
3334 To the <count>th heading.
3335 @item <count>  [[
3336 To the <count>th previous heading.
3337 @item <count>  []
3338 To the end of <count>th heading.
3339 @item  m<a-z>
3340 Mark the cursor position with a letter.
3341 @item  `<a-z>
3342 To the mark.
3343 @item  '<a-z>
3344 To the first CHAR of the line with the mark.
3345 @item [<a-z>
3346 Show contents of textmarker.
3347 @item ]<a-z>
3348 Show contents of register.
3349 @item  ``
3350 To the cursor position before the latest absolute
3351 jump (of which are examples @kbd{/} and @kbd{G}).
3352 @item  ''
3353 To the first CHAR of the line on which the cursor
3354 was placed before the latest absolute jump.
3355 @item <count>  /<string>
3356 To the <count>th occurrence of <string>.
3357 @item <count>  /<cr>
3358 To the <count>th occurrence of <string> from previous @kbd{/ or ?}.
3359 @item <count>  ?<string>
3360 To the <count>th previous occurrence of <string>.
3361 @item <count>  ?<cr>
3362 To the <count>th previous occurrence of <string> from previous @kbd{?@: or /}.
3363 @item  n
3364 Repeat latest @kbd{/} @kbd{?} (next).
3365 @item  N
3366 Repeat latest search in opposite direction.
3367 @item C-c /
3368 Without a prefix argument, this command toggles
3369 case-sensitive/case-insensitive search modes and plain vanilla/regular
3370 expression search.  With the prefix argument 1, i.e.,
3371 @kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2,
3372 toggles plain vanilla search and search using
3373 regular expressions.  @xref{Viper Specials}, for alternative ways to invoke
3374 this function.
3375 @cindex vanilla search
3376 @cindex case-sensitive search
3377 @cindex case-insensitive search
3378 @item  %
3379 Find the next bracket/parenthesis/brace and go to its match.
3380 By default, Viper ignores brackets/parentheses/braces that occur inside
3381 parentheses.  You can change this by setting
3382 @code{viper-parse-sexp-ignore-comments} to @code{nil} in your @file{.viper} file.
3383 This option can also be toggled interactively if you quickly hit @kbd{%%%}.
3385 This latter feature is implemented as a vi-style keyboard macro.  If you
3386 don't want this macro, put
3388 @example
3389 (viper-set-parsing-style-toggling-macro 'undefine)
3390 @end example
3391 @findex @code{viper-set-parsing-style-toggling-macro}
3393 in your @file{~/.viper} file.
3395 @end table
3396 @kindex @kbd{%}
3397 @kindex @kbd{C-c /}
3398 @kindex @kbd{N}
3399 @kindex @kbd{n}
3400 @kindex @kbd{?<cr>}
3401 @kindex @kbd{/<cr>}
3402 @kindex @kbd{?<string>}
3403 @kindex @kbd{/<string>}
3404 @kindex @kbd{''}
3405 @kindex @kbd{``}
3406 @kindex @kbd{]<a-z>}
3407 @kindex @kbd{[<a-z>}
3408 @kindex @kbd{'<a-z>}
3409 @kindex @kbd{`<a-z>}
3410 @kindex @kbd{m<a-z>}
3411 @kindex @kbd{[]}
3412 @kindex @kbd{[[}
3413 @kindex @kbd{]]}
3414 @kindex @kbd{@{}
3415 @kindex @kbd{@}}
3416 @kindex @kbd{(}
3417 @kindex @kbd{)}
3418 @kindex @kbd{M}
3419 @kindex @kbd{L}
3420 @kindex @kbd{H}
3421 @kindex @kbd{G}
3422 @kindex @kbd{E}
3423 @kindex @kbd{e}
3424 @kindex @kbd{B}
3425 @kindex @kbd{b}
3426 @kindex @kbd{W}
3427 @kindex @kbd{w}
3428 @kindex @kbd{,}
3429 @kindex @kbd{;}
3430 @kindex @kbd{T<char>}
3431 @kindex @kbd{F<char>}
3432 @kindex @kbd{t<char>}
3433 @kindex @kbd{f<char>}
3434 @kindex @kbd{|}
3435 @kindex @kbd{0}
3436 @kindex @kbd{<cr>}
3437 @kindex @kbd{+}
3438 @kindex @kbd{-}
3439 @kindex @kbd{^}
3440 @kindex @kbd{$}
3441 @kindex @kbd{C-p}
3442 @kindex @kbd{<lf>}
3443 @kindex @kbd{<sp>}
3444 @kindex @kbd{C-n}
3445 @kindex @kbd{C-h}
3446 @kindex @kbd{h}
3447 @kindex @kbd{j}
3448 @kindex @kbd{k}
3449 @kindex @kbd{l}
3450 @vindex @code{viper-parse-sexp-ignore-comments}
3452 @node Marking,Appending Text,Move Commands,Text Handling
3453 @subsection Marking
3455 Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}.
3456 @xref{Emacs Preliminaries}, and @xref{Basics}, for explanation.  Also
3457 see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of
3458 the Emacs mark ring.
3460 @cindex marking
3462 @table @kbd
3463 @item m<a-z>
3464 Mark the current file and position with the specified letter.
3465 @item m .
3466 Set the Emacs mark (@pxref{Emacs Preliminaries}) at point.
3467 @item m ^
3468 Set the Emacs mark (@pxref{Emacs Preliminaries}) back to where it was last
3469 set with the @kbd{m.} command. This is useful when you set the mark with
3470 @kbd{m.}, but then some other command (such as @kbd{L} or @kbd{G}) changes
3471 it in a way that you didn't like.
3472 @item m <
3473 Set the Emacs mark at beginning of buffer.
3474 @item m >
3475 Set the Emacs mark at end of buffer.
3476 @item m ,
3477 Jump to the Emacs mark.
3478 @item :mark <char>
3479 Mark position with text marker named <char>.  This is an Ex command.
3480 @item :k <char>
3481 Same as @kbd{:mark}.
3482 @item ``
3483 Exchange point and mark.
3484 @item ''
3485 Exchange point and mark and go to the first CHAR on line.
3486 @item '<a-z>
3487 Go to specified Viper mark.
3488 @item
3489 Go to specified Viper mark and go to the first CHAR on line.
3490 @end table
3491 @kindex @kbd{m<a-z>}
3492 @kindex @kbd{m.}
3493 @kindex @kbd{m>}
3494 @kindex @kbd{m<}
3495 @kindex @kbd{m,}
3496 @kindex @kbd{m^}
3497 @findex @kbd{:mark}
3498 @findex @kbd{:k}
3499 @kindex @kbd{''}
3500 @kindex @kbd{``}
3501 @kindex @kbd{`<a-z>}
3502 @kindex @kbd{'<a-z>}
3504 @node  Appending Text, Editing in Insert State, Marking,Text Handling
3505 @subsection Appending Text
3507 @xref{Options}, to see how to change tab and shiftwidth size.  See the GNU
3508 Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on).
3509 Check out the variable @code{indent-tabs-mode} to put in just spaces.
3510 Also see options for word-wrap.
3512 @cindex inserting
3513 @cindex appending
3514 @cindex paste
3515 @cindex put
3517 @table @kbd
3518 @item <count>  a
3519 <count> times after the cursor.
3520 @item <count>  A
3521 <count> times at the end of line.
3522 @item <count>  i
3523 <count> times before the cursor (insert).
3524 @item <count>  I
3525 <count> times before the first CHAR of the line
3526 @item <count>  o
3527 On a new line below the current (open).
3528 The count is only useful on a slow terminal.
3529 @item <count>  O
3530 On a new line above the current.
3531 The count is only useful on a slow terminal.
3532 @item <count>  ><move>
3533 Shift the lines described by <count><move> one
3534 shiftwidth to the right (layout!).
3535 @item <count>  >>
3536 Shift <count> lines one shiftwidth to the right.
3537 @item <count>  ["<a-z1-9>]p
3538 Put the contents of the (default undo) buffer
3539 <count> times after the cursor.  The register will
3540 be automatically down-cased.
3541 @item <count>  ["<a-z1-9>]P
3542 Put the contents of the (default undo) buffer
3543 <count> times before the cursor.  The register will
3544 @item [<a-z>
3545 Show contents of textmarker.
3546 @item ]<a-z>
3547 Show contents of register.
3548 @item <count>  .
3549 Repeat previous command <count> times.  For destructive
3550 commands as well as undo.
3551 @item f1 1 and f1 2
3552 While @kbd{.} repeats the last destructive command,
3553 these two macros repeat the second-last and the third-last destructive
3554 commands.  @xref{Vi Macros}, for more information on Vi macros.
3555 @item C-c M-p and C-c M-n
3556 In Vi state,
3557 these commands help peruse the history of Vi's destructive commands.
3558 Successive typing of @kbd{C-c M-p} causes Viper to search the history in
3559 the direction
3560 of older commands, while hitting @kbd{C-c M-n} does so in reverse
3561 order.  Each command in the history is displayed in the Minibuffer.  The
3562 displayed command can
3563 then be executed by typing `@kbd{.}'.
3565 Since typing the above sequences of keys may be tedious, the
3566 functions doing the perusing can be bound to unused keyboard keys in the
3567 @file{~/.viper} file.  @xref{Viper Specials}, for details.
3568 @end table
3569 @kindex @kbd{C-c M-p}
3570 @kindex @kbd{C-c M-n}
3571 @kindex @kbd{.}
3572 @kindex @kbd{]<a-z>}
3573 @kindex @kbd{[<a-z>}
3574 @kindex @kbd{P}
3575 @kindex @kbd{p}
3576 @kindex @kbd{"<a-z1-9>p}
3577 @kindex @kbd{"<a-z1-9>P}
3578 @kindex @kbd{>>}
3579 @kindex @kbd{><move>}
3580 @kindex @kbd{O}
3581 @kindex @kbd{o}
3582 @kindex @kbd{i}
3583 @kindex @kbd{A}
3584 @kindex @kbd{a}
3586 @node Editing in Insert State, Deleting Text, Appending Text,Text Handling
3587 @subsection Editing in Insert State
3589 Minibuffer can be edited similarly to Insert state, and you can switch
3590 between Insert/Replace/Vi states at will.
3591 Some users prefer plain Emacs feel in the Minibuffer.  To this end, set
3592 @var{viper-vi-style-in-minibuffer} to @code{nil}.
3594 @cindex Insert state
3596 @table @kbd
3597 @item C-v
3598 Deprive the next char of its special meaning (quoting).
3599 @item C-h
3600 One char back.
3601 @item C-w
3602 One word back.
3603 @item C-u
3604 Back to the begin of the change on the
3605 current line.
3607 @end table
3608 @kindex @kbd{C-u}
3609 @kindex @kbd{C-w}
3610 @kindex @kbd{C-v}
3612 @node Deleting Text, Changing Text, Editing in Insert State, Text Handling
3613 @subsection Deleting Text
3616 There is one difference in text deletion that you should be
3617 aware of.  This difference comes from Emacs and was adopted in Viper
3618 because we find it very useful.  In Vi, if you delete a line, say, and then
3619 another line, these two deletions are separated and are put back
3620 separately if you use the @samp{p} command.  In Emacs (and Viper), successive
3621 series of deletions that are @emph{not interrupted} by other commands are
3622 lumped together, so the deleted text gets accumulated and can be put back
3623 as one chunk.  If you want to break a sequence of deletions so that the
3624 newly deleted text could be put back separately from the previously deleted
3625 text, you should perform a non-deleting action, e.g., move the cursor one
3626 character in any direction.
3628 @cindex shifting text
3630 @table @kbd
3631 @item <count>  x
3632 Delete <count> chars under and after the cursor.
3633 @item <count>  X
3634 Delete <count> chars before the cursor.
3635 @item <count>  d<move>
3636 Delete from point to endpoint of <count><move>.
3637 @item <count>  dd
3638 Delete <count> lines.
3639 @item  D
3640 The rest of the line.
3641 @item <count>  <<move>
3642 Shift the lines described by <count><move> one
3643 shiftwidth to the left (layout!).
3644 @item <count>  <<
3645 Shift <count> lines one shiftwidth to the left.
3646 @end table
3647 @kindex @kbd{<<}
3648 @kindex @kbd{<<move>}
3649 @kindex @kbd{D}
3650 @kindex @kbd{dd}
3651 @kindex @kbd{d<move>}
3652 @kindex @kbd{X}
3653 @kindex @kbd{x}
3655 @node Changing Text, Search and Replace, Deleting Text,Text Handling
3656 @subsection Changing Text
3658 @cindex joining lines
3659 @cindex changing case
3660 @cindex quoting regions
3661 @cindex substitution
3663 @table @kbd
3664 @item <count>  r<char>
3665 Replace <count> chars by <char> - no <esc>.
3666 @item <count>  R
3667 Overwrite the rest of the line,
3668 appending change @var{count - 1} times.
3669 @item <count>  s
3670 Substitute <count> chars.
3671 @item <count>  S
3672 Change <count> lines.
3673 @item <count>  c<move>
3674 Change from begin to endpoint of <count><move>.
3675 @item <count>  cc
3676 Change <count> lines.
3677 @item <count>  C
3678 The rest of the line and <count> - 1 next lines.
3679 @item <count>  =<move>
3680 Reindent the region described by move.
3681 @item <count>  ~
3682 Switch lower and upper cases.
3683 @item <count>  J
3684 Join <count> lines (default 2).
3685 @item  :[x,y]s/<pat>/<repl>/<f>
3686 Substitute (on lines x through y) the pattern
3687 <pat> (default the last pattern) with <repl>.  Useful
3688 flags <f> are @samp{g} for @samp{global} (i.e.@: change every
3689 non-overlapping occurrence of <pat>) and @samp{c} for
3690 @samp{confirm} (type @samp{y} to confirm a particular
3691 substitution, else @samp{n} ).  Instead of @kbd{/} any
3692 punctuation CHAR unequal to <space> <tab> and <lf> can be used as
3693 delimiter.
3695 In Emacs, @samp{\&} stands for the last matched expression, so
3696 @kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}.
3697 Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead.
3699 Viper does not parse search patterns and does not expand special symbols
3700 found there (e.g., @samp{~} is not expanded to the result of the previous
3701 substitution).
3703 Note: @emph{The newline character (inserted as @kbd{C-qC-j})
3704 can be used in <repl>}.
3705 @item  :[x,y]copy [z]
3706 Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}.
3707 @item  :[x,y]t [z]
3708 Same as @kbd{:copy}.
3709 @item  :[x,y]move [z]
3710 Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}.
3711 @item  &
3712 Repeat latest Ex substitute command, e.g.
3713 @kbd{:s/wrong/right}.
3714 @item :x,yp
3715 @itemx :g/Pat/p
3716 @itemx :v/Pat/p
3717 The above commands display certain buffer lines in a
3718 temporary buffer. The first form above displays the buffer lines between
3719 @kbd{x} and @kbd{y}. The second displays the lines of the buffer, which
3720 match a given pattern. The third form displays the lines that do @emph{not}
3721 match the given pattern.
3722 @item #c<move>
3723 Change upper-case characters in the region to lower-case.
3724 @item #C<move>
3725 Change lower-case characters in the region to upper-case.
3726 @item #q<move>
3727 Insert specified string at the beginning of each line in the region
3728 @item C-c M-p and C-c M-n
3729 In Insert and Replace states, these keys are bound to commands that peruse
3730 the history of the text
3731 previously inserted in other insert or replace commands.  By repeatedly typing
3732 @kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to
3733 insert these previously used strings one by one.
3734 When a new string is inserted, the previous one is deleted.
3736 In Vi state, these keys are bound to functions that peruse the history of
3737 destructive Vi commands.
3738 @xref{Viper Specials}, for details.
3739 @end table
3740 @kindex @kbd{C-c M-p}
3741 @kindex @kbd{C-c M-n}
3742 @kindex @kbd{#q<move> }
3743 @kindex @kbd{#C<move>}
3744 @kindex @kbd{#c<move>}
3745 @kindex @kbd{&}
3746 @kindex @kbd{\&}
3747 @findex @kbd{:substitute/<pat>/<repl>/<f>}
3748 @findex @kbd{:s/<pat>/<repl>/<f>}
3749 @findex @kbd{:copy [z]}
3750 @findex @kbd{:t [z]}
3751 @findex @kbd{:move [z]}
3752 @kindex @kbd{J}
3753 @kindex @kbd{~}
3754 @kindex @kbd{=<move>}
3755 @kindex @kbd{C}
3756 @kindex @kbd{cc}
3757 @kindex @kbd{c<move>}
3758 @kindex @kbd{S}
3759 @kindex @kbd{s}
3760 @kindex @kbd{R}
3761 @kindex @kbd{r<char>}
3763 @node Search and Replace, Yanking, Changing Text,Text Handling
3764 @subsection Search and Replace
3766 @xref{Groundwork}, for Ex address syntax.  @xref{Options}, to see how to
3767 get literal (non-regular-expression) search and how to stop search from
3768 wrapping around.
3770 @table @kbd
3771 @item C-c /
3772 Toggle case-sensitive search.  With prefix argument, toggle vanilla/regular
3773 expression search.
3774 @item <count>  /<string>
3775 To the <count>th occurrence of <string>.
3777 Viper does not parse search patterns and does not expand special symbols
3778 found there (e.g., @samp{~} is not expanded to the result of the previous
3779 substitution).
3781 @item <count>  ?<string>
3782 To the <count>th previous occurrence of <string>.
3783 @item <count>  g<move>
3784 Search for the text described by move.  (off by default)
3785 @item n
3786 Repeat latest @kbd{/} @kbd{?} (next).
3787 @item N
3788 Idem in opposite direction.
3789 @item %
3790 Find the next bracket and go to its match
3791 @item :[x,y]g/<string>/<cmd>
3792 @cindex text processing
3793 Search globally [from line x to y] for <string>
3794 and execute the Ex <cmd> on each occurrence.
3795 @item :[x,y]v/<string>/<cmd>
3796 Execute <cmd> on the lines that don't match.
3797 @item #g<move>
3798 Execute the last keyboard macro for each line in the region.
3799 @xref{Macros and Registers}, for more info.
3800 @item Q
3801 Query Replace.
3802 @item :ta <name>
3803 Search in the tags file where <name> is defined (file, line), and go to it.
3804 @item  :[x,y]s/<pat>/<repl>/<f>
3805 Substitute (on lines x through y) the pattern <pat> (default the last
3806 pattern) with <repl>.  Useful
3807 flags <f> are @samp{g} for @samp{global} (i.e.@: change every
3808 non-overlapping occurrence of <pat>) and @samp{c} for
3809 @samp{confirm} (type @samp{y} to confirm a particular
3810 substitution, else @samp{n}).  Instead of @kbd{/} any
3811 punctuation character other than <space> <tab> and <lf> can be used as
3812 delimiter.
3814 Note: @emph{The newline character (inserted as @kbd{C-qC-j})
3815 can be used in <repl>}.
3816 @item  &
3817 Repeat latest Ex substitute command, e.g.@: @kbd{:s/wrong/right}.
3818 @item :global /<pattern>/<ex-command>
3819 @itemx :g /<pattern>/<ex-command>
3820 Execute <ex-command> on all lines that match <pattern>.
3821 @item :vglobal /<pattern>/<ex-command>
3822 @itemx :v /<pattern>/<ex-command>
3823 Execute <ex-command> on all lines that do not match <pattern>.
3824 @end table
3825 @kindex @kbd{&}
3826 @findex @kbd{:substitute/<pat>/<repl>/<f>}
3827 @kindex @kbd{Q}
3828 @kindex @kbd{#g<move>}
3829 @findex @kbd{:v}
3830 @findex @kbd{:g}
3831 @findex @kbd{:global}
3832 @findex @kbd{:vglobal}
3833 @findex @kbd{:tag <name>}
3834 @kindex @kbd{%}
3835 @kindex @kbd{N}
3836 @kindex @kbd{n}
3837 @kindex @kbd{g<move>}
3838 @kindex @kbd{?<string>}
3839 @kindex @kbd{/<string>}
3841 @node Yanking,Undoing,Search and Replace,Text Handling
3842 @subsection Yanking
3844 @cindex cut and paste
3845 @cindex paste
3847 @table @kbd
3848 @item <count>  y<move>
3849 Yank from begin to endpoint of <count><move>.
3850 @item <count>  "<a-z>y<move>
3851 Yank from begin to endpoint of <count><move> to register.
3852 @item <count>  "<A-Z>y<move>
3853 Yank from begin to endpoint of <count><move> and append
3854 to register.
3855 @item <count>  yy
3856 <count> lines.
3857 @item <count>  Y
3858 Idem (should be equivalent to @kbd{y$} though).
3859 @item  m<a-z>
3860 Mark the cursor position with a letter.
3861 @item [<a-z>
3862 Show contents of textmarker.
3863 @item ]<a-z>
3864 Show contents of register.
3865 @item <count>  ["<a-z1-9>]p
3866 Put the contents of the (default undo) buffer
3867 <count> times after the cursor.  The register will
3868 be automatically down-cased.
3869 @item <count>  ["<a-z1-9>]P
3870 Put the contents of the (default undo) buffer
3871 <count> times before the cursor.  The register will
3872 @end table
3873 @kindex @kbd{P}
3874 @kindex @kbd{p}
3875 @kindex @kbd{"<a-z1-9>p}
3876 @kindex @kbd{"<a-z1-9>P}
3877 @kindex @kbd{]<a-z>}
3878 @kindex @kbd{[<a-z>}
3879 @kindex @kbd{m<a-z>}
3880 @kindex @kbd{Y}
3881 @kindex @kbd{yy}
3882 @kindex @kbd{"<A-Z>y<move>}
3883 @kindex @kbd{"<a-z>y<move>}
3884 @kindex @kbd{y<move>}
3885 @kindex @kbd{yank}
3886 @findex @kbd{:yank}
3888 @node Undoing,, Yanking,Text Handling
3889 @subsection Undoing
3891 @cindex undo
3892 @cindex backup files
3894 @table @kbd
3895 @item  u U
3896 Undo the latest change.
3897 @item  .
3898 Repeat undo.
3899 @item :q!
3900 Quit Vi without writing.
3901 @item :e!
3902 Re-edit a messed-up file.
3903 @item :rec
3904 Recover file from autosave.  Viper also creates backup files
3905 that have a @samp{~} appended to them.
3906 @end table
3907 @findex @kbd{:rec}
3908 @findex @kbd{:e!}
3909 @findex @kbd{:q!}
3910 @kindex @kbd{.}
3911 @kindex @kbd{U}
3912 @kindex @kbd{u}
3914 @node Display, File and Buffer Handling, Text Handling, Commands
3915 @section Display
3917 @cindex scrolling
3919 @table @kbd
3920 @item C-g
3921 At user level 1,
3922 give file name, status, current line number
3923 and relative position.@*
3924 At user levels 2 and higher, abort the current command.
3925 @item C-c g
3926 Give file name, status, current line number and relative position -- all
3927 user levels.
3928 @item C-l
3929 Refresh the screen.
3930 @item <count> C-e
3931 Expose <count> more lines at bottom, cursor stays put (if possible).
3932 @item <count> C-y
3933 Expose <count> more lines at top, cursor stays put (if possible).
3934 @item <count> C-d
3935 Scroll <count> lines downward (default the number of the previous scroll;
3936 initialization: half a page).
3937 @item <count> C-u
3938 Scroll <count> lines upward (default the number of the previous scroll;
3939 initialization: half a page).
3940 @item <count> C-f
3941 <count> pages forward.
3942 @item <count> C-b
3943 <count> pages backward (in older versions @kbd{C-b} only works without count).
3944 @item <count> z<cr>
3945 @item zH
3946 Put line <count> at the top of the window (default the current line).
3947 @item <count> z-
3948 @item zL
3949 Put line <count> at the bottom of the window
3950 (default the current line).
3951 @item <count> z.
3952 @item zM
3953 Put line <count> in the center of the window
3954 (default the current line).
3955 @end table
3956 @kindex @kbd{zM}
3957 @kindex @kbd{zL}
3958 @kindex @kbd{zH}
3959 @kindex @kbd{z<cr>}
3960 @kindex @kbd{z.}
3961 @kindex @kbd{z-}
3962 @kindex @kbd{z<cr>}
3963 @kindex @kbd{C-b}
3964 @kindex @kbd{C-f}
3965 @kindex @kbd{C-u}
3966 @kindex @kbd{C-d}
3967 @kindex @kbd{C-y}
3968 @kindex @kbd{C-e}
3969 @kindex @kbd{C-l}
3970 @kindex @kbd{C-g}
3973 @node File and Buffer Handling, Mapping, Display,Commands
3974 @section File and Buffer Handling
3976 @cindex multiple files
3978 In all file handling commands, space should be typed before entering the file
3979 name.  If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't
3980 put any space between the command and the modifier.
3982 Note that many Ex commands, e.g., @kbd{:w}, accept command arguments. The
3983 effect is that the command would start acting on the current region. For
3984 instance, if the current region spans the lines 11 through 22, then if you
3985 type @kbd{1:w} you would see @samp{:11,22w} in the minibuffer.
3987 @table @kbd
3988 @item :q
3989 Quit buffer except if modified.
3990 @item :q!
3991 Quit buffer without checking.  In Viper, these two commands
3992 are identical.  Confirmation is required if exiting modified buffers that
3993 visit files.
3994 @item :suspend
3995 @item :stop
3996 Suspend Viper
3997 @item :[x,y] w
3998 Write the file.  Viper makes sure that a final newline is always added to
3999 any file where this newline is missing.  This is done by setting Emacs
4000 variable @code{require-final-newline} to @code{t}.  If you don't like this
4001 feature, use @code{setq-default} to set @code{require-final-newline} to
4002 @code{nil}.  This must be done in @file{.viper} file.
4003 @item :[x,y] w <name>
4004 Write to the file <name>.
4005 @item :[x,y] w>> <name>
4006 Append the buffer to the file <name>.  There should be no space between
4007 @kbd{w} and @kbd{>>}.  Type space after the @kbd{>>} and see what happens.
4008 @item :w!@: <name>
4009 Overwrite the file <name>.  In Viper, @kbd{:w} and @kbd{:w!} are identical.
4010 Confirmation is required for writing to an existing file (if this is not
4011 the file the buffer is visiting) or to a read-only file.
4012 @item :x,y w <name>
4013 Write lines x through y to the file <name>.
4014 @item :wq
4015 Write the file and kill buffer.
4016 @item :r <file> [<file> ...]
4017 Read file into a buffer, inserting its contents after the current line.
4018 @item :xit
4019 Same as @kbd{:wq}.
4020 @item :Write
4021 @itemx :W
4022 Save all unsaved buffers, asking for confirmation.
4023 @item :WWrite
4024 @itemx :WW
4025 Like @kbd{W}, but without asking for confirmation.
4026 @item ZZ
4027 Save current buffer and kill it.  If user level is 1, then save all files
4028 and kill Emacs.  Killing Emacs is the wrong way to use it, so you should
4029 switch to higher user levels as soon as possible.
4030 @item :x [<file>]
4031 Save and kill buffer.
4032 @item :x!@: [<file>]
4033 @kbd{:w![<file>]} and @kbd{:q}.
4034 @item :pre
4035 Preserve the file -- autosave buffers.
4036 @item :rec
4037 Recover file from autosave.
4038 @item :f [<file>]
4039 without the argument, prints file name and character/line information afout
4040 the currently visited file. With an argument, sets the currently visited
4041 filename to @file{file}.
4042 @item :cd [<dir>]
4043 Set the working directory to <dir> (default home directory).
4044 @item :pwd
4045 Print present working directory.
4046 @item :e [+<cmd>] <files>
4047 Edit files.  If no filename is given, edit the file visited by the current
4048 buffer.  If buffer was modified or the file changed on disk, ask for
4049 confirmation.  Unlike Vi, Viper allows @kbd{:e} to take multiple arguments.
4050 The first file is edited the same way as in Vi.  The rest are visited
4051 in the usual Emacs way.
4052 @item :e!@: [+<cmd>] <files>
4053 Re-edit file.  If no filename, re-edit current file.
4054 In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}.  In both cases, the
4055 user is asked to confirm if there is a danger of discarding changes to a
4056 buffer.
4057 @item :q!
4058 Quit Vi without writing.
4059 @item C-^
4060 Edit the alternate (normally the previous) file.
4061 @item :rew
4062 Obsolete
4063 @item :args
4064 List files not shown anywhere with counts for next
4065 @item :n [count]  [+<cmd>] [<files>]
4066 Edit <count> file, or edit files.  The count comes from @kbd{:args}.
4067 @item :N [count] [+<cmd>] [<files>]
4068 Like @kbd{:n}, but the meaning of the variable
4069 @var{ex-cycle-other-window} is reversed.
4070 @item :b
4071 Switch to another buffer.  If @var{ex-cycle-other-window} is @code{t},
4072 switch in another window.  Buffer completion is supported.
4073 The variable @var{viper-read-buffer-function} controls which function is
4074 actually used to read the buffer name. The default is @code{read-buffer},
4075 but better alternatives are also available in Emacs (e.g.,
4076 @code{iswitchb-read-buffer}).
4077 @vindex @var{viper-read-buffer-function}
4078 @item :B
4079 Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed.
4080 @item :<address>r <name>
4081 Read the file <name> into the buffer after the line <address>.
4082 @item v, V, C-v
4083 Edit a file in current or another window, or in another frame.  File name
4084 is typed in Minibuffer.  File completion and history are supported.
4085 @end table
4086 @kindex @kbd{v}
4087 @kindex @kbd{V}
4088 @findex @kbd{:args}
4089 @findex @kbd{:rew}
4090 @kindex @kbd{C-^}
4091 @findex @kbd{:e!@: [<files>]}
4092 @findex @kbd{:e [<files>]}
4093 @findex @kbd{:edit [<files>]}
4094 @findex @kbd{:edit!@: [<files>]}
4095 @findex @kbd{:q!}
4096 @findex @kbd{:q}
4097 @findex @kbd{:quit}
4098 @findex @kbd{:quit!}
4099 @findex @kbd{:f}
4100 @findex @kbd{:rec}
4101 @findex @kbd{:r}
4102 @findex @kbd{:read}
4103 @findex @kbd{:pre}
4104 @kindex @kbd{ZZ}
4105 @findex @kbd{:wq}
4106 @findex @kbd{:w <file>}
4107 @findex @kbd{:w!@: <file>}
4108 @findex @kbd{:w >> <file>}
4109 @findex @kbd{:write <file>}
4110 @findex @kbd{:write!@: <file>}
4111 @findex @kbd{:write >> <file>}
4112 @findex @kbd{:W}
4113 @findex @kbd{:WW}
4114 @findex @kbd{:Write}
4115 @findex @kbd{:WWrite}
4116 @findex @kbd{:WWrite}
4117 @findex @kbd{:x}
4118 @findex @kbd{:x!}
4119 @findex @kbd{:suspend}
4120 @findex @kbd{:stop}
4121 @findex @kbd{:n [<count> | <file>]}
4122 @findex @kbd{:cd [<dir>]}
4123 @findex @kbd{:pwd}
4125 @node Mapping, Shell Commands, File and Buffer Handling, Commands
4126 @section Mapping
4128 @cindex key bindings
4129 @cindex key mapping
4131 @table @kbd
4132 @item :map <string>
4133 Start defining a Vi-style keyboard macro.
4134 For instance, typing
4135 @kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )}
4136 will cause @kbd{www} to run wc on
4137 current file (Vi replaces @samp{%} with the current file name).
4138 @item C-x )
4139 Finish defining a keyboard macro.
4140 In Viper, this command completes the process of defining all keyboard
4141 macros, whether they are Emacs-style or Vi-style.
4142 This is a departure from Vi, needed to allow WYSIWYG mapping of
4143 keyboard macros and to permit the use of function keys and arbitrary Emacs
4144 functions in the macros.
4145 @item :unmap <string>
4146 Deprive <string> of its mappings in Vi state.
4147 @item :map!@: <string>
4148 Map a macro for Insert state.
4149 @item :unmap!@: <string>
4150 Deprive <string> of its mapping in Insert state (see @kbd{:unmap}).
4151 @item @@<a-z>
4152 In Vi state,
4153 execute the contents of register as a command.
4154 @item @@@@
4155 In Vi state,
4156 repeat last register command.
4157 @item @@#
4158 In Vi state,
4159 begin keyboard macro.  End with @@<a-z>.  This will
4160 put the macro in the proper register.  Register will
4161 be automatically down-cased.
4162 @xref{Macros and Registers}, for more info.
4163 @item @@!<a-z>
4164 In Vi state,
4165 yank anonymous macro to register
4166 @item *
4167 In Vi state,
4168 execute anonymous macro (defined by C-x( and C-x )).
4169 @item C-x e
4170 Like @kbd{*}, but works in all Viper states.
4171 @item #g<move>
4172 Execute the last keyboard macro for each line in the region.
4173 @xref{Macros and Registers}, for more info.
4174 @item [<a-z>
4175 Show contents of textmarker.
4176 @item ]<a-z>
4177 Show contents of register.
4178 @end table
4179 @kindex @kbd{]<a-z>}
4180 @kindex @kbd{[<a-z>}
4181 @kindex @kbd{#g<move>}
4182 @kindex @kbd{*}
4183 @kindex @kbd{@@!<a-z>}
4184 @kindex @kbd{@@#}
4185 @kindex @kbd{@@@@}
4186 @kindex @kbd{@@<a-z>}
4187 @findex @kbd{:unmap <char>}
4188 @findex @kbd{:map <char> <seq>}
4189 @findex @kbd{:unmap!@: <char>}
4190 @findex @kbd{:map!@: <char> <seq>}
4192 @node Shell Commands, Options, Mapping, Commands
4193 @section Shell Commands
4195 @cindex % (Current file)
4197 The symbol @samp{%} is used in Ex shell commands to mean current file.  If
4198 you want a @samp{%} in your command, it must be escaped as @samp{\%}.
4199 @cindex @samp{%} (Ex address)
4200 However if @samp{%} is the first character, it stands as the address for
4201 the whole file.
4202 @cindex @samp{#} (Previous file)
4203 Similarly, @samp{#} expands to the previous file.  The previous file is the
4204 first file in @kbd{:args} listing.  This defaults to the previous file in
4205 the VI sense if you have one window.@refill
4207 Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and
4208 @kbd{:r <shell-cmd>}.  The commands @kbd{:w} and the regular @kbd{:r
4209 <file>} command don't support these meta symbols, because file history is a
4210 better mechanism.
4212 @cindex shell commands
4214 @table @kbd
4215 @item :sh
4216 Execute a subshell in another window
4217 @item :[x,y]!<cmd>
4218 Execute a shell <cmd> [on lines x through y;
4219 % is replace by current file, \% is changed to %
4220 @item :[x,y]!!@: [<args>]
4221 Repeat last shell command [and append <args>].
4222 @item :!<cmd>
4223 Just execute command and display result in a buffer.
4224 @item :!!@: <args>
4225 Repeat last shell command and append <args>
4226 @item <count> !<move><cmd>
4227 The shell executes <cmd>, with standard
4228 input the lines described by <count><move>,
4229 next the standard output replaces those lines
4230 (think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.).
4231 @item <count> !!<cmd>
4232 Give <count> lines as standard input to the
4233 shell <cmd>, next let the standard output
4234 replace those lines.
4235 @item :[x,y] w !<cmd>
4236 Let lines x to y be standard input for <cmd>
4237 (notice the <sp> between @kbd{w} and @kbd{!}).
4238 @item :<address>r !<cmd>
4239 Put the output of <cmd> after the line <address> (default current).
4240 @item :<address>r <name>
4241 Read the file <name> into the buffer after the line <address> (default
4242 current).
4243 @item :make
4244 Run the make command in the current directory.
4245 @end table
4246 @findex @kbd{:<address>r <name>}
4247 @findex @kbd{:<address>r !<cmd>}
4248 @findex @kbd{!<cmd>}
4249 @findex @kbd{!!<cmd>}
4250 @findex @kbd{!<move><cmd>}
4251 @findex @kbd{:w !<cmd>}
4252 @findex @kbd{:x,y w !<cmd>}
4253 @findex @kbd{:!!@: <args>}
4254 @findex @kbd{:!<cmd>}
4255 @findex @kbd{:sh}
4256 @findex @kbd{:make}
4258 @node Options,Emacs Related Commands,Shell Commands,Commands
4259 @section Options
4261 @cindex Vi options
4263 @table @kbd
4264 @item autoindent
4265 @itemx ai
4266 @cindex autoindent
4267 autoindent -- In append mode after a <cr> the
4268 cursor will move directly below the first
4269 character on the previous line.
4270 This setting affects the current buffer only.
4271 @item autoindent-global
4272 @itemx ai-global
4273 Same as `autoindent', but affects all buffers.
4274 @item noautoindent
4275 @itemx noai
4276 Cancel autoindent.
4277 @item noautoindent-global
4278 @itemx noai-g
4279 Cancel autoindent-global.
4280 @item ignorecase
4281 @itemx ic
4282 @cindex case and searching
4283 ignorecase -- No distinction between upper and lower cases when searching.
4284 @item noignorecase
4285 @itemx noic
4286 Cancel ignorecase.
4287 @item magic
4288 @itemx ma
4289 @cindex literal searching
4290 Regular expressions used in searches; nomagic means no regexps.
4291 @item nomagic
4292 @item noma
4293 Cancel magic.
4294 @item readonly
4295 @itemx ro
4296 @cindex readonly files
4297 readonly -- The file is not to be changed.
4298 If the user attempts to write to this file, confirmation will be requested.
4299 @item noreadonly
4300 @itemx noro
4301 Cancel readonly.
4302 @item shell=<string>
4303 @itemx sh=<string>
4304 @cindex shell
4305 shell -- The program to be used for shell escapes
4306 (default @samp{$SHELL} (default @file{/bin/sh})).
4307 @item shiftwidth=<count>
4308 @itemx sw=<count>
4309 @cindex layout
4310 @cindex shifting text
4311 shiftwidth -- Gives the shiftwidth (default 8 positions).
4312 @item showmatch
4313 @itemx sm
4314 @cindex paren matching
4315 @cindex matching parens
4316 showmatch -- Whenever you append a @kbd{)}, Vi shows
4317 its match if it's on the same page; also with
4318 @kbd{@{} and @kbd{@}}.  If there's no match, Vi will beep.
4319 @item noshowmatch
4320 @itemx nosm
4321 Cancel showmatch.
4322 @item tabstop=<count>
4323 @itemx ts=<count>
4324 @cindex changing tab width
4325 @cindex tabbing
4326 tabstop -- The length of a <ht>; warning: this is
4327 only IN the editor, outside of it <ht>s have
4328 their normal length (default 8 positions).
4329 This setting affects the current buffer only.
4330 @item tabstop-global
4331 @itemx ts-g
4332 Same as `tabstop', but affects all buffers.
4333 @item wrapmargin=<count>
4334 @itemx wm=<count>
4335 @cindex auto fill
4336 @cindex word wrap
4337 wrapmargin -- In append mode Vi automatically
4338 puts a <lf> whenever there is a <sp> or <ht>
4339 within <wm> columns from the right margin.
4340 @item wrapscan
4341 @itemx ws
4342 @cindex searching
4343 wrapscan -- When searching, the end is
4344 considered @samp{stuck} to the begin of the file.
4345 @item nowrapscan
4346 @itemx nows
4347 Cancel wrapscan.
4348 @item :set <option>
4349 Turn <option> on.
4350 @item :set no<option>
4351 Turn <option> off.
4352 @item :set <option>=<value>
4353 Set <option> to <value>.
4354 @end table
4355 @findex @kbd{:set <option>=<value>}
4356 @findex @kbd{:set no<option>}
4357 @findex @kbd{:set <option>}
4358 @findex @kbd{:set ws}
4359 @findex @kbd{:set wrapscan}
4360 @findex @kbd{:set wm=<count>}
4361 @findex @kbd{:set wrapmargin=<count>}
4362 @findex @kbd{:set ts=<count>}
4363 @findex @kbd{:set tabstop=<count>}
4364 @findex @kbd{:set tab-stop-local=<count>}
4365 @findex @kbd{:set sm}
4366 @findex @kbd{:set showmatch}
4367 @findex @kbd{:set sw=<count>}
4368 @findex @kbd{:set shiftwidth=<count>}
4369 @findex @kbd{:set sh=<string>}
4370 @findex @kbd{:set shell=<string>}
4371 @findex @kbd{:set ro}
4372 @findex @kbd{:set readonly}
4373 @findex @kbd{:set magic}
4374 @findex @kbd{:set ic}
4375 @findex @kbd{:set ignorecase}
4376 @findex @kbd{:set ai}
4377 @findex @kbd{:set autoindent}
4379 @node Emacs Related Commands,,Options,Commands
4380 @section Emacs Related Commands
4382 @table @kbd
4383 @item C-\
4384 Begin Meta command in Vi or Insert states.  Most often used as C-\ x (M-x).
4386 Note: Emacs binds @kbd{C-\} to a function that offers to change the
4387 keyboard input method in the multilingual environment.  Viper overrides this
4388 binding.  However, it is still possible to switch the input method by typing
4389 @kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state.
4390 Or you can use the MULE menu on the menubar.
4391 @item C-z
4392 In Insert and Replace states, prepare Viper to accept the next command and
4393 execute it as if Viper was in Vi state.  Then return to Insert state.
4395 In Vi state, switch to Emacs state; in Emacs state, switch to Vi state.
4396 @item C-c \
4397 Switches to Vi state for the duration of a single command.  Then goes back
4398 to the original Viper state.  Works from Vi, Insert, Replace, and Emacs states.
4399 @item C-x0
4400 Close Window
4401 @item C-x1
4402 Close Other Windows
4403 @item C-x2
4404 Split Window
4405 @item C-xo
4406 Move among windows
4407 @item C-xC-f
4408 Emacs find-file, useful in Insert state
4409 @item C-y
4410 Put back the last killed text.  Similar to Vi's @kbd{p}, but also works in
4411 Insert and Replace state.  This command doesn't work in Vi command state,
4412 since this binding is taken for something else.
4413 @item M-y
4414 Undoes the last @kbd{C-y} and puts another kill from the kill ring.
4415 Using this command, you can try may different kills until you find the one
4416 you need.
4417 @end table
4418 @kindex @kbd{M-y}
4419 @kindex @kbd{C-y}
4420 @kindex @kbd{C-xC-f}
4421 @kindex @kbd{C-xo}
4422 @kindex @kbd{C-x2}
4423 @kindex @kbd{C-x1}
4424 @kindex @kbd{C-x0}
4425 @kindex @kbd{C-z}
4426 @kindex @kbd{C-\}
4427 @kindex @kbd{C-c\}
4429 @node Mouse-bound Commands,,,Commands
4430 @section Mouse-bound Commands
4432 The following two mouse actions are normally bound to special search and
4433 insert commands in of Viper:
4435 @table @kbd
4436 @item S-Mouse-1
4437 Holding Shift and clicking mouse button 1 will
4438 initiate search for
4439 a region under the mouse pointer.
4440 This command can take a prefix argument.  Note: Viper sets this
4441 binding only if this mouse action is not
4442 already bound to something else.
4443 @xref{Viper Specials}, for more information.@refill
4445 @item S-Mouse-2
4446 Holding Shift and clicking button 2 of the mouse will
4447 insert a region surrounding the mouse pointer.
4448 This command can also take a prefix argument.
4449 Note: Viper sets this binding only if this mouse action is not
4450 already bound to something else.
4451 @xref{Viper Specials}, for more details.@refill
4452 @end table
4453 @kindex @kbd{S-Mouse-1}
4454 @kindex @kbd{S-Mouse-2}
4455 @kindex @kbd{meta button1up}
4456 @kindex @kbd{meta button2up}
4458 @node Acknowledgments,,,Top
4459 @comment  node-name,  next,  previous,  up
4460 @unnumbered Acknowledgments
4462 Viper, formerly known as VIP-19, was written by Michael Kifer.  Viper is
4463 based on the original VIP package by Masahiko Sato and on its enhancement,
4464 VIP 4.4, by Aamod Sane.  This manual is an adaptation of the manual for VIP
4465 4.4, which, in turn, was based on Sato's manual for VIP 3.5.
4467 Many contributors on the Net pointed out bugs and suggested a number of
4468 useful features. Scott Bronson and Samuel Padgett contributed patches that
4469 were incorporated in this code.  Here is a hopefully complete list of
4470 contributors:
4472 @example
4473 aaronl@@vitelus.com (Aaron Lehmann),
4474 ahg@@panix.com (Al Gelders),
4475 amade@@diagram.fr (Paul-Bernard Amade),
4476 ascott@@fws214.intel.com (Andy Scott),
4477 bronson@@trestle.com (Scott Bronson),
4478 cook@@biostat.wisc.edu (Tom Cook),
4479 csdayton@@midway.uchicago.edu (Soren Dayton),
4480 dave@@hellgate.utah.edu,
4481 dm@@scs.cs.nyu.edu (David Mazieres),
4482 dominik@@strw.LeidenUniv.nl (Carsten Dominik),
4483 dwallach@@cs.princeton.edu (Dan Wallach),
4484 dwight@@toolucky.llnl.gov (Dwight Shih),
4485 dxc@@xprt.net (David X Callaway),
4486 edmonds@@edmonds.home.cs.ubc.ca (Brian Edmonds),
4487 gin@@mo.msk.ru (Golubev I.N.),
4488 gviswana@@cs.wisc.edu (Guhan Viswanathan),
4489 gvr@@halcyon.com (George V.@: Reilly),
4490 hatazaki@@bach.convex.com (Takao Hatazaki),
4491 hpz@@ibmhpz.aug.ipp-garching.mpg.de (Hans-Peter Zehrfeld),
4492 irie@@t.email.ne.jp (Irie Tetsuya),
4493 jackr@@dblues.engr.sgi.com (Jack Repenning),
4494 jamesm@@bga.com (D.J.@: Miller II),
4495 jjm@@hplb.hpl.hp.com (Jean-Jacques Moreau),
4496 jl@@cse.ogi.edu (John Launchbury),
4497 jobrien@@hchp.org (John O'Brien),
4498 johnw@@borland.com (John Wiegley),
4499 kanze@@gabi-soft.fr (James Kanze),
4500 kin@@isi.com (Kin Cho),
4501 kwzh@@gnu.org (Karl Heuer),
4502 lindstro@@biostat.wisc.edu (Mary Lindstrom),
4503 lektu@@terra.es (Juanma Barranquero),
4504 lennart.borgman.073@@student.lu.se (Lennart Borgman),
4505 minakaji@@osaka.email.ne.jp (Mikio Nakajima),
4506 Mark.Bordas@@East.Sun.COM (Mark Bordas),
4507 meyering@@comco.com (Jim Meyering),
4508 martin@@xemacs.org (Martin Buchholz),
4509 mbutler@@redfernnetworks.com (Malcolm Butler),
4510 mveiga@@dit.upm.es (Marcelino Veiga Tuimil),
4511 paulk@@summit.esg.apertus.com (Paul Keusemann),
4512 pfister@@cs.stonybrook.edu (Hanspeter Pfister),
4513 phil_brooks@@MENTORG.COM (Phil Brooks),
4514 pogrell@@informatik.hu-berlin.de (Lutz Pogrell),
4515 pradyut@@cs.uchicago.edu (Pradyut Shah),
4516 roderick@@argon.org (Roderick Schertler),
4517 rxga@@ulysses.att.com,
4518 sawdey@@lcse.umn.edu (Aaron Sawdey),
4519 simonb@@prl.philips.co.uk (Simon Blanchard),
4520 spadgett1@@nc.rr.com (Samuel Padgett),
4521 stephen@@farrell.org (Stephen Farrell),
4522 storm@@cua.dk (Kim F. Storm),
4523 sudish@@MindSpring.COM (Sudish Joseph),
4524 schwab@@issan.informatik.uni-dortmund.de (Andreas Schwab)
4525 terra@@diku.dk (Morten Welinder),
4526 thanh@@informatics.muni.cz (Han The Thanh),
4527 toma@@convex.convex.com,
4528 vrenjak@@sun1.racal.com (Milan Vrenjak),
4529 whicken@@dragon.parasoft.com (Wendell Hicken),
4530 zapman@@cc.gatech.edu (Jason Zapman II),
4531 @end example
4534 @node Key Index,Function Index,,Top
4535 @comment  node-name,  next,  previous,  up
4536 @unnumbered Key Index
4538 @printindex ky
4540 @node Function Index,Variable Index,Key Index,Top
4541 @comment  node-name,  next,  previous,  up
4542 @unnumbered Function Index
4544 @printindex fn
4546 @node Variable Index,Package Index,Function Index,Top
4547 @comment  node-name,  next,  previous,  up
4548 @unnumbered Variable Index
4550 @printindex vr
4552 @node Package Index,Concept Index,Variable Index,Top
4553 @comment  node-name,  next,  previous,  up
4554 @unnumbered Package Index
4556 @printindex pg
4558 @node Concept Index,,Package Index,Top
4559 @comment  node-name,  next,  previous,  up
4560 @unnumbered Concept Index
4562 @printindex cp
4564 @setchapternewpage odd
4565 @contents
4566 @bye
4568 @ignore
4569    arch-tag: f53e866a-15cf-4b1e-aead-77da9da1e864
4570 @end ignore