GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-16 01:01:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #8902 'doc'

Browse Source
This commit is contained in:
Justin M. Keyes
2018-10-12 17:44:44 +02:00
committed by GitHub
parent fb043f8ea3 e52293757a
commit 15a71338e3
20 changed files with 409 additions and 574 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
MAINTAIN.md Normal file
View File

@ -0,0 +1,48 @@
Maintaining the Neovim project
==============================
Notes on maintaining the Neovim project.
See also: https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt
Ticket Triage
-------------
In practice we haven't found a meaningful way to forecast more precisely than
"next" and "after next". That means there are usually one or two (at most)
planned milestones:
- Next bugfix-release (1.0.x)
- Next feature-release (1.x.0)
The forecasting problem might be solved with an explicit priority system (like
Bram's todo.txt). Meanwhile the Neovim priority system is defined by:
- PRs nearing completion (RDY).
- Issue labels. E.g. the +plan label increases the ticket's priority merely for
having a plan written down: it is _closer to completion_ than tickets without
a plan.
- Comment activity or new information.
Anything that isn't in the next milestone, and doesn't have a RDY PR ... is
just not something you care very much about, by construction. Post-release you
can review open issues, but chances are your next milestone is already getting
full :)
Release Policy
--------------
The goal is "early and often".
Up to now we use only one branch, the `master` branch.
- If `master` is unstable we don't release.
- If the last release has a major bug, we:
1. Fix the bug on `master`.
2. Disable or remove any known risks present on `master`.
3. Cut a release from `master`.
This is a bit silly, but it works ok. And it keeps `master` from biting off
more feature-creep than it can chew.
See also: https://github.com/neovim/neovim/issues/862

123
man/nvim.1
View File

@ -20,14 +20,17 @@
.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 online help with the
.Ic :help
command.
Commands in this program start with colon
.Pq Sq \&: .
Use the :help command to get help, for example ":help quickref"
is a condensed overview of almost all commands.
.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.
@ -42,7 +45,7 @@ commands.
Read 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.
User input is read from standard error, which should be a terminal.
.It Fl t Ar tag
The file to edit and the initial cursor position depends on a
tag, a sort of goto label.
@ -53,8 +56,7 @@ 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" .
.Ic ":help tag-commands"
.It Fl q Op Ar errorfile
QuickFix mode.
Display the first error in
@ -66,31 +68,29 @@ 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" .
.Ic ":help quickfix"
.It There are a number of other options:
.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 e
Ex mode. Reads stdin as Ex commands.
See
.Ic ":help Ex-mode" .
Ex mode, reading stdin as Ex commands.
.Ic ":help Ex-mode"
.It Fl E
Ex mode. Reads stdin as text.
See
.Ic :help gQ .
Ex mode, reading stdin as text.
.Ic :help Ex-mode
.It Fl es
Silent (batch) mode. Reads stdin as Ex commands.
Silent/batch mode, reading stdin as Ex commands.
.Ic :help silent-mode
.It Fl \&Es
Silent (batch) mode. Reads stdin as text.
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 'readonly' option.
@ -100,8 +100,7 @@ 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 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.
@ -113,8 +112,7 @@ 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 'lisp' and 'showmatch' options.
@ -126,19 +124,20 @@ Hebrew mode.
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 'verbose' level; defaults to
.Cm 10.
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 'updatecount' option to
@ -156,8 +155,7 @@ 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 .
@ -177,8 +175,7 @@ If
is
.Cm NONE ,
loading plugins is also skipped.
See
.Ic ":help initialization" .
.Ic ":help initialization"
.It Fl i Ar shada
Use
.Ar shada
@ -189,8 +186,7 @@ If
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
@ -243,17 +239,12 @@ 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.
Up to 10 instances allowed.
.Qq Cm +foo
and
.Cm -c \(dqfoo\(dq
@ -280,8 +271,7 @@ If
is omitted then
.Pa Session.vim
is used, if found.
See
.Ic ":help session-file" .
.Ic ":help session-file"
.It Fl s Ar scriptin
Read normal mode commands from
.Ar scriptin .
@ -310,10 +300,12 @@ 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
@ -324,11 +316,12 @@ Print version information and exit.
.Sh ENVIRONMENT
.Bl -tag -width Fl
.It Ev NVIM_LOG_FILE
Low-level log file, usually found at ~/.local/share/nvim/log. See :help
$NVIM_LOG_FILE.
Low-level log file, usually found at ~/.local/share/nvim/log.
:help $NVIM_LOG_FILE
.It Ev VIM
Used to locate user files, such as init.vim.
System-dependent, see :help $VIM.
System-dependent.
:help $VIM
.It Ev VIMRUNTIME
Used to locate runtime files (documentation, syntax highlighting, etc.).
.It Ev XDG_CONFIG_HOME
@ -336,7 +329,7 @@ Path to the user-local configuration directory, see
.Sx FILES .
Defaults to
.Pa ~/.config .
See :help xdg.
:help xdg
.It Ev XDG_DATA_HOME
Like
.Ev XDG_CONFIG_HOME ,
@ -344,19 +337,10 @@ but used to store data not generally edited by the user,
namely swap, backup, and ShaDa files.
Defaults to
.Pa ~/.local/share .
See :help xdg.
:help xdg
.It Ev VIMINIT
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" .
.Ic ":help VIMINIT"
.It Ev SHELL
Used to initialize the 'shell' option, which decides the default shell used by
features like
@ -391,10 +375,9 @@ Nvim was started by
Most of Vim was written by
.An -nosplit
.An Bram Moolenaar .
See
.Ic ":help credits" .
Vim is based on Stevie, worked on by
.An Tim Thompson ,
.An Tony Andrews ,
and
.An G.R. (Fred) Walter .
.Ic ":help credits"

27
runtime/doc/api.txt
View File

@ -1120,6 +1120,33 @@ nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
{line_end} End of range of lines to clear (exclusive)
or -1 to clear to end of file.
*nvim_buf_set_virtual_text()*
nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
{opts})
Set the virtual text (annotation) for a buffer line.
By default (and currently the only option) the text will be
placed after the buffer text. Virtual text will never cause
reflow, rather virtual text will be truncated at the end of
the screen line. The virtual text will begin after one cell to
the right of the ordinary text, this will contain the |lcs-
eol| char if set, otherwise just be a space.
Parameters: ~
{buffer} Buffer handle
{src_id} Source group to use or 0 to use a new group, or
-1 for a ungrouped annotation
{line} Line to annotate with virtual text (zero-
indexed)
{chunks} A list of [text, hl_group] arrays, each
representing a text chunk with specified
highlight. `hl_group` element can be omitted for
no highlight.
{opts} Optional parameters. Currently not used.
Return: ~
The src_id that was used
==============================================================================
Window Functions *api-window*

18
runtime/doc/channel.txt
View File

@ -32,8 +32,13 @@ Channels support multiple modes or protocols. In the most basic
mode of operation, raw bytes are read and written to the channel.
The |rpc| protocol, based on the msgpack-rpc standard, enables nvim and the
process at the other end to send remote calls and events to each other.
Additionally, the builtin |terminal-emulator|, is implemented on top of PTY
channels.
The builtin |terminal-emulator| is also implemented on top of PTY channels.
Channel Id *channel-id*
Each channel is identified by an integer id, unique for the life of the
current Nvim session. Functions like |stdioopen()| return channel ids;
functions like |chansend()| consume channel ids.
==============================================================================
2. Reading and writing raw bytes *channel-bytes*
@ -64,8 +69,8 @@ be raised.
- The arguments passed to the callback function are:
0: The channel id
1: the raw data read from the channel, formatted as a |readfile()|-style
0: |channel-id|
1: Raw data read from the channel, formatted as a |readfile()|-style
list. If EOF occured, a single empty string `['']` will be passed in.
Note that the items in this list do not directly correspond to actual
lines in the output. See |channel-lines|
@ -150,9 +155,8 @@ Nvim uses stdin/stdout to interact with the user over the terminal interface
(TUI). If Nvim is |--headless| the TUI is not started and stdin/stdout can be
used as a channel. See also |--embed|.
Call |stdioopen()| during |startup| to open the stdio channel as channel-id 1.
Nvim's stderr is always available as channel-id 2 (|v:stderr| to be explicit),
a write-only bytes channel.
Call |stdioopen()| during |startup| to open the stdio channel as |channel-id| 1.
Nvim's stderr is always available as |v:stderr|, a write-only bytes channel.
Example: >
func! OnEvent(id, data, event)

63
runtime/doc/develop.txt
View File

@ -4,7 +4,7 @@
NVIM REFERENCE MANUAL
Development of Nvim. *development*
Development of Nvim *development*
Nvim is open source software. Everybody is encouraged to contribute.
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
@ -23,37 +23,17 @@ Note that some items conflict; this is intentional. A balance must be found.
NVIM IS... IMPROVED *design-improved*
The IMproved bits of Vim should make it a better Vi, without becoming a
completely different editor. Extensions are done with a "Vi spirit".
- Use the keyboard as much as feasible. The mouse requires a third hand,
which we don't have. Many terminals don't have a mouse.
- When the mouse is used anyway, avoid the need to switch back to the
keyboard. Avoid mixing mouse and keyboard handling.
- Add commands and options in a consistent way. Otherwise people will have a
hard time finding and remembering them. Keep in mind that more commands and
options will be added later.
The Neo bits of Nvim should make it a better Vim, without becoming a
completely different editor.
- In matters of taste, prefer Vim/Unix tradition. If there is no relevant
Vim/Unix tradition, consider the "common case".
- A feature that people do not know about is a useless feature. Don't add
obscure features, or at least add hints in documentation that they exist.
- Minimize using CTRL and other modifiers, they are more difficult to type.
- There are many first-time and inexperienced Vim users. Make it easy for
them to start using Vim and learn more over time.
- There is no limit to the features that can be added. Selecting new features
is based on (1) what users ask for, (2) how much effort it takes to
implement and (3) someone actually implementing it.
NVIM IS... MULTI PLATFORM *design-multi-platform*
Vim tries to help as many users on as many platforms as possible.
- Support many kinds of terminals. The minimal demands are cursor positioning
and clear-screen. Commands should only use key strokes that most keyboards
have. Support all the keys on the keyboard for mapping.
- Support many platforms. A condition is that there is someone willing to do
Vim development on that platform, and it doesn't mean messing up the code.
- Support many compilers and libraries. Not everybody is able or allowed to
install another compiler or GUI library.
- People switch from one platform to another, and from GUI to terminal
version. Features should be present in all versions.
- Backwards compatibility is a feature. The RPC API in particular should
never break.
NVIM IS... WELL DOCUMENTED *design-documented*
@ -90,15 +70,6 @@ NVIM IS... MAINTAINABLE *design-maintain*
knowledge spread to other parts of the code.
NVIM IS... FLEXIBLE *design-flexible*
Vim should make it easy for users to work in their preferred styles rather
than coercing its users into particular patterns of work. This can be for
items with a large impact or for details. The defaults are carefully chosen
such that most users will enjoy using Vim as it is. Commands and options can
be used to adjust Vim to the desire of the user and its environment.
NVIM IS... NOT *design-not*
Nvim is not an operating system; instead it should be composed with other
@ -239,7 +210,14 @@ Example: `nvim_buf_changedtick_event`.
API-CLIENT *dev-api-client*
Standard Features ~
- Clients should call |nvim_set_client_info()| after connecting, so users and
plugins can detect the client by handling the |ChanInfo| event. This
avoids the need for special variables or other client hints.
Package Naming ~
API client packages should NOT be named something ambiguous like "neovim" or
"python-client". Use "nvim" as a prefix/suffix to some other identifier
following ecosystem conventions.
@ -255,10 +233,11 @@ Examples of API-client package names:
BAD: neovim
Implementation ~
Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is
small, efficient, and C89-compatible. It can be easily inlined in your
C project source, too. https://github.com/libmpack/libmpack/
Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is
small (can be inlined into your C/C++ project) and efficient (no allocations).
It also implements msgpack-RPC.
https://github.com/libmpack/libmpack/
EXTERNAL UI *dev-ui*
@ -267,7 +246,13 @@ versions of Nvim may add new items to existing events. The API is strongly
backwards-compatible, but clients must not break if new (optional) fields are
added to existing events.
Standard Features ~
External UIs are expected to implement these common features:
- Call |nvim_set_client_info()| after connecting, so users and plugins can
detect the UI by handling the |ChanInfo| event. This avoids the need for
special variables and UI-specific config files (gvimrc, macvimrc, …).
- Cursor style (shape, color) should conform to the 'guicursor' properties
delivered with the mode_info_set UI event.
- Send the ALT/META ("Option" on macOS) key as a |<M-| chord.

52
runtime/doc/eval.txt
View File

@ -1817,11 +1817,11 @@ v:shell_error Result of the last shell command. When non-zero, the last
v:statusmsg Last given status message. It's allowed to set this variable.
*v:stderr* *stderr-variable*
v:stderr Channel id for stderr. Unlike stdin and stdout (see
|stdioopen()|), stderr is always open for writing. This channel
ID is always 2, but this variable can be used to be explicit.
Example: >
:call chansend(v:stderr, "something bad happened\n")
v:stderr |channel-id| corresponding to stderr. The value is always 2;
use this variable to make your code more descriptive.
Unlike stdin and stdout (see |stdioopen()|), stderr is always
open for writing. Example: >
:call chansend(v:stderr, "error: toaster empty\n")
<
*v:swapname* *swapname-variable*
v:swapname Only valid when executing |SwapExists| autocommands: Name of
@ -5024,11 +5024,10 @@ jobstart({cmd}[, {opts}]) *jobstart()*
<
Returns |job-id| on success, 0 on invalid arguments (or job
table is full), -1 if {cmd}[0] or 'shell' is not executable.
For communication over the job's stdio, it is represented as a
|channel|, and a channel ID is returned on success. Use
|chansend()| (or |rpcnotify()| and |rpcrequest()| if "rpc" option
was used) to send data to stdin and |chanclose()| to close stdio
streams without stopping the job explicitly.
The returned job-id is a valid |channel-id| representing the
job's stdio streams. Use |chansend()| (or |rpcnotify()| and
|rpcrequest()| if "rpc" was enabled) to send data to stdin and
|chanclose()| to close the streams without stopping the job.
See |job-control| and |RPC|.
@ -5082,18 +5081,24 @@ jobstop({id}) *jobstop()*
See |job-control|.
jobwait({ids}[, {timeout}]) *jobwait()*
Wait for a set of jobs to finish. The {ids} argument is a list
of |job-id|s to wait for. {timeout} is the maximum number of
milliseconds to wait. During jobwait(), callbacks for jobs not
in the {ids} list may be invoked. The screen will not redraw
unless |:redraw| is invoked by a callback.
Wait for a set of jobs to complete.
{ids} is a list of |job-id|s to wait for.
{timeout} is the maximum number of milliseconds to wait.
{timeout} of zero can be used to check if a job-id is valid,
without waiting.
During jobwait() callbacks for jobs not in the {ids} list may
be invoked. The screen will not redraw unless |:redraw| is
invoked by a callback.
Returns a list of len({ids}) integers, where each integer is
the wait-result of the corresponding job. Each wait-result is:
Job exit-code, if the job exited
-1 if the wait timed out for the job
-2 if the job was interrupted
-3 if the |job-id| is invalid.
the wait-result of the corresponding job. Each wait-result is
one of the following:
* Exit-code, if the job exited
* -1 if the timeout was exceeded
* -2 if the job was interrupted
* -3 if the |job-id| is invalid
join({list} [, {sep}]) *join()*
Join the items in {list} together into one String.
@ -7325,8 +7330,8 @@ stdpath({what}) *stdpath()* *E6100*
directories.
{what} Type Description ~
cache String Cache directory. Useful for plugins
that need temporary files to work.
cache String Cache directory. Arbitrary temporary
storage for plugins, etc.
config String User configuration directory. The
|init.vim| is stored here.
config_dirs List Additional configuration directories.
@ -7334,6 +7339,9 @@ stdpath({what}) *stdpath()* *E6100*
is stored here.
data_dirs List Additional data directories.
Example: >
:echo stdpath("config")
str2float({expr}) *str2float()*
Convert String {expr} to a Float. This mostly works the same

4
runtime/doc/filetype.txt
View File

@ -152,8 +152,8 @@ file. It will be overwritten when installing a new version of Vim.
A. If you want to overrule all default file type checks.
This works by writing one file for each filetype. The disadvantage is that
means there can be many files. The advantage is that you can simply drop
this file in the right directory to make it work.
there can be many files. The advantage is that you can simply drop this
file in the right directory to make it work.
*ftdetect*
1. Create your user runtime directory. You would normally use the first
item of the 'runtimepath' option. Then create the directory "ftdetect"

236
runtime/doc/gui.txt
View File

@ -9,7 +9,7 @@ Vim's Graphical User Interface *gui* *GUI*
Type |gO| to see the table of contents.
==============================================================================
1. Starting the GUI *gui-start* *E229* *E233*
Starting the GUI *gui-start* *E229* *E233*
*ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC*
The gvimrc file is where GUI-specific startup commands should be placed. It
@ -87,7 +87,7 @@ and only the first one that is found is read.
Obsolete, use ":set lines=11 columns=22".
==============================================================================
2. Scrollbars *gui-scrollbars*
Scrollbars *gui-scrollbars*
There are vertical scrollbars and a horizontal scrollbar. You may
configure which ones appear with the 'guioptions' option.
@ -155,167 +155,7 @@ include the 'h' flag in 'guioptions'. Then the scrolling is limited by the
text of the current cursor line.
==============================================================================
3. Mouse Control *gui-mouse*
The mouse only works if the appropriate flag in the 'mouse' option is set.
When the GUI is switched on, and 'mouse' wasn't set yet, the 'mouse' option is
automatically set to "a", enabling it for all modes except for the
|hit-enter| prompt. If you don't want this, a good place to change the
'mouse' option is the "gvimrc" file.
Other options that are relevant:
'mousefocus' window focus follows mouse pointer |gui-mouse-focus|
'mousemodel' what mouse button does which action
'mousehide' hide mouse pointer while typing text
'selectmode' whether to start Select mode or Visual mode
A quick way to set these is with the ":behave" command.
*:behave* *:be*
:be[have] {model} Set behavior for mouse and selection. Valid
arguments are:
mswin MS-Windows behavior
xterm Xterm behavior
Using ":behave" changes these options:
option mswin xterm ~
'selectmode' "mouse,key" ""
'mousemodel' "popup" "extend"
'keymodel' "startsel,stopsel" ""
'selection' "exclusive" "inclusive"
In the $VIMRUNTIME directory, there is a script called |mswin.vim|, which will
also map a few keys to the MS-Windows cut/copy/paste commands. This is NOT
compatible, since it uses the CTRL-V, CTRL-X and CTRL-C keys. If you don't
mind, use this command: >
:so $VIMRUNTIME/mswin.vim
For scrolling with a wheel on a mouse, see |scroll-mouse-wheel|.
3.1 Moving Cursor with Mouse *gui-mouse-move*
Click the left mouse button somewhere in a text buffer where you want the
cursor to go, and it does!
This works in when 'mouse' contains ~
Normal mode 'n' or 'a'
Visual mode 'v' or 'a'
Insert mode 'i' or 'a'
Select mode is handled like Visual mode.
You may use this with an operator such as 'd' to delete text from the current
cursor position to the position you point to with the mouse. That is, you hit
'd' and then click the mouse somewhere.
*gui-mouse-focus*
The 'mousefocus' option can be set to make the keyboard focus follow the
mouse pointer. This means that the window where the mouse pointer is, is the
active window. Warning: this doesn't work very well when using a menu,
because the menu command will always be applied to the top window.
If you are on the ':' line (or '/' or '?'), then clicking the left or right
mouse button will position the cursor on the ':' line (if 'mouse' contains
'c', 'a' or 'A').
In any situation the middle mouse button may be clicked to paste the current
selection.
3.2 Selection with Mouse *gui-mouse-select*
The mouse can be used to start a selection. How depends on the 'mousemodel'
option:
'mousemodel' is "extend": use the right mouse button
'mousemodel' is "popup": use the left mouse button, while keeping the Shift
key pressed.
If there was no selection yet, this starts a selection from the old cursor
position to the position pointed to with the mouse. If there already is a
selection then the closest end will be extended.
If 'selectmode' contains "mouse", then the selection will be in Select mode.
This means that typing normal text will replace the selection. See
|Select-mode|. Otherwise, the selection will be in Visual mode.
Double clicking may be done to make the selection word-wise, triple clicking
makes it line-wise, and quadruple clicking makes it rectangular block-wise.
See |gui-selections| on how the selection is used.
3.3 Other Text Selection with Mouse *gui-mouse-modeless*
*modeless-selection*
A different kind of selection is used when:
- in Command-line mode
- in the Command-line window and pointing in another window
- at the |hit-enter| prompt
- whenever the current mode is not in the 'mouse' option
- when holding the CTRL and SHIFT keys in the GUI
Since Vim continues like the selection isn't there, and there is no mode
associated with the selection, this is called modeless selection. Any text in
the Vim window can be selected. Select the text by pressing the left mouse
button at the start, drag to the end and release. To extend the selection,
use the right mouse button when 'mousemodel' is "extend", or the left mouse
button with the shift key pressed when 'mousemodel' is "popup".
The selection is removed when the selected text is scrolled or changed.
On the command line CTRL-Y can be used to copy the selection into the
clipboard. To do this from Insert mode, use CTRL-O : CTRL-Y <CR>. When
'guioptions' contains a or A (default on X11), the selection is automatically
copied to the "* register.
The middle mouse button can then paste the text. On non-X11 systems, you can
use CTRL-R +.
3.4 Using Mouse on Status Lines *gui-mouse-status*
Clicking the left or right mouse button on the status line below a Vim
window makes that window the current window. This actually happens on button
release (to be able to distinguish a click from a drag action).
With the left mouse button a status line can be dragged up and down, thus
resizing the windows above and below it. This does not change window focus.
The same can be used on the vertical separator: click to give the window left
of it focus, drag left and right to make windows wider and narrower.
3.5 Various Mouse Clicks *gui-mouse-various*
<S-LeftMouse> Search forward for the word under the mouse click.
When 'mousemodel' is "popup" this starts or extends a
selection.
<S-RightMouse> Search backward for the word under the mouse click.
<C-LeftMouse> Jump to the tag name under the mouse click.
<C-RightMouse> Jump back to position before the previous tag jump
(same as "CTRL-T")
3.6 Mouse Mappings *gui-mouse-mapping*
The mouse events, complete with modifiers, may be mapped. Eg: >
:map <S-LeftMouse> <RightMouse>
:map <S-LeftDrag> <RightDrag>
:map <S-LeftRelease> <RightRelease>
:map <2-S-LeftMouse> <2-RightMouse>
:map <2-S-LeftDrag> <2-RightDrag>
:map <2-S-LeftRelease> <2-RightRelease>
:map <3-S-LeftMouse> <3-RightMouse>
:map <3-S-LeftDrag> <3-RightDrag>
:map <3-S-LeftRelease> <3-RightRelease>
:map <4-S-LeftMouse> <4-RightMouse>
:map <4-S-LeftDrag> <4-RightDrag>
:map <4-S-LeftRelease> <4-RightRelease>
These mappings make selection work the way it probably should in a Motif
application, with shift-left mouse allowing for extending the visual area
rather than the right mouse button.
Mouse mapping with modifiers does not work for modeless selection.
3.7 Drag and drop *drag-n-drop*
Drag and drop *drag-n-drop*
You can drag and drop one or more files into the Vim window, where they will
be opened as if a |:drop| command was used.
@ -334,47 +174,12 @@ names with any Ex command. Special characters (space, tab, double quote and
'|'; backslash on non-MS-Windows systems) will be escaped.
==============================================================================
4. Making GUI Selections *gui-selections*
*quotestar*
You may make selections with the mouse (see |gui-mouse-select|), or by using
Vim's Visual mode (see |v|). If 'a' is present in 'guioptions', then
whenever a selection is started (Visual or Select mode), or when the selection
is changed, Vim becomes the owner of the windowing system's primary selection
(on MS-Windows the |clipboard| is used).
*primary-selection*
There is a special register for storing this selection, it is the "*
register. Nothing is put in here unless the information about what text is
selected is about to change (e.g. with a left mouse click somewhere), or when
another application wants to paste the selected text. Then the text is put
in the "* register. For example, to cut a line and make it the current
selection/put it on the clipboard: >
"*dd
Similarly, when you want to paste a selection from another application, e.g.,
by clicking the middle mouse button, the selection is put in the "* register
first, and then 'put' like any other register. For example, to put the
selection (contents of the clipboard): >
"*p
Note that when pasting text from one Vim into another separate Vim, the type
of selection (character, line, or block) will also be copied. For other
applications the type is always character.
When the "unnamed" string is included in the 'clipboard' option, the unnamed
register is the same as the "* register. Thus you can yank to and paste the
selection without prepending "* to commands.
==============================================================================
5. Menus *menus*
Menus *menus*
For an introduction see |usr_42.txt| in the user manual.
5.1 Using Menus *using-menus*
Using Menus *using-menus*
Basically, menus can be used just like mappings. You can define your own
menus, as many as you like.
@ -420,7 +225,7 @@ Pressing <F4> will start the menu. You can now use the cursor keys to select
a menu entry. Hit <Enter> to execute it. Hit <Esc> if you want to cancel.
This does require the |+menu| feature enabled at compile time.
5.2 Creating New Menus *creating-menus*
Creating New Menus *creating-menus*
*:me* *:menu* *:noreme* *:noremenu*
*:am* *:amenu* *:an* *:anoremenu*
@ -662,7 +467,7 @@ when the right mouse button is pressed, if 'mousemodel' is set to popup or
popup_setpos.
5.3 Showing What Menus Are Mapped To *showing-menus*
Showing What Menus Are Mapped To *showing-menus*
To see what an existing menu is mapped to, use just one argument after the
menu commands (just like you would with the ":map" commands). If the menu
@ -680,7 +485,7 @@ Note that hitting <Tab> while entering a menu name after a menu command may
be used to complete the name of the menu item.
5.4 Executing Menus *execute-menus*
Executing Menus *execute-menus*
*:em* *:emenu* *E334* *E335*
:[range]em[enu] {menu} Execute {menu} from the command line.
@ -700,7 +505,7 @@ When using a range, if the lines match with '<,'>, then the menu is executed
using the last visual selection.
5.5 Deleting Menus *delete-menus*
Deleting Menus *delete-menus*
*:unme* *:unmenu*
*:aun* *:aunmenu*
@ -730,7 +535,7 @@ If you want to get rid of the menu bar: >
:set guioptions-=m
5.6 Disabling Menus *disable-menus*
Disabling Menus *disable-menus*
*:menu-disable* *:menu-enable*
If you do not want to remove a menu, but disable it for a moment, this can be
@ -746,7 +551,7 @@ When the argument is "*", all menus are affected. Otherwise the given menu
name and all existing submenus below it are affected.
5.7 Examples for Menus *menu-examples*
Examples for Menus *menu-examples*
Here is an example on how to add menu items with menu's! You can add a menu
item for the keyword under the cursor. The register "z" is used. >
@ -763,7 +568,7 @@ mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is
the <CR> key. |<>|)
5.8 Tooltips & Menu tips
Tooltips & Menu tips
See section |42.4| in the user manual.
@ -833,22 +638,5 @@ This creates a popup menu that doesn't exist on the main menu-bar.
Note that a menu that starts with ']' will not be displayed.
==============================================================================
6. Extras *gui-extras*
This section describes other features which are related to the GUI.
- With the GUI, there is no wait for one second after hitting escape, because
the key codes don't start with <Esc>.
- Typing ^V followed by a special key in the GUI will insert "<Key>", since
the internal string used is meaningless. Modifiers may also be held down to
get "<Modifiers-Key>".
- In the GUI, the modifiers SHIFT, CTRL, and ALT (or META) may be used within
mappings of special keys and mouse events. E.g.: :map <M-LeftDrag> <LeftDrag>
- In the GUI, several normal keys may have modifiers in mappings etc, these
are <Space>, <Tab>, <NL>, <CR>, <Esc>.
vim:tw=78:sw=4:ts=8:ft=help:norl:

2
runtime/doc/if_pyth.txt
View File

@ -118,7 +118,7 @@ Instead, put the Python command in a function and call that function:
Note that "EOF" must be at the start of the line.
==============================================================================
2. The vim module *python-vim*
2. The vim module *python-vim* *python2*
Python code gets all of its access to vim (with one exception - see
|python-output| below) via the "vim" module. The vim module implements two

10
runtime/doc/job_control.txt
View File

@ -16,12 +16,14 @@ Concepts
Job Id *job-id*
When a job starts it is assigned a number, unique for the life of the current
Nvim session. Functions like |jobstart()| return job ids. Functions like
Each job is identified by an integer id, unique for the life of the current
Nvim session. Each job-id is a valid |channel-id|: they share the same "key
space". Functions like |jobstart()| return job ids; functions like
|jobsend()|, |jobstop()|, |rpcnotify()|, and |rpcrequest()| take job ids.
The job's stdio streams are represented as a |channel|. It is possible to send
and recieve raw bytes, or use |msgpack-rpc|.
Job stdio streams form a |channel| which can send and receive raw bytes or
|msgpack-rpc| messages.
==============================================================================
Usage *job-control-usage*

27
runtime/doc/nvim.txt
View File

@ -8,7 +8,9 @@ Nvim *nvim* *nvim-intro*
Nvim is based on Vim by Bram Moolenaar.
If you are new to Vim see |help.txt|, or type ":Tutor".
If you are new to Vim, try the 30-minute tutorial: >
:Tutor<Enter>
If you already use Vim see |nvim-from-vim| for a quickstart.
Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is
@ -20,29 +22,24 @@ differences from Vim.
==============================================================================
Transitioning from Vim *nvim-from-vim*
To start the transition, create init.vim in the correct directory for your
platform.
1. To start the transition, create your |init.vim| (user config) file: >
For Linux, macOS and other Unixes, create the file at ~/.config/nvim/init.vim.
:call mkdir(stdpath('config'), 'p')
:exe 'edit '.stdpath('config').'/init.vim'
For Windows, create the file at %LOCALAPPDATA%\nvim\init.vim. `%LOCALAPPDATA%`
usually expands to `C:\Users\<username>\AppData\Local`.
2. Add these contents to the file: >
Note: If your system sets `$XDG_CONFIG_HOME`, use that instead of `~/.config`
or `%LOCALAPPDATA%` in the paths above. Nvim follows the XDG |base-directories|
convention.
Next, add these contents to the file:
>
set runtimepath^=~/.vim runtimepath+=~/.vim/after
let &packpath = &runtimepath
source ~/.vimrc
<
3. Restart Nvim, your existing Vim config will be loaded.
See |provider-python| and |provider-clipboard| for additional software you
might need to use some features.
Your Vim configuration might not be entirely compatible with Nvim. For a
full list of differences between Vim and Nvim see |vim-differences|.
Your Vim configuration might not be entirely Nvim-compatible.
See |vim-differences| for the full list of changes.
The |'ttymouse'| option, for example, was removed from Nvim (mouse support
should work without it). If you use the same |vimrc| for Vim and Nvim,

76
runtime/doc/options.txt
View File

@ -4036,9 +4036,14 @@ A jump table for the options with a short description can be found at |Q_op|.
'mouse' string (default "")
global
Enable the use of the mouse. Only works for certain terminals.
For using the mouse in the GUI, see |gui-mouse|. The mouse can be
enabled for different modes:
Enables mouse support. For example, to enable the mouse in Normal mode
and Visual mode: >
:set mouse=nv
<
To temporarily disable mouse support, hold the shift key while using
the mouse.
Mouse support can be enabled for different modes:
n Normal mode
v Visual mode
i Insert mode
@ -4046,17 +4051,42 @@ A jump table for the options with a short description can be found at |Q_op|.
h all previous modes when editing a help file
a all previous modes
r for |hit-enter| and |more-prompt| prompt
Normally you would enable the mouse in all four modes with: >
:set mouse=a
< When the mouse is not enabled, the GUI will still use the mouse for
modeless selection. This doesn't move the text cursor.
See |mouse-using|. Also see |'clipboard'|.
Left-click anywhere in a text buffer to place the cursor there. This
works with operators too, e.g. type |d| then left-click to delete text
from the current cursor position to the position where you clicked.
Drag the |status-line| or vertical separator of a window to resize it.
If enabled for "v" (Visual mode) then double-click selects word-wise,
triple-click makes it line-wise, and quadruple-click makes it
rectangular block-wise.
For scrolling with a mouse wheel see |scroll-mouse-wheel|.
Note: When enabling the mouse in a terminal, copy/paste will use the
"* register if there is access to an X-server. The xterm handling of
the mouse buttons can still be used by keeping the shift key pressed.
Also see the 'clipboard' option.
"* register if possible. See also 'clipboard'.
Related options:
'mousefocus' window focus follows mouse pointer
'mousemodel' what mouse button does which action
'mousehide' hide mouse pointer while typing text
'selectmode' whether to start Select mode or Visual mode
The :behave command provides some "profiles" for mouse behavior.
*:behave* *:be*
:be[have] {model} Set behavior for mouse and selection. Valid
arguments are:
mswin MS-Windows behavior
xterm Xterm behavior
Using ":behave" changes these options:
option mswin xterm ~
'selectmode' "mouse,key" ""
'mousemodel' "popup" "extend"
'keymodel' "startsel,stopsel" ""
'selection' "exclusive" "inclusive"
*'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'*
'mousefocus' 'mousef' boolean (default off)
@ -4076,7 +4106,7 @@ A jump table for the options with a short description can be found at |Q_op|.
The mouse pointer is restored when the mouse is moved.
*'mousemodel'* *'mousem'*
'mousemodel' 'mousem' string (default "extend", "popup" for Windows)
'mousemodel' 'mousem' string (default "extend")
global
Sets the model to use for the mouse. The name mostly specifies what
the right mouse button is used for:
@ -4105,8 +4135,26 @@ A jump table for the options with a short description can be found at |Q_op|.
You need to define this first, see |popup-menu|.
Note that you can further refine the meaning of buttons with mappings.
See |gui-mouse-mapping|. But mappings are NOT used for modeless
selection (because that's handled in the GUI code directly).
See |mouse-overview|. But mappings are NOT used for modeless selection.
Example: >
:map <S-LeftMouse> <RightMouse>
:map <S-LeftDrag> <RightDrag>
:map <S-LeftRelease> <RightRelease>
:map <2-S-LeftMouse> <2-RightMouse>
:map <2-S-LeftDrag> <2-RightDrag>
:map <2-S-LeftRelease> <2-RightRelease>
:map <3-S-LeftMouse> <3-RightMouse>
:map <3-S-LeftDrag> <3-RightDrag>
:map <3-S-LeftRelease> <3-RightRelease>
:map <4-S-LeftMouse> <4-RightMouse>
:map <4-S-LeftDrag> <4-RightDrag>
:map <4-S-LeftRelease> <4-RightRelease>
<
Mouse commands requiring the CTRL modifier can be simulated by typing
the "g" key before using the mouse:
"g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click)
"g<RightMouse>" is "<C-RightMouse> ("CTRL-T")
The 'mousemodel' option is set by the |:behave| command.

89
runtime/doc/provider.txt
View File

@ -13,44 +13,44 @@ Nvim delegates some features to dynamic "providers".
==============================================================================
Python integration *provider-python*
Nvim supports Python |remote-plugin|s and the Vim legacy |python-vim| and
Nvim supports Python |remote-plugin|s and the Vim legacy |python2| and
|python3| interfaces (which are implemented as remote-plugins).
Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not.
PYTHON QUICKSTART ~
If you used a package manager to install Nvim, you might already have the
required "neovim" Python package. Run |:checkhealth| to verify.
Install the "neovim" Python package:
To install the package with "pip":
- Run |:checkhealth| to see if you already have the package (some package
managers install the "neovim" Python package with Nvim itself).
- For Python 2 plugins, make sure Python 2.7 is available in your $PATH, then
install the "neovim" Python package systemwide: >
install the package systemwide: >
sudo pip2 install --upgrade neovim
<
or for the current user: >
< or for the current user: >
pip2 install --user --upgrade neovim
<
- For Python 3 plugins, make sure Python 3.4+ is available in your $PATH, then
install the "neovim" Python package systemwide: >
sudo pip3 install --upgrade neovim
<
or for the current user: >
pip3 install --user --upgrade neovim
<
Note: "pip" may refer to Python 2 or Python 3, so the steps above mention
"pip2" and "pip3" explicitly. If one is missing, try "pip".
< If "pip2" is missing, try "pip".
Note: The `--upgrade` flag ensures you have the latest version even if
a previous version was already installed.
- For Python 3 plugins, make sure Python 3.4+ is available in your $PATH, then
install the package systemwide: >
sudo pip3 install --upgrade neovim
< or for the current user: >
pip3 install --user --upgrade neovim
< If "pip3" is missing, try "pip".
- The `--upgrade` flag ensures you have the latest version even if a previous
version was already installed.
PYTHON PROVIDER CONFIGURATION ~
*g:python_host_prog*
Path to Python 2 interpreter. Setting this makes startup faster. Also useful
for working with virtualenvs. >
let g:python_host_prog = '/path/to/python' " Python 2
<
*g:python3_host_prog*
Program to use for evaluating Python code. Setting this makes startup faster.
Also useful for working with virtualenvs. >
let g:python_host_prog = '/path/to/python'
let g:python3_host_prog = '/path/to/python3'
Path to Python 3 interpreter. Setting this makes startup faster. Also useful
for working with virtualenvs. >
let g:python3_host_prog = '/path/to/python3' " Python 3
<
*g:loaded_python_provider*
To disable Python 2 support: >
@ -62,21 +62,21 @@ To disable Python 3 support: >
PYTHON VIRTUALENVS ~
If you plan to use per-project virtualenvs often, you should assign
a virtualenv for Neovim and hard-code the interpreter path via
|g:python_host_prog| (or |g:python3_host_prog|) so that the "neovim" python
package is not required for each Environment. Example using pyenv: >
If you plan to use per-project virtualenvs often, you should assign one
virtualenv for Neovim and hard-code the interpreter path via
|g:python3_host_prog| (or |g:python_host_prog|) so that the "neovim" package
is not required for each virtualenv.
Example using pyenv: >
pyenv install 3.4.4
pyenv virtualenv 3.4.4 py3neovim
pyenv activate py3neovim
pyenv virtualenv 3.4.4 py3nvim
pyenv activate py3nvim
pip install neovim
pyenv which python # Note the path
The last command reports the interpreter path, add it to your init.vim: >
let g:python3_host_prog = '/path/to/py3nvim/bin/python'
The last command reports the interpreter path. Add it to your init.vim: >
let g:python3_host_prog = '/full/path/to/py3neovim/bin/python'
More information:
https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
See also: https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
==============================================================================
Ruby integration *provider-ruby*
@ -84,13 +84,13 @@ Ruby integration *provider-ruby*
Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface
(which is itself implemented as a Nvim remote-plugin).
Run |:checkhealth| to see if your system is up-to-date.
RUBY QUICKSTART ~
To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >
gem install neovim
Run |:checkhealth| to see if your system is up-to-date.
RUBY PROVIDER CONFIGURATION ~
*g:loaded_ruby_provider*
To disable Ruby support: >
@ -103,11 +103,10 @@ avoid the need to install the "neovim" gem in every project.
To use an absolute path (e.g. to an rbenv installation): >
let g:ruby_host_prog = '~/.rbenv/versions/2.4.1/bin/neovim-ruby-host'
<
To use the RVM "system" Ruby installation: >
let g:ruby_host_prog = 'rvm system do neovim-ruby-host'
<
==============================================================================
Node.js integration *provider-nodejs*
@ -130,7 +129,7 @@ To disable Node.js support: >
Command to start the Node.js host. Setting this makes startup faster.
By default, Nvim searches for "neovim-node-host" using "npm root -g", which
can be slow. To avoid this, set g:node_host_prog to an absolute path: >
can be slow. To avoid this, set g:node_host_prog to the host path: >
let g:node_host_prog = '/usr/local/bin/neovim-node-host'
<
==============================================================================
@ -187,15 +186,15 @@ The contents of selections are held by the originating application (e.g., upon
a copy), and only passed to another application when that other application
requests them (e.g., upon a paste).
*quoteplus* *quote+*
*primary-selection* *quotestar* *quoteplus* *quote+*
There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
`CLIPBOARD` is typically used in X11 applications for copy/paste operations
(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
There are three documented X11 selections: PRIMARY, SECONDARY, and CLIPBOARD.
CLIPBOARD is typically used in X11 applications for copy/paste operations
(CTRL-c/CTRL-v), while PRIMARY is used for the last selected text, which is
generally inserted with the middle mouse button.
Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
selections, used for the '*' and '+' registers, respectively.
Nvim's X11 clipboard providers only use the PRIMARY and CLIPBOARD selections,
for the "*" and "+" registers, respectively.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

42
runtime/doc/starting.txt
View File

@ -699,27 +699,25 @@ greps in the help files) you might be able to use this: >
4. Suspending *suspend*
*iconize* *iconise* *CTRL-Z* *v_CTRL-Z*
CTRL-Z Suspend Vim, like ":stop".
CTRL-Z Suspend Nvim, like ":stop".
Works in Normal and in Visual mode. In Insert and
Command-line mode, the CTRL-Z is inserted as a normal
character. In Visual mode Vim goes back to Normal
character. In Visual mode Nvim goes back to Normal
mode.
:sus[pend][!] or *:sus* *:suspend* *:st* *:stop*
:st[op][!] Suspend Vim. Vim will continue if you make it the
foreground job again.
If the '!' is not given and 'autowrite' is set, every
:st[op][!] Suspend Nvim using OS "job control"; it will continue
if you make it the foreground job again. Triggers
|VimSuspend| before suspending and |VimResume| when
resumed.
If "!" is not given and 'autowrite' is set, every
buffer with changes and a file name is written out.
If the '!' is given or 'autowrite' is not set, changed
buffers are not written, don't forget to bring Vim
If "!" is given or 'autowrite' is not set, changed
buffers are not written, don't forget to bring Nvim
back to the foreground later!
In the GUI, suspending is implementation-defined.
In X-windows the selection is disowned when Vim suspends. this means you
can't paste it in another application (since Vim is going to sleep an attempt
to get the selection would make the program hang).
==============================================================================
5. Exiting *exiting*
@ -1373,7 +1371,7 @@ file when reading and include:
9. Standard Paths *standard-path*
Nvim stores configuration and data in standard locations. Plugins are strongly
encouraged to follow this pattern also.
encouraged to follow this pattern also. Use |stdpath()| to get the paths.
*base-directories* *xdg*
The "base" (root) directories conform to the XDG Base Directory Specification.
@ -1381,19 +1379,19 @@ https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
The $XDG_CONFIG_HOME and $XDG_DATA_HOME environment variables are used if they
exist, otherwise default values (listed below) are used.
CONFIG DIRECTORY (DEFAULT) ~
*$XDG_CONFIG_HOME* Nvim: stdpath("config")
Unix: ~/.config ~/.config/nvim
Windows: ~/AppData/Local ~/AppData/Local/nvim
DATA DIRECTORY (DEFAULT) ~
*$XDG_DATA_HOME* Nvim: stdpath("data")
Unix: ~/.local/share ~/.local/share/nvim
Windows: ~/AppData/Local ~/AppData/Local/nvim-data
Note: Throughout the user manual these defaults are used as placeholders, e.g.
"~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config".
CONFIG DIRECTORY *$XDG_CONFIG_HOME*
Base Nvim ~
Unix: ~/.config ~/.config/nvim
Windows: ~/AppData/Local ~/AppData/Local/nvim
DATA DIRECTORY *$XDG_DATA_HOME*
Base Nvim ~
Unix: ~/.local/share ~/.local/share/nvim
Windows: ~/AppData/Local ~/AppData/Local/nvim-data
LOG FILE *$NVIM_LOG_FILE*
Besides 'debug' and 'verbose', Nvim keeps a general log file for internal
debugging, plugins and RPC clients. >

94
runtime/doc/term.txt
View File

@ -257,90 +257,14 @@ effect on some UIs.
==============================================================================
Using the mouse *mouse-using*
This section is about using the mouse on a terminal or a terminal window. How
to use the mouse in a GUI window is explained in |gui-mouse|. For scrolling
with a mouse wheel see |scroll-mouse-wheel|.
These characters in the 'mouse' option tell in which situations the mouse will
be used by Vim:
n Normal mode
v Visual mode
i Insert mode
c Command-line mode
h all previous modes when in a help file
a all previous modes
r for |hit-enter| prompt
If you only want to use the mouse in a few modes or also want to use it for
the two questions you will have to concatenate the letters for those modes.
For example: >
:set mouse=nv
Will make the mouse work in Normal mode and Visual mode. >
:set mouse=h
Will make the mouse work in help files only (so you can use "g<LeftMouse>" to
jump to tags).
Whether the selection that is started with the mouse is in Visual mode or
Select mode depends on whether "mouse" is included in the 'selectmode'
option.
In an xterm, with the currently active mode included in the 'mouse' option,
normal mouse clicks are used by Vim, mouse clicks with the shift or ctrl key
pressed go to the xterm. With the currently active mode not included in
'mouse' all mouse clicks go to the xterm.
*xterm-clipboard*
The middle mouse button will insert the unnamed register. In that case, here
is how you copy and paste a piece of text:
Copy/paste with the mouse and Visual mode ('mouse' option must be set, see
above):
1. Press left mouse button on first letter of text, move mouse pointer to last
letter of the text and release the button. This will start Visual mode and
highlight the selected area.
2. Press "y" to yank the Visual text in the unnamed register.
3. Click the left mouse button at the insert position.
4. Click the middle mouse button.
Shortcut: If the insert position is on the screen at the same time as the
Visual text, you can do 2, 3 and 4 all in one: Click the middle mouse button
at the insert position.
*xterm-copy-paste*
NOTE: In some (older) xterms, it's not possible to move the cursor past column
95 or 223. This is an xterm problem, not Vim's. Get a newer xterm
|color-xterm|.
Copy/paste in xterm with (current mode NOT included in 'mouse'):
1. Press left mouse button on first letter of text, move mouse pointer to last
letter of the text and release the button.
2. Use normal Vim commands to put the cursor at the insert position.
3. Press "a" to start Insert mode.
4. Click the middle mouse button.
5. Press ESC to end Insert mode.
(The same can be done with anything in 'mouse' if you keep the shift key
pressed while using the mouse.)
Note: if you lose the 8th bit when pasting (special characters are translated
into other characters), you may have to do "stty cs8 -istrip -parenb" in your
shell before starting Vim.
Thus in an xterm the shift and ctrl keys cannot be used with the mouse. Mouse
commands requiring the CTRL modifier can be simulated by typing the "g" key
before using the mouse:
"g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click)
"g<RightMouse>" is "<C-RightMouse> ("CTRL-T")
*bracketed-paste-mode*
Bracketed paste mode allows terminal applications to distinguish between typed
text and pasted text. Thus you can paste text without Nvim trying to format or
indent the text. See also https://cirw.in/blog/bracketed-paste
Nvim enables bracketed paste by default. If it does not work in your terminal,
try the 'paste' option instead.
Nvim enables bracketed paste by default. Bracketed paste mode allows terminal
applications to distinguish between typed text and pasted text. Thus you can
paste text without Nvim trying to format or indent the text.
See also https://cirw.in/blog/bracketed-paste
*mouse-mode-table* *mouse-overview*
A short overview of what the mouse buttons do, when 'mousemodel' is "extend":
Overview of what the mouse buttons do, when 'mousemodel' is "extend":
Normal Mode:
event position selection change action ~
@ -451,14 +375,6 @@ In Insert mode, when a selection is started, Vim goes into Normal mode
temporarily. When Visual or Select mode ends, it returns to Insert mode.
This is like using CTRL-O in Insert mode. Select mode is used when the
'selectmode' option contains "mouse".
*drag-status-line*
When working with several windows, the size of the windows can be changed by
dragging the status line with the mouse. Point the mouse at a status line,
press the left button, move the mouse to the new position of the status line,
release the button. Just clicking the mouse in a status line makes that window
the current window, without moving the cursor. If by selecting a window it
will change position or size, the dragging of the status line will look
confusing, but it will work (just try it).
*<MiddleRelease>* *<MiddleDrag>*
Mouse clicks can be mapped. The codes for mouse clicks are:

27
runtime/doc/vim_diff.txt
View File

@ -205,19 +205,8 @@ certain features removed/added at compile-time. |feature-compile|
If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
are always available and may be used simultaneously. See |provider-python|.
|:!| does not support "interactive" commands. Use |:terminal| instead.
(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
:!start is not special-cased on Windows.
|system()| does not support writing/reading "backgrounded" commands. |E5677|
|:redir| nested in |execute()| works.
Nvim may throttle (skip) messages from shell commands (|:!|, |:grep|, |:make|)
if there is too much output. No data is lost, this only affects display and
makes things faster. |:terminal| output is never throttled.
|mkdir()| behaviour changed:
1. Assuming /tmp/foo does not exist and /tmp can be written to
mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar
@ -323,6 +312,22 @@ Normal commands:
Options:
'ttimeout', 'ttimeoutlen' behavior was simplified
Shell:
Shell output (|:!|, |:make|, …) is always routed through the UI, so it
cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if
you want to mess up the screen :)
Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|)
if there is too much output. No data is lost, this only affects display and
improves performance. |:terminal| output is never throttled.
|:!| does not support "interactive" commands. Use |:terminal| instead.
(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
:!start is not special-cased on Windows.
|system()| does not support writing/reading "backgrounded" commands. |E5677|
Startup:
|-e| and |-es| invoke the same "improved Ex mode" as -E and -Es.
|-E| and |-Es| reads stdin as text (into buffer 1).

6
runtime/tutor/en/vim-01-beginner.tutor
View File

@ -18,9 +18,9 @@ won't be saved. Don't worry about messing things up; just remember that
pressing [<Esc>](<Esc>) and then [u](u) will undo the latest change.
This tutorial is interactive, and there are a few things you should know.
Pressing [<Enter>](<Enter>) over text highlighted [like this](holy-grail )
will take you to some relevant help (hopefully), and pressing K over any
word will try to do so too. Sometimes you will be required to modify text like
- Type [<Enter>](<Enter>) on links [like this](holy-grail ) to open the linked help section.
- Or simply type [K](K) on any word to find its documentation!
- Sometimes you will be required to modify text like
this here
Once you have done the changes correctly, the ✗ sign at the left will change
to ✓. I imagine you can already see how neat Vim can be. ;)

34
src/nvim/README.md
View File

@ -23,15 +23,19 @@ Logs
Low-level log messages sink to `$NVIM_LOG_FILE`.
You can use `LOG_CALLSTACK();` anywhere in the source to log the current
stacktrace. To log in an alternate file, e.g. stderr, use
`LOG_CALLSTACK_TO_FILE(FILE*)`. (Currently Linux-only.)
Use `LOG_CALLSTACK()` (Linux only) to log the current stacktrace. To log to an
alternate file (e.g. stderr) use `LOG_CALLSTACK_TO_FILE(FILE*)`.
UI events are logged at level 0 (`DEBUG_LOG_LEVEL`).
UI events are logged at DEBUG level (`DEBUG_LOG_LEVEL`).
rm -rf build/
make CMAKE_EXTRA_FLAGS="-DMIN_LOG_LEVEL=0"
Many log messages have a shared prefix, such as "UI" or "RPC". Use the shell to
filter the log, e.g. at DEBUG level you might want to exclude UI messages:
tail -F ~/.local/share/nvim/log | cat -v | stdbuf -o0 grep -v UI | stdbuf -o0 tee -a log
Build with ASAN
---------------
@ -276,3 +280,25 @@ Since Nvim inherited its code from Vim, the states are not prepared to receive
"arbitrary events", so we use a special key to represent those (When a state
receives an "arbitrary event", it normally doesn't do anything other update the
screen).
Main loop
---------
The `Loop` structure (which describes `main_loop`) abstracts multiple queues
into one loop:
uv_loop_t uv;
MultiQueue *events;
MultiQueue *thread_events;
MultiQueue *fast_events;
`loop_poll_events` checks `Loop.uv` and `Loop.fast_events` whenever Nvim is
idle, and also at `os_breakcheck` intervals.
MultiQueue is cool because you can attach throw-away "child queues" trivially.
For example `do_os_system()` does this (for every spawned process!) to
automatically route events onto the `main_loop`:
Process *proc = &uvproc.process;
MultiQueue *events = multiqueue_new_child(main_loop.events);
proc->events = events;

1
src/nvim/event/loop.c
View File

@ -34,6 +34,7 @@ void loop_init(Loop *loop, void *data)
/// Processes one `Loop.uv` event (at most).
/// Processes all `Loop.fast_events` events.
/// Does NOT process `Loop.events`, that is an application-specific decision.
///
/// @returns true if `ms` timeout was reached
bool loop_poll_events(Loop *loop, int ms)

4
test/README.md
View File

@ -64,9 +64,9 @@ To run a *specific* functional test:
TEST_FILE=test/functional/foo.lua make functionaltest
To *repeat* a test many times:
To *repeat* a test:
.deps/usr/bin/busted --filter 'foo' --repeat 1000 test/functional/ui/foo_spec.lua
.deps/usr/bin/busted --lpath='build/?.lua' --filter 'foo' --repeat 1000 test/functional/ui/foo_spec.lua
### Filter by tag