| blob | ed122372f8233441c64d67075f86f94b247bc0d9 |
1 .so mnx.mac
2 .TH ELVIS 9
3 .CD "elvis \(en clone of the Berkeley vi editor"
4 .SX "elvis \fR[\fB\(enRerv\fR] [\fB\(ent \fItag\fR] \fR[\fIfile\fR] ..."
5 .FL "\(enR" "Set the read-only option"
6 .FL "\(ene" "Start up emulating \fIex\fR"
7 .FL "\(enr" "Tell the user to use \fIelvrec\fR instead
8 .FL "\(ent" "Start editing at the given tag"
9 .FL "\(env" "Start up emulating \fIvi\fR"
10 .EX "elvis" "Call the editor"
11 .EX "elvis prog.c" "edit \fIprog.c\fR"
12 .PP
13 \fIElvis\fR is a full-screen editor closely modeled on the famous Berkeley
14 \fIvi\fR editor.
15 It provides essentially the same interface to the user as \fIvi\fR, but the
16 code is completely new, written from scratch.
17 This document provides a brief introduction to \fIvi\fR.
18 It is not intended as a tutorial for beginners.
19 Most books on
20 .Ux
21 cover \fIvi\fR.
22 .PP
23 Like \fIvi\fR, \fIelvis\fR can operate as a screen editor
24 (\fIvi\fR mode) or as a line editor (\fIex\fR) mode.
25 It can be called either as \fIelvis\fR \fIvi\fR,or as \fIex\fR,
26 depending on which is desired.
27 They are all links to the same file.
28 .SS "Vi Commands"
29 .PP
30 Below is a list of the \fIvi\fR commands supported.
31 The following symbols are used in the table:
32 .HS
33 .in +1.25i
34 .ta +1.0i
35 .ti -1.0i
36 count Integer parameter telling how many or how much
37 .ti -1.0i
38 key One character parameter to the command
39 .ti -1.0i
40 inp Interactive input expected
41 .ti -1.0i
42 mv Indicates how much for commands like \fIdelete\fR and \fIchange\fR:
43 .in +0.8i
44 .ta +0.3i
45 .ti -0.3i
46 ( Previous sentence
47 .ti -0.3i
48 ) Next sentence
49 .ti -0.3i
50 { Previous paragraph
51 .ti -0.3i
52 } Next paragraph (delimited by blank line, \fI.PP, .LP, .IP\fR etc.)
53 .ti -0.3i
54 [ Previous section (delimited by \fI.SH\fR or \fI.NH\fR)
55 .br
56 A repeated command character means the scope is this line
57 .in -0.8i
58 .ta +1.0i
59 .ti -1.0i
60 MOVE Indicates commands that may also be used where \fImv\fR is specified
61 .ti -1.0i
62 EDIT These commands affect text and may be repeated by the \fI.\fR command
63 .in -1.25i
64 .HS
65 In addition to the above notation, the caret (^) is used as an abbreviation
66 for CTRL.
67 For example, ^A means CTRL-A.
68 .HS
69 .in +2i
70 .ta +1i +1i +3.3i
71 .ti -2i
72 \fBCount~~~~ Command Description Type\fR
73 .ti -2i
74 ^A (Not defined)
75 .ti -2i
76 ^B Move toward the top of the file by 1 screenful
77 .ti -2i
78 ^C (Not defined)
79 .ti -2i
80 count ^D Scroll down \fIcount\fR lines (default 1/2 screen)
81 .ti -2i
82 count ^E Scroll up \fIcount\fR lines
83 .ti -2i
84 ^F Move toward the bottom of the file by 1 screenful
85 .ti -2i
86 ^G Show file status, and the current line
87 .ti -2i
88 count ^H Move left, like \fIh\fR MOVE
89 .ti -2i
90 ^I (Not defined)
91 .ti -2i
92 count ^J Move down MOVE
93 .ti -2i
94 ^K (Not defined)
95 .ti -2i
96 ^l Redraw the screen
97 .ti -2i
98 count ^M Move to the front of the next line MOVE
99 .ti -2i
100 count ^N Move down MOVE
101 .ti -2i
102 ^O (Not defined)
103 .ti -2i
104 count ^P Move up MOVE
105 .ti -2i
106 ^Q (Not defined)
107 .ti -2i
108 ^R Redraw the screen
109 .ti -2i
110 ^S (Not defined)
111 .ti -2i
112 ^T (Not defined)
113 .ti -2i
114 count ^U Scroll up \fIcount\fR lines (default 1/2 screen)
115 .ti -2i
116 ^V (Not defined)
117 .ti -2i
118 ^W (Not defined)
119 .ti -2i
120 ^X (Not defined)
121 .ti -2i
122 count ^Y Scroll down \fIcount\fR lines
123 .ti -2i
124 ^Z (Not defined)
125 .ti -2i
126 ESC (Not defined)
127 .ti -2i
128 ^\e (Not defined)
129 .ti -2i
130 ^] If the cursor is on a tag name, go to that tag
131 .ti -2i
132 ^^ Save this file and edit the previous file
133 .ti -2i
134 ^_ (Not defined)
135 .ti -2i
136 count SPACE Move right,like \fIl\fR MOVE
137 .ti -2i
138 ! mv Run the selected lines thru an external filter program
139 .ti -2i
140 " key Select which cut buffer to use next
141 .ti -2i
142 # (Not defined)
143 .ti -2i
144 $ Move to the rear of the current line MOVE
145 .ti -2i
146 % move to the matching (){}[] character MOVE
147 .ti -2i
148 & (Not defined)
149 .ti -2i
150 ' key Move to a marked line MOVE
151 .ti -2i
152 count ( Move backward \fIcount\fR sentences MOVE
153 .ti -2i
154 count ) Move forward \fIcount\fR sentences MOVE
155 .ti -2i
156 * (Not defined)
157 .ti -2i
158 count + Move to the front of the next line MOVE
159 .ti -2i
160 count , Repeat the previous [\fIfFtT\fR] but the other way MOVE
161 .ti -2i
162 count \(en Move to the front of the preceding line MOVE
163 .ti -2i
164 . Repeat the previous \*(OQedit\*(CQ command
165 .ti -2i
166 / Text search forward for a given regular expr MOVE
167 .ti -2i
168 0 If not part of count, move to 1st char of this line MOVE
169 .ti -2i
170 1 Part of count
171 .ti -2i
172 2 Part of count
173 .ti -2i
174 3 Part of count
175 .ti -2i
176 4 Part of count
177 .ti -2i
178 5 Part of count
179 .ti -2i
180 6 Part of count
181 .ti -2i
182 7 Part of count
183 .ti -2i
184 8 Part of count
185 .ti -2i
186 9 Part of count
187 .ti -2i
188 : Text. Run single \fIex\fR cmd
189 .ti -2i
190 count ; Repeat the previous [fFtT] cmd MOVE
191 .ti -2i
192 count < mv Shift text left EDIT
193 .ti -2i
194 = (Not defined)
195 .ti -2i
196 count > mv Shift text right EDIT
197 .ti -2i
198 ? text Search backward for a given regular expression MOVE
199 .ti -2i
200 @ (Not defined)
201 .ti -2i
202 count A inp Append at end of the line EDIT
203 .ti -2i
204 count B Move back Word MOVE
205 .ti -2i
206 C inp Change text from cursor through end of line EDIT
207 .ti -2i
208 D Delete text from cursor through end of line EDIT
209 .ti -2i
210 count E Move end of Word MOVE
211 .ti -2i
212 count F key Move leftward to a given character MOVE
213 .ti -2i
214 count G Move to line #\fIcount\fR (default is the bottom line) MOVE
215 .ti -2i
216 count H Move to home row (the line at the top of the screen)
217 .ti -2i
218 count I inp Insert at the front of the line (after indents) EDIT
219 .ti -2i
220 count J Join lines, to form one big line EDIT
221 .ti -2i
222 K Look up keyword
223 .ti -2i
224 count L Move to last row (the line at the bottom of the screen)
225 .ti -2i
226 M Move to middle row (the line in the middle)
227 .ti -2i
228 N Repeat previous search, but the opposite way MOVE
229 .ti -2i
230 count O inp Open up a new line above the current line EDIT
231 .ti -2i
232 P Paste text before the cursor
233 .ti -2i
234 Q Quit to EX mode
235 .ti -2i
236 R inp Overtype EDIT
237 .ti -2i
238 count S inp Change lines, like \fIcount\fRcc
239 .ti -2i
240 count T key Move leftward \fIalmost\fR to a given character MOVE
241 .ti -2i
242 U Undo all recent changes to the current line
243 .ti -2i
244 V (Not defined)
245 .ti -2i
246 count W Move forward \fIcount\fR Words MOVE
247 .ti -2i
248 count X Delete the character(s) to the left of the cursor EDIT
249 .ti -2i
250 count Y Yank text line(s) (copy them into a cut buffer)
251 .ti -2i
252 Z Z Save the file & exit
253 .ti -2i
254 [ [ Move back 1 section MOVE
255 .ti -2i
256 \e (Not defined)
257 .ti -2i
258 ] ] Move forward 1 section MOVE
259 .ti -2i
260 ^ Move to the front of the current line (after indent) MOVE
261 .ti -2i
262 \(ul (Not defined)
263 .ti -2i
264 ` key Move to a marked character MOVE
265 .ti -2i
266 count a inp Insert text after the cursor EDIT
267 .ti -2i
268 count b Move back \fIcount\fR words MOVE
269 .ti -2i
270 c mv Change text EDIT
271 .ti -2i
272 d mv Delete text EDIT
273 .ti -2i
274 count e Move forward to the end of the current word MOVE
275 .ti -2i
276 count f key Move rightward to a given character MOVE
277 .ti -2i
278 g (Not defined)
279 .ti -2i
280 count h Move left MOVE
281 .ti -2i
282 count i inp Insert text at the cursor EDIT
283 .ti -2i
284 count j Move down MOVE
285 .ti -2i
286 count k Move up MOVE
287 .ti -2i
288 count l Move right MOVE
289 .ti -2i
290 m key Mark a line or character
291 .ti -2i
292 n Repeat the previous search MOVE
293 .ti -2i
294 count o inp Open a new line below the current line EDIT
295 .ti -2i
296 p Paste text after the cursor
297 .ti -2i
298 q (Not defined)
299 .ti -2i
300 count r key Replace \fIcount\fR chars by a given character EDIT
301 .ti -2i
302 count s inp Replace \fIcount\fR chars with text from the user EDIT
303 .ti -2i
304 count t key Move rightward \fIalmost\fR to a given character MOVE
305 .ti -2i
306 u Undo the previous edit command
307 .ti -2i
308 v (Not defined)
309 .ti -2i
310 count w Move forward \fIcount\fR words MOVE
311 .ti -2i
312 count x Delete the character that the cursor's on EDIT
313 .ti -2i
314 y mv Yank text (copy it into a cut buffer)
315 .ti -2i
316 z key Scroll current line to the screen's +=top -=bottom .=middle
317 .ti -2i
318 count { Move back \fIcount\fR paragraphs MOVE
319 .ti -2i
320 count | Move to column \fIcount\fR (the leftmost column is 1)
321 .ti -2i
322 count } Move forward \fIcount\fR paragraphs MOVE
323 .ti -2i
324 .tr ~~
325 count \(ap Switch a character between upper & lower case EDIT
326 .tr ~
327 .ti -2i
328 DEL (Not defined)
329 .in -2i
330 .SS "Ex Commands"
331 .PP
332 Below is a list of the \fIex\fR commands supported. All can be abbreviated.
333 .UU "General"
334 .LP
335 .nf
336 .ta 1.2i 2.4i
337 [line] append
338 args [files]
339 cd [directory]
340 chdir [directory]
341 [line][,line] change
342 [line][,line] copy line
343 [line][,line] debug[!]
344 [line][,line] Delete [\*(CQx]
345 edit[!] [file]
346 ex[!] [file]
347 file
348 [line][,line] global /regexp/ command
349 [line] Insert
350 [line][,line] join
351 [line][,line] list
352 map[!] key mapped_to
353 [line] mark x
354 mkexrc
355 [line][,line] Move line
356 next[!] [files]
357 Next[!]
358 previous[!]
359 [line][,line] print
360 [line] put [\*(CQx]
361 quit[!]
362 [line] read file
363 rewind[!]
364 set [options]
365 [line][,line] substitute /regexp/replacement/[p][g]
366 tag[!] tagname
367 [line][,line] to line
368 Undo
369 unmap[!] key
370 validate[!]
371 version
372 [line][,line] vglobal /regexp/ command
373 visual
374 wq
375 [line][,line] write[!] [[>>]file]
376 xit[!]
377 [line][,line] yank [\*(CQx]
378 [line][,line] ! command
379 [line][,line] <
380 [line][,line] =
381 [line][,line] >
382 .SP 0.25
383 .UU "Text Entry"
384 .SP 0.25
385 .LP
386 .ta 1.2i 2.4i
387 .nf
388 [line] append
389 [line][,line] change [\*(CQx]
390 [line] Insert
391 .fi
393 The (a)ppend command inserts text after the specified line.
395 The (i)nsert command inserts text before the specified line.
397 The (c)hange command copies the range of lines into a cut buffer,
398 deletes them, and inserts new text where the old text used to be.
400 For all of these commands, you indicate the end of the text you're
401 inserting by hitting ^D or by entering a line which contains only
402 a period.
403 .SP 0.25
404 .UU "Cut & Paste"
405 .SP 0.25
406 .LP
407 .ta 1.2i 2.4i
408 .nf
409 [line][,line] Delete [\*(CQx]
410 [line][,line] yank [\*(CQx]
411 [line] put[!] [\*(CQx]
412 [line][,line] copy line
413 [line][,line] to line
414 [line][,line] Move line
416 .fi
417 The (d)elete command copies the specified range of lines into a
418 cut buffer, and then deletes them.
420 The (y)ank command copies the specified range of lines into a cut
421 buffer, but does \fInot\fR delete them.
423 The (pu)t command inserts text from a cut buffer after the specified
424 line\(emor before it if the ! is present.
426 The (co)py and (t)o commands yank the specified range of lines and then
427 immediately paste them after some other line.
429 The (m)ove command deletes the specified range of lines and then
430 immediately pastes them after some other line. If the destination
431 line comes after the deleted text, then it will be adjusted
432 automatically to account for the deleted lines.
433 .UU "Displaying Text"
434 .LP
435 .ta 1.2i 2.4i
436 .nf
437 [line][,line] print
438 [line][,line] list
440 .fi
441 The (p)rint command displays the specified range of lines.
443 The (l)ist command also displays them, but it is careful to make
444 control characters visible.
445 .UU "Global Operations"
446 .LP
447 .ta 1.2i 2.4i
448 .nf
449 [line][,line] global /regexp/ command
450 [line][,line] vglobal /regexp/ command
452 .fi
453 The (g)lobal command searches through the lines of the specified range
454 (or through the whole file if no range is specified) for lines that
455 contain a given regular expression. It then moves the cursor to each
456 of these lines and runs some other command on them.
458 The (v)global command is similar, but it searches for lines that
459 \fIdo not\fR contain the regular expression.
460 .UU "Line Editing"
461 .LP
462 .ta 1.2i 2.4i
463 .nf
464 [line][,line] join
465 [line][,line] ! program
466 [line][,line] <
467 [line][,line] >
468 [line][,line] substitute /regexp/replacement/[p][g]
470 .fi
471 The (j)oin command concatenates all lines in the specified range together
472 to form one big line. If only a single line is specified, then the
473 following line is catenated onto it.
475 The ! command runs an external filter program, and feeds the specified
476 range of lines to it's stdin. The lines are then replaced by the
477 output of the filter. A typical example would be \*(OQ:'a,'z!sort -n\*(CQ to
478 sort the lines 'a,'z according to their numeric values.
480 The < and > commands shift the specified range of lines left or right,
481 normally by the width of 1 tab character. The \*(OQshiftwidth\*(CQ option
482 determines the shifting amount.
484 The (s)ubstitute command finds the regular expression in each line,
485 and replaces it with the replacement text. The \*(OQp\*(CQ option causes
486 the altered lines to be printed, and the \*(OQg\*(CQ option permits all
487 instances of the regular expression to be found & replaced. (Without
488 \*(OQg\*(CQ, only the first occurrence is replaced.)
489 .SP 0.25
490 .UU "Undo"
491 .SP 0.25
492 .LP
493 .ta 1.2i 2.4i
494 .nf
495 undo
497 .fi
498 The (u)ndo command restores the file to the state it was in before your
499 most recent command which changed text.
500 .SP 0.25
501 .UU "Configuration & Status"
502 .SP 0.25
503 .LP
504 .ta 1.2i 2.4i
505 .nf
506 map[!] [key mapped_to]
507 unmap[!] key
508 set [options]
509 mkexrc
510 [line] mark x
511 visual
512 version
513 [line][,line] =
514 file
516 .fi
517 The (ma)p command allows you to configure \fIelvis\fR to recognize your
518 function keys, and treat them as though they transmitted some other
519 sequence of characters. Normally this mapping is done only when in
520 the visual command mode, but with the [!] present it will map keys
521 under all contexts. When this command is given with no arguments,
522 it prints a table showing all mappings currently in effect. When
523 called with two arguments, the first is the sequence that your
524 function key really sends, and the second is the sequence that you
525 want \fIelvis\fR to treat it as having sent.
527 The (unm)ap command removes key definitions that were made via the
528 map command.
530 The (se)t command allows you examine or set various options. With
531 no arguments, it displays the values of options that have been
532 changed. With the single argument \*(OQall\*(CQ it displays the values of
533 all options, regardless of whether they've been explicitly set or
534 not. Otherwise, the arguments are treated as options to be set.
536 The (mk)exrc command saves the current configuration to a file
537 called \fI.exrc\fR in the current directory.
539 The mar(k) command defines a named mark to refer to a specific place
540 in the file. This mark may be used later to specify lines for other
541 commands.
543 The (vi)sual command puts the editor into visual mode. Instead of
544 emulating ex, \fIelvis\fR will start emulating vi.
546 The (ve)rsion command tells you that what version of \fIelvis\fR this is.
548 The = command tells you what line you specified, or, if you specified
549 a range of lines, it will tell you both endpoints and the number of
550 lines included in the range.
552 The file command tells you the name of the file, whether it has been
553 modified, the number of lines in the file, and the current line number.
554 .UU "Multiple Files"
555 .LP
556 .ta 1.2i 2.4i
557 .nf
558 args [files]
559 next[!] [files]
560 Next[!]
561 previous[!]
562 rewind[!]
564 .fi
565 When you invoke \fIelvis\fR from your shell's command line, any filenames
566 that you give to \fIelvis\fR as arguments are stored in the args list. The
567 (ar)gs command will display this list, or define a new one.
569 The (n)ext command switches from the current file to the next one in
570 the args list. You may specify a new args list here, too.
572 The (N)ext and (pre)vious commands (they're really aliases for the same
573 command) switch from the current file to the preceding file in the
574 args list.
576 The (rew)ind command switches from the current file to the first file
577 in the args list.
578 .SP 1
579 .UU "Switching Files"
580 .SP 1
581 .LP
582 .ta 1.2i 2.4i
583 .nf
584 edit[!] [file]
585 tag[!] tagname
587 .fi
588 The (e)dit command allows to switch from the current file to some other
589 file. This has nothing to do with the args list, by the way.
591 The (ta)g command looks up a given tagname in a file called \*(OQtags".
592 This tells it which file the tag is in, and how to find it in that file.
593 \fIElvis\fR then switches to the tag's file and finds the tag.
594 .SP 1
595 .UU "Exiting"
596 .SP 1
597 .LP
598 .ta 1.2i 2.4i
599 .nf
600 quit[!]
601 wq
602 xit
604 .fi
605 The (q)uit command exits from the editor without saving your file.
607 The (wq) and (x)it commands (really two names for the same command)
608 both write the file before exiting.
609 .UU "File I/O"
610 .LP
611 .ta 1.2i 2.4i
612 .nf
613 [line] read file
614 [line][,line] write[!][[>>]file]
616 .fi
617 The (r)ead command gets text from another file and inserts it after
618 the specified line.
620 .fi
621 The (w)rite command writes the whole file, or just part of it, to
622 some other file. The !, if present, will permit the lines to be
623 written even if you've set the readonly option. If you precede the
624 filename by >> then the lies will be appended to the file.
625 .UU "Directory"
626 .LP
627 .ta 1.2i 2.4i
628 .nf
629 cd [directory]
630 chdir [directory]
631 shell
633 .fi
634 The (cd) and (chd)ir commands (really two names for one command)
635 switch the current working directory.
637 The (sh)ell command starts an interactive shell.
638 .SP 0.5
639 .UU "Debugging"
640 .SP 0.5
641 .LP
642 .ta 1.2i 2.4i
643 .nf
644 [line][,line] debug[!]
645 validate[!]
647 .fi
648 These commands are only available if you compile \fIelvis\fR with the
649 \fB-DDEBUG\fR flag.
651 The de(b)ug command lists stats for the blocks which contain the
652 specified range of lines. If the ! is present, then the contents
653 of those blocks is displayed, too.
655 The (va)lidate command checks certain variables for internal
656 consistency. Normally it does not output anything unless it detects
657 a problem. With the !, though, it will always produce *some*
658 output.
659 .SP 0.5
660 .SS "Extensions"
661 .SP 0.5
662 .PP.
663 .ta 1i
664 .in +0.25i
665 In addition to the standard commands, a variety of extra features are
666 present in \fIelvis\fR that are not present in \fIvi\fR.
667 They are described below.
669 .ti -0.25i
670 .B .exrc
671 .br
672 \fIElvis\fR first runs a \fI.exrc\fR file (if there is one) from your $HOME
673 directory. After that, it runs a \fI.exrc\fR (if there is one) from the
674 current directory. The one in the current directory may override
675 settings made by the one in the $HOME directory.
677 .ti -0.25i
678 .B :mkexrc
679 .ti -0.25i
680 .B :mk
681 .br
682 This EX command saves the current :set and :map configurations in
683 the \*(OQ.exrc\*(CQ file in your current directory.
685 .ti -0.25i
686 .B :args
687 .ti -0.25i
688 .B :ar
689 .br
690 You can use the :args command to define a new args list, as in:
692 :args *.h
694 After you have defined a new args list, the next time you issue a
695 :next command \fIelvis\fR will switch to the first file of the new list.
697 .ti -0.25i
698 .B :Next
699 .ti -0.25i
700 .B :previous
701 .ti -0.25i
702 .B :N
703 .ti -0.25i
704 .B :pre
705 .br
706 These commands move backwards through the args list.
708 .ti -0.25i
709 .B zz
710 .br
711 In VI, the (lowercase) \*(OQzz\*(CQ command will center the current line on
712 the screen, like \*(OQz="
714 .ti -0.25i
715 .B .
716 .br
717 The default count value for . is the same as the previous command
718 which . is meant to repeat. However, you can supply a new count
719 if you wish.
720 For example, after \*(OQ3dw\*(CQ, \*(OQ.\*(CQ will delete 3 words,
721 but \*(OQ5.\*(CQ will delete 5 words.
723 .ti -0.25i
724 \fB"\fR
725 .br
726 The text which was most recently input (via a \*(OQcw\*(CQ command, or
727 something similar) is saved in a cut buffer called ". (which is a
728 pretty hard name to write in an English sentence). You can use this
729 with the \*(OQp\*(CQ or \*(OQP\*(CQ commands thusly:
730 .HS
731 ".p
732 .HS
733 .ti -0.25i
734 .B K
735 .br
736 You can move the cursor onto a word and press shift-K to have \fIelvis\fR
737 run a reference program to look that word up. This command alone is
738 worth the price of admission! See the ctags and ref programs.
740 .ti -0.25i
741 .B input
742 .br
743 You can backspace back past the beginning of the line.
744 If you type CTRL-A, then the text that you input last time is
745 inserted. You will remain in input mode, so you can backspace over
746 part of it, or add more to it. (This is sort of like CTRL-@ on
747 the real vi, except that CTRL-A really works.)
749 Real \fIvi\fR can only remember up to 128 characters of input, but \fIelvis\fR
750 can remember any amount.
752 .ti -0.25i
753 .B :set
754 charattr
755 .ti -0.25i
756 .B :se
757 ca
758 .br
759 \fIElvis\fR can display \*(OQbackslash-f\*(CQ style character attributes on the
760 screen as you edit. The following example shows the recognized
761 attributes:
763 normal \fBboldface\fR \fIitalics\fR
765 NOTE: you must compile \fIelvis\fR without the \(enDSET_NOCHARATTR flag for
766 this to work.
767 .in -0.25i
768 .SS "Omissions"
769 .PP
770 A few \fIvi\fR features are missing.
771 The replace mode is a hack. It does not save the text that it overwrites.
772 .PP
773 Long lines are displayed differently\(emwhere the real vi would wrap a long
774 line onto several rows of the screen, \fIelvis\fR simply displays part of the line,
775 and allows you to scroll the screen sideways to see the rest of it.
776 .PP
777 The \*(OQ:preserve\*(CQ and \*(OQ:recover\*(CQ commands are missing, as
778 is the \fB\(enr\fR flag.
779 \*(OQ:Preserve" is practically never used and since use of \*(OQ:recover\\*(CQ
780 is so rare, it was decided to implement it as a separate program. There's no
781 need to load the recovery code into memory every time you edit a file.
782 .PP
783 LISP support is missing.
784 The \*(OQ@\*(CQ and \*(OQ:@\*(CQ commands are missing.
785 You cannot APPEND to a cut buffer.
786 .SS "Options"
787 .PP
788 A variety of options can be set as described below:
789 .HS
790 .nf
791 .in +0.25i
792 .ta 0.9i 1.35i 2.1i 3.0i
793 \fBName Abbr Type Default Description\fR
794 autoindent as Bool FALSE autoindent during input?
795 autowrite aw Bool FALSE write file for :n command?
796 charattr ca Bool FALSE display bold & underline chars?
797 columns co Number 80 width of screen, in characters
798 directory dir String /usr/tmp where tmp files are kept
799 errorbells eb Bool TRUE ring bell on error?
800 exrefresh er Bool TRUE EX mode calls write() often?
801 ignorecase ic Bool FALSE searches: upper/lowercase OK?
802 keytime kt Number 1 allow slow receipt of ESC seq?
803 keywordprg kp String /usr/bin/ref program to run for shift-K
804 lines ln Number 25 height of screen, in lines
805 list li Bool FALSE show tabs as \*(OQ^I\*(CQ?
806 magic ma Bool TRUE searches: allow metacharacters?
807 paragraphs pa String PPppPApa paragraphs start with .PP, etc.
808 readonly ro Bool FALSE no file should be written back?
809 report re Number 5 report changes to X lines?
810 scroll sc Number 12 default #lines for ^U and ^D
811 sections se String SEseSHsh sections start with .SE, etc.
812 shell sh String \fI/bin/sh\fR shell program, from environment
813 shiftwidth sw Number 8 width of < or > commands
814 sidescroll ss Number 8 #chars to scroll sideways by
815 sync sy Bool FALSE call sync() after each change?
816 tabstop ts Number 8 width of a tab character
817 term te String "?" terminal type, from environment
818 vbell vb Bool TRUE use visible bell if possible?
819 warn wa Bool TRUE warn if file not saved for :!cmd
820 wrapmargin wm Number 0 Insert newline after which col?
821 wrapscan ws Bool TRUE searches: wrap at EOF?
823 .fi
824 .ti -0.25i
825 .B autoindent
826 .br
827 During input mode, the autoindent option will cause each added line
828 to begin with the same amount of leading whitespace as the line above
829 it. Without autoindent, added lines are initially empty.
831 .ti -0.25i
832 .B autowrite
833 .br
834 When you're editing one file and decide to switch to another\(emvia
835 the :tag command, or :next command, perhaps\(emif your current
836 file has been modified, then \fIelvis\fR will normally print an error
837 message and refuse to switch.
839 However, if the autowrite option is on, then \fIelvis\fR will write the
840 modified version of the current file and successfully switch to the
841 new file.
843 .ti -0.25i
844 .B charattr
845 .br
846 Many text formatting programs allow you to designate portions of
847 your text to be underlined, italicized, or boldface by embedding
848 the special strings \\fU, \\fI, and \\fB in your text. The special
849 string \\fR marks the end of underlined or boldface text.
851 \fIElvis\fR normally treats those special strings just like any other
852 text.
853 However, if the \fIcharattr\fR option is on, then \fIelvis\fR will interpret
854 those special strings correctly, to display underlined or boldface
855 text on the screen. (This only works, of course, if your terminal
856 can display underlined and boldface, and if the TERMCAP entry says
857 how to do it.)
859 .ti -0.25i
860 .B columns
861 .br
862 This is a \*(OQread only\*(CQ option. You cannot change its value, but you
863 can have \fIelvis\fR print it. It shows how wide your screen is.
865 .ti -0.25i
866 .B directory
867 .br
868 Elvis uses temporary files to store changed text.
869 This option allows you to control where those temporary files will be.
870 Ideally, you should store them on in fast non-volatile memory,
871 such as a hard disk.
873 This option can only be set in the ".exrc" file.
875 .ti -0.25i
876 .B errorbells
877 .br
878 Normally, \fIelvis\fR will ring your terminal's bell if you make an error.
879 However, in noerrorbells mode, your terminal will remain silent.
881 .ti -0.25i
882 .B exrefresh
883 .br
884 The EX mode of \fIelvis\fR writes many lines to the screen. You can make
885 \fIelvis\fR either write each line to the screen separately, or save up
886 many lines and write them all at once.
888 The exrefresh option is normally on, so each line is written to the
889 screen separately.
891 You may wish to turn the exrefresh option off (:se noer) if the
892 \*(OQwrite\*(CQ system call is costly on your machine, or if you're using a
893 windowing environment. (Windowing environments scroll text a lot
894 faster when you write many lines at once.)
896 This option has no effect in \fIvi\fR mode.
898 .ti -0.25i
899 .B ignorecase
900 .br
901 Normally, when \fIelvis\fR searches for text, it treats uppercase letters
902 as being different for lowercase letters.
904 When the ignorecase option is on, uppercase and lowercase are treated
905 as equal.
907 .ti -0.25i
908 .B keytime
909 .br
910 The arrow keys of most terminals send a multi-character sequence.
911 It takes a measurable amount of time for these sequences to be
912 transmitted. The keytime option allows you to control the maximum
913 amount of time to allow for an arrow key (or other mapped key) to
914 be received in full.
916 The default keytime value is 2. Because of the way
917 .Ux
918 timekeeping works, the actual amount of time allowed will vary slightly, but it
919 will always be between 1 and 2 seconds.
921 If you set keytime to 1, then the actual amount of time allowed will
922 be between 0 and 1 second. This will generally make the keyboard's
923 response be a little faster (mostly for the ESC key), but on those
924 occasions where the time allowed happens to be closer to 0 than 1
925 second, \fIelvis\fR may fail to allow enough time for an arrow key's
926 sequence to be received fully. Ugh.
928 As a special case, you can set keytime to 0 to disable this time
929 limit stuff altogether. The big problem here is: If your arrow
930 keys' sequences start with an ESC, then every time you hit your ESC
931 key \fIelvis\fR will wait... and wait... to see if maybe that ESC was
932 part of an arrow key's sequence.
934 NOTE: this option is a generalization of the timeout option of the
935 real vi.
937 .ti -0.25i
938 .B keywordprg
939 .br
940 \fIElvis\fR has a special keyword lookup feature. You move the cursor
941 onto a word, and hit shift-K, and \fIelvis\fR uses another program to
942 look up the word and display information about it.
944 This option says which program gets run. It should contain the full
945 pathname of the program; your whole execution path is \fInot\fR checked.
947 The default value of this option is \fI/usr/bin/ref\fR, which is a
948 program that looks up the definition of a function in C. It looks
949 up the function name in a file called \*(OQrefs\*(CQ which is created by
950 ctags.
952 You can substitute other programs, such as an English dictionary
953 program or the online manual. \fIelvis\fR runs the program, using the
954 keyword as its only argument. The program should write information
955 to stdout. The program's exit status should be 0, unless you want
956 \fIelvis\fR to print \*(OQ<<< failed >>>".
958 .ti -0.25i
959 .B lines
960 .br
961 This \*(OQread only\*(CQ option shows how many lines you screen has.
963 .ti -0.25i
964 .B list
965 .br
966 Normally (in \*(OQnolist" mode) \fIelvis\fR will expand tabs to the proper
967 number of spaces on the screen, so that the file appears the same would it would
968 be if you printed it or looked at it with \fImore\fR.
970 Sometimes, though, it can be handy to have the tabs displayed as \*(OQ^I".
971 In \*(OQlist" mode, \fIelvis\fR does this, and also displays a \*(OQ$"
972 after the end of the line.
974 .ti -0.25i
975 .B magic
976 .br
977 The search mechanism in \fIelvis\fR can accept \*(OQregular
978 expressions\*(CQ\(emstrings in which certain characters have special meaning.
979 The magic option is normally on, which causes these characters to
980 be treated specially.
981 If you turn the magic option off (:se noma), then all characters
982 except ^ and $ are treated literally. ^ and $ retain their special
983 meanings regardless of the setting of magic.
985 .ti -0.25i
986 .B paragraphs
987 .br
988 The { and } commands move the cursor forward or backward in increments
989 of one paragraph. Paragraphs may be separated by blank lines, or by
990 a \*(OQdot\*(CQ command of a text formatter. Different text formatters use
991 different \*(OQdot\*(CQ commands. This option allows you to configure \fIelvis\fR
992 to work with your text formatter.
994 It is assumed that your formatter uses commands that start with a
995 ".\*(CQ character at the front of a line, and then have a one- or
996 two-character command name.
998 The value of the paragraphs option is a string in which each pair
999 of characters is one possible form of your text formatter's paragraph
1000 command.
1002 .ti -0.25i
1003 .B readonly
1004 .br
1005 Normally, \fIelvis\fR will let you write back any file to which you have
1006 write permission. If you do not have write permission, then you
1007 can only write the changed version of the file to a \fIdifferent\fR
1008 file.
1010 If you set the readonly option, then \fIelvis\fR will pretend you do not
1011 have write permission to \fIany\fR file you edit. It is useful when
1012 you really only mean to use \fIelvis\fR to look at a file, not to change
1013 it. This way you cannot change it accidentally.
1015 This option is normally off, unless you use the \*(OQview\*(CQ alias of \fIelvis\fR.
1016 \*(OQView\*(CQ is like \fIvi\fR except that the readonly option is on.
1018 .ti -0.25i
1019 .B report
1020 .br
1021 Commands in \fIelvis\fR may affect many lines. For commands that affect
1022 a lot of lines, \fIelvis\fR will output a message saying what was done and
1023 how many lines were affected. This option allows you to define
1024 what \*(OQa lot of lines\*(CQ means. The default is 5, so any command which
1025 affects 5 or more lines will cause a message to be shown.
1027 .ti -0.25i
1028 .B scroll
1029 .br
1030 The CTRL-U and CTRL-D keys normally scroll backward or forward
1031 by half a screenful, but this is adjustable. The value of this option
1032 says how many lines those keys should scroll by.
1034 .ti -0.25i
1035 .B sections
1036 .br
1037 The [[ and ]] commands move the cursor backward or forward in
1038 increment of 1 section. Sections may be delimited by a { character
1039 in column 1 (which is useful for C source code) or by means of
1040 a text formatter's \*(OQdot\*(CQ commands.
1042 This option allows you to configure \fIelvis\fR to work with your text
1043 formatter's \*(OQsection\*(CQ command, in exactly the same way that the
1044 paragraphs option makes it work with the formatter's \*(OQparagraphs"
1045 command.
1047 .ti -0.25i
1048 .B shell
1049 .br
1050 When \fIelvis\fR forks a shell (perhaps for the :! or :shell commands)
1051 this is the program that is uses as a shell. This is \fI/bin/sh\fR
1052 by default, unless you have set the SHELL environment variable,
1053 it which case the default value is copied from the environment.
1055 .ti -0.25i
1056 .B shiftwidth
1057 .br
1058 The < and > commands shift text left or right by some uniform number
1059 of columns. The shiftwidth option defines that uniform number.
1060 The default is 8.
1062 .ti -0.25i
1063 .B sidescroll
1064 .br
1065 For long lines, \fIelvis\fR scrolls sideways. (This is different from
1066 the real \fIvi\fR, which wraps a single long line onto several rows of
1067 the screen.)
1068 To minimize the number of scrolls needed, \fIelvis\fR moves the screen
1069 sideways by several characters at a time. The value of this option
1070 says how many characters' widths to scroll at a time.
1071 Generally, the faster your screen can be redrawn, the lower the value
1072 you will want in this option.
1074 .ti -0.25i
1075 .B sync
1076 .br
1077 If the system crashes during an edit session, then most of your work
1078 can be recovered from the temporary file that \fIelvis\fR uses to store
1079 changes. However, sometimes
1080 .MX
1081 will not copy changes to the
1082 hard disk immediately, so recovery might not be possible. The [no]sync
1083 option lets you control this.
1084 In nosync mode (which is the default), \fIelvis\fR lets the operating system
1085 control when data is written to the disk. This is generally faster.
1086 In sync mode, \fIelvis\fR forces all changes out to disk every time you make
1087 a change. This is generally safer, but slower.
1089 .ti -0.25i
1090 .B tabstop
1091 .br
1092 Tab characters are normally 8 characters wide, but you can change
1093 their widths by means of this option.
1095 .ti -0.25i
1096 .B term
1097 .br
1098 This \*(OQread only\*(CQ option shows the name of the termcap entry that
1099 \fIelvis\fR is using for your terminal.
1101 .ti -0.25i
1102 .B vbell
1103 .br
1104 If your termcap entry describes a visible alternative to ringing
1105 your terminal's bell, then this option will say whether the visible
1106 version gets used or not. Normally it will be.
1108 If your termcap does NOT include a visible bell capability, then
1109 the vbell option will be off, and you cannot turn it on.
1111 .ti -0.25i
1112 .B warn
1113 .br
1114 \fIElvis\fR will normally warn you if you run a shell command without saving
1115 your changed version of a file.
1116 The \*(OQnowarn" option prevents this warning.
1118 .ti -0.25i
1119 .B wrapmargin
1120 .br
1121 Normally (with wrapmargin=0) \fIelvis\fR will let you type in extremely long
1122 lines, if you wish.
1123 However, with wrapmargin set to something other that 0 (wrapmargin=65
1124 is nice), \fIelvis\fR will automatically cause long lines to be \*(OQwrapped"
1125 on a word break for lines longer than wrapmargin's setting.
1127 .ti -0.25i
1128 .B wrapscan
1129 .br
1130 Normally, when you search for something, \fIelvis\fR will find it no matter
1131 where it is in the file. \fIelvis\fR starts at the cursor position, and
1132 searches forward. If \fIelvis\fR hits EOF without finding what you're
1133 looking for, then it wraps around to continue searching from line 1.
1135 If you turn off the wrapscan option (:se nows), then when \fIelvis\fR hits
1136 EOF during a search, it will stop and say so.
1137 .in -0.25i
1138 .SS "Cflags"
1139 .PP
1140 \fIElvis\fR uses many preprocessor symbols to control compilation.
1141 Most of these flags allow you to disable small sets of features.
1142 \s-2MINIX\s0-ST users will probably want all features enabled, but
1143 \s-2MINIX\s0-PC users will have to disable one or two feature sets
1144 because otherwise \fIelvis\fR would be too large to compile and run.
1146 These symbols can be defined via flags passed to the compiler.
1147 The best way to do this is to edit the Makefile, and append the flag
1148 to the \*(OQCFLAGS=\*(CQ line.
1149 After you do that, you must recompile elvis completely by saying
1150 .HS
1151 .Cx "make clean"
1152 .br
1153 .Cx "make"
1154 .HS
1155 .in +0.25i
1156 .ti -0.25i
1157 .B \(enDM_SYSV
1158 .br
1159 This flag causes \fIelvis\fR to use System-V ioctl() calls for controlling
1160 your terminal; normally it uses v7/BSD/\s-2MINIX\s0 ioctl() calls.
1162 .ti -0.25i
1163 .B \(enDDATE
1164 .br
1165 The symbol DATE should be defined to look like a string constant,
1166 giving the date when \fIelvis\fR was compiled.
1167 This date is reported by the \*(OQ:version\*(CQ command.
1169 You can also leave DATE undefined, in which case \*(OQ:version\*(CQ will not
1170 report the compilation date.
1172 .ti -0.25i
1173 .B \(enDCRUNCH
1174 .br
1175 This flag causes several large often-used macros to be replaced by
1176 equivalent functions.
1177 This saves about 4K of space in the \*(OQ.text\*(CQ segment, and it does not
1178 cost you any features.
1180 .ti -0.25i
1181 .B \(enDDEBUG
1182 .br
1183 This adds many internal consistency checks and the \*(OQ:debug\*(CQ
1184 and \*(OQ:validate\*(CQ
1185 commands. It increases the size of \*(OQtext\*(CQ by about 5K bytes.
1187 .ti -0.25i
1188 .B \(enDNO_CHARATTR
1189 .br
1190 This permanenently disables the \*(OQcharattr\*(CQ option.
1191 It reduces the size of \*(OQ.text\*(CQ by about 850 bytes.
1193 .ti -0.25i
1194 .B \(enDNO_RECYCLE
1195 .br
1196 Normally, \fIelvis\fR will recycle space in the temporary file which contains
1197 totally obsolete text.
1198 The \fB\(enDNO_RECYCLE\fR option disables this, making your \*(OQ.text\*(CQ segment
1199 smaller by about 1K but also permitting the temporary file to grow very
1200 quickly.
1201 If you have less than two megabytes of free space on your disk,
1202 then do not even consider using this flag.
1204 .ti -0.25i
1205 .B \(enDNO_SENTENCE
1206 .br
1207 This leaves out the \*(OQ(\*(CQ and \*(OQ)\*(CQ visual commands, and
1208 removes the code that allows the \*(OQ[[\*(CQ, \*(OQ]]\*(CQ, \*(OQ{\*(CQ,
1209 and \*(OQ}\*(CQ commands to recognize \fRnroff\fR macros.
1210 The \*(OQ[[\*(CQ and \*(OQ]]\*(CQ commands will still move to the start of
1211 the previous/next C function source code, though, and \*(OQ{\*(CQ
1212 and \*(OQ}\*(CQ will move to the previous/next blank line.
1213 This saves about 650 bytes from the \*(OQ.text\*(CQ segment.
1215 .ti -0.25i
1216 .B \(enDNO_CHARSEARCH
1217 .br
1218 This leaves out the visual commands which locate a given character in the
1219 current line: \*(OQf\*(CQ, \*(OQt\*(CQ, \*(OQF\*(CQ, \*(OQT\*(CQ, \*(OQ;\*(CQ, and \*(OQ,\*(CQ.
1220 This saves about 900 bytes.
1222 .ti -0.25i
1223 .B \(enDNO_EXTENSIONS
1224 .br
1225 This leaves out the \*(OQ:mkexrc\*(CQ command, and the \*(OQK\*(CQ and \*(OQ#\*(CQ visual commands.
1226 Other extensions are either inherent in the design of \fIelvis\fR,
1227 or are too tiny to be worth removing.
1228 This saves about 500 bytes.
1230 .ti -0.25i
1231 .B \(enDNO_MAGIC
1232 .br
1233 This permanently disables the \*(OQmagic\*(CQ option, so that most
1234 meta-characters in a regular expression are not recognized.
1235 This saves about 3K bytes from the \*(OQ.text\*(CQ segment.
1236 .HS
1237 .in -0.25i
1238 .SS "Termcap"
1239 \fIElvis\fR can use standard termcap entries,
1240 but it also recognizes and uses several extra capabilities, if you give them.
1241 All of these are optional.
1242 .nf
1243 .in +0.25i
1244 .ta 1.5i
1245 .HS
1246 \fBCapability Description\fR
1247 :PU=: sequence received from the <PgUp> key
1248 :PD=: sequence received from the <PgDn> key
1249 :HM=: sequence received from the <Home> key
1250 :EN=: sequence received from the <End> key
1251 :VB=: sequence sent to start bold printing
1252 :Vb=: sequence sent to end bold printing
1253 .in -0.25i
1254 .SS "Author"
1255 .PP
1256 \fIElvis\fR was written by Steve Kirkendall.
1257 He can be reached by email at: kirkenda@cs.pdx.edu
1258 for comments regarding \fIelvis\fR.