runtime/doc/vim.1

   1 .TH VIM 1 "2006 Apr 11"
   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 \-p[N]
 318 Open N tab pages.
 319 When N is omitted, open one tab page for each file.
 320 .TP
 321 \-R
 322 Read-only mode.
 323 The 'readonly' option will be set.
 324 You can still edit the buffer, but will be prevented from accidently
 325 overwriting a file.
 326 If you do want to overwrite a file, add an exclamation mark to the Ex command,
 327 as in ":w!".
 328 The \-R option also implies the \-n option (see below).
 329 The 'readonly' option can be reset with ":set noro".
 330 See ":help 'readonly'".
 331 .TP
 332 \-r
 333 List swap files, with information about using them for recovery.
 334 .TP
 335 \-r {file}
 336 Recovery mode.
 337 The swap file is used to recover a crashed editing session.
 338 The swap file is a file with the same filename as the text file with ".swp"
 339 appended.
 340 See ":help recovery".
 341 .TP
 342 \-s
 343 Silent mode.  Only when started as "Ex" or when the "\-e" option was given
 344 before the "\-s" option.
 345 .TP
 346 \-s {scriptin}
 347 The script file {scriptin} is read.
 348 The characters in the file are interpreted as if you had typed them.
 349 The same can be done with the command ":source! {scriptin}".
 350 If the end of the file is reached before the editor exits, further characters
 351 are read from the keyboard.
 352 .TP
 353 \-T {terminal}
 354 Tells
 355 .B Vim
 356 the name of the terminal you are using.
 357 Only required when the automatic way doesn't work.
 358 Should be a terminal known
 359 to
 360 .B Vim
 361 (builtin) or defined in the termcap or terminfo file.
 362 .TP
 363 \-u {vimrc}
 364 Use the commands in the file {vimrc} for initializations.
 365 All the other initializations are skipped.
 366 Use this to edit a special kind of files.
 367 It can also be used to skip all initializations by giving the name "NONE".
 368 See ":help initialization" within vim for more details.
 369 .TP
 370 \-U {gvimrc}
 371 Use the commands in the file {gvimrc} for GUI initializations.
 372 All the other GUI initializations are skipped.
 373 It can also be used to skip all GUI initializations by giving the name "NONE".
 374 See ":help gui\-init" within vim for more details.
 375 .TP
 376 \-V[N]
 377 Verbose.  Give messages about which files are sourced and for reading and
 378 writing a viminfo file.  The optional number N is the value for 'verbose'.
 379 Default is 10.
 380 .TP
 381 \-v
 382 Start
 383 .B Vim
 384 in Vi mode, just like the executable was called "vi".  This only has effect
 385 when the executable is called "ex".
 386 .TP
 387 \-w {scriptout}
 388 All the characters that you type are recorded in the file
 389 {scriptout}, until you exit
 390 .B Vim.
 391 This is useful if you want to create a script file to be used with "vim \-s" or
 392 ":source!".
 393 If the {scriptout} file exists, characters are appended.
 394 .TP
 395 \-W {scriptout}
 396 Like \-w, but an existing file is overwritten.
 397 .TP
 398 \-x
 399 Use encryption when writing files.  Will prompt for a crypt key.
 400 .TP
 401 \-X
 402 Don't connect to the X server.  Shortens startup time in a terminal, but the
 403 window title and clipboard will not be used.
 404 .TP
 405 \-y
 406 Start
 407 .B Vim
 408 in easy mode, just like the executable was called "evim" or "eview".
 409 Makes
 410 .B Vim
 411 behave like a click-and-type editor.
 412 .TP
 413 \-Z
 414 Restricted mode.  Works like the executable starts with "r".
 415 .TP
 416 \-\-
 417 Denotes the end of the options.
 418 Arguments after this will be handled as a file name.
 419 This can be used to edit a filename that starts with a '\-'.
 420 .TP
 421 \-\-echo\-wid
 422 GTK GUI only: Echo the Window ID on stdout.
 423 .TP
 424 \-\-help
 425 Give a help message and exit, just like "\-h".
 426 .TP
 427 \-\-literal
 428 Take file name arguments literally, do not expand wildcards.  This has no
 429 effect on Unix where the shell expands wildcards.
 430 .TP
 431 \-\-noplugin
 432 Skip loading plugins.  Implied by \-u NONE.
 433 .TP
 434 \-\-remote
 435 Connect to a Vim server and make it edit the files given in the rest of the
 436 arguments.  If no server is found a warning is given and the files are edited
 437 in the current Vim.
 438 .TP
 439 \-\-remote\-expr {expr}
 440 Connect to a Vim server, evaluate {expr} in it and print the result on stdout.
 441 .TP
 442 \-\-remote\-send {keys}
 443 Connect to a Vim server and send {keys} to it.
 444 .TP
 445 \-\-remote\-silent
 446 As \-\-remote, but without the warning when no server is found.
 447 .TP
 448 \-\-remote\-wait
 449 As \-\-remote, but Vim does not exit until the files have been edited.
 450 .TP
 451 \-\-remote\-wait\-silent
 452 As \-\-remote\-wait, but without the warning when no server is found.
 453 .TP
 454 \-\-serverlist
 455 List the names of all Vim servers that can be found.
 456 .TP
 457 \-\-servername {name}
 458 Use {name} as the server name.  Used for the current Vim, unless used with a
 459 \-\-remote argument, then it's the name of the server to connect to.
 460 .TP
 461 \-\-socketid {id}
 462 GTK GUI only: Use the GtkPlug mechanism to run gvim in another window.
 463 .TP
 464 \-\-version
 465 Print version information and exit.
 466 .SH ON-LINE HELP
 467 Type ":help" in
 468 .B Vim
 469 to get started.
 470 Type ":help subject" to get help on a specific subject.
 471 For example: ":help ZZ" to get help for the "ZZ" command.
 472 Use <Tab> and CTRL-D to complete subjects (":help cmdline\-completion").
 473 Tags are present to jump from one place to another (sort of hypertext links,
 474 see ":help").
 475 All documentation files can be viewed in this way, for example
 476 ":help syntax.txt".
 477 .SH FILES
 478 .TP 15
 479 /usr/local/lib/vim/doc/*.txt
 480 The
 481 .B Vim
 482 documentation files.
 483 Use ":help doc\-file\-list" to get the complete list.
 484 .TP
 485 /usr/local/lib/vim/doc/tags
 486 The tags file used for finding information in the documentation files.
 487 .TP
 488 /usr/local/lib/vim/syntax/syntax.vim
 489 System wide syntax initializations.
 490 .TP
 491 /usr/local/lib/vim/syntax/*.vim
 492 Syntax files for various languages.
 493 .TP
 494 /usr/local/lib/vim/vimrc
 495 System wide
 496 .B Vim
 497 initializations.
 498 .TP
 499 ~/.vimrc
 500 Your personal
 501 .B Vim
 502 initializations.
 503 .TP
 504 /usr/local/lib/vim/gvimrc
 505 System wide gvim initializations.
 506 .TP
 507 ~/.gvimrc
 508 Your personal gvim initializations.
 509 .TP
 510 /usr/local/lib/vim/optwin.vim
 511 Script used for the ":options" command, a nice way to view and set options.
 512 .TP
 513 /usr/local/lib/vim/menu.vim
 514 System wide menu initializations for gvim.
 515 .TP
 516 /usr/local/lib/vim/bugreport.vim
 517 Script to generate a bug report.  See ":help bugs".
 518 .TP
 519 /usr/local/lib/vim/filetype.vim
 520 Script to detect the type of a file by its name.  See ":help 'filetype'".
 521 .TP
 522 /usr/local/lib/vim/scripts.vim
 523 Script to detect the type of a file by its contents.  See ":help 'filetype'".
 524 .TP
 525 /usr/local/lib/vim/*.ps
 526 Files used for PostScript printing.
 527 .PP
 528 For recent info read the VIM home page:
 529 .br
 530 <URL:http://www.vim.org/>
 531 .SH SEE ALSO
 532 vimtutor(1)
 533 .SH AUTHOR
 534 Most of
 535 .B Vim
 536 was made by Bram Moolenaar, with a lot of help from others.
 537 See ":help credits" in
 538 .B Vim.
 539 .br
 540 .B Vim
 541 is based on Stevie, worked on by: Tim Thompson,
 542 Tony Andrews and G.R. (Fred) Walter.
 543 Although hardly any of the original code remains.
 544 .SH BUGS
 545 Probably.
 546 See ":help todo" for a list of known problems.
 547 .PP
 548 Note that a number of things that may be regarded as bugs by some, are in fact
 549 caused by a too-faithful reproduction of Vi's behaviour.
 550 And if you think other things are bugs "because Vi does it differently",
 551 you should take a closer look at the vi_diff.txt file (or type :help
 552 vi_diff.txt when in Vim).
 553 Also have a look at the 'compatible' and 'cpoptions' options.