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

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

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