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