Merge #8902 'doc'

20 files changed, 406 insertions, 571 deletions

diff --git a/MAINTAIN.md b/MAINTAIN.md
new file mode 100644
index 0000000000..ed0df76e36
--- /dev/null
+++ b/MAINTAIN.md
@@ -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
diff --git a/man/nvim.1 b/man/nvim.1
index 0040af2865..cfaa3ef3aa 100644
--- a/man/nvim.1
+++ b/man/nvim.1
@@ -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"
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 9fabc1cf8b..e816d0ae76 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -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*
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 1e4d643e95..be3efb371f 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -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)
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index b3b60cbab8..bd195b78b2 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -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.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 2e1d89c524..ec4b8162fa 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -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
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index 74c453f79a..302370b4cc 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -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"
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 904c4be19c..0c2cc9c865 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -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:
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 6769dd87e8..e33f89e771 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -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
diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt
index ed5f16902a..e5cd765e83 100644
--- a/runtime/doc/job_control.txt
+++ b/runtime/doc/job_control.txt
@@ -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*
 
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index b8a481a016..07eb48aea3 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -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.
-
-For Linux, macOS and other Unixes, create the file at ~/.config/nvim/init.vim.
+1. To start the transition, create your |init.vim| (user config) file: >
 
-For Windows, create the file at %LOCALAPPDATA%\nvim\init.vim. `%LOCALAPPDATA%`
-usually expands to `C:\Users\<username>\AppData\Local`.
+    :call mkdir(stdpath('config'), 'p')
+    :exe 'edit '.stdpath('config').'/init.vim'
 
-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.
+2. Add these contents to the file: >
 
-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,
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 2f2db844e8..f2962f0822 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -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.
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 8b5798a5a5..0e26dc4515 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -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
-<
+<  If "pip2" is missing, try "pip".
+
 - For Python 3 plugins, make sure Python 3.4+ is available in your $PATH, then
-  install the "neovim" Python package systemwide: >
+  install the package systemwide: >
     sudo pip3 install --upgrade neovim
-<
-  or for the current user: >
+<  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 "pip3" is missing, try "pip".
 
-Note: The `--upgrade` flag ensures you have the latest version even if
-a previous version was already installed.
+- 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:
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 34c4db4047..aebb0ef6ec 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -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,18 +1379,18 @@ 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.
 
-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 (DEFAULT) ~
+                  *$XDG_CONFIG_HOME*            Nvim: stdpath("config")
+    Unix:         ~/.config                   ~/.config/nvim
+    Windows:      ~/AppData/Local             ~/AppData/Local/nvim
 
-CONFIG DIRECTORY				*$XDG_CONFIG_HOME*
-          Base                Nvim ~
-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
 
-DATA DIRECTORY					*$XDG_DATA_HOME*
-          Base                Nvim ~
-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".
 
 LOG FILE					*$NVIM_LOG_FILE*
 Besides 'debug' and 'verbose', Nvim keeps a general log file for internal
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index 418623687f..9de5745e92 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -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:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 3b5ba26b02..2615d8a108 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -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).
diff --git a/runtime/tutor/en/vim-01-beginner.tutor b/runtime/tutor/en/vim-01-beginner.tutor
index 0d03103bca..2b30ccb5f8 100644
--- a/runtime/tutor/en/vim-01-beginner.tutor
+++ b/runtime/tutor/en/vim-01-beginner.tutor
@@ -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. ;)
diff --git a/src/nvim/README.md b/src/nvim/README.md
index d668db0cdc..02464c2500 100644
--- a/src/nvim/README.md
+++ b/src/nvim/README.md
@@ -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;
diff --git a/src/nvim/event/loop.c b/src/nvim/event/loop.c
index 7998e0b8d0..609c723c57 100644
--- a/src/nvim/event/loop.c
+++ b/src/nvim/event/loop.c
@@ -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)
diff --git a/test/README.md b/test/README.md
index 3ac8531ba8..0999f412ac 100644
--- a/test/README.md
+++ b/test/README.md
@@ -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