Patrick Welche <prlw1@cam.ac.uk>
[netbsd-mini2440.git] / usr.bin / vi / docs / vi.0.txt
blob4f9588f4584af29ee0f30a50dcf11c2067036480
1 EX/VI(1)                     BSD Reference Manual                     EX/VI(1)
3 N\bNA\bAM\bME\bE
4      e\bex\bx,\b, v\bvi\bi,\b, v\bvi\bie\bew\bw - text editors
6 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
7      e\bex\bx [-\b-e\beF\bFl\blR\bRs\bsv\bv] [-\b-c\bc _\bc_\bm_\bd] [-\b-r\br _\bf_\bi_\bl_\be] [-\b-t\bt _\bt_\ba_\bg] [-\b-w\bw _\bs_\bi_\bz_\be] [-\b-x\bx _\ba_\bw] [_\bf_\bi_\bl_\be _\b._\b._\b.]
8      v\bvi\bi [-\b-e\beF\bFl\blR\bRv\bv] [-\b-c\bc _\bc_\bm_\bd] [-\b-r\br _\bf_\bi_\bl_\be] [-\b-t\bt _\bt_\ba_\bg] [-\b-w\bw _\bs_\bi_\bz_\be] [-\b-x\bx _\ba_\bw] [_\bf_\bi_\bl_\be _\b._\b._\b.]
9      v\bvi\bie\bew\bw [-\b-e\beF\bFl\blR\bRv\bv] [-\b-c\bc _\bc_\bm_\bd] [-\b-r\br _\bf_\bi_\bl_\be] [-\b-t\bt _\bt_\ba_\bg] [-\b-w\bw _\bs_\bi_\bz_\be] [-\b-x\bx _\ba_\bw] [_\bf_\bi_\bl_\be _\b._\b._\b.]
11 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
12      V\bVi\bi is a screen oriented text editor.  E\bEx\bx is a line-oriented text editor.
13      E\bEx\bx and v\bvi\bi are different interfaces to the same program, and it is possi-
14      ble to switch back and forth during an edit session.  V\bVi\bie\bew\bw is the equiva-
15      lent of using the -\b-R\bR (read-only) option of v\bvi\bi.
17      This manual page is the one provided with the n\bne\bex\bx/\b/n\bnv\bvi\bi versions of the
18      e\bex\bx/\b/v\bvi\bi text editors.  N\bNe\bex\bx/\b/n\bnv\bvi\bi are intended as bug-for-bug compatible re-
19      placements for the original Fourth Berkeley Software Distribution (4BSD)
20      e\bex\bx and v\bvi\bi programs.  For the rest of this manual page, n\bne\bex\bx/\b/n\bnv\bvi\bi is used
21      only when it's necessary to distinguish it from the historic implementa-
22      tions of e\bex\bx/\b/v\bvi\bi.
24      This manual page is intended for users already familiar with e\bex\bx/\b/v\bvi\bi. Any-
25      one else should almost certainly read a good tutorial on the editor be-
26      fore this manual page.  If you're in an unfamiliar environment, and you
27      absolutely have to get work done immediately, read the section near the
28      end of this manual page, entitled FAST STARTUP.  It's probably enough to
29      get you going.
31      The following options are available:
33      -\b-c\bc      Execute _\bc_\bm_\bd immediately after starting the edit session.  Partic-
34              ularly useful for initial positioning in the file, however _\bc_\bm_\bd is
35              not limited to positioning commands.  This is the POSIX 1003.2
36              interface for the historic ``+cmd'' syntax.  N\bNe\bex\bx/\b/n\bnv\bvi\bi supports
37              both the old and new syntax.
39      -\b-e\be      Start editing in ex mode, as if the command name were e\bex\bx.
41      -\b-F\bF      Don't copy the entire file when first starting to edit.  (The de-
42              fault is to make a copy in case someone else modifies the file
43              during your edit session.)
45      -\b-l\bl      List the files that may be recovered using the -\b-r\br option of v\bvi\bi.
46              This is the new interface for the historic syntax of the -\b-r\br op-
47              tion without a file argument.  N\bNe\bex\bx/\b/n\bnv\bvi\bi supports both the old and
48              new syntax.
50      -\b-R\bR      Start editing in read-only mode, as if the command name was v\bvi\bie\bew\bw,
51              or the readonly option was set.
53      -\b-r\br      Recover the specified file.
55      -\b-s\bs      Enter batch mode; applicable only to e\bex\bx edit sessions.  Batch
56              mode is useful when running e\bex\bx scripts.  Prompts, informative
57              messages and other user oriented message are turned off, and no
58              startup files or environmental variables are read.  This is the
59              POSIX 1003.2 interface for the historic ``-'' argument.  N\bNe\bex\bx/\b/n\bnv\bvi\bi
60              supports both the old and new syntax.
62      -\b-t\bt      Start editing at the specified tag.  (See ctags(1)).
66      -\b-w\bw      Set the initial window size to the specified number of lines.
68      -\b-v\bv      Start editing in vi mode, as if the command name was v\bvi\bi or v\bvi\bie\bew\bw.
70      -\b-x\bx      Reserved for X11 interfaces.  _\bN_\bo _\bX_\b1_\b1 _\bs_\bu_\bp_\bp_\bo_\br_\bt _\bi_\bs _\bc_\bu_\br_\br_\be_\bn_\bt_\bl_\by
71              _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
73      E\bEx\bx/\b/v\bvi\bi exit 0 on success, and greater than 0 if an error occurs.
75 E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bTA\bAL\bL V\bVA\bAR\bRI\bIA\bAB\bBL\bLE\bES\bS
76      COLUMNS
77            The number of columns on the screen.  This value overrides any sys-
78            tem or terminal specific values.  If the COLUMNS environmental
79            variable is not set when e\bex\bx/\b/v\bvi\bi runs, or the c\bco\bol\blu\bum\bmn\bns\bs option is ex-
80            plicitly reset by the user, e\bex\bx/\b/v\bvi\bi enters the value into the envi-
81            ronment.
82      EXINIT
83            A list of e\bex\bx startup commands, read if the variable NEXINIT is not
84            set.
85      HOME  The user's home directory, used as the initial directory path for
86            the startup _\b$_\bH_\bO_\bM_\bE_\b/_\b._\bn_\be_\bx_\br_\bc and _\b$_\bH_\bO_\bM_\bE_\b/_\b._\be_\bx_\br_\bc files.  This value is also
87            used as the default directory for the v\bvi\bi c\bcd\bd command.
88      LINES
89            The number of rows on the screen.  This value overrides any system
90            or terminal specific values.  If the LINES environmental variable
91            is not set when e\bex\bx/\b/v\bvi\bi runs, or the l\bli\bin\bne\bes\bs option is explicitly reset
92            by the user, e\bex\bx/\b/v\bvi\bi enters the value into the environment.
93      NEXINIT
94            A list of e\bex\bx startup commands.
95      SHELL
96            The user's shell of choice (see also the s\bsh\bhe\bel\bll\bl option).
97      TERM  The user's terminal type.  The default is the type ``unknown''. If
98            the TERM environmental variable is not set when e\bex\bx/\b/v\bvi\bi runs, or the
99            t\bte\ber\brm\bm option is explicitly reset by the user, e\bex\bx/\b/v\bvi\bi enters the value
100            into the environment.
101      TMPDIR
102            The location used to stored temporary files (see also the d\bdi\bir\bre\bec\bct\bto\bor\bry\by
103            option).
105 S\bSE\bET\bT O\bOP\bPT\bTI\bIO\bON\bNS\bS
106      There are a large number of options that may be set (or unset) to change
107      the editor's behavior.  This section describes the options, their abbre-
108      viations and their default values.
110      In each entry below, the first part of the tag line is the full name of
111      the option, followed by any equivalent abbreviations.  The part in square
112      brackets is the default value of the option.  Most of the options are
113      boolean, i.e. they are either on or off, and do not have an associated
114      value.
116      Options apply to both e\bex\bx and v\bvi\bi modes, unless otherwise specified.
117      altwerase [off]
118            V\bVi\bi only.  Select an alternate word erase algorithm.
119      autoindent, ai [off]
120            Automatically indent new lines.
121      autoprint, ap [off]
122            E\bEx\bx only.  Display the current line automatically.
123      autowrite, aw [off]
124            Write modified files automatically when changing files.
125      beautify, bf [off]
126            Discard control characters.
127      cdpath [environment variable CDPATH, or ``.'']
128            The directory paths used as path prefixes for the c\bcd\bd command.
129      columns, co [80]
132            Set the number of columns in the screen.
133      comment [off]
134            V\bVi\bi only.  Skip leading comments in files.
135      directory, dir [environment variable TMPDIR, or /tmp]
136            The directory where temporary files are created.
137      edcompatible, ed [off]
138            Modify the behavior of certain suffices for the e\bex\bx s\bsu\bub\bbs\bst\bti\bit\btu\but\bte\be com-
139            mand.
140            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bi_\bs _\bn_\bo_\bt _\by_\be_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
141      errorbells, eb [off]
142            E\bEx\bx only.  Precede error messages with a bell.
143            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bi_\bs _\bn_\bo_\bt _\by_\be_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
144      exrc, ex [off]
145            Never read startup files in the local directory.
146      extended [off]
147            Regular expressions are extended (i.e.  egrep(1) style) expres-
148            sions.
149      flash [on]
150            Flash the screen instead of beeping the keyboard on error.
151      hardtabs, ht [8]
152            Set the spacing between hardware tab settings.
153      ignorecase, ic [off]
154            Ignore case differences in regular expressions.
155      keytime [6]
156            The 10th's of a second e\bex\bx/\b/v\bvi\bi waits for a subsequent key to complete
157            a key mapping.
158      leftright [off]
159            V\bVi\bi only.  Do left-right scrolling.
160      lines, li [24]
161            V\bVi\bi only.  Set the number of lines in the screen.
162      lisp [off]
163            V\bVi\bi only.  Modify various search commands and options to work with
164            Lisp.
165            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bi_\bs _\bn_\bo_\bt _\by_\be_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
166      list [off]
167            Display lines in an unambiguous fashion.
168      magic [on]
169            Treat certain characters specially in regular expressions.
170      matchtime [7]
171            V\bVi\bi only.  The 10th's of a second e\bex\bx/\b/v\bvi\bi pauses on the matching char-
172            acter when the s\bsh\bho\bow\bwm\bma\bat\btc\bch\bh option is set.
173      mesg [on]
174            Permit messages from other users.
175      modelines, modeline [off]
176            Read the first and last few lines of each file for e\bex\bx commands.
177            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bw_\bi_\bl_\bl _\bn_\be_\bv_\be_\br _\bb_\be _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
178      number, nu [off]
179            Precede each line displayed with its current line number.
180      open [on]
181            E\bEx\bx only.  If this option is not set, the o\bop\bpe\ben\bn and v\bvi\bis\bsu\bua\bal\bl commands
182            are disallowed.
183      optimize, opt [on]
184            V\bVi\bi only.  Optimize text throughput to dumb terminals.
185            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bi_\bs _\bn_\bo_\bt _\by_\be_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
186      paragraphs, para [IPLPPPQPP LIpplpipbp]
187            V\bVi\bi only.  Define additional paragraph boundaries for the {\b{ and }\b}
188            commands.
189      prompt [on]
190            E\bEx\bx only.  Display a command prompt.
191      readonly, ro [off]
192            Mark the file as read-only.
193      recdir [/var/tmp/vi.recover]
194            The directory where recovery files are stored.
195      redraw, re [off]
196            V\bVi\bi only.  Simulate an intelligent terminal on a dumb one.
198            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bi_\bs _\bn_\bo_\bt _\by_\be_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
199      remap [on]
200            Remap keys until resolved.
201      remapmax [on]
202            Limit the number of times a key may be remapped.
203      report [5]
204            Set the number of lines about which the editor reports changes.
205      ruler [off]
206            V\bVi\bi only.  Display a row/column ruler on the colon command line.
207      scroll, scr [window / 2]
208            Set the number of lines scrolled.
209      sections, sect [NHSHH HUnhsh]
210            V\bVi\bi only.  Define additional section boundaries for the [\b[[\b[ and ]\b]]\b]
211            commands.
212      shell, sh [environment variable SHELL, or /bin/sh]
213            Select the shell used by the editor.
214      shiftwidth, sw [8]
215            Set the autoindent and shift command indentation width.
216      showdirty [off]
217            V\bVi\bi only.  Display an asterisk on the colon command line if the file
218            has been modified.
219      showmatch, sm [off]
220            V\bVi\bi only.  Note matching ``{'' and ``('' for ``}'' and ``)'' charac-
221            ters.
222      showmode [off]
223            V\bVi\bi only.  Display the current editor mode (command or input).
224      sidescroll [16]
225            V\bVi\bi only.  Set the amount a left-right scroll will shift.
226      slowopen, slow [off]
227            Delay display updating during text input.
228            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bi_\bs _\bn_\bo_\bt _\by_\be_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
229      sourceany [off]
230            Read startup files not owned by the current user.
231            _\bT_\bh_\bi_\bs _\bo_\bp_\bt_\bi_\bo_\bn _\bw_\bi_\bl_\bl _\bn_\be_\bv_\be_\br _\bb_\be _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd_\b.
232      tabstop, ts [8]
233            This option sets tab widths for the editor display.
234      taglength, tl [0]
235            Set the number of significant characters in tag names.
236      tags, tag [tags /var/db/libc.tags /sys/kern/tags]
237            Set the list of tags files.
238      term, ttytype, tty [environment variable TERM]
239            Set the terminal type.
240      terse [off]
241            This option has historically made editor messages less verbose.  It
242            has no effect in this implementation.
243      timeout, to [on]
244            Time out on keys which may be mapped.
245      ttywerase [off]
246            V\bVi\bi only.  Select an alternate erase algorithm.
247      verbose [off]
248            only.  Display an error message for every error.
249      w300 [no default]
250            V\bVi\bi only.  Set the window size if the baud rate is less than 1200
251            baud.
252      w1200 [no default]
253            V\bVi\bi only.  Set the window size if the baud rate is equal to 1200
254            baud.
255      w9600 [no default]
256            V\bVi\bi only.  Set the window size if the baud rate is greater than 1200
257            baud.
258      warn [on]
259            E\bEx\bx only.  This option causes a warning message to the terminal if
260            the file has been modified, since it was last written, before a !\b!
261            command.
262      window, w, wi [environment variable LINES]
264            Set the window size for the screen.
265      wrapmargin, wm [0]
266            V\bVi\bi only.  Break lines automatically when they reach the right-hand
267            margin.
268      wrapscan, ws [on]
269            Set searches to wrap around the end or beginning of the file.
270      writeany, wa [off]
271            Turn off file-overwriting checks.
273 F\bFA\bAS\bST\bT S\bST\bTA\bAR\bRT\bTU\bUP\bP
274      This section will tell you the minimum amount that you need to do simple
275      editing tasks using v\bvi\bi. If you've never used any screen editor before,
276      you're likely to have problems even with this simple introduction.  In
277      that case you should find someone that already knows v\bvi\bi and have them
278      walk you through this section.
280      V\bVi\bi is a screen editor.  This means that it takes up almost the entire
281      screen, displaying part of the file on each screen line, except for the
282      last line of the screen.  The last line of the screen is used for you to
283      give commands to v\bvi\bi, and for v\bvi\bi to give information to you.
285      The other fact that you need to understand is that v\bvi\bi is a modeful edi-
286      tor, i.e. you are either entering text or you are executing commands, and
287      you have to be in the right mode to do one or the other.  You will be in
288      command mode when you first start editing a file.  There are commands
289      that switch you into input mode.  There is only one key that takes you
290      out of input mode, and that is the <escape> key.  (Key names are written
291      using less-than and greater-than signs, e.g.  <escape> means the
292      ``escape'' key, usually labeled ``esc'' on your terminal's keyboard.)  If
293      you're ever confused as to which mode you're in, keep entering the <es-
294      cape> key until v\bvi\bi beeps at you.  (Generally, v\bvi\bi will beep at you if you
295      try and do something that's not allowed.  It will also display error mes-
296      sages.)
298      To start editing a file, enter the command ``vi file_name<carriage-
299      return>''. The command you should enter as soon as you start editing is
300      ``:set verbose showmode<carriage-return>''. This will make the editor
301      give you verbose error messages and display the current mode at the bot-
302      tom of the screen.
304      The commands to move around the file are:
305      h\bh     Move the cursor left one character.
306      j\bj     Move the cursor down one line.
307      k\bk     Move the cursor up one line.
308      l\bl     Move the cursor right one character.
309      <\b<c\bcu\bur\brs\bso\bor\br-\b-a\bar\brr\bro\bow\bws\bs>\b>
310            The cursor arrow keys should work, too.
311      /\b/t\bte\bex\bxt\bt<\b<c\bca\bar\brr\bri\bia\bag\bge\be-\b-r\bre\bet\btu\bur\brn\bn>\b>
312            Search for the string ``text'' in the file, and move the cursor to
313            its first character.
315      The commands to enter new text are:
316      a\ba     Append new text, _\ba_\bf_\bt_\be_\br the cursor.
317      i\bi     Insert new text, _\bb_\be_\bf_\bo_\br_\be the cursor.
318      o\bo     Open a new line below the line the cursor is on, and start entering
319            text.
320      O\bO     Open a new line above the line the cursor is on, and start entering
321            text.
322      <\b<e\bes\bsc\bca\bap\bpe\be>\b>
323            Once you've entered input mode using the one of the a\ba, i\bi, O\bO, or o\bo
324            commands, use <\b<e\bes\bsc\bca\bap\bpe\be>\b> to quit entering text and return to command
325            mode.
327      The commands to copy text are:
330      y\byy\by    Copy the line the cursor is on.
331      p\bp     Append the copied line after the line the cursor is on.
333      The commands to delete text are:
334      d\bdd\bd    Delete the line the cursor is on.
335      x\bx     Delete the character the cursor is on.
337      The commands to write the file are:
338      :\b:w\bw<\b<c\bca\bar\brr\bri\bia\bag\bge\be-\b-r\bre\bet\btu\bur\brn\bn>\b>
339            Write the file back to the file with the name that you originally
340            used as an argument on the v\bvi\bi command line.
341      :\b:w\bw f\bfi\bil\ble\be_\b_n\bna\bam\bme\be<\b<c\bca\bar\brr\bri\bia\bag\bge\be-\b-r\bre\bet\btu\bur\brn\bn>\b>
342            Write the file back to the file with the name ``file_name''.
344      The commands to quit editing and exit the editor are:
345      :\b:q\bq<\b<c\bca\bar\brr\bri\bia\bag\bge\be-\b-r\bre\bet\btu\bur\brn\bn>\b>
346            Quit editing and leave vi (if you've modified the file, but not
347            saved your changes, v\bvi\bi will refuse to quit).
348      :\b:q\bq!\b!<\b<c\bca\bar\brr\bri\bia\bag\bge\be-\b-r\bre\bet\btu\bur\brn\bn>\b>
349            Quit, discarding any modifications that you may have made.
351      One final caution.  Unusual characters can take up more than one column
352      on the screen, and long lines can take up more than a single screen line.
353      The above commands work on ``physical'' characters and lines, i.e. they
354      affect the entire line no matter how many screen lines it takes up and
355      the entire character no matter how many screen columns it takes up.
357 B\bBU\bUG\bGS\bS
358      See the file _\bn_\bv_\bi_\b/_\bd_\bo_\bc_\bs_\b/_\bb_\bu_\bg_\bs_\b._\bc_\bu_\br_\br_\be_\bn_\bt for a list of the known bugs in this
359      version.
361 F\bFI\bIL\bLE\bES\bS
362      /bin/sh              The default user shell.
363      /etc/vi.exrc         System-wide vi startup file.
364      /tmp                 Temporary file directory.
365      /var/tmp/vi.recover  Recovery file directory.
366      $HOME/.nexrc         1st choice for user's home directory startup file.
367      $HOME/.exrc          2nd choice for user's home directory startup file.
368      .nexrc               1st choice for local directory startup file.
369      .exrc                2nd choice for local directory startup file.
371 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
372      ctags(1),  more(1),  curses(3),  dbopen(3)
374      The ``Vi Quick Reference'' card.
376      ``Introduction to Display Editing with Vi'', found in the ``UNIX User's
377      Manual Supplementary Documents''.
379      ``Edit: A tutorial'', found in the ``UNIX User's Manual Supplementary
380      Documents''.
382      ``Ex Reference Manual (Version 3.7)'', found in the ``UNIX User's Manual
383      Supplementary Documents''.
385      N\bNr\bro\bof\bff\bf/\b/t\btr\bro\bof\bff\bf source for the previous three documents are distributed with
386      n\bne\bex\bx/\b/n\bnv\bvi\bi in the _\bn_\bv_\bi_\b/_\bd_\bo_\bc_\bs_\b/_\bU_\bS_\bD_\b._\bd_\bo_\bc directory of the n\bne\bex\bx/\b/n\bnv\bvi\bi source code.
388      The files ``autowrite'', ``input'', ``quoting'', and ``structures'',
389      found in the _\bn_\bv_\bi_\b/_\bd_\bo_\bc_\bs_\b/_\bi_\bn_\bt_\be_\br_\bn_\ba_\bl_\bs directory of the n\bne\bex\bx/\b/n\bnv\bvi\bi source code.
391 H\bHI\bIS\bST\bTO\bOR\bRY\bY
392      The n\bne\bex\bx/\b/n\bnv\bvi\bi replacements for the e\bex\bx/\b/v\bvi\bi editor first appeared in 4.4BSD.
394 S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS
395      N\bNe\bex\bx/\b/n\bnv\bvi\bi is close to IEEE Std1003.2 (``POSIX'').  That document differs
396      from historical e\bex\bx/\b/v\bvi\bi practice in several places; there are changes to be
397      made on both sides.
399 4.4BSD                          March 19, 1994                               7