Mercurial > vim

comparison runtime/doc/vim.1 @ 7:3fc0f57ecb91 v7.0001

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated for version 7.0001
author vimboss
date Sun, 13 Jun 2004 20:20:40 +0000
parents
children f6033dcbaf31
comparison
equal deleted inserted replaced
6:c2daee826b8f 7:3fc0f57ecb91
1 .TH VIM 1 "2002 Feb 22"
2 .SH NAME
3 vim \- Vi IMproved, a programmers text editor
4 .SH SYNOPSIS
5 .br
6 .B vim
7 [options] [file ..]
8 .br
9 .B vim
10 [options] -
11 .br
12 .B vim
13 [options] \-t tag
14 .br
15 .B vim
16 [options] \-q [errorfile]
17 .PP
18 .br
19 .B ex
20 .br
21 .B view
22 .br
23 .B gvim
24 .B gview
25 .B evim
26 .B eview
27 .br
28 .B rvim
29 .B rview
30 .B rgvim
31 .B rgview
32 .SH DESCRIPTION
33 .B Vim
34 is a text editor that is upwards compatible to Vi.
35 It can be used to edit all kinds of plain text.
36 It is especially useful for editing programs.
37 .PP
38 There are a lot of enhancements above Vi: multi level undo,
39 multi windows and buffers, syntax highlighting, command line
40 editing, filename completion, on-line help, visual selection, etc..
41 See ":help vi_diff.txt" for a summary of the differences between
42 .B Vim
43 and Vi.
44 .PP
45 While running
46 .B Vim
47 a lot of help can be obtained from the on-line help system, with the ":help"
48 command.
49 See the ON-LINE HELP section below.
50 .PP
51 Most often
52 .B Vim
53 is started to edit a single file with the command
54 .PP
55 vim file
56 .PP
57 More generally
58 .B Vim
59 is started with:
60 .PP
61 vim [options] [filelist]
62 .PP
63 If the filelist is missing, the editor will start with an empty buffer.
64 Otherwise exactly one out of the following four may be used to choose one or
65 more files to be edited.
66 .TP 12
67 file ..
68 A list of filenames.
69 The first one will be the current file and read into the buffer.
70 The cursor will be positioned on the first line of the buffer.
71 You can get to the other files with the ":next" command.
72 To edit a file that starts with a dash, precede the filelist with "--".
73 .TP
74 -
75 The file to edit is read from stdin. Commands are read from stderr, which
76 should be a tty.
77 .TP
78 -t {tag}
79 The file to edit and the initial cursor position depends on a "tag", a sort
80 of goto label.
81 {tag} is looked up in the tags file, the associated file becomes the current
82 file and the associated command is executed.
83 Mostly this is used for C programs, in which case {tag} could be a function
84 name.
85 The effect is that the file containing that function becomes the current file
86 and the cursor is positioned on the start of the function.
87 See ":help tag-commands".
88 .TP
89 -q [errorfile]
90 Start in quickFix mode.
91 The file [errorfile] is read and the first error is displayed.
92 If [errorfile] is omitted, the filename is obtained from the 'errorfile'
93 option (defaults to "AztecC.Err" for the Amiga, "errors.err" on other
94 systems).
95 Further errors can be jumped to with the ":cn" command.
96 See ":help quickfix".
97 .PP
98 .B Vim
99 behaves differently, depending on the name of the command (the executable may
100 still be the same file).
101 .TP 10
102 vim
103 The "normal" way, everything is default.
104 .TP
105 ex
106 Start in Ex mode.
107 Go to Normal mode with the ":vi" command.
108 Can also be done with the "-e" argument.
109 .TP
110 view
111 Start in read-only mode. You will be protected from writing the files. Can
112 also be done with the "-R" argument.
113 .TP
114 gvim gview
115 The GUI version.
116 Starts a new window.
117 Can also be done with the "-g" argument.
118 .TP
119 evim eview
120 The GUI version in easy mode.
121 Starts a new window.
122 Can also be done with the "-y" argument.
123 .TP
124 rvim rview rgvim rgview
125 Like the above, but with restrictions. It will not be possible to start shell
126 commands, or suspend
127 .B Vim.
128 Can also be done with the "-Z" argument.
129 .SH OPTIONS
130 The options may be given in any order, before or after filenames.
131 Options without an argument can be combined after a single dash.
132 .TP 12
133 +[num]
134 For the first file the cursor will be positioned on line "num".
135 If "num" is missing, the cursor will be positioned on the last line.
136 .TP
137 +/{pat}
138 For the first file the cursor will be positioned on the
139 first occurrence of {pat}.
140 See ":help search-pattern" for the available search patterns.
141 .TP
142 +{command}
143 .TP
144 -c {command}
145 {command} will be executed after the
146 first file has been read.
147 {command} is interpreted as an Ex command.
148 If the {command} contains spaces it must be enclosed in double quotes (this
149 depends on the shell that is used).
150 Example: Vim "+set si" main.c
151 .br
152 Note: You can use up to 10 "+" or "-c" commands.
153 .TP
154 -S {file}
155 {file} will be sourced after the first file has been read.
156 This is equivalent to -c "source {file}".
157 {file} cannot start with '-'.
158 If {file} is omitted "Session.vim" is used (only works when -S is the last
159 argument).
160 .TP
161 --cmd {command}
162 Like using "-c", but the command is executed just before
163 processing any vimrc file.
164 You can use up to 10 of these commands, independently from "-c" commands.
165 .TP
166 -A
167 If
168 .B Vim
169 has been compiled with ARABIC support for editing right-to-left
170 oriented files and Arabic keyboard mapping, this option starts
171 .B Vim
172 in Arabic mode, i.e. 'arabic' is set. Otherwise an error
173 message is given and
174 .B Vim
175 aborts.
176 .TP
177 -b
178 Binary mode.
179 A few options will be set that makes it possible to edit a binary or
180 executable file.
181 .TP
182 -C
183 Compatible. Set the 'compatible' option.
184 This will make
185 .B Vim
186 behave mostly like Vi, even though a .vimrc file exists.
187 .TP
188 -d
189 Start in diff mode.
190 There should be two or three file name arguments.
191 .B Vim
192 will open all the files and show differences between them.
193 Works like vimdiff(1).
194 .TP
195 -d {device}
196 Open {device} for use as a terminal.
197 Only on the Amiga.
198 Example:
199 "\-d con:20/30/600/150".
200 .TP
201 -D
202 Debugging. Go to debugging mode when executing the first command from a
203 script.
204 .TP
205 -e
206 Start
207 .B Vim
208 in Ex mode, just like the executable was called "ex".
209 .TP
210 -E
211 Start
212 .B Vim
213 in improved Ex mode, just like the executable was called "exim".
214 .TP
215 -f
216 Foreground. For the GUI version,
217 .B Vim
218 will not fork and detach from the shell it was started in.
219 On the Amiga,
220 .B Vim
221 is not restarted to open a new window.
222 This option should be used when
223 .B Vim
224 is executed by a program that will wait for the edit
225 session to finish (e.g. mail).
226 On the Amiga the ":sh" and ":!" commands will not work.
227 .TP
228 --nofork
229 Foreground. For the GUI version,
230 .B Vim
231 will not fork and detach from the shell it was started in.
232 .TP
233 -F
234 If
235 .B Vim
236 has been compiled with FKMAP support for editing right-to-left
237 oriented files and Farsi keyboard mapping, this option starts
238 .B Vim
239 in Farsi mode, i.e. 'fkmap' and 'rightleft' are set.
240 Otherwise an error message is given and
241 .B Vim
242 aborts.
243 .TP
244 -g
245 If
246 .B Vim
247 has been compiled with GUI support, this option enables the GUI.
248 If no GUI support was compiled in, an error message is given and
249 .B Vim
250 aborts.
251 .TP
252 -h
253 Give a bit of help about the command line arguments and options.
254 After this
255 .B Vim
256 exits.
257 .TP
258 -H
259 If
260 .B Vim
261 has been compiled with RIGHTLEFT support for editing right-to-left
262 oriented files and Hebrew keyboard mapping, this option starts
263 .B Vim
264 in Hebrew mode, i.e. 'hkmap' and 'rightleft' are set.
265 Otherwise an error message is given and
266 .B Vim
267 aborts.
268 .TP
269 -i {viminfo}
270 When using the viminfo file is enabled, this option sets the filename to use,
271 instead of the default "~/.viminfo".
272 This can also be used to skip the use of the .viminfo file, by giving the name
273 "NONE".
274 .TP
275 -L
276 Same as -r.
277 .TP
278 -l
279 Lisp mode.
280 Sets the 'lisp' and 'showmatch' options on.
281 .TP
282 -m
283 Modifying files is disabled.
284 Resets the 'write' option.
285 You can still modify the buffer, but writing a file is not possible.
286 .TP
287 -M
288 Modifications not allowed. The 'modifiable' and 'write' options will be unset,
289 so that changes are not allowed and files can not be written. Note that these
290 options can be set to enable making modifications.
291 .TP
292 -N
293 No-compatible mode. Reset the 'compatible' option.
294 This will make
295 .B Vim
296 behave a bit better, but less Vi compatible, even though a .vimrc file does
297 not exist.
298 .TP
299 -n
300 No swap file will be used.
301 Recovery after a crash will be impossible.
302 Handy if you want to edit a file on a very slow medium (e.g. floppy).
303 Can also be done with ":set uc=0".
304 Can be undone with ":set uc=200".
305 .TP
306 -nb
307 Become an editor server for NetBeans. See the docs for details.
308 .TP
309 -o[N]
310 Open N windows stacked.
311 When N is omitted, open one window for each file.
312 .TP
313 -O[N]
314 Open N windows side by side.
315 When N is omitted, open one window for each file.
316 .TP
317 -R
318 Read-only mode.
319 The 'readonly' option will be set.
320 You can still edit the buffer, but will be prevented from accidently
321 overwriting a file.
322 If you do want to overwrite a file, add an exclamation mark to the Ex command,
323 as in ":w!".
324 The -R option also implies the -n option (see below).
325 The 'readonly' option can be reset with ":set noro".
326 See ":help 'readonly'".
327 .TP
328 -r
329 List swap files, with information about using them for recovery.
330 .TP
331 -r {file}
332 Recovery mode.
333 The swap file is used to recover a crashed editing session.
334 The swap file is a file with the same filename as the text file with ".swp"
335 appended.
336 See ":help recovery".
337 .TP
338 -s
339 Silent mode. Only when started as "Ex" or when the "-e" option was given
340 before the "-s" option.
341 .TP
342 -s {scriptin}
343 The script file {scriptin} is read.
344 The characters in the file are interpreted as if you had typed them.
345 The same can be done with the command ":source! {scriptin}".
346 If the end of the file is reached before the editor exits, further characters
347 are read from the keyboard.
348 .TP
349 -T {terminal}
350 Tells
351 .B Vim
352 the name of the terminal you are using.
353 Only required when the automatic way doesn't work.
354 Should be a terminal known
355 to
356 .B Vim
357 (builtin) or defined in the termcap or terminfo file.
358 .TP
359 -u {vimrc}
360 Use the commands in the file {vimrc} for initializations.
361 All the other initializations are skipped.
362 Use this to edit a special kind of files.
363 It can also be used to skip all initializations by giving the name "NONE".
364 See ":help initialization" within vim for more details.
365 .TP
366 -U {gvimrc}
367 Use the commands in the file {gvimrc} for GUI initializations.
368 All the other GUI initializations are skipped.
369 It can also be used to skip all GUI initializations by giving the name "NONE".
370 See ":help gui-init" within vim for more details.
371 .TP
372 -V[N]
373 Verbose. Give messages about which files are sourced and for reading and
374 writing a viminfo file. The optional number N is the value for 'verbose'.
375 Default is 10.
376 .TP
377 -v
378 Start
379 .B Vim
380 in Vi mode, just like the executable was called "vi". This only has effect
381 when the executable is called "ex".
382 .TP
383 -w {scriptout}
384 All the characters that you type are recorded in the file
385 {scriptout}, until you exit
386 .B Vim.
387 This is useful if you want to create a script file to be used with "vim -s" or
388 ":source!".
389 If the {scriptout} file exists, characters are appended.
390 .TP
391 -W {scriptout}
392 Like -w, but an existing file is overwritten.
393 .TP
394 -x
395 Use encryption when writing files. Will prompt for a crypt key.
396 .TP
397 -X
398 Don't connect to the X server. Shortens startup time in a terminal, but the
399 window title and clipboard will not be used.
400 .TP
401 -y
402 Start
403 .B Vim
404 in easy mode, just like the executable was called "evim" or "eview".
405 Makes
406 .B Vim
407 behave like a click-and-type editor.
408 .TP
409 -Z
410 Restricted mode. Works like the executable starts with "r".
411 .TP
412 --
413 Denotes the end of the options.
414 Arguments after this will be handled as a file name.
415 This can be used to edit a filename that starts with a '-'.
416 .TP
417 --echo-wid
418 GTK GUI only: Echo the Window ID on stdout
419 .TP
420 --help
421 Give a help message and exit, just like "-h".
422 .TP
423 --literal
424 Take file name arguments literally, do not expand wildcards. Not needed on
425 Unix, the shell expand wildcards.
426 .TP
427 --noplugin
428 Skip loading plugins. Implied by -u NONE.
429 .TP
430 --remote
431 Connect to a Vim server and make it edit the files given in the rest of the
432 arguments. If no server is found a warning is given and the files are edited
433 in the current Vim.
434 .TP
435 --remote-expr {expr}
436 Connect to a Vim server, evaluate {expr} in it and print the result on stdout.
437 .TP
438 --remote-send {keys}
439 Connect to a Vim server and send {keys} to it.
440 .TP
441 --remote-silent
442 As --remote, but without the warning when no server is found.
443 .TP
444 --remote-wait
445 As --remote, but Vim does not exit until the files have been edited.
446 .TP
447 --remote-wait-silent
448 As --remote-wait, but without the warning when no server is found.
449 .TP
450 --serverlist
451 List the names of all Vim servers that can be found.
452 .TP
453 --servername {name}
454 Use {name} as the server name. Used for the current Vim, unless used with a
455 --remote argument, then it's the name of the server to connect to.
456 .TP
457 --socketid {id}
458 GTK GUI only: Use the GtkPlug mechanism to run gvim in another window.
459 .TP
460 --version
461 Print version information and exit.
462 .SH ON-LINE HELP
463 Type ":help" in
464 .B Vim
465 to get started.
466 Type ":help subject" to get help on a specific subject.
467 For example: ":help ZZ" to get help for the "ZZ" command.
468 Use <Tab> and CTRL-D to complete subjects (":help cmdline-completion").
469 Tags are present to jump from one place to another (sort of hypertext links,
470 see ":help").
471 All documentation files can be viewed in this way, for example
472 ":help syntax.txt".
473 .SH FILES
474 .TP 15
475 /usr/local/lib/vim/doc/*.txt
476 The
477 .B Vim
478 documentation files.
479 Use ":help doc-file-list" to get the complete list.
480 .TP
481 /usr/local/lib/vim/doc/tags
482 The tags file used for finding information in the documentation files.
483 .TP
484 /usr/local/lib/vim/syntax/syntax.vim
485 System wide syntax initializations.
486 .TP
487 /usr/local/lib/vim/syntax/*.vim
488 Syntax files for various languages.
489 .TP
490 /usr/local/lib/vim/vimrc
491 System wide
492 .B Vim
493 initializations.
494 .TP
495 /usr/local/lib/vim/gvimrc
496 System wide gvim initializations.
497 .TP
498 /usr/local/lib/vim/optwin.vim
499 Script used for the ":options" command, a nice way to view and set options.
500 .TP
501 /usr/local/lib/vim/menu.vim
502 System wide menu initializations for gvim.
503 .TP
504 /usr/local/lib/vim/bugreport.vim
505 Script to generate a bug report. See ":help bugs".
506 .TP
507 /usr/local/lib/vim/filetype.vim
508 Script to detect the type of a file by its name. See ":help 'filetype'".
509 .TP
510 /usr/local/lib/vim/scripts.vim
511 Script to detect the type of a file by its contents. See ":help 'filetype'".
512 .TP
513 /usr/local/lib/vim/*.ps
514 Files used for PostScript printing.
515 .PP
516 For recent info read the VIM home page:
517 .br
518 <URL:http://www.vim.org/>
519 .SH SEE ALSO
520 vimtutor(1)
521 .SH AUTHOR
522 Most of
523 .B Vim
524 was made by Bram Moolenaar, with a lot of help from others.
525 See ":help credits" in
526 .B Vim.
527 .br
528 .B Vim
529 is based on Stevie, worked on by: Tim Thompson,
530 Tony Andrews and G.R. (Fred) Walter.
531 Although hardly any of the original code remains.
532 .SH BUGS
533 Probably.
534 See ":help todo" for a list of known problems.
535 .PP
536 Note that a number of things that may be regarded as bugs by some, are in fact
537 caused by a too-faithful reproduction of Vi's behaviour.
538 And if you think other things are bugs "because Vi does it differently",
539 you should take a closer look at the vi_diff.txt file (or type :help
540 vi_diff.txt when in Vim).
541 Also have a look at the 'compatible' and 'cpoptions' options.