doc: job/channel, misc #7783

doc: termios defaults. ref #6992
doc: :help shell-powershell
doc: provider: Python minimum version is 2.7, 3.4
doc: remove :!start special-case. #5844
doc: mention #7917 change which accepts empty Array for Dictionary parameter
doc: <Cmd> pseudokey
doc: lmap change #5658
doc: -s, -es

25 files changed, 428 insertions, 413 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 91b7a06a5a..6ad29c5b7c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,3 +1,7 @@
+# CMAKE REFERENCE
+#   intro: https://codingnest.com/basic-cmake/
+#   best practices (3.0+): https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1
+
 cmake_minimum_required(VERSION 2.8.7)
 project(nvim)
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 05a97ebf18..1b73c60773 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,8 +14,15 @@ low-risk/isolated tasks:
 Developer guidelines
 --------------------
 
-- Nvim developers should read `:help dev`.
+- Nvim contributors should read `:help dev` (especially `:help dev-api`).
 - External UI developers should read `:help dev-ui`.
+- API client developers should read `:help dev-api-client`.
+- Nvim developers are _strongly encouraged_ to install `ninja` for faster builds.
+  ```
+  sudo apt-get install ninja-build
+  make distclean
+  make  # Nvim build system uses ninja automatically, if available.
+  ```
 
 Reporting problems
 ------------------
@@ -157,7 +164,7 @@ shows each commit's diff. To show the whole surrounding function of a change
 as context, use the `-W` argument as well.
 
 [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
-[git-bisect]: http://git-scm.com/book/tr/v2/Git-Tools-Debugging-with-Git
+[git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git
 [git-feature-branch]: https://www.atlassian.com/git/tutorials/comparing-workflows
 [git-history-filtering]: https://www.atlassian.com/git/tutorials/git-log/filtering-the-commit-history
 [git-history-rewriting]: http://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
diff --git a/README.md b/README.md
index f0e69fee63..803e16aaf0 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@
 [![Clang Scan Build](https://neovim.io/doc/reports/clang/badge.svg)](https://neovim.io/doc/reports/clang)
 [![PVS-studio Check](https://neovim.io/doc/reports/pvs/badge.svg)](https://neovim.io/doc/reports/pvs/PVS-studio.html.d)
 
+[![Packages](https://repology.org/badge/tiny-repos/neovim.svg)](https://repology.org/metapackage/neovim)
 [![Debian CI](https://badges.debian.net/badges/debian/testing/neovim/version.svg)](https://buildd.debian.org/neovim)
 [![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592001)](https://github.com/neovim/neovim/releases/)
 
@@ -43,6 +44,8 @@ To list all targets:
 
     cmake --build build --target help
 
+To skip "bundled" dependencies define `USE_BUNDLED_DEPS=NO` (CMake option: `USE_BUNDLED=NO`).
+
 See [the wiki](https://github.com/neovim/neovim/wiki/Building-Neovim) for details.
 
 Install from package
@@ -73,9 +76,6 @@ Project layout
     ├─ third-party/     cmake subproject to build dependencies
     └─ test/            tests (see test/README.md)
 
-- To disable `third-party/` specify `USE_BUNDLED_DEPS=NO` or `USE_BUNDLED=NO`
-  (CMake option).
-
 Features
 --------
 
diff --git a/man/nvim.1 b/man/nvim.1
index 75c037946a..2afd31155d 100644
--- a/man/nvim.1
+++ b/man/nvim.1
@@ -54,7 +54,7 @@ If
 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
@@ -67,7 +67,7 @@ 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.
@@ -76,21 +76,21 @@ Can be used to edit files starting with a hyphen
 .It Fl e
 Ex mode.  Reads stdin as Ex commands.
 See
-.Ic :help Ex-mode .
+.Ic ":help Ex-mode" .
 .It Fl E
 Ex mode, improved.  Reads stdin as text.
 See
 .Ic :help gQ .
 .It Fl es
 Silent (batch) mode.  Reads stdin as Ex commands.
-.It Fl Es
+.It Fl \&Es
 Silent (batch) mode.  Reads stdin as text.
 .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.
@@ -101,7 +101,7 @@ 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.
@@ -114,7 +114,7 @@ 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.
@@ -157,7 +157,7 @@ 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 .
@@ -178,7 +178,7 @@ is
 .Cm NONE ,
 loading plugins is also skipped.
 See
-.Ic :help initialization .
+.Ic ":help initialization" .
 .It Fl i Ar shada
 Use
 .Ar shada
@@ -190,7 +190,7 @@ 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
@@ -244,7 +244,7 @@ and
 inside
 .Nm .
 See
-.Ic :help search-pattern .
+.Ic ":help search-pattern" .
 .It Fl c Ar command
 Execute
 .Ar command
@@ -281,12 +281,12 @@ 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 .
 The same can be done with the command
-.Ic :source! scriptin .
+.Ic ":source! scriptin" .
 If the end of the file is reached before
 .Nm
 exits, further characters are read from the keyboard.
@@ -353,7 +353,7 @@ quit immediately after starting, set
 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
@@ -389,7 +389,7 @@ Most of Vim was written by
 .An -nosplit
 .An Bram Moolenaar .
 See
-.Ic :help credits .
+.Ic ":help credits" .
 Vim is based on Stevie, worked on by
 .An Tim Thompson ,
 .An Tony Andrews ,
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 6c730ae6cd..c5421ca86e 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -16,26 +16,23 @@ Applications can also embed libnvim to work with the C API directly.
 ==============================================================================
 API Types							   *api-types*
 
-Nvim's C API uses custom types for all functions. Some are just typedefs
-around C99 standard types, and some are Nvim-defined data structures.
+The Nvim C API defines custom types for all function parameters. Some are just
+typedefs around C99 standard types, others are Nvim-defined data structures.
 
-Boolean				  -> bool
-Integer (signed 64-bit integer)	  -> int64_t
-Float (IEEE 754 double precision) -> double
-String				  -> {char* data, size_t size} struct
-
-Additionally, the following data structures are defined:
-
-Array
-Dictionary
-Object
+  Boolean				-> bool
+  Integer (signed 64-bit integer)	-> int64_t
+  Float (IEEE 754 double precision)	-> double
+  String				-> {char* data, size_t size} struct
+  Array
+  Dictionary
+  Object
 
 The following handle types are defined as integer typedefs, but are
 discriminated as separate types in an Object:
 
-Buffer				  -> enum value kObjectTypeBuffer
-Window				  -> enum value kObjectTypeWindow
-Tabpage				  -> enum value kObjectTypeTabpage
+  Buffer				-> enum value kObjectTypeBuffer
+  Window				-> enum value kObjectTypeWindow
+  Tabpage				-> enum value kObjectTypeTabpage
 
 ==============================================================================
 API metadata							 *api-metadata*
@@ -60,10 +57,14 @@ External programs ("clients") can use the metadata to discover the |rpc-api|.
 ==============================================================================
 API contract                                                     *api-contract*
 
-The API is made of functions and events. Clients call functions like those
-described at |api-global|, and may "attach" to receive rich |ui-events|.
+The Nvim API is composed of functions and events.
+
+- Clients call functions like those described at |api-global|.
+- Clients can subscribe to |ui-events|, |api-buffer-updates|, etc.
+- API function names are prefixed with "nvim_".
+- API event names are prefixed with "nvim_" and suffixed with "_event".
 
-As Nvim develops, its API may change only according the following "contract":
+As Nvim evolves the API may change in compliance with this CONTRACT:
 
 - New functions and events may be added.
   - Any such extensions are OPTIONAL: old clients may ignore them.
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index df36969fe3..6e6d50d21f 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -904,14 +904,11 @@ SpellFileMissing		When trying to load a spell checking file and
 				language, 'encoding' also matters.  See
 				|spell-SpellFileMissing|.
 							*StdinReadPost*
-StdinReadPost			After reading from the stdin into the buffer,
-				before executing the modelines.  Only used
-				when the "-" argument was used when Vim was
-				started |--|.
+StdinReadPost			During startup, after reading from stdin into
+				the buffer, before executing modelines. |--|
 							*StdinReadPre*
-StdinReadPre			Before reading from stdin into the buffer.
-				Only used when the "-" argument was used when
-				Vim was started |--|.
+StdinReadPre			During startup, before reading from stdin into
+				the buffer. |--|
 							*SwapExists*
 SwapExists			Detected an existing swap file when starting
 				to edit a file.  Only when it is possible to
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index dbac878a33..1e4d643e95 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -126,10 +126,14 @@ all data has been processed:
 For additional examples with jobs, see |job-control|.
 
 							      *channel-pty*
-A special case is PTY channels opened by  `jobstart(..., {'pty': v:true})` .
-No preprocessing of ANSI escape sequences is done, these will be sent raw to
-the callback. However, change of PTY size can be signaled to the slave using
-|jobresize()|. See also |terminal-emulator|.
+Special case: PTY channels opened with `jobstart(..., {'pty': v:true})` do not
+preprocess ANSI escape sequences, these will be sent raw to the callback.
+However, change of PTY size can be signaled to the slave using |jobresize()|.
+See also |terminal-emulator|.
+
+Terminal characteristics (termios) for |:terminal| and PTY channels are copied
+from the host TTY, or if Nvim is |--headless| it uses default values: >
+    :echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q')
 
 ==============================================================================
 3. Communicating using msgpack-rpc			      *channel-rpc*
@@ -140,37 +144,27 @@ rpc channels are implicitly trusted and the process at the other end can
 invoke any |api| function!
 
 ==============================================================================
-4. Using the stdio channel				    *channel-stdio*
+4. Standard IO channel					    *channel-stdio*
 
-When invoked normally, nvim will use stdin and stdout to interact with the
-user over the terminal interface (TUI). However when invoked with
-`--headless`, the TUI is not started and stdin and stdout can be used as a
-channel. To open the stdio channel |stdioopen()| must be called during
-|startup|, as there later will be no way of invoking a command.  As a
-convenience, the stdio channel will always have channel id 1.
+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|.
 
-Here is an example:
->
+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.
+
+Example: >
     func! OnEvent(id, data, event)
       if a:data == [""]
-	quit
+        quit
       end
       call chansend(a:id, map(a:data, {i,v -> toupper(v)}))
     endfunc
-
     call stdioopen({'on_stdin': 'OnEvent'})
 <
-Put this in `uppercase.vim` and invoke nvim with
->
+Put this in `uppercase.vim` and run:  >
     nvim --headless --cmd "source uppercase.vim"
-<
-								*--embed*
-An common use case is another program embedding nvim and communicating with it
-over rpc. Therefore, the option `--embed` exists as a shorthand for
-`nvim --headless --cmd "call stdioopen({'rpc': v:true})"`
-
-Nvim's stderr is implicitly open as a write-only bytes channel. It will
-always have channel id 2, however to be explicit |v:stderr| can be used.
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 00e654841c..c46a9fc2d8 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -382,7 +382,7 @@ CTRL-N		After using 'wildchar' which got multiple matches, go to next
 <S-Tab>							*c_CTRL-P* *c_<S-Tab>*
 CTRL-P		After using 'wildchar' which got multiple matches, go to
 		previous match.  Otherwise recall older command-line from
-		history.  <S-Tab> only works with the GUI.
+		history.
 							*c_CTRL-A*
 CTRL-A		All names that match the pattern in front of the cursor are
 		inserted.
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 03699b3dfb..7c98b81867 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -12,10 +12,6 @@ updated.
 
 ==============================================================================
 
-Normal commands ~
-*]f*
-*[f*			Same as "gf".
-
 Commands ~
 *:rv*
 *:rviminfo*		Deprecated alias to |:rshada| command.
@@ -51,6 +47,10 @@ Modifiers ~
 *:map-<special>*
 *:map-special*		<> notation is always enabled. |cpo-<|
 
+Normal commands ~
+*]f*
+*[f*			Same as "gf".
+
 Options ~
 *'cscopeverbose'*	Enabled by default. Use |:silent| instead.
 'gd'
@@ -61,4 +61,8 @@ Options ~
 *'vi'*
 *'viminfo'*		Deprecated alias to 'shada' option.
 
+Variables~
+*b:terminal_job_pid*	PID of the top-level process in a |:terminal|.
+			Use `jobpid(&channel)` instead.
+
  vim:noet:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 4e77f40035..689f720583 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -203,7 +203,7 @@ DOCUMENTATION						*dev-doc*
 
 API							*dev-api*
 
-Use this pattern to name new API functions:
+Use this template to name new API functions:
     nvim_{thing}_{action}_{arbitrary-qualifiers}
 
 If the function acts on an object then {thing} is the name of that object
@@ -231,6 +231,11 @@ Example: `nvim_list_bufs` operates in a global context (first parameter is
 _not_ a Buffer). The common {action} "list" indicates that it lists all
 bufs (plural) in the global context.
 
+Use this template to name new API events:
+    nvim_{thing}_{event}_event
+
+Example: `nvim_buf_changedtick_event`.
+
 
 API-CLIENT						*dev-api-client*
 
@@ -267,7 +272,11 @@ Common Features ~
 External UIs are expected to implement these common features:
 - Cursor style (shape, color) should respond to the 'guicursor' properties
   delivered with the mode_info_set UI event.
+- Send the ALT/META ("Option" on macOS) key as a |<M-| chord.
 - Send the "super" key (Windows key, Apple key) as a |<D-| chord.
+- Avoid mappings that conflict with Nvim defaults. GUIs have many new chords
+  like <C-,> <C-Enter> <C-S-x> <D-x> and patterns like "shift shift", which
+  don't conflict with typical Nvim mappings.
 
 Implementation ~
 - UI-related options ('guifont', 'ambiwidth', …) are published in the
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index f404192abb..197bc1d2d7 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -7265,10 +7265,8 @@ stdioopen({opts})			 *stdioopen()*
 
 
 stdpath({what})					*stdpath()* *E6100*
-		Returns the standard path(s) for {what}.
-
-		These directories are the default locations for various files
-		used by Neovim.
+		Returns |standard-path| locations of various default files and
+		directories.
 
 		{what}       Type    Description ~
 		cache        String  Cache directory. Useful for plugins
@@ -8609,18 +8607,36 @@ See |:verbose-cmd| for more information.
 			implies that the effect of |:nohlsearch| is undone
 			when the function returns.
 
-					*:endf* *:endfunction* *E126* *E193*
-:endf[unction]		The end of a function definition.  Must be on a line
-			by its own, without other commands.
-
-				    *:delf* *:delfunction* *E130* *E131* *E933*
-:delf[unction] {name}	Delete function {name}.
+				*:endf* *:endfunction* *E126* *E193* *W22*
+:endf[unction] [argument]
+			The end of a function definition.  Best is to put it
+			on a line by its own, without [argument].
+
+			[argument] can be:
+				| command	command to execute next
+				\n command	command to execute next
+				" comment	always ignored
+				anything else	ignored, warning given when
+						'verbose' is non-zero
+			The support for a following command was added in Vim
+			8.0.0654, before that any argument was silently
+			ignored.
+
+			To be able to define a function inside an `:execute`
+			command, use line breaks instead of |:bar|: >
+				:exe "func Foo()\necho 'foo'\nendfunc"
+<
+				*:delf* *:delfunction* *E130* *E131* *E933*
+:delf[unction][!] {name}
+			Delete function {name}.
 			{name} can also be a |Dictionary| entry that is a
 			|Funcref|: >
 				:delfunc dict.init
-<			This will remove the "init" entry from "dict".	The
+<			This will remove the "init" entry from "dict".  The
 			function is deleted if there are no more references to
 			it.
+			With the ! there is no error if the function does not
+			exist.
 							*:retu* *:return* *E133*
 :retu[rn] [expr]	Return from a function.  When "[expr]" is given, it is
 			evaluated and returned as the result of the function.
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 1feff0723b..d612f038a6 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -42,7 +42,7 @@ char		action	~
 		abbreviation.
 		Note: If your <Esc> key is hard to hit, try CTRL-[ instead.
 						*i_META* *i_ALT*
-                |ALT| (|META|) acts like <Esc> if the chord is not mapped.
+                ALT (|META|) acts like <Esc> if the chord is not mapped.
 		For example <A-x> acts like <Esc>x if <A-x> does not have an
                 insert-mode mapping.
 						*i_CTRL-C*
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 7633dbf352..804b7410f6 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -234,8 +234,7 @@ For this reason the following is blocked:
 - Moving the cursor is allowed, but it is restored afterwards.
 - If the cmdline is changed, the old text and cursor position are restored.
 If you want the mapping to do any of these let the returned characters do
-that. Alternatively use a |<Cmd>| mapping which doesn't have these
-restrictions.
+that. Or use a |<Cmd>| mapping (which doesn't have these restrictions).
 
 You can use getchar(), it consumes typeahead if there is any. E.g., if you
 have these mappings: >
@@ -274,29 +273,30 @@ again for using <expr>.  This does work: >
 Using 0x80 as a single byte before other text does not work, it will be seen
 as a special key.
 
-						*<Cmd>* *:map-command*
-A command mapping is a mapping that directly executes a command. Command
-mappings are written by placing a command in between <Cmd> and <CR> in the
-rhs of a mapping (in any mode): >
-	noremap <f3> <Cmd>echo mode(1)<cr>
+						*<Cmd>* *:map-cmd*
+The <Cmd> pseudokey may be used to define a "command mapping", which executes
+the command directly (without changing modes, etc.).  Where you might use
+":...<CR>" in the {lhs} of a mapping, you can instead use "<Cmd>...<CR>".
+Example: >
+	noremap x <Cmd>echo mode(1)<cr>
 <
+This is more flexible than `:<C-U>` in visual and operator-pending mode, or
+`<C-O>:` in insert-mode, because the commands are executed directly in the
+current mode (instead of always going to normal-mode).  Visual-mode is
+preserved, so tricks with |gv| are not needed.  Commands can be invoked
+directly in cmdline-mode (which otherwise would require timer hacks).
+
+Unlike <expr> mappings, there are no special restrictions on the <Cmd>
+command: it is executed as if an (unrestricted) |autocmd| was invoked or an
+async event event was processed.
+
+In select-mode, |:map| and |:vmap| command mappings are executed in
+visual-mode.  Use |:smap| to handle select-mode.
+
 							*E5520*
-The command must be complete and ended with a <CR>. If the command is
-incomplete, an error is raised. |Command-line| mode is never entered.
-
-This is more flexible than using `:<c-u>` in visual and operator pending
-mode, or `<c-o>:` in insert mode, as the commands are exectued directly in the
-mode, and not normal mode. Also visual mode is not aborted. Commands can be
-invoked directly in cmdline mode, which is not simple otherwise (a timer has
-to be used). Unlike <expr> mappings, there are not any specific restrictions
-what the command can do, except for what is normally possible to do in every
-specific mode. The command should be executed the same way as if an
-(unrestricted) |autocmd| was invoked or an async event event was processed.
-
-Note: In select mode, |:map| or |:vmap| command mappings will be executed in
-visual mode. If a mapping is intended to work in select mode, it is
-recomendend to map it using |:smap|, possibly in addition to the same mapping
-with |:map| or |:xmap|.
+<Cmd> commands must terminate, that is, they must be followed by <CR> in the
+{lhs} of the mapping definition.  |Command-line| mode is never entered.
+
 
 1.3 MAPPING AND MODES					*:map-modes*
 		*mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* *mapmode-t*
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 01d4e10cea..a29569f049 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -190,10 +190,10 @@ prefix is stripped off.
 5. Types							    *rpc-types*
 
 The Nvim C API uses custom types for all functions. |api-types|
-At the RPC layer, the types can be split into two groups:
+At the RPC layer, types form two groups:
 
-  - Basic types that map natively to msgpack (and probably have a default
-    representation in msgpack-supported programming languages)
+  - Basic types that map natively to msgpack (and have a default
+    representation in most msgpack-supported programming languages)
   - Special Nvim types that map to msgpack EXT with custom type codes.
 
 Basic types ~
@@ -206,6 +206,8 @@ Basic types ~
   Array                             -> msgpack array
   Dictionary                        -> msgpack map
 
+  Note: in function calls, empty Array is accepted for Dictionary parameter.
+
 Special types (msgpack EXT) ~
 
   Buffer                            -> enum value kObjectTypeBuffer
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index 8c6edc0fb8..cdcb61404f 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -118,8 +118,6 @@ variables:
   running in the terminal can set this title via an escape sequence.
 - |'channel'| The nvim channel ID for the underlying PTY.
   |chansend()| can be used to send input to the terminal.
-- *b:terminal_job_pid* The PID of the top-level process running in the
-  terminal.
 
 These variables are initialized before TermOpen, so you can use them in
 a local 'statusline'. Example: >
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 1f880eeb36..7ff1281274 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2024,7 +2024,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	security reasons.
 
 					*'display'* *'dy'*
-'display' 'dy'		string	(default "lastline", Vi default: "")
+'display' 'dy'		string	(default "lastline,msgsep", Vi default: "")
 			global
 	Change the way text is displayed.  This is comma separated list of
 	flags:
@@ -2036,11 +2036,10 @@ A jump table for the options with a short description can be found at |Q_op|.
 			column of the last screen line.  Overrules "lastline".
 	uhex		Show unprintable characters hexadecimal as <xx>
 			instead of using ^C and ~C.
-	msgsep		When showing messages longer than 'cmdheight' lines,
-			only scroll the message lines and not the entire
-			screen. This also shows a separator line filled with
-			chars determined by 'fillchars' option, and
-			highlighted with the |MsgSeparator| group.
+	msgsep		When showing messages longer than 'cmdheight', only
+			scroll the message lines, not the entire screen. The
+			separator line is decorated by |MsgSeparator| and the
+			"msgsep" flag of 'fillchars'.
 
 	When neither "lastline" nor "truncate" is included, a last line that
 	doesn't fit is replaced with "@" lines.
@@ -2063,13 +2062,11 @@ A jump table for the options with a short description can be found at |Q_op|.
 
 
 					*'encoding'* *'enc'* *E543*
-'encoding' 'enc'	Removed. |vim-differences| {Nvim}
-	Nvim always uses UTF-8 internally. RPC communication
-	(remote plugins/GUIs) must use UTF-8 strings.
+'encoding' 'enc'
+	String-encoding used internally and for |RPC| communication.
+	Always UTF-8.
 
-	The character encoding of files can be different than UTF-8.
-	This is specified with 'fileencoding'.  The conversion is done with
-	iconv() or as specified with 'charconvert'.
+	See 'fileencoding' to control file-content encoding.
 
 			*'endofline'* *'eol'* *'noendofline'* *'noeol'*
 'endofline' 'eol'	boolean	(default on)
@@ -2185,16 +2182,16 @@ A jump table for the options with a short description can be found at |Q_op|.
 				*'fileencoding'* *'fenc'* *E213*
 'fileencoding' 'fenc'	string (default: "")
 			local to buffer
-			{only available when compiled with the |+multi_byte|
-			feature}
-	Sets the character encoding for the file of this buffer.
+	File-content encoding for the current buffer. Conversion is done with
+	iconv() or as specified with 'charconvert'.
 
-	When 'fileencoding' is different from "utf-8", conversion will be
-	done when writing the file.  For reading see below.
-	When 'fileencoding' is empty, the file will be saved with utf-8
-	encoding.  (no conversion when reading or writing a file).
-		WARNING: Conversion to a non-Unicode encoding can cause loss of
-		information! 
+	When 'fileencoding' is not UTF-8, conversion will be done when
+	writing the file.  For reading see below.
+	When 'fileencoding' is empty, the file will be saved with UTF-8
+	encoding (no conversion when reading or writing a file).
+
+	WARNING: Conversion to a non-Unicode encoding can cause loss of
+	information!
 
 	See |encoding-names| for the possible values.  Additionally, values may be
 	specified that can be handled by the converter, see
@@ -2221,7 +2218,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	written.  If you do set 'fenc' in a modeline, you might want to set
 	'nomodified' to avoid not being able to ":q".
 
-	This option can not be changed when 'modifiable' is off.
+	This option cannot be changed when 'modifiable' is off.
 
 					*'fileencodings'* *'fencs'*
 'fileencodings' 'fencs'	string (default: "ucs-bom,utf-8,default,latin1")
@@ -2294,7 +2291,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	'fileformats' is not empty and 'binary' is off.
 	When this option is set, after starting to edit a file, the 'modified'
 	option is set, because the file would be different when written.
-	This option can not be changed when 'modifiable' is off.
+	This option cannot be changed when 'modifiable' is off.
 
 					*'fileformats'* *'ffs'*
 'fileformats' 'ffs'	string (default:
@@ -5139,8 +5136,12 @@ A jump table for the options with a short description can be found at |Q_op|.
 	   to escape quote: 'a\"b"' is the same as "a\b".
 	Note that such processing is done after |:set| did its own round of 
 	unescaping, so to keep yourself sane use |:let-&| like shown above.
+							*shell-powershell*
+	To use powershell (on Windows): >
+		set shell=powershell shellquote=( shellpipe=\| shellredir=> shellxquote=
+		set shellcmdflag=-NoLogo\ -NoProfile\ -ExecutionPolicy\ RemoteSigned\ -Command
 
-	This option cannot be set from a |modeline| or in the |sandbox|, for
+<	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
 						*'shellcmdflag'* *'shcf'*
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 4a76f1399e..153021a616 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -20,31 +20,29 @@ 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 see if your system is
-up-to-date.
+required `neovim` Python package. Run |:checkhealth| to verify.
 
-Following are steps to install the package with Python's `pip` tool.
+Following are steps to install the package with Python `pip`.
 
-Note: Depending on your system, `pip` might refer to Python 2 or Python 3,
-      which is why the following instructions mention `pip2` or `pip3`
-      explicitly. If one of these is not available, try `pip`.
 
-To use Vim Python 2/3 plugins with Nvim:
 
-- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is
-  available in your `$PATH`, then install the `neovim` Python package systemwide: >
+- For Python 2 plugins, make sure Python 2.7 is available in your `$PATH`,
+  then install the `neovim` Python package systemwide: >
     sudo pip2 install --upgrade neovim
 <
   or for the current user: >
     pip2 install --user --upgrade neovim
 <
-- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is
-  available in your `$PATH`, then install the `neovim` Python package systemwide: >
+- 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 instructions mention
+`pip2` or `pip3` explicitly. If one is missing, try `pip`.
+
 Note: The `--upgrade` flag ensures you have the latest version even if
 a previous version was already installed.
 
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 5ff9e0b5dc..e89d72bce3 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -35,23 +35,23 @@ filename	One or more file names.  The first one will be the current
 		no other options or "+command" argument can follow.
 
 							*--*
--		This argument can mean two things, depending on whether Ex
-		mode is to be used.
-
-		Starting in Normal mode: >
-			nvim -
-<		Start editing a new buffer, which is filled with text
-		that is read from stdin.  The commands that would normally be
-		read from stdin will now be read from stderr.  Example: >
-			find . -name "*.c" -print | nvim -
+-		Alias for stdin (standard input).
+		Example: >
+			echo text | nvim - file
+<		"text" is read into buffer 1, "file" is opened as buffer 2.
+		In most cases (except -s, -es, |--embed|, --headless) if stdin
+		is not a TTY then it is read as text, so "-" is implied: >
+			echo text | nvim file
 <		The buffer will be marked modified, because it contains text
-		that needs to be saved.  Except when in readonly mode, then
-		the buffer is not marked modified.  Example: >
-			ls | nvim -R -
-<		Starting in Ex mode: >
-			nvim -e -
-			nvim -E
-<		Start editing in |silent-mode|.
+		that needs to be saved (except for readonly |-R| mode).
+
+		To read stdin as Normal commands use |-s| with "-": >
+			echo "ifoo" | nvim -s -
+<		To read stdin as Ex commands use |-es| or |-e|: >
+			echo "echo getpid()" | nvim -e - -V1
+<		To open a file literally named "-", put it after "--": >
+			echo foo | nvim -- -
+<		To read stdin as text with |--headless| use "-".
 
 							*-t* *-tag*
 -t {tag}	A tag.  "tag" is looked up in the tags file, the associated
@@ -191,28 +191,24 @@ argument.
 							*-E*
 -E		Start Vim in improved Ex mode |gQ|.
 
-							*-s-ex* *silent-mode*
--s		Silent or batch mode.  Only when "-s" is preceded by the "-e"
-		argument.  Otherwise see |-s|, which does take an argument
-		while this use of "-s" doesn't.  To be used when Vim is used
-		to execute Ex commands from a file instead of a terminal.
-		Switches off most prompts and informative messages.  Also
-		warnings and error messages.  The output of these commands is
-		displayed (to stdout):
+							*-es* *-Es*
+-es							*-s-ex* *silent-mode*
+-Es		Silent or batch mode: execute Ex commands from a file instead
+		of a terminal.  Special case of |-s| (which takes an argument
+		while "-es" doesn't).  Disables most prompts, messages,
+		warnings and errors.
+		Output of these commands is displayed (to stdout):
 			:print
 			:list
 			:number
 			:set      to display option values.
-		When 'verbose' is non-zero messages are printed (for
-		debugging, to stderr).
+		When 'verbose' is set messages are printed to stderr, e.g.: >
+			echo foo | nvim -V1 -es
+<
+		User |init.vim| is skipped (unless given with |-u|).
 		|$TERM| is not used.
-		If Vim appears to be stuck try typing "qa!<Enter>".  You don't
-		get a prompt thus you can't see Vim is waiting for you to type
-		something.
-		Initializations are skipped (except the ones given with the
-		"-u" argument).
 		Example: >
-			vim -es < thefilter  thefile
+			printf "put ='foo'\n%%print\n" | nvim -es
 <
 							*-b*
 -b		Binary mode.  File I/O will only recognize <NL> to separate
@@ -315,12 +311,15 @@ argument.
 		":rsh" or ":wsh" are used.  See also |shada-file|.
 
 							*-s*
--s {scriptin}	The script file "scriptin" is read.  The characters in the
-		file are interpreted as if you had typed them.  The same can
-		be done with the command ":source! {scriptin}".  If the end
-		of the file is reached before the editor exits, further
-		characters are read from the keyboard.  Only works when not
-		started in Ex mode, see |-s-ex|.  See also |complex-repeat|.
+-s {scriptin}	Read script file {scriptin}, interpreting characters as
+		Normal-mode input.  The same can be done with ":source!": >
+			:source! {scriptin}
+<		Reads from stdin if {scriptin} is "-": >
+			echo "ifoo" | nvim -s -
+<		If the end of the file is reached before Nvim exits, further
+		characters are read from the keyboard.
+
+		Does not work with |-es|.  See also |complex-repeat|.
 
 							*-w_nr*
 -w {number}
@@ -340,11 +339,30 @@ argument.
 							*--api-info*
 --api-info 	Print msgpack-encoded |api-metadata| and exit.
 
+							*--embed*
+--embed		Use stdin/stdout as a msgpack-RPC channel, so applications can
+		embed and control Nvim via the |rpc-api|.  Implies |--headless|.
+		Equivalent to: >
+			nvim --headless --cmd "call stdioopen({'rpc': v:true})"
+<
+		See also |channel-stdio|.
+
 							*--headless*
---headless 	Do not start the built-in UI.
-                See |channel-stdio| for how to use stdio for other purposes
-                instead.
-		See also |silent-mode|, which does start a (limited) UI.
+--headless 	Do not start the default UI, so stdio can be used as an
+		arbitrary communication channel. |channel-stdio|
+
+		Also useful for scripting (tests) to see messages that would
+		not be printed by |-es|.
+
+		To detect if a UI is available, check if |nvim_list_uis()| is
+		empty after |VimEnter|.
+
+		To read stdin as text, "-" must be given explicitly:
+		--headless cannot assume that stdin is just text. >
+			echo foo | nvim --headless +"%print" +"q!" -
+<
+		See also |--embed|.
+		See also |-es|, which also disables most messages.
 
 --listen {addr}						*--listen*
 		Start |RPC| server on pipe or TCP address {addr}. Sets the
@@ -604,27 +622,15 @@ there is not enough room, you will see only part of it).
    To avoid the intro message on startup, add the 'I' flag to 'shortmess'.
 
 							*info-message*
-The |--help| and |--version| arguments cause Vim to print a message and then
+The |--help| and |--version| arguments cause Nvim to print a message and then
 exit.  Normally the message is sent to stdout, thus can be redirected to a
 file with: >
 
-	vim --help >file
-
-From inside Vim: >
+	nvim --help >file
 
-	:read !vim --help
+From inside Nvim: >
 
-When using gvim, it detects that it might have been started from the desktop,
-without a terminal to show messages on.  This is detected when both stdout and
-stderr are not a tty.  This breaks the ":read" command, as used in the example
-above.  To make it work again, set 'shellredir' to ">" instead of the default
-">&": >
-
-	:set shellredir=>
-	:read !gvim --help
-
-This still won't work for systems where gvim does not use stdout at all
-though.
+	:read !nvim --help
 
 ==============================================================================
 3. $VIM and $VIMRUNTIME
@@ -1344,12 +1350,12 @@ file when reading and include:
   complete MessagePack object.
 
 ==============================================================================
-9. Standard Paths
+9. Standard Paths				*standard-path*
 
 Nvim stores configuration and data in standard locations. Plugins are strongly
 encouraged to follow this pattern also.
 
-						      *base-directories* *xdg*
+						*base-directories* *xdg*
 The "base" (root) directories conform to the XDG Base Directory Specification.
 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
 The $XDG_CONFIG_HOME and $XDG_DATA_HOME environment variables are used if they
@@ -1358,22 +1364,19 @@ 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					*$XDG_CONFIG_HOME*
+CONFIG DIRECTORY				*$XDG_CONFIG_HOME*
           Base                Nvim ~
 Unix:     ~/.config           ~/.config/nvim
 Windows:  ~/AppData/Local     ~/AppData/Local/nvim
 
-DATA DIRECTORY						*$XDG_DATA_HOME*
+DATA DIRECTORY					*$XDG_DATA_HOME*
           Base                Nvim ~
 Unix:     ~/.local/share      ~/.local/share/nvim
 Windows:  ~/AppData/Local     ~/AppData/Local/nvim-data
 
-STANDARD PATHS						*standard-path*
-
-							      *$NVIM_LOG_FILE*
-Besides 'debug' and 'verbose', Nvim has a low-level "log of last resort" that
-is written directly to the filesystem. This log may also be used by plugins or
-RPC clients for debugging. $NVIM_LOG_FILE contains the log file path: >
+LOG FILE					*$NVIM_LOG_FILE*
+Besides 'debug' and 'verbose', Nvim keeps a general log file for internal
+debugging, plugins and RPC clients. >
 	:echo $NVIM_LOG_FILE
 Usually the file is ~/.local/share/nvim/log unless that path is inaccessible
 or if $NVIM_LOG_FILE was set before |startup|.
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 6f6df2d7ae..e11fdb5271 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -60,8 +60,8 @@ elements itself; Nvim will not draw those elements on the grid. This is
 controlled by the |ui-ext-options|.
 
 Future versions of Nvim may add new update kinds and may append new parameters
-to existing update kinds. Clients must be prepared to ignore such extensions
-to be forward-compatible. |api-contract|
+to existing update kinds. Clients must be prepared to ignore such extensions,
+for forward-compatibility. |api-contract|
 
 ==============================================================================
 Global Events							    *ui-global*
@@ -97,7 +97,7 @@ Global Events							    *ui-global*
 	listed below:
 
 	'arabicshape'
-	'ambiwith'
+	'ambiwidth'
 	'emoji'
 	'guifont'
 	'guifontset'
@@ -110,7 +110,7 @@ Global Events							    *ui-global*
 	Options are not added to the list if their effects are already taken
 	care of. For instance, instead of forwarding the raw 'mouse' option
 	value, `mouse_on` and `mouse_off` directly indicate if mouse support
-	is active right now. Some options like 'ambiwith' have already taken
+	is active right now. Some options like 'ambiwidth' have already taken
 	effect on the grid, where appropriate empty cells are added, however
 	an ui might still use these options when rendering raw text sent from
 	Nvim, like the text of the cmdline when |ui-ext-cmdline| is set.
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 9232cd70c5..2a9a181b7a 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -253,8 +253,6 @@ g8			Print the hex values of the bytes used in the
 			to a pipe (not a terminal). Use |:terminal| to run an
 			interactive shell connected to a terminal.
 
-			For Win32 also see |:!start|.
-
 			After the command has been executed, the timestamp and
 			size of the current file is checked |timestamp|.
 
@@ -271,21 +269,6 @@ g8			Print the hex values of the bytes used in the
 <			The screen is not redrawn then, thus you have to use
 			CTRL-L or ":redraw!" if the command did display
 			something.
-							*:!start*
-:!start	{cmd}		(Windows only). Special-case of |:!| which works
-			asynchronously, for running a program that does not
-			affect the files you are editing.
-			Optional arguments (can only use one at a time):
-				/min  window will be minimized
-				/b    no console window will be opened
-			Note: If the process requires input, /b will get an
-			EOF error because its input stream (stdin) would be
-			redirected to \\.\NUL (stdout and stderr too).
-
-			Programs begun with :!start do not get passed Vim's
-			open file handles, which means they do not have to be
-			closed before Vim. To avoid this special treatment,
-			use ":! start".
 
 							*:!!*
 :!!			Repeat last ":!{cmd}".
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index ceae8eba8c..6de295303c 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -14,11 +14,10 @@ a complete and centralized reference of those differences.
 ==============================================================================
 1. Configuration					    *nvim-configuration*
 
-- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for storing
-  configuration.
+- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for configuration.
 - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files.
 - Use `$XDG_DATA_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent
-  session information.
+  session information.  |shada|
 
 ==============================================================================
 2. Defaults					            *nvim-defaults*
@@ -35,7 +34,9 @@ a complete and centralized reference of those differences.
 - 'cscopeverbose' is enabled
 - 'directory' defaults to ~/.local/share/nvim/swap// (|xdg|), auto-created
 - 'display' defaults to "lastline,msgsep"
+- 'encoding' is UTF-8 (cf. 'fileencoding' for file-content encoding)
 - 'fillchars' defaults (in effect) to "vert:│,fold:·"
+- 'fsync' is disabled
 - 'formatoptions' defaults to "tcqj"
 - 'history' defaults to 10000 (the maximum)
 - 'hlsearch' is set by default
@@ -117,54 +118,42 @@ by Nvim developers.
 
 FEATURES ~
 
-"Outline": Type |gO| in |:Man| and |:help| pages to see a document outline.
-
-|META| (ALT) chords are recognized, even in the terminal. Any |<M-| mapping
-will work. Some examples: <M-1>, <M-2>, <M-BS>, <M-Del>, <M-Ins>, <M-/>,
-<M-\>, <M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ...
-META chords are case-sensitive: <M-a> and <M-A> are two different keycodes.
-
-Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
-(even in the terminal). Specifically, the following are known to work:
-  <C-Tab>, <C-S-Tab>, <C-BS>, <C-S-BS>, <C-Enter>, <C-S-Enter>
-
-Options:
-  'cpoptions' flags: |cpo-_|
-  'display' flag `msgsep` to minimize scrolling when showing messages
-  'guicursor' works in the terminal
-  'fillchars' flag `msgsep` (see 'display' above)
-  'inccommand' shows interactive results for |:substitute|-like commands
-  'scrollback'
-  'statusline' supports unlimited alignment sections
-  'tabline' %@Func@foo%X can call any function on mouse-click
-  'winhighlight' window-local highlights
-
-Variables:
-  |v:event|
-  |v:exiting|
-  |v:progpath| is always absolute ("full")
-  |v:windowid| is always available (for use by external UIs)
+Command-line highlighting:
+  The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
+  using a built-in VimL expression parser. |expr-highlight|
+					*E5408* *E5409*
+  |input()|, |inputdialog()| support custom highlighting. |input()-highlight|
+					*g:Nvim_color_cmdline*
+  (Experimental) Command-line (|:|) is colored by callback defined in
+  `g:Nvim_color_cmdline` (this callback is for testing only, and will be
+  removed in the future).
 
 Commands:
   |:checkhealth|
-  |:drop| is available on all platforms
+  |:cquit| can use [count] to set the exit code
+  |:drop| is always available
   |:Man| is available by default, with many improvements such as completion
   |:tchdir| tab-local |current-directory|
 
-Functions:
-  |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
-  |dictwatcherdel()|
-  |menu_get()|
-  |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization
-
 Events:
   |DirChanged|
   |TabNewEntered|
   |TermClose|
   |TermOpen|
   |TextYankPost|
+  |VimResume|
+  |VimSuspend|
+
+Functions:
+  |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
+  |dictwatcherdel()|
+  |menu_get()|
+  |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization
+  |stdpath()|
+  |system()|, |systemlist()| can run {cmd} directly (without 'shell')
 
 Highlight groups:
+  |expr-highlight| highlight groups (prefixed with "Nvim")
   |hl-NormalNC| highlights non-current windows
   |hl-MsgSeparator| highlights separator for scrolled messages
   |hl-QuickFixLine|
@@ -172,43 +161,51 @@ Highlight groups:
   |hl-TermCursor|
   |hl-TermCursorNC|
   |hl-Whitespace| highlights 'listchars' whitespace
-  |expr-highlight| highlight groups (prefixed with "Nvim")
 
-Command-line highlighting:
-  The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
-  using a built-in VimL expression parser. |expr-highlight|
-					*E5408* *E5409*
-  |input()|, |inputdialog()| support custom highlighting. |input()-highlight|
-					*g:Nvim_color_cmdline*
-  (Experimental) Command-line (|:|) is colored by callback defined in
-  `g:Nvim_color_cmdline` (this callback is for testing only, and will be
-  removed in the future).
+Input:
+  ALT (|META|) chords always work (even in the |TUI|). Map |<M-| with any key:
+  <M-1>, <M-BS>, <M-Del>, <M-Ins>, <M-/>, <M-\>, <M-Space>, <M-Enter>, etc.
+  Case-sensitive: <M-a> and <M-A> are two different keycodes.
+
+  ALT in insert-mode behaves like <Esc> if not mapped. |i_ALT|
+
+Mappings:
+  |<Cmd>| pseudokey
+
+Normal commands:
+  "Outline": Type |gO| in |:Man| and |:help| pages to see a document outline.
+
+Options:
+  'cpoptions' flags: |cpo-_|
+  'display' flag `msgsep` to minimize scrolling when showing messages
+  'guicursor' works in the terminal
+  'fillchars' flag `msgsep` (see 'display' above)
+  'inccommand' shows interactive results for |:substitute|-like commands
+  'scrollback'
+  'statusline' supports unlimited alignment sections
+  'tabline' %@Func@foo%X can call any function on mouse-click
+  'winhighlight' window-local highlights
+
+Variables:
+  |v:event|
+  |v:exiting|
+  |v:progpath| is always absolute ("full")
+  |v:windowid| is always available (for use by external UIs)
 
 ==============================================================================
 4. Changed features					 *nvim-features-changed*
 
 Nvim always builds with all features, in contrast to Vim which may have
-certain features removed/added at compile-time.  This is like if Vim's "HUGE"
-build was the only Vim release type (except Nvim is smaller than Vim's "HUGE"
-build).
+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 in separate plugins.  The
-`neovim` pip package must be installed to use Python plugins in Nvim (see
-|provider-python|).
-
-Because of general |256-color| usage whereever possible, Nvim will even use
-256-colour capability on Linux virtual terminals.  Vim uses only 8 colours
-plus bright foreground on Linux VTs.
-
-Vim combines what is in its |builtin-terms| with what it reads from termcap,
-and has a |ttybuiltin| setting to control how that combination works.  Nvim
-uses either one or the other of an external |terminfo| entry or the built-in
-one.  It does not attempt to mix data from the two.
+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.
@@ -225,8 +222,6 @@ makes things faster. |:terminal| output is never throttled.
    'p')) mkdir() will silently exit. In Vim this was an error.
 3. mkdir() error messages now include strerror() text when mkdir fails.
 
-'encoding' is always "utf-8".
-
 |string()| and |:echo| behaviour changed:
 1. No maximum recursion depth limit is applied to nested container
    structures.
@@ -309,22 +304,53 @@ Highlight groups:
   |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other
   groups
 
+Macro/|recording| behavior
+  Replay of a macro recorded during :lmap produces the same actions as when it
+  was recorded. In Vim if a macro is recorded while using :lmap'ped keys then
+  the behaviour during record and replay differs.
+
+  'keymap' is implemented via :lmap instead of :lnoremap so that you can use
+  macros and 'keymap' at the same time. This also means you can use |:imap| on
+  the results of keys from 'keymap'.
+
+Options:
+  'ttimeout', 'ttimeoutlen' behavior was simplified
+
+Startup:
+  |-s| reads Normal commands from stdin if the script name is "-".
+  Reading text (instead of commands) from stdin |--|:
+    - works by default: "-" file is optional
+    - works in more cases: |-Es|, file args
+
+TUI:
+			*:set-termcap*
+  Start Nvim with 'verbose' level 3 to show terminal capabilities: >
+	nvim -V3
+<
+			*'term'* *E529* *E530* *E531*
+  'term' reflects the terminal type derived from |$TERM| and other environment
+  checks.  For debugging only; not reliable during startup. >
+	  :echo &term
+<  "builtin_x" means one of the |builtin-terms| was chosen, because the expected
+  terminfo file was not found on the system.
+
+  Nvim will use 256-colour capability on Linux virtual terminals.  Vim uses
+  only 8 colours plus bright foreground on Linux VTs.
+
+  Vim combines what is in its |builtin-terms| with what it reads from terminfo,
+  and has a |ttybuiltin| setting to control how that combination works.  Nvim
+  uses one or the other, it does not attempt to merge the two.
+
 VimL (Vim script) compatibility:
   `count` does not alias to |v:count|
 
-|:lmap|s are applied to macro recordings, in Vim if a macro is recorded while
-using |:lmap|ped keys then the behaviour during record and replay differs.
-'keymap' is implemented via |:lmap| instead of |:lnoremap| in order to allow
-using macros and 'keymap' at the same time.
-This means that you can use |:imap| on the results of keys from 'keymap'.
-
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
 
 Some legacy Vim features are not implemented:
 
 - |if_py|: vim.bindeval() and vim.Function() are not supported
-- |if_lua|: the `vim` object is missing most legacy methods
+- |if_lua|: the `vim` object is missing some legacy methods
 - *if_perl*
 - *if_mzscheme*
 - *if_tcl*
@@ -334,71 +360,43 @@ Some legacy Vim features are not implemented:
 
 These Vim features were intentionally removed from Nvim.
 
-			*'cp'* *'nocompatible'* *'nocp'* *'compatible'*
-Nvim is always "non-compatible" with Vi.
-  ":set nocompatible" is ignored
-  ":set compatible" is an error
+Aliases:
+  ex        (alias for "nvim -e")
+  exim      (alias for "nvim -E")
+  gex       (GUI)
+  gview     (GUI)
+  gvim      (GUI)
+  gvimdiff  (GUI)
+  rgview    (GUI)
+  rgvim     (GUI)
+  rview     (alias for "nvim -RZ")
+  rvim      (alias for "nvim -Z")
+  view      (alias for "nvim -R")
+  vimdiff   (alias for "nvim -d" |diff-mode|)
 
-			*'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
-Ed-compatible mode:
-  ":set noedcompatible" is ignored
-  ":set edcompatible" is an error
-
-			*t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI*
-Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure
-terminal capabilities. Instead Nvim treats the terminal as any other UI. For
-example, 'guicursor' sets the terminal cursor style if possible.
-
-			*:set-termcap*
-Start Nvim with 'verbose' level 3 to see the terminal capabilities. >
-	nvim -V3
-<
-			*'term'* *E529* *E530* *E531*
-'term' reflects the terminal type derived from |$TERM| and other environment
-checks.  For debugging only; not reliable during startup. >
-	:echo &term
-"builtin_x" means one of the |builtin-terms| was chosen, because the expected
-terminfo file was not found on the system.
-
-			*termcap*
-Nvim never uses the termcap database, only |terminfo| and |builtin-terms|.
-
-			*xterm-8bit* *xterm-8-bit*
-Xterm can be run in a mode where it uses true 8-bit CSI.  Supporting this
-requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8
-mode, as the 8-bit CSI character has to be written differently in each case.
-Vim issues a "request version" sequence to the terminal at startup and looks
-at how the terminal is sending CSI.  Nvim does not issue such a sequence and
-always uses 7-bit control sequences.
-
-'ttyfast':
-  ":set ttyfast" is ignored
-  ":set nottyfast" is an error
-
-Encryption support:
-  *'cryptmethod'* *'cm'*
-  *'key'*
-
-MS-DOS support:
-  'bioskey'
-  'conskey'
+Commands:
+  :fixdel
+  :helpfind
+  :mode (no longer accepts an argument)
+  :open
+  :Print
+  :shell
+  :smile
+  :tearoff
 
-Test functions:
-  test_alloc_fail()
-  test_autochdir()
-  test_garbagecollect_now()
-  test_null_channel()
-  test_null_dict()
-  test_null_job()
-  test_null_list()
-  test_null_partial()
-  test_null_string()
-  test_override()
-  test_settime()
+Compile-time features:
+  EBCDIC
+  Emacs tags support
+  X11 integration (see |x11-selection|)
 
-Other options:
+Options:
   'antialias'
-  'cpoptions' (g j k H w < * - and all POSIX flags were removed)
+  'bioskey' (MS-DOS)
+  'conskey' (MS-DOS)
+  *'cp'* *'nocompatible'* *'nocp'* *'compatible'* (Nvim is always "nocompatible".)
+  'cpoptions' (gjkHw<*- and all POSIX flags were removed)
+  *'cryptmethod'* *'cm'* *'key'* (Vim encryption implementation)
+  *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
   'encoding' ("utf-8" is always used)
   'esckeys'
   'guioptions' "t" flag was removed
@@ -423,42 +421,45 @@ Other options:
   *'ttymouse'* *'ttym'*
   *'ttyscroll'* *'tsl'*
   *'ttytype'* *'tty'*
+  'ttyfast'
   'weirdinvert'
 
-Other commands:
-  :Print
-  :fixdel
-  :helpfind
-  :mode (no longer accepts an argument)
-  :open
-  :shell
-  :smile
-  :tearoff
-
-Other compile-time features:
-  EBCDIC
-  Emacs tags support
-  X11 integration (see |x11-selection|)
-
 Startup:
   --literal (file args are always literal; to expand wildcards on Windows, use
     |:n| e.g. `nvim +"n *"`)
+  Easy mode: eview, evim, nvim -y
+  Vi mode: nvim -v
 
-Nvim does not have a built-in GUI and hence the following aliases have been
-removed: gvim, gex, gview, rgvim, rgview
-
-"Easy mode" (eview, evim, nvim -y)
-"(g)vimdiff" (alias for "(g)nvim -d" |diff-mode|)
-"Vi mode" (nvim -v)
-
-The ability to start nvim via the following aliases has been removed in favor
-of just using their command line arguments:
+Test functions:
+  test_alloc_fail()
+  test_autochdir()
+  test_disable_char_avail()
+  test_garbagecollect_now()
+  test_null_channel()
+  test_null_dict()
+  test_null_job()
+  test_null_list()
+  test_null_partial()
+  test_null_string()
+  test_override()
+  test_settime()
 
-  ex        nvim -e
-  exim      nvim -E
-  view      nvim -R
-  rvim      nvim -Z
-  rview     nvim -RZ
+TUI:
+			  *t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI*
+  Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure
+  terminal capabilities. Instead Nvim treats the terminal as any other UI,
+  e.g. 'guicursor' sets the terminal cursor style if possible.
+
+			  *termcap*
+  Nvim never uses the termcap database, only |terminfo| and |builtin-terms|.
+
+			  *xterm-8bit* *xterm-8-bit*
+  Xterm can be run in a mode where it uses true 8-bit CSI.  Supporting this
+  requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8
+  mode, as the 8-bit CSI character has to be written differently in each case.
+  Vim issues a "request version" sequence to the terminal at startup and looks
+  at how the terminal is sending CSI.  Nvim does not issue such a sequence and
+  always uses 7-bit control sequences.
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index b3ae52602b..002d9da781 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -102,12 +102,13 @@ Dictionary nvim_get_hl_by_id(Integer hl_id, Boolean rgb, Error *err)
   return hl_get_attr_by_id(attrcode, rgb, err);
 }
 
-/// Passes input keys to Nvim.
+/// Sends input-keys to Nvim, subject to various quirks controlled by `mode`
+/// flags. This is a blocking call, unlike |nvim_input()|.
 ///
 /// On execution error: does not fail, but updates v:errmsg.
 ///
 /// @param keys         to be typed
-/// @param mode         mapping options
+/// @param mode         behavior flags, see |feedkeys()|
 /// @param escape_csi   If true, escape K_SPECIAL/CSI bytes in `keys`
 /// @see feedkeys()
 /// @see vim_strsave_escape_csi
@@ -169,13 +170,12 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
   }
 }
 
-/// Passes keys to Nvim as raw user-input.
+/// Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a low-level
+/// input buffer and the call is non-blocking (input is processed
+/// asynchronously by the eventloop).
 ///
 /// On execution error: does not fail, but updates v:errmsg.
 ///
-/// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call
-/// is not deferred. This is the most reliable way to send real user input.
-///
 /// @note |keycodes| like <CR> are translated, so "<" is special.
 ///       To input a literal "<", send <LT>.
 ///
diff --git a/src/nvim/main.c b/src/nvim/main.c
index e1a01fdba6..8d98f9e915 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -236,7 +236,7 @@ int main(int argc, char **argv)
   char_u *fname = NULL;   // file name from command line
   mparm_T params;         // various parameters passed between
                           // main() and other functions.
-  char_u *cwd = NULL;     // current workding dir on startup
+  char_u *cwd = NULL;     // current working dir on startup
   time_init();
 
   // Many variables are in `params` so that we can pass them around easily.
diff --git a/src/nvim/os/pty_process_unix.c b/src/nvim/os/pty_process_unix.c
index 71bb2d8a5e..bd23596ea7 100644
--- a/src/nvim/os/pty_process_unix.c
+++ b/src/nvim/os/pty_process_unix.c
@@ -44,6 +44,7 @@ static struct termios termios_default;
 /// @param tty_fd   TTY file descriptor, or -1 if not in a terminal.
 void pty_process_save_termios(int tty_fd)
 {
+  DLOG("tty_fd=%d", tty_fd);
   if (tty_fd == -1 || tcgetattr(tty_fd, &termios_default) != 0) {
     return;
   }
diff --git a/test/README.md b/test/README.md
index 58aa6a06aa..9b1f0d084a 100644
--- a/test/README.md
+++ b/test/README.md
@@ -17,11 +17,6 @@ For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight.
 Running tests
 -------------
 
-Neovim uses third-party tooling to execute tests. So be sure, from the
-repository directory, to build the tools before testing:
-
-    make cmake
-
 ## Executing Tests
 
 To run all _non-legacy_ (unit + functional) tests:
@@ -89,6 +84,7 @@ To run only the tagged tests:
     TEST_TAG=foo make functionaltest
 
 **NOTES**:
+
 * Tags are mainly used for testing issues (ex: `#1234`), so use the following
   method.
 * `TEST_FILE` is not a pattern string like `TEST_TAG` or `TEST_FILTER`. The