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

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: 
        !            73:  * `:w` -- Write the buffer to file.  
        !            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:
        !           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.  
        !           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: 
        !           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.  
        !           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