summaryrefslogtreecommitdiffstats
path: root/runtime/doc/vim.1
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/vim.1')
-rw-r--r--runtime/doc/vim.1558
1 files changed, 558 insertions, 0 deletions
diff --git a/runtime/doc/vim.1 b/runtime/doc/vim.1
new file mode 100644
index 0000000..5613dd4
--- /dev/null
+++ b/runtime/doc/vim.1
@@ -0,0 +1,558 @@
+.TH VIM 1 "2021 Jun 13"
+.SH NAME
+vim \- Vi IMproved, a programmer's text editor
+.SH SYNOPSIS
+.br
+.B vim
+[options] [file ..]
+.br
+.B vim
+[options] \-
+.br
+.B vim
+[options] \-t tag
+.br
+.B vim
+[options] \-q [errorfile]
+.PP
+.br
+.B ex
+.br
+.B view
+.br
+.B gvim
+.B gview
+.B evim
+.B eview
+.br
+.B rvim
+.B rview
+.B rgvim
+.B rgview
+.SH DESCRIPTION
+.B Vim
+is a text editor that is upwards compatible to Vi.
+It can be used to edit all kinds of plain text.
+It is especially useful for editing programs.
+.PP
+There are a lot of enhancements above Vi: multi level undo,
+multi windows and buffers, syntax highlighting, command line
+editing, filename completion, on-line help, visual selection, etc..
+See ":help vi_diff.txt" for a summary of the differences between
+.B Vim
+and Vi.
+.PP
+While running
+.B Vim
+a lot of help can be obtained from the on-line help system, with the ":help"
+command.
+See the ON-LINE HELP section below.
+.PP
+Most often
+.B Vim
+is started to edit a single file with the command
+.PP
+ vim file
+.PP
+More generally
+.B Vim
+is started with:
+.PP
+ vim [options] [filelist]
+.PP
+If the filelist is missing, the editor will start with an empty buffer.
+Otherwise exactly one out of the following four may be used to choose one or
+more files to be edited.
+.TP 12
+file ..
+A list of filenames.
+The first one will be the current file and read into the buffer.
+The cursor will be positioned on the first line of the buffer.
+You can get to the other files with the ":next" command.
+To edit a file that starts with a dash, precede the filelist with "\-\-".
+.TP
+\-
+The file to edit is read from stdin. Commands are read from stderr, which
+should be a tty.
+.TP
+\-t {tag}
+The file to edit and the initial cursor position depends on a "tag", a sort
+of goto label.
+{tag} is looked up in the tags file, the associated file becomes the current
+file and the associated command is executed.
+Mostly this is used for C programs, in which case {tag} could be a function
+name.
+The effect is that the file containing that function becomes the current file
+and the cursor is positioned on the start of the function.
+See ":help tag\-commands".
+.TP
+\-q [errorfile]
+Start in quickFix mode.
+The file [errorfile] is read and the first error is displayed.
+If [errorfile] is omitted, the filename is obtained from the 'errorfile'
+option (defaults to "AztecC.Err" for the Amiga, "errors.err" on other
+systems).
+Further errors can be jumped to with the ":cn" command.
+See ":help quickfix".
+.PP
+.B Vim
+behaves differently, depending on the name of the command (the executable may
+still be the same file).
+.TP 10
+vim
+The "normal" way, everything is default.
+.TP
+ex
+Start in Ex mode.
+Go to Normal mode with the ":vi" command.
+Can also be done with the "\-e" argument.
+.TP
+view
+Start in read-only mode. You will be protected from writing the files.
+Can also be done with the "\-R" argument.
+.TP
+gvim gview
+The GUI version.
+Starts a new window.
+Can also be done with the "\-g" argument.
+.TP
+evim eview
+The GUI version in easy mode.
+Starts a new window.
+Can also be done with the "\-y" argument.
+.TP
+rvim rview rgvim rgview
+Like the above, but with restrictions. It will not be possible to start shell
+commands, or suspend
+.B Vim.
+Can also be done with the "\-Z" argument.
+.SH OPTIONS
+The options may be given in any order, before or after filenames.
+Options without an argument can be combined after a single dash.
+.TP 12
++[num]
+For the first file the cursor will be positioned on line "num".
+If "num" is missing, the cursor will be positioned on the last line.
+.TP
++/{pat}
+For the first file the cursor will be positioned in the line with the
+first occurrence of {pat}.
+See ":help search\-pattern" for the available search patterns.
+.TP
++{command}
+.TP
+\-c {command}
+{command} will be executed after the first file has been read.
+{command} is interpreted as an Ex command.
+If the {command} contains spaces it must be enclosed in double quotes (this
+depends on the shell that is used).
+Example: vim "+set si" main.c
+.br
+Note: You can use up to 10 "+" or "\-c" commands.
+.TP
+\-S {file}
+{file} will be sourced after the first file has been read.
+This is equivalent to \-c "source {file}".
+{file} cannot start with '\-'.
+If {file} is omitted "Session.vim" is used (only works when \-S is the last
+argument).
+.TP
+\-\-cmd {command}
+Like using "\-c", but the command is executed just before
+processing any vimrc file.
+You can use up to 10 of these commands, independently from "\-c" commands.
+.TP
+\-A
+If
+.B Vim
+has been compiled with ARABIC support for editing right-to-left
+oriented files and Arabic keyboard mapping, this option starts
+.B Vim
+in Arabic mode, i.e. 'arabic' is set. Otherwise an error
+message is given and
+.B Vim
+aborts.
+.TP
+\-b
+Binary mode.
+A few options will be set that makes it possible to edit a binary or
+executable file.
+.TP
+\-C
+Compatible. Set the 'compatible' option.
+This will make
+.B Vim
+behave mostly like Vi, even though a .vimrc file exists.
+.TP
+\-d
+Start in diff mode.
+There should between two to eight file name arguments.
+.B Vim
+will open all the files and show differences between them.
+Works like vimdiff(1).
+.TP
+\-d {device}
+Open {device} for use as a terminal.
+Only on the Amiga.
+Example:
+"\-d con:20/30/600/150".
+.TP
+\-D
+Debugging. Go to debugging mode when executing the first command from a
+script.
+.TP
+\-e
+Start
+.B Vim
+in Ex mode, just like the executable was called "ex".
+.TP
+\-E
+Start
+.B Vim
+in improved Ex mode, just like the executable was called "exim".
+.TP
+\-f
+Foreground. For the GUI version,
+.B Vim
+will not fork and detach from the shell it was started in.
+On the Amiga,
+.B Vim
+is not restarted to open a new window.
+This option should be used when
+.B Vim
+is executed by a program that will wait for the edit
+session to finish (e.g. mail).
+On the Amiga the ":sh" and ":!" commands will not work.
+.TP
+\-\-nofork
+Foreground. For the GUI version,
+.B Vim
+will not fork and detach from the shell it was started in.
+.TP
+\-F
+If
+.B Vim
+has been compiled with FKMAP support for editing right-to-left
+oriented files and Farsi keyboard mapping, this option starts
+.B Vim
+in Farsi mode, i.e. 'fkmap' and 'rightleft' are set.
+Otherwise an error message is given and
+.B Vim
+aborts.
+.TP
+\-g
+If
+.B Vim
+has been compiled with GUI support, this option enables the GUI.
+If no GUI support was compiled in, an error message is given and
+.B Vim
+aborts.
+.TP
+\-h
+Give a bit of help about the command line arguments and options.
+After this
+.B Vim
+exits.
+.TP
+\-H
+If
+.B Vim
+has been compiled with RIGHTLEFT support for editing right-to-left
+oriented files and Hebrew keyboard mapping, this option starts
+.B Vim
+in Hebrew mode, i.e. 'hkmap' and 'rightleft' are set.
+Otherwise an error message is given and
+.B Vim
+aborts.
+.TP
+\-i {viminfo}
+Specifies the filename to use when reading or writing the viminfo file,
+instead of the default "~/.viminfo".
+This can also be used to skip the use of the .viminfo file, by giving the name
+"NONE".
+.TP
+\-L
+Same as \-r.
+.TP
+\-l
+Lisp mode.
+Sets the 'lisp' and 'showmatch' options on.
+.TP
+\-m
+Modifying files is disabled.
+Resets the 'write' option.
+You can still modify the buffer, but writing a file is not possible.
+.TP
+\-M
+Modifications not allowed. The 'modifiable' and 'write' options will be unset,
+so that changes are not allowed and files can not be written. Note that these
+options can be set to enable making modifications.
+.TP
+\-N
+No-compatible mode. Resets the 'compatible' option.
+This will make
+.B Vim
+behave a bit better, but less Vi compatible, even though a .vimrc file does
+not exist.
+.TP
+\-n
+No swap file will be used.
+Recovery after a crash will be impossible.
+Handy if you want to edit a file on a very slow medium (e.g. floppy).
+Can also be done with ":set uc=0".
+Can be undone with ":set uc=200".
+.TP
+\-nb
+Become an editor server for NetBeans. See the docs for details.
+.TP
+\-o[N]
+Open N windows stacked.
+When N is omitted, open one window for each file.
+.TP
+\-O[N]
+Open N windows side by side.
+When N is omitted, open one window for each file.
+.TP
+\-p[N]
+Open N tab pages.
+When N is omitted, open one tab page for each file.
+.TP
+\-R
+Read-only mode.
+The 'readonly' option will be set.
+You can still edit the buffer, but will be prevented from accidentally
+overwriting a file.
+If you do want to overwrite a file, add an exclamation mark to the Ex command,
+as in ":w!".
+The \-R option also implies the \-n option (see above).
+The 'readonly' option can be reset with ":set noro".
+See ":help 'readonly'".
+.TP
+\-r
+List swap files, with information about using them for recovery.
+.TP
+\-r {file}
+Recovery mode.
+The swap file is used to recover a crashed editing session.
+The swap file is a file with the same filename as the text file with ".swp"
+appended.
+See ":help recovery".
+.TP
+\-s
+Silent mode. Only when started as "Ex" or when the "\-e" option was given
+before the "\-s" option.
+.TP
+\-s {scriptin}
+The script file {scriptin} is read.
+The characters in the file are interpreted as if you had typed them.
+The same can be done with the command ":source! {scriptin}".
+If the end of the file is reached before the editor exits, further characters
+are read from the keyboard.
+.TP
+\-T {terminal}
+Tells
+.B Vim
+the name of the terminal you are using.
+Only required when the automatic way doesn't work.
+Should be a terminal known to
+.B Vim
+(builtin) or defined in the termcap or terminfo file.
+.TP
+\-u {vimrc}
+Use the commands in the file {vimrc} for initializations.
+All the other initializations are skipped.
+Use this to edit a special kind of files.
+It can also be used to skip all initializations by giving the name "NONE".
+See ":help initialization" within vim for more details.
+.TP
+\-U {gvimrc}
+Use the commands in the file {gvimrc} for GUI initializations.
+All the other GUI initializations are skipped.
+It can also be used to skip all GUI initializations by giving the name "NONE".
+See ":help gui\-init" within vim for more details.
+.TP
+\-V[N]
+Verbose. Give messages about which files are sourced and for reading and
+writing a viminfo file. The optional number N is the value for 'verbose'.
+Default is 10.
+.TP
+\-v
+Start
+.B Vim
+in Vi mode, just like the executable was called "vi". This only has effect
+when the executable is called "ex".
+.TP
+\-w {scriptout}
+All the characters that you type are recorded in the file
+{scriptout}, until you exit
+.B Vim.
+This is useful if you want to create a script file to be used with "vim \-s" or
+":source!".
+If the {scriptout} file exists, characters are appended.
+.TP
+\-W {scriptout}
+Like \-w, but an existing file is overwritten.
+.TP
+\-x
+Use encryption when writing files. Will prompt for a crypt key.
+.TP
+\-X
+Don't connect to the X server. Shortens startup time in a terminal, but the
+window title and clipboard will not be used.
+.TP
+\-y
+Start
+.B Vim
+in easy mode, just like the executable was called "evim" or "eview".
+Makes
+.B Vim
+behave like a click-and-type editor.
+.TP
+\-Z
+Restricted mode. Works like the executable starts with "r".
+.TP
+\-\-
+Denotes the end of the options.
+Arguments after this will be handled as a file name.
+This can be used to edit a filename that starts with a '\-'.
+.TP
+\-\-clean
+Do not use any personal configuration (vimrc, plugins, etc.). Useful to see if
+a problem reproduces with a clean Vim setup.
+.TP
+\-\-echo\-wid
+GTK GUI only: Echo the Window ID on stdout.
+.TP
+\-\-help
+Give a help message and exit, just like "\-h".
+.TP
+\-\-literal
+Take file name arguments literally, do not expand wildcards. This has no
+effect on Unix where the shell expands wildcards.
+.TP
+\-\-noplugin
+Skip loading plugins. Implied by \-u NONE.
+.TP
+\-\-remote
+Connect to a Vim server and make it edit the files given in the rest of the
+arguments. If no server is found a warning is given and the files are edited
+in the current Vim.
+.TP
+\-\-remote\-expr {expr}
+Connect to a Vim server, evaluate {expr} in it and print the result on stdout.
+.TP
+\-\-remote\-send {keys}
+Connect to a Vim server and send {keys} to it.
+.TP
+\-\-remote\-silent
+As \-\-remote, but without the warning when no server is found.
+.TP
+\-\-remote\-wait
+As \-\-remote, but Vim does not exit until the files have been edited.
+.TP
+\-\-remote\-wait\-silent
+As \-\-remote\-wait, but without the warning when no server is found.
+.TP
+\-\-serverlist
+List the names of all Vim servers that can be found.
+.TP
+\-\-servername {name}
+Use {name} as the server name. Used for the current Vim, unless used with a
+\-\-remote argument, then it's the name of the server to connect to.
+.TP
+\-\-socketid {id}
+GTK GUI only: Use the GtkPlug mechanism to run gvim in another window.
+.TP
+\-\-startuptime {file}
+During startup write timing messages to the file {fname}.
+.TP
+\-\-version
+Print version information and exit.
+.SH ON-LINE HELP
+Type ":help" in
+.B Vim
+to get started.
+Type ":help subject" to get help on a specific subject.
+For example: ":help ZZ" to get help for the "ZZ" command.
+Use <Tab> and CTRL-D to complete subjects (":help cmdline\-completion").
+Tags are present to jump from one place to another (sort of hypertext links,
+see ":help").
+All documentation files can be viewed in this way, for example
+":help syntax.txt".
+.SH FILES
+.TP 15
+/usr/local/lib/vim/doc/*.txt
+The
+.B Vim
+documentation files.
+Use ":help doc\-file\-list" to get the complete list.
+.TP
+/usr/local/lib/vim/doc/tags
+The tags file used for finding information in the documentation files.
+.TP
+/usr/local/lib/vim/syntax/syntax.vim
+System wide syntax initializations.
+.TP
+/usr/local/lib/vim/syntax/*.vim
+Syntax files for various languages.
+.TP
+/usr/local/lib/vim/vimrc
+System wide
+.B Vim
+initializations.
+.TP
+~/.vimrc
+Your personal
+.B Vim
+initializations.
+.TP
+/usr/local/lib/vim/gvimrc
+System wide gvim initializations.
+.TP
+~/.gvimrc
+Your personal gvim initializations.
+.TP
+/usr/local/lib/vim/optwin.vim
+Script used for the ":options" command, a nice way to view and set options.
+.TP
+/usr/local/lib/vim/menu.vim
+System wide menu initializations for gvim.
+.TP
+/usr/local/lib/vim/bugreport.vim
+Script to generate a bug report. See ":help bugs".
+.TP
+/usr/local/lib/vim/filetype.vim
+Script to detect the type of a file by its name. See ":help 'filetype'".
+.TP
+/usr/local/lib/vim/scripts.vim
+Script to detect the type of a file by its contents. See ":help 'filetype'".
+.TP
+/usr/local/lib/vim/print/*.ps
+Files used for PostScript printing.
+.PP
+For recent info read the VIM home page:
+.br
+<URL:http://www.vim.org/>
+.SH SEE ALSO
+vimtutor(1)
+.SH AUTHOR
+Most of
+.B Vim
+was made by Bram Moolenaar, with a lot of help from others.
+See ":help credits" in
+.B Vim.
+.br
+.B Vim
+is based on Stevie, worked on by: Tim Thompson,
+Tony Andrews and G.R. (Fred) Walter.
+Although hardly any of the original code remains.
+.SH BUGS
+Probably.
+See ":help todo" for a list of known problems.
+.PP
+Note that a number of things that may be regarded as bugs by some, are in fact
+caused by a too-faithful reproduction of Vi's behaviour.
+And if you think other things are bugs "because Vi does it differently",
+you should take a closer look at the vi_diff.txt file (or type :help
+vi_diff.txt when in Vim).
+Also have a look at the 'compatible' and 'cpoptions' options.