diff options
Diffstat (limited to 'usr.bin/vi/docs')
| -rw-r--r-- | usr.bin/vi/docs/README | 200 | ||||
| -rw-r--r-- | usr.bin/vi/docs/bugs.current | 47 | ||||
| -rw-r--r-- | usr.bin/vi/docs/changelog | 519 | ||||
| -rw-r--r-- | usr.bin/vi/docs/ev | 55 | ||||
| -rw-r--r-- | usr.bin/vi/docs/features | 92 | ||||
| -rw-r--r-- | usr.bin/vi/docs/internals/autowrite | 88 | ||||
| -rw-r--r-- | usr.bin/vi/docs/internals/context | 32 | ||||
| -rw-r--r-- | usr.bin/vi/docs/internals/gdb.script | 68 | ||||
| -rw-r--r-- | usr.bin/vi/docs/internals/input | 350 | ||||
| -rw-r--r-- | usr.bin/vi/docs/internals/quoting | 219 | ||||
| -rw-r--r-- | usr.bin/vi/docs/internals/structures | 61 | ||||
| -rw-r--r-- | usr.bin/vi/docs/tutorial/vi.advanced | 1458 | ||||
| -rw-r--r-- | usr.bin/vi/docs/tutorial/vi.beginner | 741 | ||||
| -rwxr-xr-x | usr.bin/vi/docs/tutorial/vi.tut.csh | 24 |
14 files changed, 3954 insertions, 0 deletions
diff --git a/usr.bin/vi/docs/README b/usr.bin/vi/docs/README new file mode 100644 index 000000000000..5bece9929082 --- /dev/null +++ b/usr.bin/vi/docs/README @@ -0,0 +1,200 @@ +# @(#)README 8.84 (Berkeley) 8/15/94 + +This is the README for version 1.32 of nex/nvi, a freely redistributable +replacement for the Berkeley ex and vi text editors. The compressed or +gzip'd archive, for this and future versions, can be retrieved by using +anonymous ftp to ftp.cs.berkeley.edu, from the file ucb/4bsd/nvi.tar.Z, +or ucb/4bsd/nvi.tar.gz. + +If you have any questions about nvi, or problems making it work, please +contact me by electronic mail at one of the following addresses: + + uunet!bostic + bostic@cs.berkeley.edu + +Keith Bostic + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +o Redistribution: + +This software is copyrighted by the The Regents of the University of +California, but may be freely redistributed (or sold, or used to line +your birdcage) under the following conditions: + +/*- + * Copyright (c) 1991, 1992, 1993, 1994 + * The Regents of the University of California. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. All advertising materials mentioning features or use of this software + * must display the following acknowledgement: + * This product includes software developed by the University of + * California, Berkeley and its contributors. + * 4. Neither the name of the University nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +o Credit where it's due: + + This software was originally derived from software contributed + to the University of California, Berkeley by Steve Kirkendall, + the author of the vi clone elvis. Without his work, this work + would have been far more difficult. + + POSIX 1003.2 style regular expression support is courtesy of + Henry Spencer, for which I am *very* grateful. + + The curses library was originally done by Ken Arnold. Scrolling + and general reworking for 4.4BSD was done by Elan Amir. + +o From the original vi acknowledgements, by William Joy and Mark Horton: + + Bruce Englar encouraged the early development of this display + editor. Peter Kessler helped bring sanity to version 2's + command layout. Bill Joy wrote versions 1 and 2.0 through 2.7, + and created the framework that users see in the present editor. + Mark Horton added macros and other features and made the editor + work on a large number of terminals and Unix systems. + +o And... + The financial support of UUNET Communications Services is gratefully + acknowledged. + +=-=-=-=-=-=-=-=-=-=-= +o Status: + +This software is in beta test, and it's pretty stable. Almost all of +the historic functionality in ex/vi is there, the only major missing +pieces are open mode and the lisp option. (Also, the options hardtabs, +optimize, redraw, and slowopen are recognized, but ignored.) + +Nvi is mostly 8-bit clean. This isn't difficult to fix, and was left +in during initial development to keep things simple. Wide character +support will be integrated at the same time that it is made fully 8-bit +clean. + +There aren't a lot of new features in nex/nvi, but there are a few things +you might like. The "Additional Features" section of the reference page +(USD.doc/vi.ref/vi.ref.txt, USD.doc/vi.ref/vi.ref.ps) has more information. + +=-=-=-=-=-=-=-=-=-=-= +o Porting information: + +The directory "PORT" has directories for specific OS/machine combinations, +including V7-style Makefiles, for building nex/nvi on different machines. +See the file PORT/README for detailed information. + +=-=-=-=-=-=-=-=-=-=-= +o Debugging: + +Code fixes are appreciated, of course, but if you can't provide them, +please email me as much information as you can as to how to reproduce +the bug, and I'll try to fix it locally. Stack traces of core dumps +are only rarely helpful -- an example file with a set of keystrokes that +causes the problem is almost invariably necessary. + +Please include the following in the bug report; + + o The version of nvi you're running (use :version to get it). + o The row/column dimensions of the screen (80 x 32). + o Unless you're confident that they're not part of the problem, + your startup files (.exrc, .nexrc) and the environment variable + (EXININT, NEXINIT) values. (Cutting and pasting the output + of ":set all" is usually sufficient.) + +If you're running a memory checker (e.g. Purify) on nvi, you will want +to recompile everything with "-DPURIFY" in the CFLAGS, first. By +default, allocated pages are not initialized by the DB code, and they +will show up as reads of uninitialized memory in the buffer write routines. + +=-=-=-=-=-=-=-=-=-=-= +o Directory layout: + +nvi/USD.doc: + Ex/vi documentation, both historic and current. + + edit/ Roff source for "Edit: A tutorial", USD:14 in the + 4.3BSD manuals. + ex/ Roff source for "Ex Reference Manual -- Version + 3.7", USD:16 in the 4.3BSD manuals. + vi/ Roff source for "An Introduction to Display + Editing with Vi", USD:15 in the 4.3BSD manuals. + Includes the "Vi Quick Reference" card. + vi.man/ Manual page for nex/nvi; an updated version of + the document distributed with 4.4BSD-Lite. + vi.ref/ Reference document for nex/nvi; an updated version + of the document distributed with 4.4BSD-Lite. + +nvi/common: + Source files for pieces of code that are shared by all the editors, + like searching and logging code or code translating line numbers + into requests to the dbopen(3) database code. It also has the + interface code for modifying "records" in the underlying database. + +nvi/docs: + Random nvi documentation: + + README -- Nvi main README file. + bugs.current -- Major known bugs in the current nvi. + changelog -- Log of changes from version to version. + features -- Todo list, suggested features list. + internals/ + autowrite -- Vi autowrite option discussion. + gdb.script -- GDB debugging scripts. + input -- Vi maps, executable buffers, and input discussion. + quoting -- Vi quoting discussion. + structures -- Out-of-date nvi internal structure description. + tutorial/ -- Historic vi tutorial(s), of unknown quality. + +nvi/ex: + The ex source code. Because vi has the colon command, lots of + this code is used by vi. Generally, if functionality is shared + by both ex and vi, it's in nvi/ex. If it's vi only, it's in + nvi/vi. Files are generally named by the command(s) they support, + but occasionally with a name that describes their functionality. + +nvi/install: + Things to install on the local system. + + recover.script -- Vi recovery script. + +nvi/PORT: + Porting directories, one per OS/architecture combination. See + nvi/PORT/README for porting information. + + curses/ -- 4.4BSD curses implementation + db/ -- 4.4BSD DB routines. + regex/ -- Henry Spencer's POSIX.2 RE support. + +nvi/sex: + The screen support for the ex editor. + +nvi/svi: + The screen support for a curses based vi editor. + +nvi/vi: + The vi source code. + +nvi/xaw: + Place reserved for an X11 (Athena Widget) screen. diff --git a/usr.bin/vi/docs/bugs.current b/usr.bin/vi/docs/bugs.current new file mode 100644 index 000000000000..92b2a5c3b43b --- /dev/null +++ b/usr.bin/vi/docs/bugs.current @@ -0,0 +1,47 @@ +List of known bugs: + ++ The number option doesn't display line numbers in ex append/insert + mode. + ++ The option sidescroll is completely wrong, and setting it does more + harm than good. + ++ We're not blocking signals when manipulating the SCR/EXF chains. + This is necessary, since we walk them on signal receipt. + ++ When nvi edits files that don't have trailing newlines, it appends + one, regardless. + ++ Open mode is not yet implemented. + ++ ^C isn't passed to the shell in the script windows as an interrupt + character. + ++ The options: + + hardtabs, lisp, optimize, redraw, slowopen + + are recognized, but not implemented. These options are unlikely to + be implemented, so if you want them you might want to say something! + I will implement lisp if anyone ever documents how it worked. + ++ Screen repainting over slow lines, for some screen changes, isn't + as good as the historic vi's. + ++ The line movement commands ('k', 'j' are easy examples) don't find the + most attractive cursor position correctly when wrapped lines are longer + than 80 characters, and they're on the second or subsequent lines. + ++ Colon commands longer than a single line cause the display to be + incorrect. + ++ The usages of S_{REDRAW,REFORMAT,REFRESH,RENUMBER,RESIZE} are + inconsistent, and should be reviewed. In particular, S_REFRESH + in any screen redraws all screens. + ++ Historic vi permitted :g/xxx/vi, i.e. you could execute ex/vi as + global commands. Need to review all of the old commands to verify + which ones could/could not be used as global commands. + ++ If you run out of space in the recovery directory, the recovery + file is left in place. diff --git a/usr.bin/vi/docs/changelog b/usr.bin/vi/docs/changelog new file mode 100644 index 000000000000..335acd863921 --- /dev/null +++ b/usr.bin/vi/docs/changelog @@ -0,0 +1,519 @@ +1.31 -> 1.32 Mon Aug 15 14:27:49 1994 + + Turn off recno mmap call for Solaris 2.4/SunOS 5.4. +1.30 -> 1.31 Sun Aug 14 13:13:35 1994 + + Fix bug were cG on the last line of a file wasn't done in line mode, + and where the cursor wasn't positioned correctly after exiting text + insert mode. + + Add termcap workaround to make function keys greater than 9 work + correctly (or fail if old-style termcap support). + + Change ex/vi to not flush mapped keys on error -- this is historic + practice, and people depended on it. + + Rework vi parser so that no command including a mapped key ever + becomes the '.' command, matching historic practice. + + Make <escape> cancellation in the vi parser match POSIX 1003.2. + + Fix curses bug where standout string was written for each standout + character, and where standout mode was never exited explicitly. + Fix bugs in curses SF/sf and SR/sr scrolling, as seen on Sun and + x86 consoles. + + The v/global commands execute the print command by default. + + The number option historically applies to ex as well as vi. +1.29 -> 1.30 Mon Aug 8 10:30:42 1994 + + Make first read into a temporary set the file's name. + + Permit any key to continue scrolling or ex commands -- this + allows stacked colon commands, and matches historic practice. + + Don't output normal ! command commentary in ex silent mode. + + Allow +/- flags after substitute commands, make line (flag) + offsets from vi mode match historic practice. + + Return <eof> to ex immediately, even if preceded by spaces. Rework + ex parser to do erase the prompt instead of depending on the print + routines to do it. Minor fixes to the ex parser for display of + default and scrolling commands. MORE EX PARSER CHANGES. +1.28 -> 1.29 Fri Aug 5 10:18:07 1994 + + Make the abbreviated ex delete command work (:dele---###lll for + example, is historically legal. + + When autoprint fires, multiple flags may be set, use ex_print + directly instead of the stub routines. + + Change v/global commands to turn off autoprint while running. + + Minor changes to make the ! command display match historic output. + + Rework the ex parser to permit multiple command separators without + commands -- MAJOR CHANGE, likely to introduce all sorts of new bugs. + + Fix cd command to expand argument in the context of each element + of the cdpath option, make relative paths always relative to the + current directory. + + Rework write/quit cases for temporary files, so that user's don't + discard them accidentally. + + Check for window size changes when continuing after a suspend. + + Fix memory problem in svi_screen, used free'd memory. + + Change the ex change, insert, append commands to match historic + cursor positions if no data entered by the user. + + Change ex format flags (#, l, p) to affect future commands, not + just the current one, to match historic practice. + + Make the user's EOF character an additional scroll character in ex. + + Fix ex ^D scrolling to be the value of the scroll option, not half + the screen. + + Fix buffer execution to match historic practice -- bugs where the + '*' command didn't work, and @<carriage-return> didn't work. + + Fix doubled reporting of deleted lines in filters. + + Rework the % ` / ? ( ) N n { and ^A commands to always cut into + numeric buffers regardless of the location or length of the cut. + This matches historic practice. + + Fix the { command to check the current line if the cursor doesn't + start on the first character of the line. + + Do '!' expansion in the ex read command arguments, it's historic + practice. In addition, it sets the last '!' command. +1.27 -> 1.28 Wed Jul 27 21:29:18 1994 + + Add support for scrolling using the CS and SF/sf/SR/sr termcap + strings to the 4BSD curses. + + Rework of getkey() introduced a bug where command interrupt put + nvi into an infinite loop. + + Piping through a filter historically cut the replaced lines into + the default buffer, although not the numeric ones. + + Read of a filter and !! historically moved to the first nonblank + of the resulting cursor line (most of the time). + + Rework cursor motion flags, to support '!' as a motion command. +1.26 -> 1.27 Tue Jul 26 10:27:58 1994 + + Add the meta option, to specify characters the shell will expand. + + Fix the read command to match historic practice, the white space + and bang characters weren't getting parsed correctly. + + Change SIGALRM handler to save and restore errno. + + Change SunOS include/compat.h to include <vfork.h> so that the + ex/filter.c code works again. + + Don't put lines deleted by the ex delete command into the numeric + buffers, matching historic practice. + + Fix; if appending to a buffer, default buffer historically only + references the appended text, not the resulting text. + + Support multiple, semi-colon separated search strings, and 'z' + commands after search strings. + + Make previous context mark setting match historic practice (see + docs/internals/context). + + Fix the set command to permit whitespace between the option and + the question mark, fix question marks in general. + + Fix bug where ex error messages could be accidentally preceded + by a single space. + + Fix bug where curses reorganization could lose screen specific + mappings as soon as any screen exited. + + Fix bug in paragraph code where invalid macros could be matched. + Make paragraph motions stop at formfeed (^L) characters. + + Change 'c' to match historic practice, it cut text into numeric + buffers. +1.25 -> 1.26 Tue Jul 19 17:46:24 1994 + + Ignore SIGWINCH if the screen size is unchanged; SunOS systems + deliver one when a screen is uncovered. + + Fix: don't permit a command with a motion component to wrap due + to wrapscan and return to the original cursor position. + + Fix: ^E wasn't beeping when reaching the bottom of the file. + + Fix bg/fg bug where tmp file exiting caused a NULL dereference. + + Rework file locking code to use fcntl(2) explicitly. + + Fix bug in section code where invalid macros could be matched. + + Fix bug where line number reset by vi's Q command. + + Add explicit character mode designation to character mode buffers. + + Add <sys/ioctl.h> include to sex/sex_window.c, needed by NET/2 + vintage systems. + + Change to always flush a character during suspend, 4BSD curses + has the optimization where it doesn't flush after a standend(). + + Fix bug on OSF1 where <curses.h> changes the values of VERASE, + VKILL and VWERASE to incorrect ones. + + Fix bug where optarg used incorrectly in main.c. + + Block all signals when acting on a signal delivery. + + Fix recovery bug where RCV_EMAIL could fire even if there wasn't + a backing file; format recovery message. +1.24 -> 1.25 Sun Jul 17 14:33:38 1994 + + Stop allowing keyboard suspends (^Z) in insert mode, it's hard + to get autowrite correct, and it's not historic practice. + + Fix z^, z+ to match historic practice. + + Bug in message handling, "vi +35 non-existent_file" lost the + status message because the "+35" pushed onto the stack erased + it. For now, change so that messages aren't displayed if there + are keys waiting -- may need to add a "don't-erase" bit to the + character in the stack instead. + + Bug in svi_msgflush(), where error messages could come out in + normal video. +1.23 -> 1.24 Sat Jul 16 18:30:18 1994 + + Fix core dump in exf.c, where editing a non-existent file and + exiting could cause already free'd memory to be free'd. + + Clean up numerous memory errors, courtesy of Purify. + + Change process wait code to fail if wait fails, and not attempt + to interpret the wait return information. + + Open recovery and DB files for writing as well as reading, System + V (fcntl) won't let you acquire LOCK_EX locks otherwise. + + Fix substitute bug where could malloc 0 bytes (AIX breaks). + + Permit the mapping of <carriage-return>, it's historic practice. + + Historic vi didn't eat <blank> characters before the force + flag, match historic practice. + + Bug in ex argument parsing, corrected for literal characters + twice. + + Delete screen specific maps when the screen closes. + + Move to the first non-<blank> in the line on startup; historic + practice. + + Change the ex visual command to move directly to a line if no + trailing 'z' command. + + Fix "[[" and "]]" to match historic practice (yet again...). + + Fix "yb" and "y{" commands to update the cursor correctly. + + Change "~<motion>" to match the yank cursor movement semantics + exactly. + + Move all of the curses related code into sex/svi -- major rework, + but should help in future ports. + + Fix bug in split code caused by new file naming code, where would + drop core when a split screen exited. + + Change svi_ex_write to do character display translation, so that + messages with file names in them are displayed correctly. + + Display the file name on split screens instead of a divider line. + + Fix move bug, wasn't copying lines before putting them. + + Fix bug were :n dropped core if no arguments supplied. + + Don't quote characters in executed buffer: "ifoo<esc>" should leave + insert mode after the buffer is executed. + + Tagpop and tagpush should set the absolute mark in case only moving + within a file. + + Skip leading whitespace characters before tags and cursor word + searches. + + Fix bug in ex_global where re_conv() was allocating the temporary + buffer and not freeing it. +1.22 -> 1.23: Wed Jun 29 19:22:33 1994 + + New <sys/cdefs.h> required "inline" to change to "__inline" + + Fix System V curses code for new ^Z support. + + Fix off-by-one in the move code, avoid ":1,$mo$" with only one + line in the buffer. + + Line orientation of motion commands was remembered too long, + i.e. '.' command could be incorrectly marked as line oriented. + + Move file modification time into EXF, so it's shared across + split screens. + + Put the prev[ious] command back in, people complained. + + Random fixes to next/prev semantics changed in 1.22. + + Historically vi doesn't only move to the last address if there's + ANYTHING after the addresses, e.g. ":3" moves to line 3, ":3|" + prints line 3. +1.21 -> 1.22: Mon Jun 27 11:01:41 1994 + + Make the line between split screens inverse video again. + + Delete the prev[ious] command, it's not useful enough to keep. + + Rework :args/file name handling from scratch -- MAJOR CHANGE, + likely to introduce all sorts of new bugs. + + Fix RE bug where no subexpressions in the pattern but there were + subexpressions referenced in the replacement, e.g. "s/XXX/\1/g". + + Change recovery to not leave unmodified files around after a + crash, by using the owner 'x' bit on unmodified backup files. + MAJOR CHANGE, the system recovery script has to change! + + Change -r option to delete recovery.* files that reference non- + existent vi.* files. + + Rework recovery locking so that fcntl(2) locking will work. + + Fix append (upper-case) buffers, broken by cut fixes. + + Fix | to not set the absolute motion mark. + + Read $HOME/.exrc file on startup if the effective user ID is + root. This makes running vi while su(1)'d work correctly. + + Use the full pathname of the file as the recovery name, not + just the last component. Matches historic practice. + + Keep marks in empty files from being destroyed. + + Block all caught signals before calling the DB routines. + + Make the line change report match historic practice (yanked + lines were different than everything else). + + Add section on multiple screens to the reference manual. + + Display all messages at once, combine onto a single line if + possible. Delete the trailing period from all messages. +1.20 -> 1.21: Thu May 19 12:21:58 1994 + + Delete the -l flag from the recover mail. + + Send the user email if ex command :preserve executed, this matches + historic practice. Lots of changes to the preserve and recovery + code, change preserve to snapshot files (again, historic practice). + + Make buffers match historic practice: "add logically stores text + into buffer a, buffer 1, and the unnamed buffer. + + Print <tab> characters as ^I on the colon command line if the + list option set. + + Adjust ^F and ^B scroll values in the presence of split screens + and small windows. + + Break msg* routines out from util.c into msg.c, start thinking + about message catalogs. + + Add tildeop set option, based on stevie's option of the same name. + Changes the ~ command into "[count] ~ motion", i.e. ~ takes a + trailing motion. + + Chose NOT to match historic practice on cursor positioning after + consecutive undo commands on a single line; see vi/v_undo.c for + the comment. + + Add a one line cache so that multiple changes to the same line + are only counted once (e.g. "dl35p" changes one line, not 35). + + Rework signals some more. Block file sync signals in vi routines + that interface to DB, so can sync the files at interrupt time. + Write up all of the signal handling arguments, see signal.c. +1.19 -> 1.20: Thu May 5 19:24:57 1994 + + Return ^Z to synchronous handling. See the dicussion in signal.c + and svi_screen.c:svi_curses_init(). + + Fix bug where line change report was wrong in util.c:msg_rpt(). +1.18 -> 1.19: Thu May 5 12:59:51 1994 + + Block DSUSP so that ^Y isn't delivered at SIGTSTP. + + Fix bug -- put into an empty file leaves the cursor at 1,0, + not the first nonblank. + + Fix bug were number of lines reported for the 'P' command was + off-by-one. + + Fix bug were 0^D wasn't being handled correctly. + + Delete remnants of ^Z as a raw character. + + Fix bug where if a map was an entire colon command, it may never + have been displayed. + + Final cursor position fixes for the vi T and t commands. + + The ex :next command took an optional ex command as it's first + argument similar to the :edit commands. Match historic practice. +1.17 -> 1.18: Wed May 4 13:57:10 1994 + + Rework curses information in the PORT/Makefile's. + + Minor fixes to ^Z asynchronous code. +1.16 -> 1.17: Wed May 4 11:15:56 1994 + + Make ex comment handling match historic practice. + + Make ^Z work asynchronously, we can no longer use the SIGTSTP + handler in the curses library. +1.15 -> 1.16: Mon May 2 19:42:07 1994 + + Make the 'p' and 'P' commands support counts, i.e. "Y10p" works. + + Make characters that map to themselves as the first part of the + mapping work, it's historic practice. + + Fix bug where "s/./\& /" discarded the space in the replacement + string. + + Add support for up/down cursor arrows in text input mode, rework + left/right support to match industry practice. + + Fix bug were enough character remapping could corrupt memory. + + Delete O_REMAPMAX in favor of setting interrupts after N mapped + characters without a read, delete the map counter per character. + MAJOR CHANGE. All of the interrupt signal handling has been + reworked so that interrupts are always turned on instead of + being turned on periodically, when an interruptible operation is + pending. + + Fix bug where vi wait() was interrupted by the recovery alarm. + + Make +cmd's and initial commands execute with the current line + set to the last line of the file. This is historic practice. + + Change "lock failed" error message to a file status message. + It always fails over NFS, and making all NFS files readonly + isn't going to fly. + + Use the historic line number format, but check for overflow. + + Fix bug where vi command parser ignored buffers specified as + part of the motion command. + + Make [@*]buffer commands on character mode buffers match historic + practice. + + Fix bug where the cmap/chf entries of the tty structure weren't + being cleared when new characters were read. + + Fix bug where the default command motion flags were being set + when the command was a motion component. + + Fix wrapmargin bug; if appending characters, and wrapmargin breaks + the line, an additional space is eaten. +1.14 -> 1.15: Fri Apr 29 07:44:57 1994 + + Make the ex delete command work in any empty file. + + Fix bug where 't' command placed the cursor on the character + instead of to its left. + + ^D and ^U didn't set the scroll option value historically. + Note, this change means that any user set value (e.g. 15^D) + will be lost when splitting the screen, since the split code + now resets the scroll value regardless. + + Fix the ( command to set the absolute movement mark. + + Only use TIOCGWINSZ for window information if SIGWINCH signal + caught. + + Delete the -l flag, and make -r work for multiple arguments. + Add the ex "recover[!] file" command. + + Switch into ex terminal mode and use the sex routines when + append/change/insert called from vi mode. + + Make ^F and ^B match historic practice. This required a fairly + extensive rework of the svi scrolling code. + + Cursor positioning in H, M, L, G (first non-blank for 1G) wasn't + being done correctly. Delete the SETLFNB flag. H, M, and L stay + logical movements (SETNNB) and G always moves to the first nonblank. + + System V uses "lines" and "cols", not "li" and "co", change as + necessary. Check termcap function returns for errors. + + Fix `<character> command to do start/end of line correction, + and to set line mode if starting and stopping at column 0. + + Fix bug in delete code where dropped core if deleted in character + mode to an empty line. (Rework the delete code for efficiency.) + + Give up on SunOS 4.1.X, and use "cc" instead of /usr/5bin/cc. + + Protect ex_getline routine from interrupted system calls (if + possible, set SA_RESTART on SIGALRM, too). + + Fix leftright scrolling bug, when moving to a shorter line. + + Do validity checking on the copy, move, t command target line + numbers. + + Change for System V % pattern broke trailing flags for empty + replacement strings. + + Fix bug when RCM flags retained in the saved dot structure. + + Make the ex '=' command work for empty files. + + Fix bug where special_key array was being free'd (it's no longer + allocated). + + Matches cut in line mode only if the starting cursor is at or + before the first nonblank in its line, and the ending cursor is + at or after the last nonblank in its line. + + Add the :wn command, so you can write a file and switch to a new + file in one command. + + Allow only a single key as an argument to :viusage. + + New movement code broke filter/paragraph operations in empty + files ("!}date" in an empty file was dropping core). +1.12 -> 1.14: Mon Apr 18 11:05:10 1994 (PUBLICLY AVAILABLE VERSION, 4.4BSD) + + Fix FILE structure leakage in the ex filter code. + + Rework suspend code for System V curses. Nvi has to do the + the work, there's no way to get curses to do it right. + + Revert SunOS 4.1.X ports to the distributed curses. There's + a bug in Sun's implementation that we can't live with. + + Quit immediately if row/column values are unreasonable. + + Fix the function keys to match vi historic behavior. + + Replace the echo/awk magic in the Makefile's with awk scripts. +1.11 -> 1.12: Thu Apr 14 11:10:19 1994 + + Fix bug where only the first vi key was checked for validity. + + Make 'R' continue to overwrite after a <carriage-return>. + + Only display the "no recovery" message once. + + Rework line backup code to restore the line to its previous + condition. + + Don't permit :q in a .exrc file or EXINIT variable. + + Fix wrapscan option bug where forward searches become backward + searches and do cursor correction accordingly. + + Change "dd" to move the cursor to the first non-blank on the line. + + Delete cursor attraction to the first non-blank, change non-blank + motions to set the most attractive cursor position instead. + + Fix 'r' substitute option to set the RE to the last RE, not the + last substitute RE. + + Fix 'c' and 'g' substitute options to always toggle, and fix + edcompatible option to not reset them. + + Display ex error messages in inverse video. + + Fix errorbells option to match historic practice. + + Delete fixed character display table in favor of table built based + on the current locale. + + Add ":set octal" option, that displays unknown characters as octal + values instead of the default hexadecimal. + + Make all command and text input modes interruptible. + + Fix ex input mode to display error messages immediately, instead + of waiting for the lines to be resolved. + + Fix bug where vi calling append could overwrite the command. + + Fix off-by-one in the ex print routine tab code. + + Fix incorrect ^D test in vi text input routines. + + Add autoindent support for ex text insert routines. + + Add System V substitute command replacement pattern semantics, + where '%' means the last replacement pattern. + + Fix bug that \ didn't escape newlines in ex commands. + + Regularize the names of special characters to CH_*. + + Change hex insert character from ^Vx<hex_char> to ^X<hex_char> + + Integrate System V style curses, so SunOS and Solaris ports can + use the native curses implementation. +1.10 -> 1.11: Thu Mar 24 16:07:45 EST 1994 (PUBLICLY AVAILABLE VERSION) + + Change H, M, and L to set the absolute mark, historical practice. + + Fix bug in stepping through multiple tags files. + + Add "remapmax" option that turns off map counts so you can remap + infinitely. If it's off, term_key() can be interrupted from the + keyboard, which will cause the buffers to flush. I also dropped + the default max number of remaps to 50. (Only Dave Hitz's TM + macros and maze appear to go over that limit.) + + Change :mkexrc to not dump w{300,1200,9600}, lisp options. + + Fix backward search within a line bug. + + Change all the includes of "pathnames.h" to use <>'s so that the + PORT versions can use -I. to replace it with their own versions. + + Make reads and writes interruptible. Rework code that enters and + leaves ex for '!' and filter commands, rework all interrupt and + timer code. + + Fix core dump when user displayed option in .exrc file. + + Fix bug where writing empty files didn't update the saved + modification time. + + Fix bug where /pattern/ addressing was always a backward search. + + Fix bug triggered by autoindent of more than 32 characters, where + nvi wasn't checking the right TEXT length. + + Fix bug where joining only empty lines caused a core dump. +1.09 -> 1.10: Sat Mar 19 15:40:29 EST 1994 + + Fix "set all" core dump. +1.08 -> 1.09: Sat Mar 19 10:11:14 EST 1994 + + If the tag's file path is relative, and it doesn't exist, check + relative to the tag file location. + + Fix ~ command to free temporary buffer on error return. + + Create vi.ref, a first cut at a reference document for vi. + The manual page and the reference document only document the + set options, so far. + + Fix 1G bug not always going to the first non-blank. + + Upgrade PORT/regex to release alpha3.4, from Henry Spencer. + + Add MKS vi's "cdpath" option, supporting a cd search path. + + Handle if search as a motion was discarded, i.e. "d/<erase>". + + Change nvi to not create multiple recovery files if modifying + a recovered file. + + Decide to ignore that the cursor is before the '$' when inserting + in list mode. It's too hard to fix. +1.07 -> 1.08: Wed Mar 16 07:37:36 EST 1994 + + Leftright and big line scrolling fixes. This meant more changes + to the screen display code, so there may be new problems. + + Don't permit search-style addresses until a file has been read. + + "c[Ww]" command incorrectly handled the "in whitespace" case. + + Fix key space allocation bug triggered by cut/paste under SunOS. + + Ex move command got the final cursor position wrong. + + Delete "optimize option not implemented" message. + + Make the literal-next character turn off mapping for the next + character in text input mode. +1.06 -> 1.07: Mon Mar 14 11:10:33 EST 1994 + + The "wire down" change in 1.05 broke ex command parsing, there + wasn't a corresponding change to handle multiple K_VLNEXT chars. + + Fix final position for vi's 't' command. +1.05 -> 1.06: Sun Mar 13 16:12:52 EST 1994 + + Wire down ^D, ^H, ^W, and ^V, regardless of the user's termios + values. + + Add ^D as the ex scroll command. + + Support ^Q as a literal-next character. + + Rework abbreviations to be delimited by any !inword() character. + + Add options description to the manual page. + + Minor screen cache fix for svi_get.c. + + Rework beautify option support to match historical practice. + + Exit immediately if not reading from a tty and a command fails. + + Default the SunOS 4.* ports to the distributed curses, not SMI's. +1.04 -> 1.05: Thu Mar 24 16:07:45 EST 1994 + + Make cursor keys work in input mode. + + Rework screen column code in vi curses screen. MAJOR CHANGE -- + after this, we'll be debugging curses screen presentation from + scratch. + + Explode include files in vi.h into the source files. +1.03 -> 1.04: Sun Mar 6 14:14:16 EST 1994 + + Make the ex move command keep the marks on the moved lines. + + Change resize semantics so you can set the screen size to a + specific value. A couple of screen fixes for the resize code. + + Fixes for foreground/background due to SIGWINCH. + + Complete rework of all of vi's cursor movements. The underlying + assumption in the old code was that the starting cursor position + was part of the range of lines cut or deleted. The command + "d[[" is an example where this isn't true. Change it so that all + motion component commands set the final cursor position separately + from the range, as it can't be done correctly later. This is a + MAJOR CHANGE -- after this change, we'll be debugging the cursor + positioning from scratch. + + Rewrite the B, b, E, e commands to use vi's getc() interface + instead of rolling their own. + + Add a second MARK structure, LMARK, which is the larger mark + needed by the logging and mark queue code. Everything else uses + the reworked MARK structure, which is simply a line/column pair. + + Rework cut/delete to not expect 1-past-the-end in the range, but + to act on text to the end of the range, inclusive. + + Sync on write's, to force NFS to flush. +1.01 -> 1.03: Sun Jan 23 17:50:35 EST 1994 (PUBLICLY AVAILABLE VERSION) + + Tag stack fixes, was returning to the tag, not the position from + which the user tagged. + + Only use from the cursor to the end of the word in cursor word + searches and tags. (Matches historical vi behavior.) + + Fix delete-last-line bug when line number option set. + + Fix usage line for :split command. + + If O_NUMBER set, long input lines would eventually fail, the column + count for the second screen of long lines wasn't set correctly. + + Fix for [[ reaching SOF with a column longer than the first line. + + Fix for multiple error messages if no screen displayed. + + Fix :read to set alternate file name as in historical practice. + + Fix cut to rotate the numeric buffers if line mode flag set. +1.00 -> 1.01: Wed Jan 12 13:37:18 EST 1994 + + Don't put cut items into numeric buffers if cutting less than + parts of two lines. +0.94 -> 1.00: Mon Jan 10 02:27:27 EST 1994 + + Read-ahead not there; BSD tty driver problem, SunOS curses + problem. + + Global command could error if it deleted the last line of + the file. + + Change '.' to only apply to the 'u' if entered immediately + after the 'u' command. "1pu.u.u. is still broken, but I + expect that it's going to be sacrificed for multiple undo. + + If backward motion on a command, now move to the point; get + yank cursor positioning correct. + + Rework cut buffers to match historic practice -- yank/delete + numeric buffers redone sensibly, ignoring historic practice. +0.92 -> 0.93: Mon Dec 20 19:52:14 EST 1993 + + Christos Zoulas reimplemented the script windows using pty's, + which means that they now work reasonably. The down side of + this is that almost all ports other than 4.4BSD need to include + two new files, login_tty.c and pty.c from the PORT/clib directory. + I've added them to the Makefiles. + + All calloc/malloc/realloc functions now cast their pointers, for + SunOS -- there should be far fewer warning messages, during the + build. The remaining messages are where CHAR_T's meet char *'s, + i.e. where 8-bit clean meets strcmp. + + The user's argument list handling has been reworked so that there + is always a single consistent position for use by :next, :prev and + :rewind. + + All of the historical options are now at least accepted, although + not all of them are implemented. (Edcompatible, hardtabs, lisp, + optimize, redraw, and slowopen aren't implemented.) + + The RE's have been reworked so that matches of length 0 are handled + in the same way as vi used to handle them. + + Several more mapping fixes and ex parser addressing fixes. diff --git a/usr.bin/vi/docs/ev b/usr.bin/vi/docs/ev new file mode 100644 index 000000000000..144295a319f2 --- /dev/null +++ b/usr.bin/vi/docs/ev @@ -0,0 +1,55 @@ +# @(#)ev 8.4 (Berkeley) 4/29/94 + +Ev: Vi: Result: +<CK> <CK> (Cursor keys). Move around the file. + +Meta key commands: +^A<#> <#>G Goto line #. +^A$ G Goto the end of the file. +^A/ / Prompt and execute a forward search. +^A: : Prompt and execute an ex command. +^A? ? Prompt and execute a backward search. +^Ac y'<c> Copy to mark in line mode (or copy the current line). +^AC y`<c> Copy to mark in character mode. +^Ad d'<c> Delete to mark in line mode (or delete the current line). +^AD d`<c> Delete to mark in character mode. +^Aj J Join lines. +^Am m<c> Mark the current cursor position. +^AN N Repeat search in the reverse direction. +^An ^A Search for the word under the cursor. +^Ar u Redo a command. +^Au u Undo a command. + +Single key commands: +^B ^B Page up a screen. +^C ^C Interrupt long-running commands. +^D ^D Page down a half-screen. +^E $ End of line. +^F ^F Page down a screen. +^G ^G File status/information. +^H X Delete the character to the left of the cursor. +^I (TAB) +^J j Cursor down one line. +^K k Cursor up one line. +^L ^L Redraw the screen. +^M (CR) ^M In insert mode, split the line at the current cursor, + creating a new line. + In overwrite mode, cursor down one line. +^N n Repeat previous search, in previous direction. +^O (UNUSED) +^P p Paste the cut text at the cursor position. +^Q (XON/XOFF) +^R (UNUSED) +^S (XON/XOFF) +^T D Truncate the line at the cursor position. +^U ^U Page up a half-screen. +^V<c> ^V<c> Insert/overwrite with a literal next character. +^W w Move forward one whitespace separated word. +^X x Delete the current character. +^Y (UNUSED) +^Z ^Z Suspend. + +New ex mode commands: + +^A:set ov[erwrite] Toggle "insert" mode, so that input keys overwrite + the existing characters. diff --git a/usr.bin/vi/docs/features b/usr.bin/vi/docs/features new file mode 100644 index 000000000000..d410722db5d6 --- /dev/null +++ b/usr.bin/vi/docs/features @@ -0,0 +1,92 @@ +List of things that should be added at some point: +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= + ++ X11 interface. + ++ Message catalogs. + ++ Forms editing package; use RE's to verify field contents. + ++ Internationalization, including wide character support. + ++ Make db, curses real libraries that we load against instead of + compiling directly. + ++ Full editing capability on the : command line. + ++ Rob Pike's sam RE's. + ++ Filename completion. While on the subject of completion, it would be + nice to have the completion mechanism found in tcsh version >= 6.03. + For instance, the completion for the `:cd' command will be directories + only. The completion for the `:set' command will be all options not + set at that moment, and for `:set un' will be all options that are set + at that moment. The completion for `:< count' will be the flags. + +List of suggested features: +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= ++ Add a "push" command that would push a file on the tags stack. + (Essentially make tags a special case of the stack, and make + the stack more general purpose.) + ++ Make :script just run a command and edit the output, and :interactive, + which allows interactive shell session, instead of just the current + :script. + ++ Add versioning based on a "set version" variable, that would + create backup copies when the file was written back, i.e. the + ":w" and autowrite's would copy the original. + ++ Add tagging information to the man page so that users can display + the part of the man page that discusses the command in which they're + interested. + ++ Add a zone option so that you can declare that top/bottom few lines + of the screen aren't filled except by accident, so that the text + you ask for is always concentrated in the center of the screen. + ++ Add "set searchdir" for a list of directories to look in for + files to edit. The semantic is that ":e foo" is replaced with + the file name that is found, so there's no confusion as to + which file is written. + ++ Change + :di[splay] tags -> :tags + :di[splay] screens -> :screens + :di[splay] buffers -> :buffers + ++ A macro record function. Add the ability to record a sequence + of keystrokes into a named buffer for later use. Handy when + you're trying to build a semi-complex macro. + ++ The semantics of :split, :bg, and :fg aren't right. Someone needs to + rethink how they should interact. The main problem arises when users + want to get a window into a new file. Currently, the necessary sequence + is ":split newfile|^W|:bg". It would be nice if you could simply + background the current screen and edit a new one. + ++ An option to turn on a ``quarter plane'' model so that you can + go as far to the right or down as you wish. The File or the + current line is only extended if you actually put down a char at + the new location. Very handy for ascii graphics and tables. + ++ Some way of replacing the command bindings. For this to work + cleanly the notion of a command must be separate from that of a + key. (Simulate the Rand editor?) + ++ Vertical splitting, so you can see files side by side. + ++ Tracking. Two or more files are associated so that when one file + is scrolled up/down/left/right other files track by the same amount. + Tracking may be constrained such that two files only track vertically + or horizontally. This is relatively easy to implement. + ++ A status file so that the next time invocation of the editor returns + to the same place, with the same number of windows etc. In case of + change of the screen size, reasonable defaults are used. For each + window size and location of the window, name of the file and position + in it, any tab settings, any other settings for the window (such as + insert/overwrite mode, auto indent etc). Last search RE and maybe + direction. If a file does not exist the next time you invoke the + editor, its window is left in the same place but with some default + message. diff --git a/usr.bin/vi/docs/internals/autowrite b/usr.bin/vi/docs/internals/autowrite new file mode 100644 index 000000000000..55cd13b8f72e --- /dev/null +++ b/usr.bin/vi/docs/internals/autowrite @@ -0,0 +1,88 @@ +# @(#)autowrite 8.2 (Berkeley) 9/28/93 + +Vi autowrite behavior, the fields with *'s are "don't cares". + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Commands that are affected only by autowrite: + +Command File Autowrite? Action: + modified? +----------------------------------------------- +^Z Y Y Write file and suspend. +^Z Y N Suspend. +^Z N * Suspend. + +# This behavior is NOT identical to :edit. +^ Y Y Write file and jump. +^ Y N Error. +^ N * Jump. + +# The new nvi command ^T (:tagpop) behaves identically to ^]. +# This behavior is identical to :tag, :tagpop, and :tagpush with +# force always set to N. +^] Y Y Write file and jump. +^] Y N Error. +^] N * Jump. + +# There's no way to specify a force flag to the '!' command. +:! Y Y Write file and execute. +:! Y N Warn (if warn option) and execute. +:! N * Execute. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Commands that are affected by both autowrite and force: + +NOTE: the "force" flag is never passed on, i.e. the write +to the file caused by the autowrite flag is never forced. + +Command File Autowrite? Force? Action: + modified? (!) +------------------------------------------------------- +# The first rule (YYY) is historic practice, but seems wrong. +# In nvi, :next and :prev commands behave identically to :rewind. +:next Y Y Y Write changes and jump. +:next Y Y N Write changes and jump. +:next Y N Y Abandon changes and jump. +:next Y N N Error. +:next N * * Jump. + +:rewind Y Y Y Abandon changes and jump. +:rewind Y Y N Write changes and jump. +:rewind Y N Y Abandon changes and jump. +:rewind Y N N Error. +:rewind N * * Jump. + +# The new nvi commands, :tagpop and :tagtop, behave identically to :tag. +# Note, this behavior is the same as :rewind and friends, as well. +:tag Y Y Y Abandon changes and jump. +:tag Y Y N Write changes and jump. +:tag Y N Y Abandon changes and jump. +:tag Y N N Error. +:tag N * * Jump. + +# The command :suspend behaves identically to :stop. +:stop Y Y Y Suspend. +:stop Y Y N Write changes and suspend. +:stop Y N Y Suspend. +:stop Y N N Suspend. +:stop N * * Suspend. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Commands that might be affected by autowrite, but aren't: + +Command File Autowrite? Force? Action: + modified? (!) +------------------------------------------------------- +#:ex, and :vi (executed while in vi mode) behave identically to :edit. +:edit Y * Y Abandon changes and jump. +:edit Y * N Error. +:edit N * * Jump. + +:quit Y * Y Quit. +:quit Y * N Error. +:quit N * * Quit. + +:shell * * * Execute shell. + +:xit Y * * Write changes and exit. +:xit N * * Exit. diff --git a/usr.bin/vi/docs/internals/context b/usr.bin/vi/docs/internals/context new file mode 100644 index 000000000000..139a1c3fdb41 --- /dev/null +++ b/usr.bin/vi/docs/internals/context @@ -0,0 +1,32 @@ +# @(#)context 8.5 (Berkeley) 7/23/94 + +In historic vi, the previous context mark was always set: + +ex address: + any number, <question-mark>, <slash>, <dollar-sign>, + <single-quote>, <backslash> + +ex commands: undo, "z.", global, vglobal + +vi commands: (, ), {, }, %, [[, ]], ^] + +nvi adds the vi command ^T to this list. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +In historic vi, the previous context mark was set if the +line changed: + +vi commands: '<mark>, G, H, L, M, z + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +In historic vi, the previous context mark was set if the +line or column changed: + +vi commands: `<mark>, /, ?, N, n + +nvi adds the vi command ^A to this list. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +In historic vi, the previous context mark was set in non-visual +mode for ^R and ^L if the line changed, but I have yet to figure +out how the line could change. diff --git a/usr.bin/vi/docs/internals/gdb.script b/usr.bin/vi/docs/internals/gdb.script new file mode 100644 index 000000000000..5f180edcd642 --- /dev/null +++ b/usr.bin/vi/docs/internals/gdb.script @@ -0,0 +1,68 @@ +# @(#)gdb.script 8.2 (Berkeley) 9/29/93 + +# display the SVI screen map +# usage dmap(sp) +define dmap + set $h = ((SVI_PRIVATE *)$arg0->svi_private)->h_smap + set $t = ((SVI_PRIVATE *)$arg0->svi_private)->t_smap + while ($h <= $t) + printf "lno: %d; off %d ", (int)$h->lno, (int)$h->off + if ($h->c_ecsize == 0) + printf "flushed\n" + else + printf "\n\tsboff %d; scoff %d\n", \ + (int)$h->c_sboff, (int)$h->c_scoff + printf "\teboff %d; eclen %d; ecsize %d\n", \ + (int)$h->c_eboff, (int)$h->c_eclen, \ + (int)$h->c_ecsize + end + set $h = $h + 1 + end +end + +# display the tail of the SVI screen map +define tmap + set $h = ((SVI_PRIVATE *)$arg0->svi_private)->h_smap + set $t = ((SVI_PRIVATE *)$arg0->svi_private)->t_smap + while ($t >= $h) + printf "lno: %d; off %d ", (int)$t->lno, (int)$t->off + if ($t->c_ecsize == 0) + printf "flushed\n" + else + printf "\n\tsboff %d; scoff %d\n", \ + (int)$t->c_sboff, (int)$t->c_scoff + printf "\teboff %d; eclen %d; ecsize %d\n", \ + (int)$t->c_eboff, (int)$t->c_eclen, \ + (int)$t->c_ecsize + end + set $t = $t - 1 + end +end + +# display the SVI private structure +define svp + print *((SVI_PRIVATE *)sp->svi_private) +end + +# display the marks +define markp + set $h = sp->ep->marks.next + set $t = &sp->ep->marks + while ($h != 0 && $h != $t) + printf "key %c lno: %d cno: %d flags: %x\n", \ + ((MARK *)$h)->name, ((MARK *)$h)->lno, \ + ((MARK *)$h)->cno, ((MARK *)$h)->flags + set $h = ((MARK *)$h)->next + end +end + +# display the tags +define tagp + set $h = sp->taghdr.next + set $t = &sp->taghdr + while ($h != 0 && $h != $t) + printf "tag: %s lno %d cno %d\n", ((TAG *)$h)->frp->fname, \ + ((TAG *)$h)->lno, ((TAG *)$h)->cno + set $h= ((TAG *)$h)->next + end +end diff --git a/usr.bin/vi/docs/internals/input b/usr.bin/vi/docs/internals/input new file mode 100644 index 000000000000..9a7506ee2337 --- /dev/null +++ b/usr.bin/vi/docs/internals/input @@ -0,0 +1,350 @@ +# @(#)input 5.5 (Berkeley) 7/2/94 + +MAPS, EXECUTABLE BUFFERS AND INPUT IN EX/VI: + +The basic rule is that input in ex/vi is a stack. Every time a key which +gets expanded is encountered, it is expanded and the expansion is treated +as if it were input from the user. So, maps and executable buffers are +simply pushed onto the stack from which keys are returned. The exception +is that if the "remap" option is turned off, only a single map expansion +is done. I intend to be fully backward compatible with this. + +Historically, if the mode of the editor changed (ex to vi or vice versa), +any queued input was silently discarded. I don't see any reason to either +support or not support this semantic. I intend to retain the queued input, +mostly because it's simpler than throwing it away. + +Historically, neither the initial command on the command line (the + flag) +or the +cmd associated with the ex and edit commands was subject to mapping. +Also, while the +cmd appears to be subject to "@buffer" expansion, once +expanded it doesn't appear to work correctly. I don't see any reason to +either support or not support these semantics, so, for consistency, I intend +to pass both the initial command and the command associated with ex and edit +commands through the standard mapping and @ buffer expansion. + +One other difference between the historic ex/vi and nex/nvi is that nex +displays the executed buffers as it executes them. This means that if +the file is: + + set term=xterm + set term=yterm + set term=yterm + +the user will see the following during a typical edit session: + + nex testfile + testfile: unmodified: line 3 + :1,$yank a + :@a + :set term=zterm + :set term=yterm + :set term=xterm + :q! + +This seems like a feature and unlikely to break anything, so I don't +intend to match historic practice in this area. + +The rest of this document is a set of conclusions as to how I believe +the historic maps and @ buffers work. The summary is as follows: + +1: For buffers that are cut in "line mode", or buffers that are not cut + in line mode but which contain portions of more than a single line, a + trailing <newline> character appears in the input for each line in the + buffer when it is executed. For buffers not cut in line mode and which + contain portions of only a single line, no additional characters + appear in the input. +2: Executable buffers that execute other buffers don't load their + contents until they execute them. +3: Maps and executable buffers are copied when they are executed -- + they can be modified by the command but that does not change their + actions. +4: Historically, executable buffers are discarded if the editor + switches between ex and vi modes. +5: Executable buffers inside of map commands are expanded normally. + Maps inside of executable buffers are expanded normally. +6: If an error is encountered while executing a mapped command or buffer, + the rest of the mapped command/buffer is discarded. No user input + characters are discarded. +7: Characters in executable buffers are remapped. +8: Characters in executable buffers are not quoted. + +Individual test cases follow. Note, in the test cases, control characters +are not literal and will have to be replaced to make the test cases work. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +1: For buffers that are cut in "line mode", or buffers that are not cut + in line mode but which contain portions of more than a single line, a + trailing <newline> character appears in the input for each line in the + buffer when it is executed. For buffers not cut in line mode and which + contain portions of only a single line, no additional characters + appear in the input. + +=== test file === +3Gw +w +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +=== end test file === + + If the first line is loaded into 'a' and executed: + +1G"ayy@a + + The cursor ends up on the '2', a result of pushing "3Gw^J" onto + the stack. + + If the first two lines are loaded into 'a' and executed: + +1G2"ayy@a + + The cursor ends up on the 'f' in "foo" in the fifth line of the + file, a result of pushing "3Gw^Jw^J" onto the stack. + + If the first line is loaded into 'a', but not using line mode, + and executed: + +1G"ay$@a + + The cursor ends up on the '1', a result of pushing "3Gw" onto + the stack + + If the first two lines are loaded into 'a', but not using line mode, + and executed: + +1G2"ay$@a + + The cursor ends up on the 'f' in "foo" in the fifth line of the + file, a result of pushing "3Gw^Jw^J" onto the stack. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +2: Executable buffers that execute other buffers don't load their + contents until they execute them. + +=== test file === +cwLOAD B^[ +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +@a@b +"byy +=== end test file === + + The command is loaded into 'e', and then executed. 'e' executes + 'a', which loads 'b', then 'e' executes 'b'. + +5G"eyy6G"ayy1G@e + + The output should be: + +=== output file === +cwLOAD B^[ +LOAD B 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +@a@b +"byy +=== end output file === + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +3: Maps and executable buffers are copied when they are executed -- + they can be modified by the command but that does not change their + actions. + + Executable buffers: + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +@a@b +"eyy +cwEXECUTE B^[ +=== end test file === + +4G"eyy5G"ayy6G"byy1G@eG"ep + + The command is loaded into 'e', and then executed. 'e' executes + 'a', which loads 'e', then 'e' executes 'b' anyway. + + The output should be: + +=== output file === +line 1 foo bar baz +EXECUTE B 2 foo bar baz +line 3 foo bar baz +@a@b +"eyy +cwEXECUTE B^[ +line 1 foo bar baz +=== end output file === + + Maps: + +=== test file === +Cine 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +=== end test file === + + Entering the command ':map = :map = rB^V^MrA^M1G==' shows that + the first time the '=' is entered the '=' map is set and the + character is changed to 'A', the second time the character is + changed to 'B'. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +4: Historically, executable buffers are discarded if the editor + switches between ex and vi modes. + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +cwCHANGE^[Q:set +set|visual|1Gwww +=== end test file === + +vi testfile +4G"ayy@a + +ex testfile +$p +yank a +@a + + In vi, the command is loaded into 'a' and then executed. The command + subsequent to the 'Q' is (historically, silently) discarded. + + In ex, the command is loaded into 'a' and then executed. The command + subsequent to the 'visual' is (historically, silently) discarded. The + first set command is output by ex, although refreshing the screen usually + causes it not to be seen. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +5: Executable buffers inside of map commands are expanded normally. + Maps inside of executable buffers are expanded normally. + + Buffers inside of map commands: + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +cwREPLACE BY A^[ +=== end test file === + +4G"ay$:map x @a +1Gx + + The output should be: + +=== output file === +REPLACE BY A 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +cwREPLACE BY A^[ +=== end output file === + + Maps commands inside of executable buffers: + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +=== end test file === + +:map X cwREPLACE BY XMAP^[ +4G"ay$1G@a + + The output should be: + +=== output file === +REPLACE BY XMAP 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +=== end output file === + + Here's a test that does both, repeatedly. + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +Y +cwREPLACED BY C^[ +blank line +=== end test file === + +:map x @a +4G"ay$ +:map X @b +5G"by$ +:map Y @c +6G"cy$ +1Gx + + The output should be: + +=== output file === +REPLACED BY C 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +Y +cwREPLACED BY C^[ +blank line +=== end output file === + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +6: If an error is encountered while executing a mapped command or + a buffer, the rest of the mapped command/buffer is discarded. No + user input characters are discarded. + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +:map = 10GcwREPLACMENT^V^[^[ +=== end test file === + + The above mapping fails, however, if the 10G is changed to 1, 2, + or 3G, it will succeed. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +7: Characters in executable buffers are remapped. + +=== test file === +abcdefghijklmnnop +ggg +=== end test file === + +:map g x +2G"ay$1G@a + + The output should be: + +=== output file === +defghijklmnnop +ggg +=== end output file === + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +8: Characters in executable buffers are not quoted. + +=== test file === +iFOO^[ + +=== end test file === + +1G"ay$2G@a + + The output should be: + +=== output file === +iFOO^[ +FOO +=== end output file === +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= diff --git a/usr.bin/vi/docs/internals/quoting b/usr.bin/vi/docs/internals/quoting new file mode 100644 index 000000000000..f20bd3f2b1e9 --- /dev/null +++ b/usr.bin/vi/docs/internals/quoting @@ -0,0 +1,219 @@ +# @(#)quoting 5.4 (Berkeley) 8/20/93 + +QUOTING IN EX/VI: + +There are two escape characters in historic ex/vi, ^V (or whatever +character the user specified as their literal next character) and +backslashes. There are two different areas in ex/vi where escaping +is interesting: the command and text input modes, and within the ex +commands themselves. In the examples below, ^V is used as the +typical literal next character. + +1: Escaping characters in ex and vi command and text input modes. + The set of characters that users might want to escape are as + follows: + + vi text input mode (a, i, o, etc.): + + carriage return (^M) + escape (^[) + autoindent characters + (^D, 0, ^, ^T) + erase, word erase, and line erase + (^H, ^W, ^U) + newline (^J) (not historic practice) + suspend (^Z) (not historic practice) + repaint (^L) (not historic practice) + + vi command line (:colon commands): + + carriage return (^M) + escape (^[) + erase, word erase, and line erase + (^H, ^W, ^U) + newline (^J) (not historic practice) + suspend (^Z) (not historic practice) + repaint (^L) (not historic practice) + + ex text input mode (a, i, o, etc.): + + carriage return (^M) + erase, word erase, and line erase + (^H, ^W, ^U) + newline (^J) (not historic practice) + + ex command line: + + carriage return (^M) + erase, word erase, and line erase + (^H, ^W, ^U) + newline (^J) (not historic practice) + suspend (^Z) + + I intend to follow historic practice for all of these cases, which + was that ^V was the only way to escape any of these characters, and + that whatever character followed the ^V was taken literally, i.e. + ^V^V is a single ^V. + + The historic ex/vi disallowed the insertion of various control + characters (^D, ^T, whatever) during various different modes, or, + permitted the insertion of only a single one, or lots of other random + behaviors (you can use ^D to enter a command in ex). I have + regularized this behavior in nvi, there are no characters that cannot + be entered or which have special meaning other than the ones listed + above. + + One comment regarding the autoindent characters. In historic vi, + if you entered "^V0^D" autoindent erasure was still triggered, + although it wasn't if you entered "0^V^D". In nvi, if you escape + either character, autoindent erasure is not triggered. + + This doesn't permit whitespace in command names, but that wasn't + historic practice and doesn't seem worth doing. + + Fun facts to know and tell: + The historic vi implementation for the 'r' command requires + *three* ^V's to replace a single character with ^V. + +2: Ex commands: + + Ex commands are delimited by '|' or newline characters. Within + the commands, whitespace characters delimit the arguments. + + I intend to treat ^V, followed by any character, as that literal + character. + + This is historic behavior in vi, although there are special + cases where it's impossible to escape a character, generally + a whitespace character. + +3: Escaping characters in file names in ex commands: + + :cd [directory] (directory) + :chdir [directory] (directory) + :edit [+cmd] [file] (file) + :ex [+cmd] [file] (file) + :file [file] (file) + :next [file ...] (file ...) + :read [!cmd | file] (file) + :source [file] (file) + :write [!cmd | file] (file) + :wq [file] (file) + :xit [file] (file) + + I intend to treat a backslash in a file name, followed by any + character, as that literal character. + + This is historic behavior in vi. + + In addition, since file names are also subject to word expansion, + the rules for escape characters in section 3 of this document also + apply. This is NOT historic behavior in vi, making it impossible + to insert a whitespace, newline or carriage return character into + a file name. This change could cause a problem if there were files + with ^V's in their names, but I think that's unlikely. + +4: Escaping characters in non-file arguments in ex commands: + + :abbreviate word string (word, string) +* :edit [+cmd] [file] (+cmd) +* :ex [+cmd] [file] (+cmd) + :k key (key) + :map word string (word, string) + :mark key (key) +* :set [option ...] (option) +* :tag string (string) + :unabbreviate word (word) + :unmap word (word) + + These commands use whitespace to delimit their arguments, and use + ^V to escape those characters. The exceptions are starred in the + above list, and are discussed below. + + In general, I intend to treat a ^V in any argument, followed by + any character, as that literal character. This will permit + editing of files name "foo|", for example, by using the string + "foo\^V|", where the literal next character protects the pipe + from the ex command parser and the backslash protects it from the + shell expansion. + + This is backward compatible with historical vi, although there + were a number of special cases where vi wasn't consistent. + +4.1: The edit/ex commands: + + The edit/ex commands are a special case because | symbols may + occur in the "+cmd" field, for example: + + :edit +10|s/abc/ABC/ file.c + + In addition, the edit and ex commands have historically ignored + literal next characters in the +cmd string, so that the following + command won't work. + + :edit +10|s/X/^V / file.c + + I intend to handle the literal next character in edit/ex consistently + with how it is handled in other commands. + + More fun facts to know and tell: + The acid test for the ex/edit commands: + + date > file1; date > file2 + vi + :edit +1|s/./XXX/|w file1| e file2|1 | s/./XXX/|wq + + No version of vi, of which I'm aware, handles it. + +4.2: The set command: + + The set command treats ^V's as literal characters, so the following + command won't work. Backslashes do work in this case, though, so + the second version of the command does work. + + set tags=tags_file1^V tags_file2 + set tags=tags_file1\ tags_file2 + + I intend to continue permitting backslashes in set commands, but + to also permit literal next characters to work as well. This is + backward compatible, but will also make set consistent with the + other commands. I think it's unlikely to break any historic + .exrc's, given that there are probably very few files with ^V's + in their name. + +4.3: The tag command: + + The tag command ignores ^V's and backslashes; there's no way to + get a space into a tag name. + + I think this is a don't care, and I don't intend to fix it. + +5: Regular expressions: + + :global /pattern/ command + :substitute /pattern/replace/ + :vglobal /pattern/ command + + I intend to treat a backslash in the pattern, followed by the + delimiter character or a backslash, as that literal character. + + This is historic behavior in vi. It would get rid of a fairly + hard-to-explain special case if we could just use the character + immediately following the backslash in all cases, or, if we + changed nvi to permit using the literal next character as a + pattern escape character, but that would probably break historic + scripts. + + There is an additional escaping issue for regular expressions. + Within the pattern and replacement, the '|' character did not + delimit ex commands. For example, the following is legal. + + :substitute /|/PIPE/|s/P/XXX/ + + This is a special case that I will support. + +6: Ending anything with an escape character: + + In all of the above rules, an escape character (either ^V or a + backslash) at the end of an argument or file name is not handled + specially, but used as a literal character. diff --git a/usr.bin/vi/docs/internals/structures b/usr.bin/vi/docs/internals/structures new file mode 100644 index 000000000000..d49ab65cbeed --- /dev/null +++ b/usr.bin/vi/docs/internals/structures @@ -0,0 +1,61 @@ +# @(#)structures 5.2 (Berkeley) 11/1/93 + +There are three major data structures in this package. The first is a +single global structure (named GS) which contains information common to +all files and screens. It's really pretty tiny, and functions more as a +single place to hang things than anything else. + +The second and third structures are the file structures (named EXF) and +the screen structures (named SCR). They contain information theoretically +unique to a screen or file, respectively. Each SCR structure has a set +of functions which update the screen and/or return information about the +screen from the underlying screen package. + +The GS structure contains linked lists SCR structures. The structures +can also be classed by persistence. The GS structure never goes away +and the SCR structure persists over instances of files. + +File names have different properties than files themselves, so the name +information for a file is held in an FREF structure which is chained from +the SCR structure. + +In general, functions are always passed an SCR structure and often an EXF +structure as well. The SCR structure is necessary for any routine that +wishes to talk to the screen, the EXF structure is necessary for any +routine that wants to modify the file. The relationship between an SCR +structure and its underlying EXF structure is not fixed, and although you +can translate from an SCR to the underlying EXF, it is discouraged. If +this becomes too onerous, I suspect I'll just stop passing around the EXF +in the future. + +The naming of the structures is consistent across the program. (Macros +even depend on it, so don't try and change it!) The global structure is +"gp", the screen structure is "sp", and the file structure is "ep". + +A few other data structures: + +TEXT In nvi/cut.h. This structure describes a portion of a line, + and is used by the input routines and as the "line" part of a + cut buffer. + +CB In nvi/cut.h. A cut buffer. A cut buffer is a place to + hang a list of TEXT structures. + +MARK In nvi/mark.h. A cursor position, consisting of a line number + and a column number. + +MSG In nvi/msg.h. A chain of messages for the user. + +SEQ In nvi/seq.h. An abbreviation or a map entry. + +EXCMDARG + In nvi/ex/excmd.h.stub. The structure that gets passed around + to the functions that implement the ex commands. (The main + ex command loop (see nvi/ex/ex.c) builds this up and then passes + it to the ex functions.) + +VICMDARG + In nvi/vi/vcmd.h. The structure that gets passed around to the + functions that implement the vi commands. (The main vi command + loop (see nvi/vi/vi.c) builds this up and then passes it to the + vi functions.) diff --git a/usr.bin/vi/docs/tutorial/vi.advanced b/usr.bin/vi/docs/tutorial/vi.advanced new file mode 100644 index 000000000000..f757ad19c44a --- /dev/null +++ b/usr.bin/vi/docs/tutorial/vi.advanced @@ -0,0 +1,1458 @@ +Section 26: Index to the rest of the tutorial + +The remainder of the tutorial can be perused at your leisure. Simply find the +topic of interest in the following list, and {/Section xx:/^M} to get to the +appropriate section. (Remember that ^M means the return key) + +The material in the following sections is not necessarily in a bottom up +order. It should be fairly obvious that if a section mentions something with +which you are not familiar, say, buffers, you might {/buffer/^M} followed by +several {n} to do a keyword search of the file for more details on that item. +Another point to remember is that commands are surrounded by curly-braces and +can therefore be found rather easily. To see where, say, the X command is +used try {/{X}/^M}. Subsequent {n} will show you other places the command was +used. We have tried to maintain the convention of placing the command letter +surrounded by curly-braces on the section line where that command is +mentioned. + +Finally, you should have enough 'savvy' at this point to be able to do your +own experimentation with commands without too much hand-holding on the part of +the tutorial. Experimentation is the best way to learn the effects of the +commands. + + Section Topic - description + ------- ------------------- +(Sections 1 through 25 are located in the file vi.beginner.) + 1 introduction: {^F} {ZZ} + 2 introduction (con't) and positioning: {^F} {^B} + 3 introduction (con't) and positioning: {^F} {^B} + 4 positioning: {^F} {^B} ^M (return key) + 5 quitting: {:q!} ^M key + 6 marking, cursor and screen positioning: {m} {G} {'} {z} + 7 marking, cursor and screen positioning: {m} {G} {'} {z} + 8 marking, cursor and screen positioning: {z} {m} {'} + 9 marking and positioning: {m} {''} + 10 line positioning: {^M} {-} + 11 scrolling with {^M} + 12 scrolling with {-} and screen adjustment {z} + 13 notes on use of tutorial + 14 other scrolling and postioning commands: {^E} {^Y} {^D} {^U} + 15 searching: {/ .. /^M} + 16 searching: {? .. ?^M} {n} (in search strings ^ $) + 17 searching: \ and magic-characters in search strings + 18 colon commands, exiting: {:} {ZZ} + 19 screen positioning: {H} {M} {L} + 20 character positioning: {w} {b} {0} {W} {B} {e} {E} {'} {`} + 21 cursor positioning: {l} {k} {j} {h} + 22 adding text: {i} {a} {I} {A} {o} {O} ^[ (escape key) + 23 character manipulation: {f} {x} {X} {w} {l} {r} {R} {s} {S} {J} + 24 undo: {u} {U} + 25 review +(The following sections are in this file.) + 26 Index to the rest of the tutorial ******** YOU ARE HERE ******* + 27 discussion of repeat counts and the repeat command: {.} + 28 more on low-level character motions: {t} {T} {|} + 29 advanced correction operators: {d} {c} + 30 updating the screen: {^R} + 31 text buffers: {"} + 32 rearranging and duplicating text: {p} {P} {y} {Y} + 33 recovering lost lines + 34 advanced file manipulation with vi + 34.1 more than one file at a time: {:n} + 34.2 reading files and command output: {:r} + 34.3 invoking vi from within vi: {:e} {:vi} + 34.4 escaping to a shell: {:sh} {:!} + 34.5 writing parts of a file: {:w} + 34.6 filtering portions of text: {!} + 35 advanced searching: magic patterns + 36 advanced substitution: {:s} + 37 advanced line addressing: {:p} {:g} {:v} + 38 higher level text objects and nroff: ( ) { } [[ ]] + 39 more about inserting text + 40 more on operators: {d} {c} {<} {>} {!} {=} {y} + 41 abbreviations: {:ab} + 42 vi's relationship with the ex editor: {:} + 43 vi on hardcopy terminals and dumb terminals: open mode + 44 options: {:set} {setenv EXINIT} + 44.1 autoindent + 44.2 autoprint + 44.3 autowrite + 44.4 beautify + 44.5 directory + 44.6 edcompatible + 44.7 errorbells + 44.8 hardtabs + 44.9 ignorecase + 44.10 lisp + 44.11 list + 44.12 magic + 44.13 mesg + 44.14 number + 44.15 open + 44.16 optimize + 44.17 paragraphs + 44.18 prompt + 44.19 readonly + 44.20 redraw + 44.21 remap + 44.22 report + 44.23 scroll + 44.24 sections + 44.25 shell + 44.26 shiftwidth + 44.27 showmatch + 44.28 slowopen + 44.29 tabstop + 44.30 tags + 44.31 taglength + 44.32 term + 44.33 terse + 44.34 timeout + 44.35 ttytype + 44.36 warn + 44.37 window + 44.38 wrapscan + 44.39 wrapmargin + 44.40 writeany + 44.41 w300, w1200, w9600 + +Section 27: repetition counts and the repeat command {.} + +Most vi commands will use a preceding count to affect their behavior in some +way. We have already seen how {3x} deletes three characters, and {22G} moves +us to line 22 of the file. For almost all of the commands, one can survive by +thinking of these leading numbers as a 'repeat count' specifying that the +command is to be repeated so many number of times. + +Other commands use the repeat count slightly differently, like the {G} command +which use it as a line number. + +For example: + +{3^D} means scroll down in the file three lines. Subsequent {^D} OR {^U} will +scroll only three lines in their respective directions! + +{3z^M} says put line three of the file at the top of the screen, while {3z.} +says put line three as close to the middle of the screen as possible. + +{50|} moves the cursor to column fifty in the current line. + +{3^F} says move forward 3 screenfulls. This is a repetition count. The +documents advertise that {3^B} should move BACK three screenfulls, but I +can't get it to work. + +Position the cursor on some text and try {3r.}. This replaces three characters +with '...'. However, {3s.....^[} is the same as {3xi.....^[}. + +Try {10a+----^[}. + +A very useful instance of a repetition count is one given to the '.' command, +which repeats the last 'change' command. If you {dw} and then {3.}, you will +delete first one and then three words. You can then delete two more words with +{2.}. If you {3dw}, you will delete three words. A subsequent {.} will delete +three more words. But a subsequent {2.} will delete only two words, not three +times two words. + +Caveat: The author has noticed that any repetition count with {^B} will NOT +work: indeed, if you are at the end of your file and try {3^B} sufficiently +often, the editor will hang you in an infinite loop. Please don't try it: +take my word for it. + +Section 28: {t} {T} {|} + +Position the cursor on line 13 below: + +Line 13: Four score and seven years ago, our forefathers brought ... + +Note that {fv} moves the cursor on/over the 'v' in 'seven'. Do a {0} to return +to the beginning of the line and try a {tv}. The cursor is now on/over the +first 'e' in 'seven'. The {f} command finds the next occurrence of the +specified letter and moves the cursor to it. The {t} command finds the +specified letter and moves the cursor to the character immediately preceding +it. {T} searches backwards, as does {F}. + +Now try {60|}: the cursor is now on the 'o' in 'brought', which is the +sixtieth character on the line. + +Section 29: {d} {c} + +Due to their complexity we have delayed discussion of two of the most powerful +operators in vi until now. Effective use of these operators requires more +explanation than was deemed appropriate for the first half of the tutorial. + +{d} and {c} are called operators instead of commands because they consist of +three parts: a count specification or a buffer specification (see section +#BUFFERS), the {d} or {c}, and the object or range description. We will not +discuss buffers at this stage, but will limit ourselves to count +specifications. Examples speak louder than words: position the cursor at the +beginning of line 14: + +Line 14: Euclid alone has looked on beauty bear. + +Obviously, there is something wrong with this quotation. Type {2fb} to +position the cursor on the 'b' of 'bear'. Now, type {cwbare^[} +and observe the results. The {cw} specifies that the change command {c} is to +operate on a word object. More accurately, it specifies that the range of the +change command includes the next word. + +Position the cursor on the period in Line 14. (one way is to use {f.}) +Now, type {cbbeast^[}. This specifies the range of the change command to be the +previous word (the 'b' reminiscent of the {b} command). If we had wished to +delete the word rather than change it, we would have used the {d} operator, +rather than the {c} operator. + +Position the cursor at the beginning of the line with {0}. Type +{d/look/^M}. The search string specified the range of the delete. +Everything UP TO the word 'looking' was deleted from the line. + +In general, almost any command that would move the cursor will specify a range +for these commands. The most confusing exception to this rule is when {dd} or +{cc} is entered: they refer to the whole line. Following is a summary of the +suffixes (suffices? suffici?) and the ranges they specify: + + suffix will delete{d}/change{c} + ------ ------------------------ + ^[ cancels the command + w the word to the right of the cursor + W ditto, but ignoring punctuation + b the word to the left of the cursor + B ditto, but ignoring punctuation + e see below. + E ditto + (space) a character + $ to the end of the line + ^ to the beginning of the line + / .. / up to, but not including, the string + ? .. ? back to and including the string + fc up to and including the occurrence of c + Fc back to and including the occurrence of c + tc up to but not including the occurrence of c + Tc back to but not including the occurrence of c + ^M TWO lines (that's right: two) + (number)^M that many lines plus one + (number)G up to and including line (number) + ( the previous sentence if you are at the beginning of + the current sentence, or the current sentence up to where + you are if you are not at the beginning of the current + sentence. Here, 'sentence' refers to the intuitive + notion of an English sentence, ending with '!', '?', + or '.' and followed by an end of line or two spaces. + ) the rest of the current sentence + { analogous to '(', but in reference to paragraphs: + sections of text surrounded by blank lines + } analogous to ')', but in reference to paragraphs + [[ analogous to '(', but in reference to sections + ]] analogous to ')', but in reference to sections + H the first line on the screen + M the middle line on the screen + L the last line on the screen + 3L through the third line from the bottom of the screen + ^F forward a screenful + ^B backward a screenful + : + : etc. etc. etc. + +This list is not exhaustive, but it should be sufficient to get the idea +across: after the {c} or {d} operator, you can specify a range with another +move-the-cursor command, and that is the region of text over which the command +will be effective. + +Section 30: updating the screen {^R} + +Vi tries to be very intelligent about the type of terminal you are working on +and tries to use the in-terminal computing power (if any) of your terminal. +Also if the terminal is running at a low baud rate (say 1200 or below), vi sets +various parameters to make things easier for you. For example, if you were +running on a 300 baud terminal (that's 30 characters per second transmission +rate) not all 24 lines of the screen would be used by vi. In addition, there +is a large portion of the editor keeping track of what your screen currently +looks like, and what it would look like after a command has been executed. Vi +then compares the two, and updates only those portions of the screen that have +changed. + +Furthermore, some of you may have noticed (it depends on your terminal) that +deleting lines or changing large portions of text may leave some lines on the +screen looking like: +@ +meaning that this line of the screen does not correspond to any line in your +file. It would cost more to update the line than to leave it blank for the +moment. If you would like to see your screen fully up-to-date with the +contents of your file, type {^R}. + +To see it in action, delete several lines with {5dd}, type {^R}, and then type +{u} to get the lines back. + +Here is as good a place as any to mention that if the editor is displaying the +end of your file, there may be lines on the screen that look like: +~ +indicating that that screen line would not be affected by {^R}. These lines +simply indicate the end of the file. + +Section 31: text buffers {"} + +Vi gives you the ability to store text away in "buffers". This feature is very +convenient for moving text around in your file. There are a total of thirty- +five buffers available in vi. There is the "unnamed" buffer that is used by all +commands that delete text, including the change operator {c}, the substitute +and replace commands {s} and {r}, as well as the delete operator {d} and delete +commands {x} and {X}. This buffer is filled each time any of these commands +are used. However, the undo command {u} has no effect on the unnamed buffer. + +There are twenty-six buffers named 'a' through 'z' which are available for the +user. If the name of the buffer is capitalized, then the buffer is not +overwritten but appended to. For example, the command {"qdd} will delete one +line and store that line in the 'q' buffer, destroying the previous contents of +the buffer. However, {"Qdd} will delete one line of text and append that line +to the current contents of the 'q' buffer. + +Finally, there are nine buffers named '1' through '9' in which the last nine +deletes are stored. Buffer 1 is the default buffer for the modify commands and +is sometimes called the unnamed buffer. + +To reference a specific buffer, use the double-quote command {"} followed by +the name of the buffer. The next two sections show how buffers can be used to +advantage. + +Section 32: rearranging and duplicating text: {y} {Y} {p} {P} + +Position yourself on line 15 below and {z^M}: + +Line 15: A tree as lovely as a poem ... +Line 16: I think that I shall never see + +Type {dd}. Line 15 has disappeared and been replaced with the empty line (one +with the single character @ on it) or (again depending on your terminal) Line +16 has moved up and taken its place. We could recover Line 15 with an undo +{u} but that would simply return it to its original location. Obviously, the +two lines are reversed, so we want to put line 15 AFTER line 16. This is +simply done with the put command {p}, which you should type now. What has +happened is that {dd} put Line 15 into the unnamed buffer, and the {p} command +retrieved the line from the unnamed buffer. + +Now type {u} and observe that Line 15 disappears again (the put was undone +without affecting the unnamed buffer). Type {P} and see that the capital {P} +puts the line BEFORE the cursor. + +To get Line 15 where it belongs again type {dd}{p}. + +Also in Line 15 note that the words 'tree' and 'poem' are reversed. Using the +unnamed buffer again: {ft}{dw}{ma}{fp}{P}{w}{dw}{`aP} will set things aright +(note the use of the reverse quote). + +The put commands {p} and {P} do not affect the contents of the buffer. +Therefore, multiple {p} or {P} will put multiple copies of the unnamed buffer +into your file. + +Experiment with {d} and {p} on words, paragraphs, etc. Whatever {d} +deletes, {p} can put. + +Position the cursor on Line 17 and {z^M}: + +Line 17: interest apple cat elephant boy dog girl hay farmer + +Our task is to alphabetize the words on line 17. With the named buffers (and a +contrived example) it is quite easy: + +{"idw}{"adw}{"cdw}{"edw}{"bdw}{"ddw}{"gdw}{"hdw}{"fdw} + +stores each of the words in the named buffer corresponding to the first letter +of each of the words ('interest' goes in buffer "i, 'apple' goes in buffer "a, +etc.). Now to put the words in order type: + +{"ap$}{"bp$}{"cp$}{"dp$}{"ep$}{"fp$}{"gp$}{"hp$}{"ip$} + +Notice that, because 'farmer' was at the end of the line, {dw} did not include +a space after it, and that, therefore, there is no space between 'farmer' and +'girl'. This is corrected with {Fg}{i ^[}. + +This example could have been done just as easily with lines as with +words. + +You do not have to delete the text in order to put it into a buffer. If all +you wish to do is to copy the text somewhere else, don't use {d}, rather use +the yank commands {y} or {Y}. {y} is like {d} and {c} - an operator rather +than a command. It, too, takes a buffer specification and a range +specification. Therefore, instead of {dw}{P} to load the unnamed buffer with a +word without deleting the word, use {yw} (yank a word). + +{Y} is designed yank lines, and not arbitrary ranges. That is, {Y} is +equivalent to {yy} (remember that operators doubled means the current line), +and {3Y} is equivalent to {3yy}. + +If the text you yank or modify forms a part of a line, or is an object such as +a sentence which partially spans more than one line, then when you put the text +back, it will be placed after the cursor (or before if you use {P}). If the +yanked text forms whole lines, they will be put back as whole lines, without +changing the current line. In this case, the put acts much like the {o} or {O} +command. + +The named buffers "a through "z are not affected by changing edit files. +However, the unnamed buffer is lost when you change files, so to move text from +one file to another you should use a named buffer. + +Section 33: recovering lost lines + +Vi also keeps track of the last nine deletes, whether you ask for it or not. +This is very convenient if you would like to recover some text that was +accidentally deleted or modified. Position the cursor on line 18 following, +and {z^M}. + + +Line 18: line 1 +Line 19: line 2 +Line 20: line 3 +Line 21: line 4 +Line 22: line 5 +Line 23: line 6 +Line 24: line 7 +Line 25: line 8 +Line 26: line 9 +Type {dd} nine times: now don't cheat with {9dd}! That is totally different. + +The command {"1p} will retrieve the last delete. Furthermore, when the +numbered buffers are used, the repeat-command command {.} will increment the +buffer numbers before executing, so that subsequent {.} will recover all nine +of the deleted lines, albeit in reverse order. If you would like to review the +last nine deletes without affecting the buffers or your file, do an undo {u} +after each put {p} and {.}: + +{"1p}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.} + +will show you all the buffers and leave them and your file intact. + +If you had cheated above and deleted the nine lines with {9dd}, all nine lines +would have been stored in both the unnamed buffer and in buffer number 1. +(Obviously, buffer number 1 IS the unnamed buffer and is just the default +buffer for the modify commands.) + +Section 34: advanced file manipulation: {:r} {:e} {:n} {:w} {!} {:!} + +We've already looked at writing out the file you are editing with the +{:w} command. Now let's look at some other vi commands to make editing +more efficient. + +Section 34.1: more than one file at a time {:n} {:args} + +Many times you will want to edit more than one file in an editing session. +Instead of entering vi and editing the first file, exiting, entering vi and +editing the second, etc., vi will allow you to specify ALL files that you wish +to edit on the invocation line. Therefore, if you wanted to edit file1 and +file2: + +% vi file1 file2 + +will set up file1 for editing. When you are done editing file one, write it +out {:w^M} and then type {:n^M} to get the next file on the list. On large +programming projects with many source files, it is often convenient just to +specify all source files with, say: + +% vi *.c + +If {:n^M} brings in a file that does not need any editing, another {:n^M} +will bring in the next file. + +If you have made changes to the first file, but decide to discard these changes +and proceed to the next file, {:n!^M} forces the editor to discard the current +contents of the editor. + +You can specify a new list of files after {:n}; e.g., {:n f1 f2 f3^M}. This +will replace the current list of files (if any). + +You can see the current list of files being edited with {:args^M}. + +Section 34.2: reading files and command output: {:r} + +Typing {:r fname^M} will read the contents of file fname into the editor and +put the contents AFTER the cursor line. + +Typing {:r !cmd^M} will read the output of the command cmd and place that +output after the cursor line. + +Section 34.3: invoking vi from within vi: {:e} {:vi} + +To edit another file not mentioned on the invocation line, type {:e filename^M} +or {:vi filename^M}. If you wish to discard the changes to the current file, +use the exclamation point after the command, e.g. {:e! filename^M}. + +Section 34.4: escaping to a shell: {:sh} {:!} {^Z} + +Occasionally, it is useful to interrupt the current editing session to perform +a UNIX task. However, there is no need to write the current file out, exit +the editor, perform the task, and then reinvoke the editor on the same file. +One thing to do is to spin off another process. If there are several UNIX +commands you will need to execute, simply create another shell with {:sh^M}. +At this point, the editor is put to sleep and will be reawakened when you log +out of the shell. + +If it is a single command that you want to execute, type {:!cmd^M}, where cmd +is the command that you wish to run. The output of the command will come to +the terminal as normal, and will not be made part of your file. The message +"[Hit return to continue]" will be displayed by vi after the command is +finished. Hitting return will then repaint the screen. Typing another +{:!cmd^M} at this point is also acceptable. + +However, there is a quicker, easier way: type {^Z}. Now this is a little +tricky, but hang in there. When you logged into UNIX, the first program you +began communicating with was a program that is called a "shell" (i.e. it 'lays +over' the operating system protecting you from it, sort of like a considerate +porcupine). When you got your first prompt on the terminal (probably a '%' +character) this was the shell telling you to type your first command. When +you typed {vi filename} for some file, the shell did not go away, it just went +to sleep. The shell is now the parent of vi. When you type {^Z} the editor +goes to sleep, the shell wakes up and says "you rang?" in the form of another +prompt (probably '%'). At this point you are talking to the shell again and +you can do anything that you could before including edit another file! (The +only thing you can't do is log out: you will get the message "There are +stopped jobs.") + +When your business with the shell is done, type {fg} for 'foreground' and the +last process which you ^Z'd out of will be reawakened and the shell will go +back to sleep. I will refer you to the documentation for the Berkeley shell +'csh' for more information on this useful capability. + +Section 34.5: writing parts of a file: {:w} + +The {:w} command will accept a range specifier that will then write only a +selected range of lines to a file. To write this section to a file, position +the cursor on the section line (e.g. {/^Section 34.5:/^M}) and {z^M}. Now type +{^G} to find out the line number (it will be something like "line 513"). Now +{/^Section 34.6:/-1^M} to find the last line of this section, and {^G} to find +its line number (it will be something like 542). To write out this section of +text by itself to a separate file which we will call "sepfile", type +{:510,542w sepfile^M}. If sepfile already exists, you will have to use the +exclamation point: {:1147,1168w! sepfile^M} or write to a different, non- +existent file. + +{:!cat sepfile^M} will display the file just written, and it should be the +contents of this section. + +There is an alternate method of determining the line numbers for the write. +{:set number^M} will repaint the screen with each line numbered. When the file +is written and the numbers no longer needed, {:set nonumber^M} will remove the +numbers, and {^R} will adjust the screen. + +Or, if you remember your earlier lessons about marking lines of text, +mark the beginning and ending lines. Suppose we had used {ma} to mark the +first line of the section and {mb} to mark the last. Then the command +{:'a,'bw sepfile^M} will write the section into "sepfile". In general, +you can replace a line number with the 'name' of a marked line (a single-quote +followed by the letter used to mark the line) + + +Section 34.6: filtering portions of text: {!} + +{!} is an operator like {c} and {d}. That is, it consists of a repetition +count, {!}, and a range specifier. Once the {!} operator is entered in its +entirety, a prompt will be given at the bottom of the screen for a UNIX +command. The text specified by the {!} operator is then deleted and +passed/filtered/piped to the UNIX command you type. The output of the UNIX +command is then placed in your file. For example, place the cursor at the +beginning of the following line and {z^M}: + +ls -l vi.tutorial +********* marks the bottom of the output from the ls command ********** + +Now type {!!csh^M}. The line will be replaced with the output from the ls +command. The {u} command works on {!}, also. + +Here is an extended exercise to display some of these capabilities. When this +tutorial was prepared, certain auxiliary programs were created to aid in its +development. Of major concern was the formatting of sections of the tutorial +to fit on a single screen, particularly the first few sections. What was +needed was a vi command that would 'format' a paragraph; that is, fill out +lines with as many words as would fit in eighty columns. There is no such vi +command. Therefore, another method had to be found. + +Of course, nroff was designed to do text formatting. However, it produces a +'page'; meaning that there may be many blank lines at the end of a formatted +paragraph from nroff. The awk program was used to strip these blank lines from +the output from nroff. Below are the two files used for this purpose: I refer +you to documentation on nroff and awk for a full explanation of their function. +Position the cursor on the next line and {z^M}. + +******** contents of file f ********** +# +nroff -i form.mac | awk "length != 0 { print }" +***** contents of file form.mac ****** +.na +.nh +.ll 79 +.ec +.c2 +.cc +************************************** + +Determine the line numbers of the two lines of file f. They should be +something like 574 and 575, although you better double check: this file is +under constant revision and the line numbers may change inadvertently. Then +{:574,575w f^M}. Do the same for the lines of file form.mac. They will be +approximately 577 and 582. Then {:577,582w form.mac^M}. File f must have +execute privileges as a shell file: {:!chmod 744 f^M}. + +Observe that this paragraph is +rather ratty in appearance. With our newly created files we can +clean it up dramatically. Position the cursor at the beginning +of this paragraph and type the following sequence of +characters +(note that we must abandon temporarily our convention +of curly braces since the command itself contains a curly brace - we +will use square brackets for the nonce): [!}f^M]. + +Here is a brief explanation of what has happened. By typing [!}f^M] we +specified that the paragraph (all text between the cursor and the first blank +line) will be removed from the edit file and piped to a UNIX program called +"f". This is a shell command file that we have created. This shell file runs +nroff, pipes its output to awk to remove blank lines, and the output from awk +is then read back into our file in the place of the old, ratty paragraph. The +file form.mac is a list of commands to nroff to get it to produce paragraphs +to our taste (the right margin is not justified, the line is 79 characters +long, words are not hyphenated, and three nroff characters are renamed to +avoid conflict: note that in this file, the {^G} you see there is vi's display +of the control-G character, and not the two separate characters ^ up-arrow and +G upper-case g). + +This example was created before the existence of the fmt program. I now type +[!}fmt^M] to get the same effect much faster. Actually, I don't type those +six keys each time: I have an abbreviation (which see). + +Section 35: searching with magic patterns + +The documentation available for "magic patterns" (i.e. regular expressions) is +very scanty. The following should explain this possibly very confusing feature +of the editor. This section assumes that the magic option is on. To make +sure, you might want to type {:set magic^M}. + +By "magic pattern" we mean a general description of a piece of text that the +editor attempts to find during a search. Most search patterns consist of +strings of characters that must be matched exactly, e.g. {/card/^M} searches +for a specific string of four characters. Let us suppose that you have +discovered that you consistently have mistyped this simple word as either ccrd +or czrd (this is not so far-fetched for touch typists). You could {/ccrd/^M} +and {n} until there are no more of this spelling, followed by {/czrd/^M} and +{n} until there are no more of these. Or you could {/c.rd/^M} and catch all of +them on the first pass. Try typing {/c.rd/^M} followed by several {n} and +observe the effect. + +Line 27: card cord curd ceard + +When '.' is used in a search string, it has the effect of matching any single +character. + +The character '^' (up-arrow) used at the beginning of a search string means +the beginning of the line. {/^Line 27/^M} will find the example line above, +while {/Line 27/^M} will find an occurrence of this string anywhere in the +line. + +Similarly, {/ the$/^M} will find all occurrences of the word 'the' occurring +at the end of a line. There are several of them in this file. + +Note that {:set nomagic^M} will turn off the special meaning of these magic +characters EXCEPT for '^' and '$' which retain their special meanings at the +beginning and end of a search string. Within the search string they hold no +special meaning. Try {/\/ the$\//^M} and note that the dollar-sign is not the +last character in the search string. Let the dollar-sign be the last +character in the search string, as in {/\/ the$/^M} and observe the result. + +Observe the result of {/back.*file/^M}. This command, followed by sufficient +{n}, will show you all lines in the file that contain both the words 'back' +and 'file' on the same line. The '*' magic character specifies that the +previous regular expression (the '.' in our example) is to be repeatedly +matched zero or more times. In our example we specified that the words 'back' +and 'file' must appear on the same line (they may be parts of words such as +'backwards' or 'workfile') separated by any number (including zero) of +characters. + +We could have specified that 'back' and 'file' are to be words by themselves by +using the magic sequences '\<' or '\>'. E.g. {/\<back\>.*\<file\>/^M}. The +sequence '\<' specifies that this point of the search string must match the +beginning of a word, while '\>' specifies a match at the end of a word. By +surrounding a string with these characters we have specified that they must be +words. + +To find all words that begin with an 'l' or a 'w', followed by an 'a' or an +'e', and ending in 'ing', try {/\<[lw][ea][a-z]*ing\>/^M}. This will match +words like 'learning', 'warning', and 'leading'. The '[..]' notation matches +exactly ONE character. The character matched will be one of the characters +enclosed in the square brackets. The characters may be specified individually +as in [abcd] or a '-' may be used to specify a range of characters as in [a-d]. +That is, [az] will match the letter 'a' OR the letter 'z', while [a-z] will +match any of the lower case letters from 'a' through 'z'. If you would like to +match either an 'a', a '-', or a 'z', then the '-' must be escaped: [a\-z] will +match ONE of the three characters 'a', '-', or 'z'. + +If you wish to find all Capitalized words, try {/\<[A-Z][a-z]*\>/^M}. The +following will find all character sequences that do NOT begin with an +uncapitalized letter by applying a special meaning to the '^' character in +square brackets: {/\<[^a-z][a-z]*\>/^M}. When '^' is the first character of a +square-bracket expression, it specifies "all but these characters". (No +one claimed vi was consistent.) + +To find all variable names (the first character is alphabetic, the remaining +characters are alphanumeric): try {/\<[A-Za-z][A-Za-z0-9]*\>/^M}. + +In summary, here are the primitives for building regular expressions: + + ^ at beginning of pattern, matches beginning of line + $ at end of pattern, matches end of line + . matches any single character + \< matches the beginning of a word + \> matches the end of a word + [str] matches any single character in str + [^str] matches any single character NOT in str + [x-y] matches any character in the ASCII range between x and y + * matches any number (including zero) of the preceding pattern + +Section 36: advanced substitution: {:s} + +The straightforward colon-substitute command looks like the substitute +command of most line-oriented editors. Indeed, vi is nothing more than a +superstructure on the line-oriented editor ex and the colon commands are +simply a way of accessing commands within ex (see section #EX). This gives us +a lot of global file processing not usually found in visual oriented editors. + +The colon-substitute command looks like: {:s/ .. / .. /^M} and will find the +pattern specified after the first slash (this is called the search pattern), +and replace it with the pattern specified after the second slash (called, +obviously enough, the replacement pattern). E.g. position the cursor on line +28 below and {:s/esample/example/^M}: + +Line 28: This is an esample. + +The {u} and {U} commands work for {:s}. The first pattern (the search pattern) +may be a regular expression just as for the search command (after all, it IS a +search, albeit limited to the current line). Do an {u} on the above line, and +try the following substitute, which will do almost the same thing: +{:s/s[^ ]/x/^M}. +Better undo it with {u}. The first pattern {s[^ ]} matches an 's' +NOT followed by a blank: the search therefore ignores the 's'es in 'This' and +'is'. However, the character matched by {[^ ]} must appear in the replacement +pattern. But, in general, we do not know what that character is! (In this +particular example we obviously do, but more complicated examples will follow.) +Therefore, vi (really ex) has a duplication mechanism to copy patterns matched +in the search string into the replacement string. Line 29 below is a copy of +line 28 above so you can adjust your screen. + +Line 29: This is an esample. + +In general, you can nest parts of the search pattern in \( .. \) and refer to +it in the replacement pattern as \n, where n is a digit. The problem outlined +in the previous paragraph is solved with {:s/s\([^ ]\)/x\1/^M}: try it. Here +\1 refers to the first pattern grouping \( .. \) in the search string. + +Obviously, for a single line, this is rather tedious. Where it becomes +powerful, if not necessary, is in colon-substitutes that cover a range of +lines. (See the next section for a particularly comprehensive example.) + +If the entire character sequence matched by the search pattern is needed in +the replacement pattern, then the unescaped character '&' can be used. On +Line 29 above, try {:s/an e.ample/not &/^M}. If another line is to have the +word 'not' prepended to a pattern, then '~' can save you from re-typing the +replacement pattern. E.g. {:s/some pattern/~/^M} after the previous example +would be equivalent to {:s/some pattern/not &/^M}. + +One other useful replacement pattern allows you to change the case of +individual letters. The sequences {\u} and {\l} cause the immediately +following character in the replacement to be converted to upper- or lower-case, +respectively, if this character is a letter. The sequences {\U} and {\L} turn +such conversion on, either until {\E} or {\e} is encountered, or until the end +of the replacement pattern. + +For example, position the cursor on a line: pick a line, any line. Type +{:s/.*/\U&/^M} and observe the result. You can undo it with {u}. + +The search pattern may actually match more than once on a single line. +However, only the first pattern is substituted. If you would like ALL +patterns matched on the line to be substituted, append a 'g' after the +replacement pattern: {:s/123/456/g^M} will substitute EVERY occurrence +on the line of 123 with 456. + +Section 37: advanced line addressing: {:p} {:g} {:v} + +Ex (available through the colon command in vi) offers several methods for +specifying the lines on which a set of commands will act. For example, if you +would like to see lines 50 through 100 of your file: {:50,100p^M} will display +them, wait for you to [Hit return to continue], and leave you on line 100. +Obviously, it would be easier just to do {100G} from within vi. But +what if you would like to make changes to just those lines? Then the +addressing is important and powerful. + +Line 30: This is a text. +Line 31: Here is another text. +Line 32: One more text line. + +The lines above contain a typing error that the author of this tutorial tends +to make every time he attempts to type the word 'test'. To change all of these +'text's into 'test's, try the following: +{:/^Line 30/,/^Line 32/s/text/test/^M}. This finds the beginning and end of +the portion of text to be changed, and limits the substitution to each of the +lines in that range. The {u} command applies to ALL of the substitutions as +a group. + +This provides a mechanism for powerful text manipulations. +And very complicated examples. + +Line 33: This test is a. +Line 34: Here test is another. +Line 35: One line more test. + +The above three lines have the second word out of order. The following command +string will put things right. Be very careful when typing this: it is very +long, full of special characters, and easy to mess up. You may want to +consider reading the following section to understand it before trying the +experiment. Don't worry about messing up the rest of the file, though: the +address range is specified. + +{:/^Line 33/,/^Line 35/s/\([^:]*\): \([^ ]*\) \([^ ]*\) \([^.]*\)/\1: \2 \4 \3/^M} + +There are several things to note about this command string. First of all, the +range of the substitute was limited by the address specification {/^Line +33/,/^Line 35/^M}. It might have been simpler to do {:set number^M} to see the +line numbers directly, and then, in place of the two searches, typed +the line numbers, e.g. {1396,1398}. Or to mark the lines with {ma} and {mb} +and use {'a,'b}. + +Then follows the substitute pattern itself. To make it easier to understand +what the substitute is doing, the command is duplicated below with the various +patterns named for easier reference: + + s/\([^:]*\): \([^ ]*\) \([^ ]*\) \([^.]*\)/\1: \2 \4 \3/ + |--\1---| |--\2---| |--\3---| |--\4---| + |--------search pattern------------------|-replacement| + |--pattern---| + +In overview, the substitute looks for a particular pattern made up of +sub-patterns, which are named \1, \2, \3, and \4. These patterns are specified +by stating what they are NOT. Pattern \1 is the sequence of characters that +are NOT colons: in the search string, {[^:]} will match exactly one character +that is not a colon, while appending the asterisk {[^:]*} specifies that the +'not a colon' pattern is to be repeated until no longer satisfied, and +{\([^:]*\)} then gives the pattern its name, in this case \1. Outside of the +specification of \1 comes {: }, specifying that the next two characters must be +a colon followed by a blank. + +Patterns \2 and \3 are similar, specifying character sequences that are +not blanks. Pattern \4 matches up to the period at the end of the line. + +The replacement pattern then consists of specifying the new order of the +patterns. + +This is a particularly complicated example, perhaps the most complicated +in this tutorial/reference. For our small examples, it is obviously +tedious and error prone. For large files, however, it may be the most +efficient way to make the desired modifications. + +(The reader is advised to look at the documentation for awk. This tool is very +powerful and slightly simpler to use than vi for this kind of file +manipulation. But, it is another command language to learn.) + +Many times, you will not want to operate on every line in a certain +range. Rather you will want to make changes on lines that satisfy +certain patterns; e.g. for every line that has the string 'NPS' on it, +change 'NPS' to 'Naval Postgraduate School'. The {:g} addressing +command was designed for this purpose. The example of this paragraph +could be typed as {:g/NPS/s//Naval Postgraduate School/^M}. + +The general format of the command is {:g/(pattern)/cmds^M} and it +works in the following way: all lines that match the pattern +following the {:g} are 'tagged' in a special way. Then each of these +lines have the commands following the pattern executed over them. + +Line 36: ABC rhino george farmer Dick jester lest +Line 37: george farmer rhino lest jester ABC +Line 38: rhino lest george Dick farmer ABC jester + +Type: + +{:g/^Line.*ABC/s/Dick/Harry Binswanger/|s/george farmer/gentleman george/p^M} + +There are several things of note here. First, lines 36, 37, and 38 above are +tagged by the {:g}. Type {:g/^Line.*ABC/p^M} to verify this. Second, there +are two substitutes on the same line separated by '|'. In general, any colon +commands can be strung together with '|'. Third, both substitutes operate on +all three lines, even though the first stubstitute works on only two of the +lines (36 and 38). Fourth, the second substitute works on only two lines (36 +and 37) and those are the two lines printed by the trailing 'p'. + +The {:v} command works similarly to the {:g} command, except that the sense of +the test for 'tagging' the lines is reversed: all lines NOT matching the search +pattern are tagged and operated on by the commands. + +Using {^V} to quote carriage return (see section 39) can be used in global +substitutions to split two lines. For example, the command +{:g/\. /s//.^V^M/g^M} will change your file so that each sentence is on a +separate line. (Note that we have to 'escape' the '.', because '.' by itself +matches any character. Our command says to find any line which contains a +period followed by 2 spaces, and inserts a carriage return after the period.) + +Caveat: In some of the documentation for ex and vi you may find the +comment to the effect that {\^M} can be used between commands following +{:g}. The author of this tutorial has never gotten this to work and has +crashed the editor trying. + +Section 38: higher level text objects and nroff: {(} {)} [{] [}] {[[} {]]} + +(Note: this section may be a little confusing because of our command +notation. Using curly braces to surround command strings works fine as +long as the command string does not contain any curly braces itself. +However, the curly braces are legitimate commands in vi. Therefore, for +any command sequence that contains curly braces, we will surround that +sequence with SQUARE braces, as on the previous Section line.) + +In working with a document, particularly if using the text formatting +programs nroff or troff, it is often advantageous to work in terms of +sentences, paragraphs, and sections. The operations {(} and {)} move to +the beginning of the previous and next sentences, respectively. Thus +the command {d)} will delete the rest of the current sentence; likewise +{d(} will delete the previous sentence if you are at the beginning of +the current sentence, or, if you are not at the beginning of a sentence, +it will delete the current sentence from the beginning +up to where you are. + +A sentence is defined to end at a '.', '!', or '?' which is followed +by either the end of a line, or by two spaces. Any number of closing +')', ']', '"', and ''' characters may appear after the '.', '!', or '?' +before the spaces or end of line. Therefore, the {(} and {)} commands +would recognize only one sentence in the following line, but two +sentences on the second following line. + +Line 39: This is one sentence. Even though it looks like two. +Line 40: This is two sentences. Because it has two spaces after the '.'. + +The operations [{] and [}] move over paragraphs and the operations {[[} +and {]]} move over sections. + +A paragraph begins after each empty line, and also at each of a set of nroff +paragraph macros. A section begins after each line with a form-feed ^L in the +first column, and at each of a set of nroff section macros. When preparing a +text file as input to nroff, you will probably be using a set of nroff macros +to make the formatting specifications easier, or more to your taste. These +macros are invoked by beginning a line with a period followed by the one or two +letter macro name. Vi has been programmed to recognize these nroff macros, and +if it doesn't recognize your particular macro you can use the {:set paragraphs} +or {:set sections} commands so that it will. + +Section 39: more about inserting text + +There are a number of characters which you can use to make correnctions +during input mode. These are summarized in the following table. + + ^H deletes the last input character + ^W deletes the last input word + (erase) same as ^H; each terminal can define its own erase character; + for some it is ^H, for others it is the DELETE key, and for + others it is '@'. + (kill) deletes the input on this line; each terminal can define its + own line-kill character; for some it is ^U, for others it is + '@'; you will need to experiment on your terminal to find + out what your line-kill and erase characters are. + \ escapes a following ^H, (kill), and (erase) characters: i.e. + this is how to put these characters in your file. + ^[ escape key; ends insertion mode + ^? the delete key; interrupts an insertion, terminating it + abnormally. + ^M the return key; starts a new line. + ^D backtabs over the indentation set by the autoindent option + 0^D backtabs over all indentation back to the beginning of the line + ^^D (up-arrow followed by control-d)same as 0^D, except the indentation + will be restored at the beginning of the next line. + ^V quotes the next non-printing character into the file + +If you wish to type in your erase or kill character (say # or @ or ^U) then you +must precede it with a \, just as you would do at the normal system command +level. A more general way of typing non-printing characters into the file is +to precede them with a ^V. The ^V echoes as a ^ character on which the cursor +rests. This indicates that the editor expects you to type a control character +and it will be inserted into the file at that point. There are a few +exceptions to note. The implementation of the editor does not allow the null +character ^@ to appear in files. Also the linefeed character ^J is used by the +editor to separate lines in the file, so it cannot appear in the middle of a +line. (Trying to insert a ^M into a file, or putting it in the replacement +part of a substitution string will result in the matched line being split in +two. This, in effect, is how to split lines by using a substitution.) You can +insert any other character, however, if you wait for the editor to echo the ^ +before you type the character. In fact, the editor will treat a following +letter as a request for the corresponding control character. This is the only +way to type ^S or ^Q, since the system normally uses them to suspend and resume +output and never gives them to the editor to process. + +If you are using the autoindent option you can backtab over the indent which it +supplies by typing a ^D. This backs up to the boundary specified by the +shiftwidth option. This only works immediately after the supplied autoindent. + +When you are using the autoindent option you may wish to place a label at the +left margin of a line. The way to do this easily is to type ^ (up-arrow) and +then ^D. The editor will move the cursor to the left margin for one line, and +restore the previous indent on the next. You can also type a 0 followed +immediately by a ^D if you wish to kill all indentation and not have it resume +on the next line. + +Section 40: more on operators: {d} {c} {<} {>} {!} {=} {y} + +Below is a non-exhaustive list of commands that can follow the operators +to affect the range over which the operators will work. However, note +that the operators {<}, {>}, {!}, and {=} do not operate on any object +less than a line. Try {!w} and you will get a beep. To get the +operator to work on just the current line, double it. E.g. {<<}. + + suffix will operate on + ------ ------------------------ + ^[ cancels the command + w the word to the right of the cursor + W ditto, but ignoring punctuation + b the word to the left of the cursor + B ditto, but ignoring punctuation + e see below. + E ditto + (space) a character + $ to the end of the line + ^ to the beginning of the line + / .. / up to, but not including, the string + ? .. ? back to and including the string + fc up to and including the occurrence of c + Fc back to and including the occurrence of c + tc up to but not including the occurrence of c + Tc back to but not including the occurrence of c + ^M TWO lines (that's right: two) + (number)^M that many lines plus one + (number)G up to and including line (number) + ( the previous sentence if you are at the beginning of + the current sentence, or the current sentence up to where + you are if you are not at the beginning of the current + sentence. Here, 'sentence' refers to the intuitive + notion of an English sentence, ending with '!', '?', + or '.' and followed by an end of line or two spaces. + ) the rest of the current sentence + { analogous to '(', but in reference to paragraphs: + sections of text surrounded by blank lines + } analogous to ')', but in reference to paragraphs + [[ analogous to '(', but in reference to sections + ]] analogous to ')', but in reference to sections + H the first line on the screen + M the middle line on the screen + L the last line on the screen + 3L through the third line from the bottom of the screen + ^F forward a screenful + ^B backward a screenful + : + : etc. etc. etc. + +This list is not exhaustive, but it should be sufficient to get the idea +across: after the operator, you can specify a range with a move-the-cursor +command, and that is the region of text over which the operator will be +effective. + +Section 41: abbreviations: {:ab} + +When typing large documents you may find yourself typing a large phrase +over and over. Vi gives you the ability to specify an abbreviation for +a long string such that typing the abbreviation will automatically +expand into the longer phrase. + +Type {:ab nps Naval Postgraduate School^M}. Now type: + +{iThis is to show off the nps's UNIX editor.^M^[} + +Section 42: vi's relationship with the ex editor: {:} + +Vi is actually one mode of editing within the editor ex. When you are +running vi you can escape to the line oriented editor of ex by giving +the command {Q}. All of the colon-commands which were introduced above +are available in ex. Likewise, most ex commands can be invoked from vi +using {:}. + +In rare instances, an internal error may occur in vi. In this case you +will get a diagnostic and will be left in the command mode of ex. You can +then save your work and quit if you wish by giving the command {x} after +the colon prompt of ex. Or you can reenter vi (if you are brave) by +giving ex the command {vi}. + +Section 43: vi on hardcopy terminals and dumb terminals: open mode + +(The author has not checked the following documentation for accuracy. It is +abstracted from the Introduction to Vi Editing document.) + +If you are on a hardcopy terminal or a terminal which does not have a cursor +which can move off the bottom line, you can still use the command set of vi, +but in a different mode. When you give the vi command to UNIX, the editor will +tell you that it is using open mode. This name comes from the open command in +ex, which is used to get into the same mode. + +The only difference between visual mode (normal vi) and open mode is the way in +which the text is displayed. + +In open mode the editor uses a single line window into the file, and moving +backward and forward in the file causes new lines to be displayed, always below +the current line. Two commands of vi work differently in open: {z} and {^R}. +The {z} command does not take parameters, but rather draws a window of context +around the current line and then returns you to the current line. + +If you are on a hardcopy terminal, the {^R} command will retype the current +line. On such terminals, the editor normally uses two lines to represent the +current line. The first line is a copy of the line as you started to edit it, +and you work on the line below this line. When you delete characters, the +editor types a number of \'s to show you the characters which are deleted. The +editor also reprints the current line soon after such changes so that you can +see what the line looks like again. + +It is sometimes useful to use this mode on very slow terminals which can +support vi in the full screen mode. You can do this by entering ex and using +an {open} command. + +********************************************************************* +Section 44: options: {:set} {setenv EXINIT} + +You will discover options as you need them. Do not worry about them very much +on the first pass through this document. My advice is to glance through them, +noting the ones that look interesting, ignoring the ones you don't understand, +and try re-scanning them in a couple of weeks. + +If you decide that you have a favorite set of options and would like to change +the default values for the editor, place a {setenv EXINIT} command in your +.login file. When you are given an account under UNIX your directory has +placed in it a file that is executed each time you log in. If one of the +commands in this file sets the environment variable EXINIT to a string of vi +commands, you can have many things done for you each time you invoke vi. For +example, if you decide that you don't like tabstops placed every eight columns +but prefer every four columns, and that you wish the editor to insert linefeeds +for you when your typing gets you close to column 72, and you want +autoindentation, then include the following line in your .login file: + +setenv EXINIT='set tabstop=4 wrapmargin=8 autoindent' + +or equivalently + +setenv EXINIT='se ts=4 wm=8 ai' + +Each time you bring up vi, this command will be executed and the options set. + +There are forty options in the vi/ex editor that the user can set for his/her +own convenience. They are described in more detail in individual sections +below. The section line will show the full spelling of the option name, the +abbreviation, and the default value of the option. The text itself +comes from the ex reference manual and is not the epitome of clarity. + +Section 44.1: {autoindent}, {ai} default: noai + +Can be used to ease the preparation of structured program text. At the +beginning of each append, change or insert command or when a new line is opened +or created by an append, change, insert, or substitute operation within open or +visual mode, ex looks at the line being appended after, the first line changed +or the line inserted before and calculates the amount of white space at the +start of the line. It then aligns the cursor at the level of indentation so +determined. + +If the user then types lines of text in, they will continue to be justified at +the displayed indenting level. If more white space is typed at the beginning +of a line, the following line will start aligned with the first non-white +character of the previous line. To back the cursor up to the preceding tab +stop one can hit {^D}. The tab stops going backwards are defined at multiples +of the shiftwidth option. You cannot backspace over the indent, except by +sending an end-of-file with a {^D}. A line with no characters added to it +turns into a completely blank line (the white space provided for the autoindent +is discarded). Also specially processed in this mode are lines beginning with +an up-arrow `^' and immediately followed by a {^D}. This causes the input to +be repositioned at the beginning of the line, but retaining the previous indent +for the next line. Similarly, a `0' followed by a {^D} repositions at the +beginning but without retaining the previous indent. Autoindent doesn't happen +in global commands or when the input is not a terminal. + +Section 44.2: {autoprint}, {ap} default: ap + +Causes the current line to be printed after each delete, copy, join, move, +substitute, t, undo or shift command. This has the same effect as supplying a +trailing `p' to each such command. Autoprint is suppressed in globals, and +only applies to the last of many commands on a line. + +Section 44.3: {autowrite}, {aw} default: noaw + +Causes the contents of the buffer to be written to the current file if you have +modified it and give a next, rewind, stop, tag, or {!} command, or a control- +up-arrow {^^} (switch files) or {^]} (tag goto) command in visual. Note, that +the edit and ex commands do not autowrite. In each case, there is an +equivalent way of switching when autowrite is set to avoid the autowrite +({edit} for next, rewind! for rewind, stop! for stop, tag! for tag, shell +for {!}, and {:e #} and a {:ta!} command from within visual). + +Section 44.4: {beautify}, {bf} default: nobeautify + +Causes all control characters except tab ^I, newline ^M and form-feed ^L to be +discarded from the input. A complaint is registered the first time a backspace +character is discarded. Beautify does not apply to command input. + +Section 44.5: {directory}, {dir} default: dir=/tmp + +Specifies the directory in which ex places its buffer file. If this directory +in not writable, then the editor will exit abruptly when it fails to be able to +create its buffer there. + +Section 44.6: {edcompatible} default: noedcompatible + +Causes the presence or absence of g and c suffixes on substitute commands to be +remembered, and to be toggled by repeating the suffices. The suffix r makes +the substitution be as in the {~} command, instead of like {&}. + +[Author's note: this should not concern users of vi.] + +Section 44.7: {errorbells}, {eb} default: noeb + +Error messages are preceded by a bell. However, bell ringing in open and +visual modes on errors is not suppressed by setting noeb. If possible the +editor always places the error message in a standout mode of the terminal (such +as inverse video) instead of ringing the bell. + +Section 44.8: {hardtabs}, {ht} default: ht=8 + +Gives the boundaries on which terminal hardware tabs are set (or on which the +system expands tabs). + +Section 44.9: {ignorecase}, {ic} default: noic + +All upper case characters in the text are mapped to lower case in regular +expression matching. In addition, all upper case characters in regular +expressions are mapped to lower case except in character class specifications +(that is, character in square brackets). + +Section 44.10: {lisp} default: nolisp + +Autoindent indents appropriately for lisp code, and the {(}, {)}, [{], [}], +{[[}, and {]]} commands in open and visual modes are modified in a +striaghtforward, intuitive fashion to have meaning for lisp. + +[Author's note: but don't ask me to define them precisely.] + +Section 44.11: {list} default: nolist + +All printed lines will be displayed (more) unambiguously, showing tabs as ^I +and end-of-lines with `$'. This is the same as in the ex command {list}. + +Section 44.12: {magic} default: magic for {ex} and {vi}, nomagic for edit. + +If nomagic is set, the number of regular expression metacharacters is greatly +reduced, with only up-arrow `^' and `$' having special effects. In addition +the metacharacters `~' and `&' of the replacement pattern are treated as normal +characters. All the normal metacharacters may be made magic when nomagic is +set by preceding them with a `\'. + +[Author's note: In other words, if magic is set a back-slant turns the magic +off for the following character, and if nomagic is set a back-slant turns the +magic ON for the following character. And, no, we are not playing Dungeons and +Dragons, although I think the writers of these option notes must have played it +all the time.] + +Section 44.13: {mesg} default: mesg + +Causes write permission to be turned off to the terminal while you are in +visual mode, if nomesg is set. + +[Author's note: I don't know if anyone could have made any one sentence +paragraph more confusing than this one. What it says is: mesg allows people to +write to you even if you are in visual or open mode; nomesg locks your terminal +so they can't write to you and mess up your screen.] + +Section 44.14: {number, nu} default: nonumber + +Causes all output lines to be printed with their line numbers. In addition +each input line will be prompted with its line number. + +Section 44.15: {open} default: open + +If {noopen}, the commands open and visual are not permitted. This is set for +edit to prevent confusion resulting from accidental entry to open or visual +mode. + +[Author's note: As you may have guessed by now, there are actually three +editors available under Berkeley UNIX that are in reality the same +program, ex, with different options set: ex itself, vi, and edit.] + +Section 44.16: {optimize, opt} default: optimize + +Throughput of text is expedited by setting the terminal to not do automatic +carriage returns when printing more than one (logical) line of output, greatly +speeding output on terminals without addressable cursors when text with leading +white space is printed. + +[Author's note: I still don't know what this option does.] + +Section 44.17: {paragraphs, para} default: para=IPLPPPQPP LIbp + +Specifies the paragraphs for the [{] and [}] operations in open and visual. +The pairs of characters in the option's value are the names of the nroff macros +which start paragraphs. + +Section 44.18: {prompt} default: prompt + +Command mode input is prompted for with a `:'. + +[Author's note: Doesn't seem to have any effect on vi.] + +Section 44.19: {readonly}, {ro} default: noro, unless invoked with -R + or insufficient privileges on file + +This option allows you to guarantee that you won't clobber your file by +accident. You can set the option and writes will fail unless you use an `!' +after the write. Commands such as {x}, {ZZ}, the autowrite option, and in +general anything that writes is affected. This option is turned on if you +invoke the editor with the -R flag. + +Section 44.20: {redraw} default: noredraw + +The editor simulates (using great amounts of output), an intelligent terminal +on a dumb terminal (e.g. during insertions in visual the characters to the +right of the cursor position are refreshed as each input character is typed). +Useful only at very high baud rates, and should be used only if the system is +not heavily loaded: you will notice the performance degradation yourself. + +Section 44.21: {remap} default: remap + +If on, macros are repeatedly tried until they are unchanged. For example, if o +is mapped to O, and O is mapped to I, then if remap is set, o will map to I, +but if noremap is set, it will map to O . + +Section 44.22: {report} default: report=5 for ex and vi, 2 for edit + +Specifies a threshold for feedback from commands. Any command which modifies +more than the specified number of lines will provide feedback as to the scope +of its changes. For commands such as global, open, undo, and visual which have +potentially more far reaching scope, the net change in the number of lines in +the buffer is presented at the end of the command, subject to this same +threshold. Thus notification is suppressed during a global command on the +individual commands performed. + +Section 44.23: {scroll} default: scroll=1/2 window + +Determines the number of logical lines scrolled when a {^D} is received from a +terminal in command mode, and determines the number of lines printed by a +command mode z command (double the value of scroll). + +[Author's note: Doesn't seem to affect {^D} and {z} in visual (vi) mode.] + +Section 44.24: sections {sections} default: sections=SHNHH HU + +Specifies the section macros from nroff for the {[[} and {]]} operations in +open and visual. The pairs of characters in the options's value are the names +of the macros which start paragraphs. + +Section 44.25: {shell}, {sh} default: sh=/bin/sh + +Gives the path name of the shell forked for the shell escape command `!', and +by the shell command. The default is taken from SHELL in the environment, if +present. + +[Editor's note: I would suggest that you place the following line in +your .login file: +setenv SHELL '/bin/csh' +] + +Section 44.26: {shiftwidth}, {sw} default: sw=8 + +Used in reverse tabbing with {^D} when using autoindent to append text, and +used by the shift commands. Should probably be the same value as the tabstop +option. + +Section 44.27: {showmatch}, {sm} default: nosm + +In open and visual mode, when a `)' or `}' is typed, if the matching `(' or `{' +is on the screen, move the cursor to it for one second. Extremely useful with +complicated nested expressions, or with lisp. + +Section 44.28: {slowopen}, {slow} default: terminal dependent + +Affects the display algorithm used in visual mode, holding off display updating +during input of new text to improve throughput when the terminal in use is both +slow and unintelligent. See "An Introduction to Display Editing with Vi" for +more details. + +Section 44.29: {tabstop}, {ts} default: ts=8 + +The editor expands tabs ^I to tabstop boundaries in the display. + +Section 44.30: {taglength}, {tl} default: tl=0 + +Tags are not significant beyond this many characters. +A value of zero (the default) means that all characters are significant. + +Section 44.31: {tags} default: tags=tags /usr/lib/tags + +A path of files to be used as tag files for the tag command. A requested tag +is searched for in the specified files, sequentially. By default files called +tags are searched for in the current directory and in /usr/lib (a master file +for the entire system). + +[Author's note: The author of this tutorial has never used this option, nor +seen it used. I'm not even sure I know what they are talking about.] + +Section 44.32: {term} default: from environment variable TERM + +The terminal type of the output device. + +Section 44.33: {terse} default: noterse + +Shorter error diagnostics are produced for the experienced user. + +Section 44.34: {timeout} default: timeout + +Causes macros to time out after one second. Turn it off and they will +wait forever. This is useful if you want multi-character macros, but if +your terminal sends escape sequences for arrow keys, it will be +necessary to hit escape twice to get a beep. + +[Editor's note: Another paragraph which requires a cryptographer.] + +Section 44.35: ttytype + +[Editor's note: I have found no documentation for this option at all.] + +Section 44.36: {warn} default: warn + +Warn if there has been `[No write since last change]' before a `!' command +escape. + +Section 44.37: {window} default: window=speed dependent + +The number of lines in a text window in the visual command. The default is 8 +at slow speeds (600 baud or less), 16 at medium speed (1200 baud), and the full +screen (minus one line) at higher speeds. + +Section 44.38: {wrapscan}, {ws} default: ws + +Searches using the regular expressions in addressing will wrap around past the +end of the file. + +Section 44.39: {wrapmargin}, {wm} default: wm=0 + +Defines a margin for automatic wrapover of text during input in open and visual +modes. The numeric value is the number of columns from the right edge of the +screen around which vi looks for a convenient place to insert a new-line +character (wm=0 is OFF). This is very convenient for touch typists. +Wrapmargin behaves much like fill/nojustify mode does in nroff. + +Section 44.40: {writeany}, {wa} default: nowa + +Inhibit the checks normally made before write commands, allowing a write to any +file which the system protection mechanism will allow. + +Section 44.41: {w300}, {w1200}, {w9600} defaults: w300=8 + w1200=16 + w9600=full screen minus one + +These are not true options but set the default size of the window for when the +speed is slow (300), medium (1200), or high (9600), respectively. They are +suitable for an EXINIT and make it easy to change the 8/16/full screen rule. + +Section 45: Limitations + +Here are some editor limits that the user is likely to encounter: + 1024 characters per line + 256 characters per global command list + 128 characters per file name + 128 characters in the previous inserted and deleted text in open or + visual + 100 characters in a shell escape command + 63 characters in a string valued option + 30 characters in a tag name + 250000 lines in the file (this is silently enforced). + +The visual implementation limits the number of macros defined with map to 32, +and the total number of characters in macros to be less than 512. + +[Editor's note: these limits may not apply to versions after 4.1BSD.] diff --git a/usr.bin/vi/docs/tutorial/vi.beginner b/usr.bin/vi/docs/tutorial/vi.beginner new file mode 100644 index 000000000000..3bf35ac939f8 --- /dev/null +++ b/usr.bin/vi/docs/tutorial/vi.beginner @@ -0,0 +1,741 @@ +Section 1: {^F} {ZZ} + +To get out of this tutorial, type: ZZ (two capital Z's). + +Learning a new computer system implies learning a new text editor. These +tutorial lessons were created by Dain Samples to help you come to grips with +UC Berkeley's screen oriented editor called vi (for VIsual). This tutorial +uses the vi editor itself as the means of presentation. + +For best use of this tutorial, read all of a screen before performing any of +the indicated actions. This tutorial (or, at least, the first half of it) has +been designed to systematically present the vi commands IF THE INSTRUCTIONS +ARE FOLLOWED! If you are too adventuresome, you may find yourself lost. If +you ever find yourself stuck, remember the first line of this section. + +OK, now find the control key on your keyboard; it usually has CTL or CTRL +written on its upper surface. Your first assignment is to hold the control +key down while you press the 'F' key on your keyboard. Please do so now. + + + +Section 2: {^F} {^B} +Many of vi's commands use the control key and some other key in combination, +as with the control and the 'F' key above. This is abbreviated CTL-F, or ^F. + +As you have probably guessed by now, ^F (CTL-F) moves you forward a fixed +number of lines in the file. Throughout the remainder of the tutorial when +you are ready to advance to the next section of text, hit ^F. + +The opposite command is ^B. Just for fun, you might want to try a ^B to see +the previous section again. Be sure to do a ^F to return you here. + +Determine what the cursor looks like on your screen. Whatever it is (a box, +an underscore, blinking, flashing, inverse, etc.) it should now be positioned +in the upper left-hand corner of your screen under or on the S of Section. +Become familiar with your cursor: to use vi correctly it is important to +always know where the cursor is. + +Did you notice that when you do a ^F the cursor is left at the top of the +screen, and a ^B leaves the cursor near the bottom of the screen? Try the two +commands ^B^F again. And now do another ^F to see the next section. + +Section 3: {^F} {^B} +You now have two basic commands for examining a file, both forwards (^F) and +backwards (^B). + +Note that these are vi text editing commands: they are not commands for the +tutorial. Indeed, this tutorial is nothing but a text file which you are now +editing. Everything you do and learn in this tutorial will be applicable to +editing text files. + +Therefore, when you are editing a file and are ready to see more of the text, +entering ^F will get you to the next section of the file. Entering ^B will +show you the previous section. + +Time for you to do another ^F. + + + + + + + +Section 4: {^F} {^B} {^M} (return key) +We will adopt the notation of putting commands in curly braces so we can write +them unambiguously. For example, if you are to type the command sequence +"control B control F" (as we asked you to do above) it would appear as {^B^F}. +This allows clear delineation of the command strings from the text. Remember +that the curly braces are NOT part of the command string you are to type. Do +NOT type the curly braces. + +Sometimes, the command string in the curly braces will be rather long, and may +be such that the first couple of characters of the command will erase from +the screen the string you are trying to read and type. It is suggested that +you write down the longer commands BEFORE you type them so you won't forget +them once they disappear. + +Now locate the return key on your keyboard: it is usually marked 'RETURN', +indicate hitting the return key. In fact, the control-M key sequence is +exactly the same as if you hit the return key, and vice versa. + +Now type {^F}. + + +Section 5: {:q!} {ZZ} {^M} (return key) +Recognize that this tutorial is nothing more than a text file that you +are editing. This means that if you do something wrong, it is possible +for you to destroy the information in this file. Don't worry. If this +happens, type {ZZ} (two capital Z's) or {:q!^M} to leave the tutorial. +Restart the tutorial. Once in the tutorial, you can then page forward +with {^F} until you are back to where you want to be. (There are +easier ways to do this, some of which will be discussed later, but this +is the most straightforward.) + +You may want to write these commands down in a convenient place for quick +reference: {:q!^M} and {ZZ} + +We will assume that you now know to do a {^F} to advance the file + + + + + + + +Section 6: {m} {G} {'} {z} +Now that you know how to get around in the file via ^F and ^B let's look at +other ways of examining a text file. Sometimes it is necessary, in the midst +of editing a file, to examine another part of the file. You are then faced +with the problem of remembering your place in the file, looking at the other +text, and then getting back to your original location. Vi has a 'mark' +command, m. Type {mp}. You have just 'marked' your current location in the +file and given it the name 'p'. The command string below will do three +things: position you at the beginning of the file (line 1), then return you to +the location 'p' that you just marked with the 'm' command, and, since the +screen will not look exactly the same as it does right now, the 'z' command +will reposition the screen. (You may want to write the string down before +typing it: once you type {1G} it will no longer be on the screen.) + +So now type {1G'pz^M} - a one followed by a capital G, followed by the quote +mark, followed by a lower case 'p', then a lower case 'z', then a return +(which is the same as a ^M). The {1G} moves you to line 1, i.e. the beginning +of the file. The {'p} moves you to the location you marked with {mp}. The +{z^M} command will repaint the screen putting the cursor at the top of the +screen. (Now {^F}.) + +Section 7: {m} {G} {'} {z} +Let's look at some variations on those commands. If you wanted to look at +line 22 in the file and return to this location you could type {mp22G'p}. Do +so now, observing that {22G} puts your cursor at the beginning of section 2 in +the middle of the screen. + +Also note that, without the {z^M} command, the line with 'Section 7' on it is +now in the MIDDLE of the screen, and not at the top. Our cursor is on the +correct line (where we did the {mp} command) but the line is not where we +might like it to be on the screen. That is the function of the {z^M} command. +(Remember, ^M is the same as the 'return' key on your keyboard.) Type {z^M} +now and observe the effect. + +As you can see, the 'Section 7' line is now at the top of the screen with the +cursor happily under the capital S. If you would like the cursor line (i.e. +the line which the cursor is on) in the middle of the screen again, you would +type {z.}. If you wanted the cursor line to be at the BOTTOM of the screen, +type {z-}. Try typing {z-z.z^M} and watch what happens. + +{^F} + +Section 8: {z} {m} {'} + +Note that the z command does not change the position of our cursor in the file +itself, it simply moves the cursor around on the screen by moving the contents +of the file around on the screen. The cursor stays on the same line of the +file when using the z command. + +This brings up an important point. There are two questions that the users of +vi continually need to know the answer to: "Where am I in the file?" and +"Where am I on the screen?" The cursor on your terminal shows the answer to +both questions. Some commands will move you around in the file, usually +changing the location of the cursor on the screen as well. Other commands +move the cursor around on the screen without changing your location in the +file. + +Now type {ma}. Your location in the file has been given the name 'a'. If you +type {'p'a} you will see the previous location we marked in section 7, and +then will be returned to the current location. (You will want to do a {z^M} +to repaint the screen afterwards.) Try it. +{^F} + +Section 9: {m} {''} +Now we can move about in our file pretty freely. By using the {m} command we +can give the current cursor position a lower-case-character name, like 'p', +'a', 'e', 'm', or 'b'. Using the {G} command preceded by a line number we can +look at any line in the file we like. Using the single quote command {'} +followed by a character used in an {m} command, we can return to any location +in the file we have marked. + +However, try {m3}, or {mM}. You should hear a beep, or bell. Only lower-case +letters are acceptable to the {m} and {'} commands: numbers, upper-case +letters, and special characters are not acceptable. + +If you type the {'} command with a character that is lower-case alphabetic but +that has not been used in an {m} command, or for which the 'marked' text has +been deleted, you will also get a beep. Try {'i}. You should get a beep +because the command {mi} has never been issued. (Unless you've been +experimenting.) + +The command {''} attempts to return you to the location at which you last +modified some part of your file. However, my experience has been that it is +difficult to predict exactly where you will end up. +Section 10: {^M} {-} +Now do {ma}, marking your position at the top of the screen. Now hit {^M} (or +return) until the cursor is right ... +* <- here, over/under the asterisk. Now +type {mb'a'b} and watch the cursor move from the asterisk to the top of the +screen and back again. + +The {^M} command moves the cursor to the beginning of the next line. Now type +{^M} until the cursor is right ... +* <- here. The command to move the cursor to the beginning of the +previous line is {-}. Practice moving the cursor around on the screen by using +{^M} and {-}. BE CAREFUL to not move the cursor OFF the screen just yet. If +you do, type {'az^M}. + +Now we can move to any line within the screen. Practice moving around in the +file using the {^F}, {^B}, {-}, {^M}, {z}, and {'} commands. When you are +fairly confident that you can get to where you need to be in the file, and +position the cursor on the screen where you want it type {'az^M^F} (which, of +course, moves you back to the beginning of this section, repositions the +cursor at the top of the screen, and advances you to the next section). + +Section 11: scrolling: {^M} +The cursor should now be on the S of 'Section 11', and this should be on the +first line of the screen. If it is not, do {^M} or {-} as appropriate to put +the cursor on the section line, and type {z^M}. + +Type {mc} to mark your place. + +Now type {^M} until the cursor is on the last line of this screen. Now do one +more {^M} and observe the result. This is called scrolling. When you +attempted to move to a line not displayed on the screen, the line at the top of +the screen was 'scrolled off', and a line at the bottom of the screen was +'scrolled on'. The top line with 'Section 11' should no longer be visible. + +Now type {'cz^M} to reset the screen and type {^F} for the next section. + + + + + + + +Section 12: {-} {z} + +The {-} command moves the cursor to the previous line in the file. Now type +{-}, which attempts to move the cursor to the previous line in this file. +However, that line is not on the screen. The resulting action will depend on +your terminal. (Do a {^Mz^M} to reposition the file). On intelligent +terminals (e.g. VT100s, Z19s, Concept 100s), a top line is 'scrolled on' and +the bottom line is 'scrolled off'. Other terminals, however, may not have +this 'reverse scrolling' feature. They will simply repaint the screen with +the cursor line in the middle of the screen. On such terminals it is +necessary to type {z^M} to get the cursor line back to the top of the screen. + + + + + + + + + + +Section 13: +Up until this point, the tutorial has always tried to make sure that the first +line of each screen has on it the section number and a list of the commands +covered in that section. This will no longer be strictly maintained. If you +want the section line at the top of the screen, you now know enough commands to +do it easily: do {^M} or {-} until the cursor is on the section line and +then {z^M}. Also, from this point on, it may not be the case that a {^F} will +put you at the beginning of the next section. Therefore, be aware of where you +are in the file as we look at other commands. You may have to find your way +back to a particular section without any help from the tutorial. If you do not +feel comfortable with this, then it is suggested that you practice moving from +section 1 to section 13, back and forth, using {^M}, {-}, {^F}, and {^B} +commands for a while. + +Also make liberal use of the mark command {m}: if, for example, you make a +habit of using {mz} to mark your current location in the file, then you will +always be able to return to that location with {'z} if the editor does +something strange and you have no idea where you are or what happened. + +And finally, the proscription against experimentation is hereby lifted: play +with the editor. Feel free to try out variations on the commands and move +around in the file. By this time you should be able to recover from any gross +errors. + +Section 14: {^E} {^Y} {^D} {^U} +Let us now look at a few other commands for moving around in the file, and +moving the file around on the screen. Note that the commands we have already +looked at are sufficient: you really don't need any more commands for looking +in a file. The following commands are not absolutely necessary. However, +they can make editing more convenient, and you should take note of their +existence. But it would be perfectly valid to decide to ignore them on this +first pass: you can learn them later when you see a need for them, if you ever +do. + +First, let's clear up some potentially confusing language. In at least one +place in the official document ('An Introduction to Display Editing with Vi' +by William Joy, and Mark Horton, September 1980), the expression "to scroll +down text" means that the cursor is moved down in your file. However, note +that this may result in the text on the screen moving UP. This use of the +word 'scroll' refers to the action of the cursor within the file. However, +another legitimate use of the word refers to the action of the text on the +screen. That is, if the lines on your screen move up toward the top of the +screen, this would be 'scrolling the screen up'. If the lines move down +toward the bottom of the screen, this would be refered to as scrolling down. + +I have tried to maintain the following jargon: 'scrolling' refers to what the +text does on the screen, not to what the cursor does within the file. For the +latter I will refer to the cursor 'moving', or to 'moving the cursor'. I +realize that this is not necessarily consistent with Joy and Horton, but they +were wrong. + +{^E} scrolls the whole screen up one line, keeping the cursor on the same line, +if possible. However, if the cursor line is the first line on the screen, then +the cursor is moved to the next line in the file. Try typing {^E}. + +{^Y} scrolls the screen down one line, keeping the cursor on the same line, if +possible. However, if the cursor line is the last line on the screen, then the +cursor is moved to the previous line in the file. Try it. + +{^D} moves the cursor down into the file, scrolling the screen up. + +{^U} moves the cursor up into the file, also scrolling the screen if the +terminal you are on has the reverse scroll capability. Otherwise the +screen is repainted. + +Note that {^E} and {^Y} move the cursor on the screen while trying to keep the +cursor at the same place in the file (if possible: however, the cursor can +never move off screen), while {^D} and {^U} keep the cursor at the same place +on the screen while moving the cursor within the file. + +Section 15: {/ .. /^M} + +Another way to position yourself in the file is by giving the editor a string +to search for. Type the following: {/Here 1/^M} and the cursor should end up +right ...........................here ^. Now type {/Section 15:/^M} and the +cursor will end up over/on .....................here ^. Now type {//^M} and +observe that the cursor is now over the capital S five lines above this line. +Typing {//^M} several more times will bounce the cursor back and forth between +the two occurrences of the string. In other words, when you type a string +between the two slashes, it is searched for. Typing the slashes with nothing +between them acts as if you had typed the previous string again. + +Observe that the string you type between the two slashes is entered on the +bottom line of the screen. Now type {/Search for x /^M} except replace the 'x' +in the string with some other character, say 'b'. The message "Pattern not +found" should appear on the bottom of the screen. If you hadn't replaced the +'x', then you would have found the string. Try it. + +Section 16: {? .. ?^M} {n} (search strings: ^ $) + +When you surround the sought-for string with slashes as in {/Search/}, the +file is searched beginning from your current position in the file. If the +string is not found by the end of the file, searching is restarted at the +beginning of the file. However, if you do want the search to find the +PREVIOUS rather than the NEXT occurrence of the string, surround the string +with question marks instead of slash marks. + +Below are several occurrences of the same string. +Here 2 Here 2 Here 2 + Here 2 Here 2. +Observe the effect of the following search commands (try them in the +sequence shown): +{/Here 2/^M} {//^M} {??^M} +{/^Here 2/^M} {//^M} {??^M} +{/Here 2$/^M} {//^M} {??^M} + +The first command looks for the next occurrence of the string 'Here 2'. +However the second line of commands looks for an occurrence of 'Here 2' that +is at the beginning of the line. When the up-arrow is the first character of +a search string it stands for the beginning of the line. When the dollar-sign +is the last character of the search string it stands for the end of the line. +Therefore, the third line of commands searches for the string only when it is +at the end of the line. Since there is only one place the string begins a +line, and only one place the string ends the line, subsequent {//^M} and +{??^M} will find those same strings over and over. + +The {n} command will find the next occurrence of the / or ? search +string. Try {/Here 2/^M} followed by several {n} and observe the +effect. Then try {??^M} followed by several {n}. The {n} command +remembers the direction of the last search. It is just a way to save a +few keystrokes. + +Section 17: \ and magic-characters in search strings + +Now type {/Here 3$/^M}. You might expect the cursor to end up +right......^ here. However, you will get "Pattern not found" at the bottom of +the screen. Remember that the dollar-sign stands for the end of the line. +Somehow, you must tell vi that you do not want the end of the line, but a +dollar-sign. In other words, you must take away the special meaning that the +dollar-sign has for the search mechanism. You do this (for any special +character, including the up-arrow ^) by putting a back-slash ('\', not '/') in +front of the character. + +Now try {/Here 3\$/^M} and you should end up nine lines above this one. Try +{//^M} and note that it returns you to the same place, and not to the first +line of this paragraph: the back-slash character is not part of the search +string and will not be found. To find the string in the first line of this +paragraph, type {/Here 3\\\$/^M}. There are three back-slashes: the first takes +away the special meaning from the second, and the third takes away the special +meaning from the dollar-sign. + +Following is a list of the characters that have special meanings in search +strings. If you wish to find a string containing one of these characters, you +will have to be precede the character with a backslash. These characters are +called magic characters because of the fun and games you can have with them +and they can have with you, if you aren't aware of what they do. + + ^ - (up-arrow) beginning of a line + $ - (dollar-sign) end of a line + . - (period) matches any character + \ - (backslant) the escape character itself + [ - (square bracket) for finding patterns (see section #SEARCH) + ] - (square bracket) ditto + * - (asterisk) ditto + +Without trying to explain it here, note that {:set nomagic^M} turns off the +special meanings of all but the ^ up-arrow, $ dollar-sign, and backslash +characters. + +Section 18: {: (colon commands)} {ZZ} + +In this section we will discuss getting into and out of the editor in more +detail. If you are editing a file and wish to save the results the command +sequence {:w^M} writes the current contents of the file out to disk, using the +file name you used when you invoked the editor. That is, if you are at the +command level in Unix, and you invoke vi with {vi foo} where foo is the name +of the file you wish to edit, then foo is the name of the file used by the +{:w^M} command. + +If you are done, the write and quit commands can be combined into a single +command {:wq^M}. An even simpler way is the command {ZZ} (two capital Z's). + +If, for some reason, you wish to exit without saving any changes you have made, +{:q!^M} does the trick. If you have not made any changes, the exclamation +point is not necessary: {:q^M}. Vi is pretty good about not letting you +get out without warning you that you haven't saved your file. + +We have mentioned before that you are currently in the vi editor, editing a +file. If you wish to start the tutorial over from the very beginning, you +could {ZZ}, and then type {vi.tut beginner} in response to the Unix prompt. +This will create a fresh copy of this file for you, which might be necessary +if you accidentally destroyed the copy you were working with. Just do a +search for the last section you were in: e.g. {/Section 18:/^Mz^M}. + +Section 19: {H} {M} {L} + +Here are a few more commands that will move you around on the screen. Again, +they are not absolutely necessary, but they can make screen positioning easier: + +{H} - puts the cursor at the top of the screen (the 'home' position) + +{M} - puts the cursor in the middle of the screen + +{L} - puts the cursor at the bottom of the screen. + +Try typing {HML} and watch the cursor. + +Try typing {5HM5L} and note that 5H puts you five lines from the top of the +screen, and 5L puts you five lines from the bottom of the screen. + +Section 20: {w} {b} {0} {W} {B} {e} {E} {'} {`} + +Up to this point we have concentrated on positioning in the file, and +positioning on the screen. Now let's look at positioning in a line. Put the +cursor at the beginning of the following line and type {z^M}: + +This is a test line: your cursor should initially be at its beginning. + +The test line should now be at the top of your screen. Type {w} several times. +Note that it moves you forward to the beginning of the next word. Now type +{b} (back to the beginning of the word) several times till you are at the +beginning of the line. (If you accidentally type too many {b}, type {w} until +you are on the beginning of the line again.) Type {wwwww} (five w's) and note +that the cursor is now on the colon in the sentence. The lower-case w command +moves you forward one word, paying attention to certain characters such as +colon and period as delimiters and counting them as words themselves. Now +type {0} (zero, not o 'oh'): this moves you to the beginning of the current +line. Now type {5w} and notice that this has the effect of repeating {w} five +times and that you are now back on the colon. Type {0} (zero) again. To +ignore the delimiters and to move to the beginning of the next word using only +blanks, tabs and carriage-returns (these are called white-space characters) to +delimit the words, use the {W} command: upper-case W. {B} takes you back a +word using white-space characters as word delimiters. + +Note that the commands {wbWB} do not stop at the beginning or end of a line: +they will continue to the next word on the next line in the direction specified +(a blank line counts as a word). + +If you are interested in the END of the word, and not the BEGINNING, then use +the {e} and {E} commands. These commands only move forward and there are no +corresponding 'reverse search' commands for the end of a word. + +Also, we have been using the {'} command to move the cursor to a position that +we have previously marked with the {m} command. However, position the cursor +in the middle of a line (any line, just pick one) and type {mk}, marking that +position with the letter k. Now type a few returns {^M} and type {'k}. +Observe that the cursor is now at the beginning of the line that you marked. +Now try {`k}: note that this is the reverse apostrophe, or back-quote, or grave +accent, or whatever you want to call it. Also note that it moves you to the +character that was marked, not just to the line that was marked. + +In addition, the {``} command works just like the {''} command except that you +are taken to the exact character, not just to the line. (I'm still not +sure which exact character, just as I'm still not sure which line.) + +Section 21: {l} {k} {j} {h} + +There are several commands to move around on the screen on a character by +character basis: + +l - moves the cursor one character to the RIGHT +k - moves the cursor UP one line +j - moves the cursor DOWN one line +h - moves the cursor one character to the LEFT + +Section 22: {i} {a} {I} {A} {o} {O} ^[ (escape key) + +For this and following sections you will need to use the ESCAPE key on your +terminal. It is usually marked ESC. Since the escape key is the same as +typing {^[} we will use ^[ for the escape key. + +Probably the most often used command in an editor is the insert command. Below +are two lines of text, the first correct, the second incorrect. Position your +cursor at the beginning of Line 1 and type {z^M}. + +Line 1: This is an example of the insert command. +Line 2: This is an of the insert command. + +To make line 2 look like line 1, we are going to insert the characters +'example ' before the word 'of'. So, now move the cursor so that it is +positioned on the 'o' of 'of'. (You can do this by typing {^M} to move +to the beginning of line 2, followed by {6w} or {wwwwww} to position the cursor +on the word 'of'.) + +Now carefully type the following string and observe the effects: + {iexample ^[} (remember: ^[ is the escape key)} +The {i} begins the insert mode, and 'example ' is inserted into the line: +be sure to notice the blank in 'example '. The ^[ ends insertion mode, +and the line is updated to include the new string. Line 1 should look exactly +like Line 2. + +Move the cursor to the beginning of Line 3 below and type {z^M}: + +Line 3: These lines are examples for the 'a' command. +Line 4: These line are examples for the ' + +We will change line four to look like line three by using the append command. +We need to append an 's' to the word 'line'. Position the cursor on the 'e' +of 'line'. You can do this in several ways, one way is the following: +First, type {/line /^M}. This puts us on the word 'line' in Line 4 +(the blank in the search string is important!). Next, type {e}. The 'e' puts +us at the end of the word. Now, type {as^[ (^[ is the escape character)}. +The 'a' puts us in insert mode, AFTER the current character. We appended the +'s', and the escape ^[ ended the insert mode. + +The difference between {i} (insert) and {a} (append) is that {i} begins +inserting text BEFORE the cursor, and {a} begins inserting AFTER the cursor. + +Now type {Aa' command.^[}. The cursor is moved to the end of the line and the +string following {A} is inserted into the text. Line 4 should now look like +line 3. + +Just as {A} moves you to the end of the line to begin inserting, {I} would +begin inserting at the FRONT of the line. + +To begin the insertion of a line after the cursor line, type {o}. To insert a +line before the cursor line, type {O}. In other words {o123^[} is equivalent +to {A^M123^[}, and {O123^[} is equivalent to {I123^M^[}. The text after the +{o} or {O} is ended with an escape ^[. + +This paragraph contains information that is terminal dependent: you will just +have to experiment to discover what your terminal does. Once in the insert +mode, if you make a mistake in the typing, ^H will delete the previous +character up to the beginning of the current insertion. ^W will delete the +previous word, and one of ^U, @, or ^X will delete the current line (up to the +beginning of the current insertion). You will need to experiment with ^U, @, +and ^X to determine which works for your terminal. + +Section 23: {f} {x} {X} {w} {l} {r} {R} {s} {S} {J} + +Position the cursor at the beginning of line 5 and {z^M}: + +Line 5: The line as it should be. +Line 6: The line as it shouldn't be. + +To make Line 6 like Line 5, we have to delete the 'n', the apostrophe, and the +'t'. There are several ways to position ourselves at the 'n'. Choose +whichever one suits your fancy: + +{/n't/^M} +{^M7w6l} or {^M7w6 } (note the space) +{^M3fn} (finds the 3rd 'n' on the line) + +Now {xxx} will delete the three characters, as will {3x}. + +Note that {X} deletes the character just BEFORE the cursor, as opposed +to the character AT the cursor. + +Position the cursor at line 7 and {z^M}: + +Line 7: The line as it would be. +Line 8: The line as it could be. + +To change line 8 into line 7 we need to change the 'c' in 'could' into a 'w'. +The 'r' (replace) command was designed for this. Typing {rc} is the same as +typing {xic^[} (i.e. delete the 'bad' character and insert the correct +new character). Therefore, assuming that you have positioned the cursor on the +'c' of 'could', the easiest way to change 'could' into 'would' is {rw}. + +If you would like to now change the 'would' into 'should', use the substitute +command, 's': {ssh^[}. The difference between 'r' and 's' is that 'r' +(replace) replaces the current character with another character, while 's' +(substitute) substitutes the current character with a string, ended with an +escape. + +The capital letter version of replace {R} replaces each character by a +character one at a time until you type an escape, ^[. The 'S' command +substitutes the whole line. + +Position your cursor at the beginning of line 9 and {z^M}. + +Line 9: Love is a many splendored thing. +Line 10: Love is a most splendored thing. + +To change line 10 into line 9, position the cursor at the beginning of 'most', +and type {Rmany^[}. + +You may have noticed that, when inserting text, a new line is formed by typing +{^M}. When changing, replacing, or substituting text you can make a new line +by typing {^M}. However, neither {x} nor {X} will remove ^M to make two lines +into one line. To do this, position the cursor on the first of the two lines +you wish to make into a single line and type {J} (uppercase J for 'Join'). + +Section 24: {u} {U} + +Finally, before we review, let's look at the undo command. Position +your cursor on line 11 below and {z^M}. + +Line 11: The quick brown fox jumped over the lazy hound dog. +Line 12: the qwick black dog dumped over the laxy poune fox. + +Type the following set of commands, and observe carefully the effect of each +of the commands: + +{/^Line 12:/^M} {ft} {rT} {fw} {ru} {w} {Rbrown fox^[} {w} {rj} +{fx} {rz} {w} {Rhound dog^[} + +Line 12 now matches line 11. Now type {U} - capital 'U'. And line 12 now +looks like it did before you typed in the command strings. Now type: + +{ft} {rT} {fw} {ru} {^M} {^M} + +and then type {u}: the cursor jumps back to the line containing the second +change you made and 'undoes' it. That is, {U} 'undoes' all the changes on the +line, and {u} 'undoes' only the last change. Type {u} several times and +observe what happens: {u} can undo a previous {u}! + +Caveat: {U} only works as long as the cursor is still on the line. Move the +cursor off the line and {U} will have no effect, except to possibly beep at +you. However, {u} will undo the last change, no matter where it occurred. + +Section 25: review + +At this point, you have all the commands you need in order to make use of vi. +The remainder of this tutorial will discuss variations on these commands as +well as introduce new commands that make the job of editing more efficient. +Here is a brief review of the basic commands we have covered. They are listed +in the order of increasing complexity and/or decreasing necessity (to say that +a command is less necessary is not to say that it is less useful!). These +commands allow you to comfortably edit any text file. There are other +commands that will make life easier but will require extra time to learn, +obviously. You may want to consider setting this tutorial aside for several +weeks and returning to it later after gaining experience with vi and getting +comfortable with it. The convenience of some of the more exotic commands may +then be apparent and worth the extra investment of time and effort +required to master them. + +to get into the editor from Unix: {vi filename} +to exit the editor + saving all changes {ZZ} or {:wq^M} + throwing away all changes {:q!^M} + when no changes have been made {:q^M} +save a file without exiting the editor {:w^M} +write the file into another file {:w filename^M} +insert text + before the cursor {i ...text... ^[} + at the beginning of the line {I ...text... ^[} + after the cursor (append) {a ...text... ^[} + at the end of the line {A ...text... ^[} + after the current line {o ...text... ^[} + before the current line {O ...text... ^[} +delete the character ... + under the cursor {x} + to the left of the cursor {X} +delete n characters {nx} or {nX} (for n a number) +make two lines into one line (Join) {J} +find a string in the file ... + searching forward {/ ...string... /^M} + searching backwards {? ...string... ?^M} +repeat the last search command {n} +repeat the last search command in the + opposite direction {N} +find the character c on this line ... + searching forward {fc} + searching backward {Fc} +repeat the last 'find character' command {;} +replace a character with character x {rx} +substitute a single character with text {s ...text... ^[} +substitute n characters with text {ns ...text... ^[} +replace characters one-by-one with text {R ...text... ^[} +undo all changes to the current line {U} +undo the last single change {u} +move forward in the file a "screenful" {^F} +move back in the file a "screenful" {^B} +move forward in the file one line {^M} or {+} +move backward in the file one line {-} +move to the beginning of the line {0} +move to the end of the line {$} +move forward one word {w} +move forward one word, ignoring punctuation {W} +move forward to the end of the next word {e} +to the end of the word, ignoring punctuation{E} +move backward one word {b} +move back one word, ignoring punctuation {B} +return to the last line modified {''} +scroll a line onto the top of the screen {^Y} +scroll a line onto the bottom of the screen {^E} +move "up" in the file a half-screen {^U} +move "down" in the file a half-screen {^D} +move the cursor to the top screen line {H} +move the cursor to the bottom screen line {L} +move the cursor to the middle line {M} +move LEFT one character position {h} or {^H} +move RIGHT one character position {l} or { } +move UP in the same column {k} or {^P} +move DOWN in the same column {j} or {^N} +mark the current position, name it x {mx} +move to the line marked/named x {'x} +move to the character position named x {`x} +move to the beginning of the file {1G} +move to the end of the file {G} +move to line 23 in the file {23G} +repaint the screen with the cursor line + at the top of the screen {z^M} + in the middle of the screen {z.} + at the bottom of the screen {z-} + +More information on vi can be found in the file vi.advanced, which you can +peruse at your leisure. From UNIX, type {vi.tut advanced^M}. diff --git a/usr.bin/vi/docs/tutorial/vi.tut.csh b/usr.bin/vi/docs/tutorial/vi.tut.csh new file mode 100755 index 000000000000..01554bc4e5fd --- /dev/null +++ b/usr.bin/vi/docs/tutorial/vi.tut.csh @@ -0,0 +1,24 @@ +#!/bin/csh -f +# +# This makes the user's EXINIT variable set to the 'correct' things. +# I don't know what will happen if they also have a .exrc file! +# +# XXX +# Make sure that user is using a 24 line window!!! +# +if ($1 != "beginner" && $1 != "advanced") then + echo Usage: $0 beginner or $0 advanced + exit +endif + +if ($?EXINIT) then + set oexinit="$EXINIT" + setenv EXINIT 'se ts=4 wm=8 sw=4' +endif + +vi vi.{$1} + +onintr: + if ($?oexinit) then + setenv EXINIT "$oexinit" +endif |