diff options
Diffstat (limited to 'man/nvim.1')
| -rw-r--r-- | man/nvim.1 | 284 |
1 files changed, 119 insertions, 165 deletions
diff --git a/man/nvim.1 b/man/nvim.1 index 2fa3ab8ff5..4d338321c4 100644 --- a/man/nvim.1 +++ b/man/nvim.1 @@ -1,4 +1,4 @@ -.Dd January 28, 2016 +.Dd December 17, 2017 .Dt NVIM 1 .Os .Sh NAME @@ -20,41 +20,52 @@ .Sh DESCRIPTION .Nm is a text editor based on Vim. -To enter commands in -.Nm , -type a colon -.Pq Sq \&: -which is also used in this manual to denote commands. -For more information, consult the on-line help system with the -.Ic :help -command. +Start +.Nm +followed by any number of options and/or files: +.Pp +.Dl nvim [options] [file ...] +.Pp +Commands in +.Nm +begin with colon +.Pq Sq \&: . +Type ":help subject" to get help on a specific subject. +Use <Tab> and CTRL-D to complete subjects (":help cmdline\-completion"). +.Pp +The "quickref" help section is a condensed reference of editor features: +.Dl :help quickref +.Pp +If you are new to Vim/Nvim, start with the 30-minute tutorial: +.Dl :Tutor +.Pp +After installing/updating Nvim, it's a good idea to run the self-check: +.Dl :checkhealth +.Pp .Bl -tag -width Fl .It Ar file ... File(s) to edit. -If none are specified, open an empty buffer. -If multiple files are specified, open one buffer for each file. +Opens one buffer per file. To switch between buffers, use the .Ic :next and .Ic :previous commands. .It Fl -Read text from standard input until +Reads text from standard input until .Dv EOF , -then open a buffer with that text. -Commands are read from standard error, which should be a terminal. +then opens a buffer with that text. +User input is read from standard error, which should be a terminal. +.El +.Sh OPTIONS +.Bl -tag -width Fl .It Fl t Ar tag -The file to edit and the initial cursor position depends on a -tag, a sort of goto label. +Finds .Ar tag -is looked up in the tags file, the associated file becomes the current +in the tags file, the associated file becomes the current file and the associated command is executed. -If -.Ar tag -is a function name, the file containing that function is opened -with the cursor positioned at the start of the function. -See -.Ic :help tag-commands . +Cursor is positioned at the tag location in the file. +.Ic ":help tag-commands" .It Fl q Op Ar errorfile QuickFix mode. Display the first error in @@ -66,96 +77,80 @@ is omitted, the value of the 'errorfile' option is used (defaults to Further errors can be jumped to with the .Ic :cnext command. -See -.Ic :help quickfix . -.It There are a number of other options: +.Ic ":help quickfix" .It Fl - -Interpret all further arguments as files. -Can be used to edit files starting with a hyphen +End of options. +Remaining arguments are treated as literal file names, including filenames starting with hyphen .Pq Sq - . -.It Fl -literal -Interpret filenames literally, that is, do not expand wildcards. -Has no effect on Unix-like systems, where the shell expands wildcards. .It Fl e -Ex mode. -See -.Ic :help Ex-mode . +Ex mode, reading stdin as Ex commands. +.Ic ":help Ex-mode" .It Fl E -Improved Ex mode. -See -.Ic :help gQ . -.It Fl s -Silent mode. -Only takes effect if -.Fl e -or -.Fl E -is specified before it. +Ex mode, reading stdin as text. +.Ic :help Ex-mode +.It Fl es +Silent/batch mode, reading stdin as Ex commands. +.Ic :help silent-mode +.It Fl \&Es +Silent/batch mode, reading stdin as text. +.Ic :help silent-mode .It Fl d Diff mode. Show the difference between two to four files, similar to .Xr sdiff 1 . -See -.Ic :help diff . +.Ic ":help diff" .It Fl R Read-only mode. -Sets the option 'readonly'. +Sets the 'readonly' option. Implies .Fl n . Buffers can still be edited, but cannot be written to disk if already associated with a file. -To overwrite a file, add an exclamation mark to the needed Ex command, such as +To overwrite a file, add an exclamation mark to the relevant Ex command, such as .Ic :w! . -See -.Ic :help 'readonly' . +.Ic ":help 'readonly'" .It Fl Z Restricted mode. Disable commands that make use of an external shell. .It Fl m -Disable file modifications. -Unsets the option 'write'. +Resets the 'write' option, to disable file modifications. Writing to a file is disabled, but buffers can still be modified. .It Fl M -Disable file and buffer modifications. -Unsets the options 'write' and 'modifiable'. -Note that these options can be set to re-enable making modifications. +Resets the 'write' and 'modifiable' options, to disable file and buffer +modifications. .It Fl b Binary mode. -See -.Ic :help edit-binary . +.Ic ":help edit-binary" .It Fl l Lisp mode. -Sets the options 'lisp' and 'showmatch'. +Sets the 'lisp' and 'showmatch' options. .It Fl A Arabic mode. -Sets the option 'arabic'. -.It Fl F -Farsi mode. -Sets the options 'fkmap' and 'rightleft'. +Sets the 'arabic' option. .It Fl H Hebrew mode. -Sets the options 'hkmap' and 'rightleft'. +Sets the 'hkmap' and 'rightleft' options. .It Fl V Ns Oo Ar N Oc Ns Op Ar file Verbose mode. -Print messages about which files are being sourced and for reading and -writing a ShaDa file. +Prints debug messages. .Ar N -is the value for the 'verbose' option; defaults to -.Cm 10 -if omitted. +is the 'verbose' level, defaults to +.Cm 10 . If .Ar file is specified, append messages to .Ar file instead of printing them. +.Ic ":help 'verbose'" .It Fl D -Debugging mode. +Debug mode for VimL (Vim script). Started when executing the first command from a script. +:help debug-mode .It Fl n Disable the use of swap files. -Sets the option 'updatecount' to +Sets the 'updatecount' option to .Cm 0 . -Can be useful for editing file(s) on a slow medium. +Can be useful for editing files on a slow medium. .It Fl r Op Ar file Recovery mode. If @@ -168,41 +163,38 @@ is used to recover a crashed session. The swap file has the same name as the file it's associated with, but with .Sq .swp appended. -See -.Ic :help recovery . +.Ic ":help recovery" .It Fl L Op Ar file Alias for .Fl r . .It Fl u Ar vimrc Use .Ar vimrc -instead of the default of +instead of the default .Pa ~/.config/nvim/init.vim . If .Ar vimrc is .Cm NORC , -do not load any initialization files (excluding plugins), +do not load any initialization files (except plugins), and do not attempt to parse environment variables. If .Ar vimrc is .Cm NONE , loading plugins is also skipped. -See -.Ic :help initialization . +.Ic ":help initialization" .It Fl i Ar shada Use .Ar shada -instead of the default of +instead of the default .Pa ~/.local/share/nvim/shada/main.shada . If .Ar shada is .Cm NONE , do not read or write a ShaDa file. -See -.Ic :help shada . +.Ic ":help shada" .It Fl -noplugin Skip loading plugins. Implied by @@ -233,7 +225,6 @@ For the first file, position the cursor on line If .Ar linenum is omitted, position the cursor on the last line of the file. -Note that .Cm +5 and .Cm -c 5 @@ -246,8 +237,7 @@ For the first file, position the cursor on the first occurrence of .Ar pattern . If .Ar pattern -is omitted, the most recently used search pattern is used (if there is one). -Note that +is omitted, the most recent search pattern is used (if any). .Cm +/foo and .Cm -c /foo @@ -257,21 +247,15 @@ and .Ic :/foo inside .Nm . -See -.Ic :help search-pattern . -.It Fl c Ar command +.Ic ":help search-pattern" +.It \fB\+\fR\fI\,command\/\fR , Fl c Ar command Execute .Ar command after reading the first file. -Up to 10 instances of -.Fl c -or -.Cm + -can be used. -Note that -.Qq Cm +set si +Up to 10 instances allowed. +.Qq Cm +foo and -.Cm -c \(dqset si\(dq +.Cm -c \(dqfoo\(dq are equivalent. .It Fl -cmd Ar command Like @@ -292,16 +276,15 @@ cannot start with a hyphen .Pq Sq - . If .Ar session -is omitted, then -.Pa Session.vim , -if found, is used. -See -.Ic :help session-file . +is omitted then +.Pa Session.vim +is used, if found. +.Ic ":help session-file" .It Fl s Ar scriptin Read normal mode commands from .Ar scriptin . The same can be done with the command -.Ic :source! scriptin . +.Ic ":source! scriptin" . If the end of the file is reached before .Nm exits, further characters are read from the keyboard. @@ -325,10 +308,14 @@ Can be used to diagnose slow startup times. Dump API metadata serialized to msgpack and exit. .It Fl -embed Use standard input and standard output as a msgpack-rpc channel. -Implies -.Fl -headless . +:help --embed .It Fl -headless -Do not start a user interface. +Do not start a UI. +When supplied with --embed this implies that the embedding application does not intend to (immediately) start a UI. +Also useful for "scraping" messages in a pipe. +:help --headless +.It Fl -listen Ar address +Start RPC server on this pipe or TCP socket. .It Fl h , -help Print usage information and exit. .It Fl v , -version @@ -336,102 +323,69 @@ Print version information and exit. .El .Sh ENVIRONMENT .Bl -tag -width Fl +.It Ev NVIM_LOG_FILE +Low-level log file, usually found at ~/.local/share/nvim/log. +:help $NVIM_LOG_FILE .It Ev VIM -Used to locate various user files, such as the user's init.vim. +Used to locate user files, such as init.vim. +System-dependent. +:help $VIM .It Ev VIMRUNTIME -Used to locate run time files, such as on-line documentation and -syntax highlighting definitions. +Used to locate runtime files (documentation, syntax highlighting, etc.). .It Ev XDG_CONFIG_HOME -Path to use for the user-local configuration directory, see +Path to the user-local configuration directory, see .Sx FILES . Defaults to -.Pa ~/.config -if not set. +.Pa ~/.config . +:help xdg .It Ev XDG_DATA_HOME Like .Ev XDG_CONFIG_HOME , but used to store data not generally edited by the user, namely swap, backup, and ShaDa files. Defaults to -.Pa ~/.local/share/nvim -if not set. +.Pa ~/.local/share . +:help xdg .It Ev VIMINIT -A string of Ex commands to be executed at startup. -For example, the command to quit is -.Ic :q , -so to have -.Nm -quit immediately after starting, set -.Ev VIMINIT -to -.Cm q . -See -.Ic :help VIMINIT . +Ex commands to be executed at startup. +.Ic ":help VIMINIT" .It Ev SHELL -Used to set the 'shell' option, which determines the shell used by the -.Ic :terminal -command. -.It Ev NVIM_TUI_ENABLE_CURSOR_SHAPE -If defined, change the cursor shape to a vertical bar while in insert mode. -Requires that the host terminal supports the DECSCUSR CSI escape sequence. -Has no effect in GUIs. -.Pp -Depending on the terminal emulator, using this option with -.Nm -under -.Xr tmux 1 -might require adding the following to -.Pa ~/.tmux.conf : -.Bd -literal -offset indent -set -ga terminal-overrides ',*:Ss=\eE[%p1%d q:Se=\eE[2 q' -.Ed -.Pp -See -.Ic terminal-overrides -in the -.Xr tmux 1 -manual page for more information. +Used to initialize the 'shell' option, which decides the default shell used by +features like +.Ic :terminal , +.Ic :! , and +.Ic system() . .El .Sh FILES .Bl -tag -width "~/.config/nvim/init.vim" .It Pa ~/.config/nvim/init.vim -The user-local +User-local .Nm configuration file. -See -.Ev XDG_CONFIG_HOME -above. .It Pa ~/.config/nvim -The user-local +User-local .Nm configuration directory. -See -.Ev XDG_CONFIG_HOME -above. +See also +.Ev XDG_CONFIG_HOME . .It Pa $VIM/sysinit.vim -The system-global +System-global .Nm configuration file. .It Pa /usr/local/share/nvim -The system-global +System-global .Nm runtime directory. .El .Sh AUTHORS -.Nm -was started by -.An Thiago de Arruda , -with a lot of help from others. -.Pp +Nvim was started by +.An Thiago de Arruda . Most of Vim was written by .An -nosplit -.An Bram Moolenaar , -with a lot of help from others. -See -.Ic :help credits . -.Pp +.An Bram Moolenaar . Vim is based on Stevie, worked on by .An Tim Thompson , .An Tony Andrews , and .An G.R. (Fred) Walter . +.Ic ":help credits" |