Annotation of wikisrc/guide/edit.mdwn, revision 1.3

1.3     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
1.1       jdf         5: # Editing
                      6: 
                      7: ## Introducing vi
                      8: 
                      9: It is not like the vi editor needs introducing to seasoned UNIX users. The vi
                     10: editor, originally developed by Bill Joy of Sun Microsystems, is an endlessly
                     11: extensible, easy to use *light* ASCII editor and the bane of the newbie
                     12: existence. This section will introduce the vi editor to the newbie and perhaps
                     13: toss in a few ideas for the seasoned user as well.
                     14: 
                     15: The first half of this section will overview editing, saving, yanking/putting
                     16: and navigating a file within a vi session. The second half will be a step by
                     17: step sample vi session to help get started.
                     18: 
                     19: This is intended as a primer for using the vi editor, it is *not by any means* a
                     20: thorough guide. It is meant to get the first time user up and using vi with
                     21: enough skills to make changes to and create files.
                     22: 
                     23: ### The vi interface
                     24: 
                     25: Using the vi editor really is not much different than any other terminal based
                     26: software with one exception, it does not use a tab type (or curses if you will)
                     27: style interface, although many versions of vi *do use* curses it does not give
                     28: the same look and feel of the typical curses based interface. Instead it works
                     29: in two modes, *command* and *edit*. While this may seem strange, it is not much
                     30: different than windows based editing if you think about it. Take this as an
                     31: example, if you are using say gedit and you take the mouse, highlight some text,
                     32: select cut and then paste, the whole time you are using the mouse you are not
                     33: editing (even though you can). In vi, the same action is done by simply deleting
                     34: the whole line with `dd` in command mode, moving to the line you wish to place
                     35: it below and hitting `p` in command mode. One could almost say the analogy is
                     36: *mouse mode vs. command mode* (although they are not exactly identical,
                     37: conceptually the idea is similar).
                     38: 
                     39: To start up a vi session, one simply begins the way they might with any terminal
                     40: based software:
                     41: 
                     42:     $ vi filename
                     43: 
                     44: One important note to remember here is that when a file is edited, it is loaded
                     45: into a memory buffer. The rest of the text will make reference to the buffer and
                     46: file in their proper context. A file *only* changes when the user has committed
                     47: changes with one of the write commands.
                     48: 
                     49: ### Switching to Edit Mode
                     50: 
                     51: The vi editor sports a range of options one can provide at start up, for the
                     52: time being we will just look at the default startup. When invoked as shown
                     53: above, the editors default startup mode is command mode, so in essence you
                     54: cannot commence to typing into the buffer. Instead you must switch out out of
                     55: command mode to enter text. The following text describes edit start modes:
                     56: 
                     57:  * `a` -- Append after cursor.
                     58:  * `A` -- Append to end of line.
                     59:  * `C` -- Change the rest of current line.
                     60:  * `cw` -- Change the current word.
                     61:  * `i` -- Insert before cursor.
                     62:  * `I` -- Insert before first non blank line.
                     63:  * `o` -- Open a line below for insert.
                     64:  * `O` -- Open a line above for insert.
                     65: 
                     66: ### Switching Modes & Saving Buffers to Files
                     67: 
                     68: Of course knowing the edit commands does not do much good if you can't switch
                     69: back to command mode and save a file, to switch back simply hit the `ESC` key.
                     70: To enter certain commands, the colon must be used. Write commands are one such
                     71: set of commands. To do this, simply enter `:`.
                     72: 
                     73: Hitting the colon then will put the user at the colon (or *command* if you will)
                     74: prompt at the bottom left corner of the screen. Now let us look at the save
                     75: commands:
                     76: 
1.2       jdf        77:  * `:w` -- Write the buffer to file.
1.1       jdf        78:  * `:wq` -- Write the buffer to file and quit.
                     79: 
                     80: ### Yanking and Putting
                     81: 
                     82: What good is an editor if you cannot manipulate blocks of text? Of course vi
                     83: supports this feature as well and as with most of the vi commands it somewhat
                     84: intuitive. To yank a line but *not* delete it, simply enter `yy` or `Y` in
                     85: command mode and the current line will be copied into a buffer. To put the line
                     86: somewhere, navigate to the line above where the line is to be put and hit the
                     87: `p` key for the *put* command. To move a line, simply delete the whole line
                     88: with the `dd` command, navigate and put.
                     89: 
                     90: #### Oops I Did Not Mean to do that!
                     91: 
                     92: Undo is pretty simple, `u` undoes the last action and `U` undoes the last line
                     93: deleted or changes made on the last line.
                     94: 
                     95: ### Navigation in the Buffer
                     96: 
                     97: Most vi primers or tutorials start off with navigation, however, not unlike most
                     98: editors in order to navigate a file there must be something to navigate to and
                     99: from (hence why this column sort of went in reverse). Depending on your flavor
                    100: of vi (or if it even *is* vi and not say elvis, nvi or vim) you can navigate in
                    101: both edit and command mode.
                    102: 
                    103: For the beginner I feel that switching to command mode and then navigating is a
                    104: bit safer until one has practiced for awhile. The navigation keys for terminals
                    105: that are not recognized or do not support the use of arrow keys are the
                    106: following:
1.2       jdf       107: 
                    108:  * `k` -- Moves the cursor up one line.
                    109:  * `j` -- Moves the cursor down one line.
                    110:  * `l` -- Moves the cursor right one character.
1.1       jdf       111:  * `h` -- Moves the cursor left one character.
                    112: 
                    113: If the terminal is recognized and supports them, the arrow keys can be used to
                    114: navigate the buffer in command mode.
                    115: 
                    116: In addition to simple *one spot navigation* vi supports jumping to a line by
                    117: simply typing in the line number at the colon prompt. For example, if you wanted
                    118: to jump to line 223 the keystrokes from editor mode would look like so:
                    119: 
                    120:     ESC
                    121:     :223
                    122: 
                    123: ### Searching a File, the Alternate Navigational Aid
                    124: 
                    125: The vi editor supports searching using regular expression syntax, however, it is
                    126: slightly different to invoke from command mode. One simply hits the `/` key in
                    127: command mode and enters what they are searching for, as an example let us say I
                    128: am searching for the expression *foo*:
                    129: 
                    130:     /foo
                    131: 
                    132: That is it, to illustrate a slightly different expression, let us say I am
                    133: looking for *foo bar*:
                    134: 
                    135:     /foo bar
                    136: 
                    137: #### Additional Navigation Commands
                    138: 
                    139: Searching and scrolling are not the only ways to navigate a vi buffer. Following
                    140: is a list of succinct navigation commands available for vi:
                    141: 
1.2       jdf       142:  * `0` -- Move to beginning of line.
                    143:  * `$` -- Move to end of line.
                    144:  * `b` -- Back up one word.
                    145:  * `w` -- Move forward one word.
                    146:  * `G` -- Move to the bottom of the buffer.
                    147:  * `H` -- Move to the top line on the screen.
                    148:  * `L` -- Move to the last line on the screen.
                    149:  * `M` -- Move the cursor to the middle of the screen.
                    150:  * `N` -- Scan for next search match but opposite direction.
1.1       jdf       151:  * `n` -- Scan for next search match in the same direction.
                    152: 
                    153: ### A Sample Session
                    154: 
                    155: Now that we have covered the basics, let us run a sample session using a couple
                    156: of the items discussed so far. First, we open an empty file into the buffer from
                    157: the command line like so:
                    158: 
                    159:     # vi foo.txt
                    160: 
                    161: Next, we switch to edit mode and enter two lines separated by an empty line,
                    162: remember our buffer is empty so we hit the `i` key to insert before cursor and
                    163: enter some text:
                    164: 
                    165:     This is some text
                    166:     
                    167:     there we skipped a line
                    168:     ~
                    169:     ~
                    170:     ~
                    171:     ~
                    172: 
                    173: Now hit the `ESC` key to switch back into command mode.
                    174: 
                    175: Now that we are in command mode, let us save the file. First, hit the `:` key,
                    176: the cursor should be sitting in the lower left corner right after a prompt. At
                    177: the `:` prompt enter `w` and hit the `ENTER` or `RETURN` key. The file has just
                    178: been saved. There should have been a message to that effect, some vi editors
                    179: will also tell you the name, how many lines and the size of the file as well.
                    180: 
                    181: It is time to navigate, the cursor should be sitting wherever it was when the
                    182: file was saved. Try using the arrow keys to move around a bit. If they do not
                    183: work (or you are just plain curious) try out the `hjkl` keys to see how they
                    184: work.
                    185: 
                    186: Finally, let us do two more things, first, navigate up to the first line and
                    187: then to the first character. Try out some of the other command mode navigation
                    188: keys on that line, hit the following keys a couple of times:
                    189: 
                    190:     $
                    191:     0
                    192:     $
                    193:     0
                    194: 
                    195: The cursor should hop to the end of line, back to the beginning and then to the
                    196: end again.
                    197: 
                    198: Next, search for an expression by hitting the `/` key and an expression like so:
                    199: 
                    200:     /we
                    201: 
                    202: The cursor should jump to the *first occurrence* of *we*.
                    203: 
                    204: Now save the file and exit using write and quit:
                    205: 
                    206:     :wq
                    207: 
                    208: ## Configuring vi
                    209: 
                    210: The standard editor supplied with NetBSD is, needless to say, vi, the most loved
                    211: and hated editor in the world. If you don't use vi, skip this section, otherwise
                    212: read it before installing other versions of vi. NetBSD's vi (*nvi*) was written
                    213: by Keith Bostic of UCB to have a freely redistributable version of this editor
                    214: and has many powerful extensions worth learning while being still very
                    215: compatible with the original vi. Nvi has become the standard version of vi for
                    216: BSD.
                    217: 
                    218: Amongst the most interesting extensions are:
                    219: 
                    220:  * Extended regular expressions (egrep style), enabled with option `extended`.
                    221:  * Tag stacks.
                    222:  * Infinite undo (to undo, press `u`; to continue undoing, press `.`).
                    223:  * Incremental search, enabled with the option `searchincr`.
                    224:  * Left-right scrolling of lines, enabled with the option `leftright`; the
                    225:    number of columns to scroll is defined by the `sidescroll` option.
                    226:  * Command line history editing, enabled with the option `cedit`.
                    227:  * Filename completion, enabled by the `filec` option.
                    228:  * Backgrounded screens and displays.
                    229:  * Split screen editing.
                    230: 
                    231: ### Extensions to `.exrc`
                    232: 
                    233: The following example shows a `.exrc` file with some extended options enabled.
                    234: 
                    235:     set showmode ruler
                    236:     set filec=^[
                    237:     set cedit=^[
                    238: 
                    239: The first line enables the display of the cursor position (row and column) and
                    240: of the current mode (Command, Insert, Append) on the status line. The second
                    241: line (where \^[ is the ESC character) enables filename completion with the ESC
                    242: character. The third line enables command line history editing (also with the
                    243: ESC character.) For example, writing `:` and then pressing ESC opens a window
                    244: with a list of the previous commands which can be edited and executed (pressing
                    245: Enter on a command executes it.)
                    246: 
                    247: ### Documentation
                    248: 
                    249: The source *tarball* (`src.tgz`) contains a lot of useful documentation on (n)vi
                    250: and ex, in the `/usr/src/usr.bin/vi/docs` directory. For example:
                    251: 
                    252:  * Edit: A tutorial
                    253:  * Ex Reference Manual
                    254:  * Vi man page
                    255:  * An Introduction to Display Editing with Vi by William Joy and Mark Horton
                    256:  * Ex/Vi Reference Manual by Keith Bostic
                    257:  * Vi Command & Function Reference
                    258:  * Vi tutorial (beginner and advanced)
                    259: 
                    260: 
                    261: If you have never used vi, the *Vi tutorial* is a good starting point. It is
                    262: meant to be read using vi and it gradually introduces the reader to all the vi
                    263: commands, which can be tested while reading. *An Introduction to Display Editing
                    264: with Vi* by William Joy and Mark Horton is also a very good starting point.
                    265: 
                    266: If you want to learn more about vi and the nvi extensions you should read the
                    267: *Ex/Vi Reference Manual* by Keith Bostic which documents all the editor's
                    268: commands and options.
                    269: 
                    270: ## Using tags with vi
                    271: 
                    272: This topic is not directly related to NetBSD but it can be useful, for example,
                    273: for examining the kernel sources.
                    274: 
                    275: When you examine a set of sources in a tree of directories and subdirectories
                    276: you can simplify your work using the *tag* feature of vi. The method is the
                    277: following:
                    278: 
                    279: 1. `cd` to the base directory of the sources.
                    280: 
                    281:        $ cd /path
                    282: 
                    283: 2. Write the following commands:
                    284: 
                    285:        $ find . -name "*.[ch]" > filelist
                    286:        $ cat filelist | xargs ctags
                    287: 
                    288: 3. Add the following line to `.exrc`
                    289: 
                    290:        set tags=/path/tags
                    291: 
                    292:    (substitute the correct path instead of *`path`*.)
                    293: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb