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

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)
 

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

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
 --------
 

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 ,

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
+The Nvim C API defines custom types for all function parameters. Some are just
-around C99 standard types, and some are Nvim-defined data structures.
+typedefs around C99 standard types, others are Nvim-defined data structures.
 
-Boolean				  -> bool
+  Boolean				-> bool
-Integer (signed 64-bit integer)	  -> int64_t
+  Integer (signed 64-bit integer)	-> int64_t
-Float (IEEE 754 double precision) -> double
+  Float (IEEE 754 double precision)	-> double
-String				  -> {char* data, size_t size} struct
+  String				-> {char* data, size_t size} struct
-
+  Array
-Additionally, the following data structures are defined:
+  Dictionary
-
+  Object
-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
+  Buffer				-> enum value kObjectTypeBuffer
-Window				  -> enum value kObjectTypeWindow
+  Window				-> enum value kObjectTypeWindow
-Tabpage				  -> enum value kObjectTypeTabpage
+  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
+The Nvim API is composed of functions and events.
-described at |api-global|, and may "attach" to receive rich |ui-events|.
 
-As Nvim develops, its API may change only according the following "contract":
+- 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 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.

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,
+StdinReadPost			During startup, after reading from stdin into
-				before executing the modelines.  Only used
+				the buffer, before executing modelines. |--|
-				when the "-" argument was used when Vim was
-				started |--|.
 							*StdinReadPre*
-StdinReadPre			Before reading from stdin into the buffer.
+StdinReadPre			During startup, before reading from stdin into
-				Only used when the "-" argument was used when
+				the buffer. |--|
-				Vim was started |--|.
 							*SwapExists*
 SwapExists			Detected an existing swap file when starting
 				to edit a file.  Only when it is possible to

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})` .
+Special case: PTY channels opened with `jobstart(..., {'pty': v:true})` do not
-No preprocessing of ANSI escape sequences is done, these will be sent raw to
+preprocess ANSI escape sequences, these will be sent raw to the callback.
-the callback. However, change of PTY size can be signaled to the slave using
+However, change of PTY size can be signaled to the slave using |jobresize()|.
-|jobresize()|. See also |terminal-emulator|.
+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
+Nvim uses stdin/stdout to interact with the user over the terminal interface
-user over the terminal interface (TUI). However when invoked with
+(TUI). If Nvim is |--headless| the TUI is not started and stdin/stdout can be
-`--headless`, the TUI is not started and stdin and stdout can be used as a
+used as a channel. See also |--embed|.
-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.
 
-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:

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.

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:

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

runtime/doc/eval.txt

@@ -7265,10 +7265,8 @@ stdioopen({opts})			 *stdioopen()*
 
 
 stdpath({what})					*stdpath()* *E6100*
-		Returns the standard path(s) for {what}.
+		Returns |standard-path| locations of various default files and
-
+		directories.
-		These directories are the default locations for various files
-		used by Neovim.
 
 		{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* *:endfunction* *E126* *E193* *W22*
-:endf[unction]		The end of a function definition.  Must be on a line
+:endf[unction] [argument]
-			by its own, without other commands.
+			The end of a function definition.  Best is to put it
+			on a line by its own, without [argument].
 
-				    *:delf* *:delfunction* *E130* *E131* *E933*
+			[argument] can be:
-:delf[unction] {name}	Delete function {name}.
+				| 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.

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*

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
+that. Or use a |<Cmd>| mapping (which doesn't have these restrictions).
-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*
+						*<Cmd>* *:map-cmd*
-A command mapping is a mapping that directly executes a command. Command
+The <Cmd> pseudokey may be used to define a "command mapping", which executes
-mappings are written by placing a command in between <Cmd> and <CR> in the
+the command directly (without changing modes, etc.).  Where you might use
-rhs of a mapping (in any mode): >
+":...<CR>" in the {lhs} of a mapping, you can instead use "<Cmd>...<CR>".
-	noremap <f3> <Cmd>echo mode(1)<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
+<Cmd> commands must terminate, that is, they must be followed by <CR> in the
-incomplete, an error is raised. |Command-line| mode is never entered.
+{lhs} of the mapping definition.  |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|.
 
 1.3 MAPPING AND MODES					*:map-modes*
 		*mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* *mapmode-t*

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
+  - Basic types that map natively to msgpack (and have a default
-    representation in msgpack-supported programming languages)
+    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

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: >

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,
+	msgsep		When showing messages longer than 'cmdheight', only
-			only scroll the message lines and not the entire
+			scroll the message lines, not the entire screen. The
-			screen. This also shows a separator line filled with
+			separator line is decorated by |MsgSeparator| and the
-			chars determined by 'fillchars' option, and
+			"msgsep" flag of 'fillchars'.
-			highlighted with the |MsgSeparator| group.
 
 	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}
+'encoding' 'enc'
-	Nvim always uses UTF-8 internally. RPC communication
+	String-encoding used internally and for |RPC| communication.
-	(remote plugins/GUIs) must use UTF-8 strings.
+	Always UTF-8.
 
-	The character encoding of files can be different than UTF-8.
+	See 'fileencoding' to control file-content encoding.
-	This is specified with 'fileencoding'.  The conversion is done with
-	iconv() or as specified with 'charconvert'.
 
 			*'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|
+	File-content encoding for the current buffer. Conversion is done with
-			feature}
+	iconv() or as specified with 'charconvert'.
-	Sets the character encoding for the file of this buffer.
 
-	When 'fileencoding' is different from "utf-8", conversion will be
+	When 'fileencoding' is not UTF-8, conversion will be done when
-	done when writing the file.  For reading see below.
+	writing the file.  For reading see below.
-	When 'fileencoding' is empty, the file will be saved with utf-8
+	When 'fileencoding' is empty, the file will be saved with UTF-8
-	encoding.  (no conversion when reading or writing a file).
+	encoding (no conversion when reading or writing a file).
-		WARNING: Conversion to a non-Unicode encoding can cause loss of
+
-		information! 
+	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'*

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
+required `neovim` Python package. Run |:checkhealth| to verify.
-up-to-date.
 
-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
+- For Python 2 plugins, make sure Python 2.7 is available in your `$PATH`,
-  available in your `$PATH`, then install the `neovim` Python package systemwide: >
+  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
+- For Python 3 plugins, make sure Python 3.4+ is available in your `$PATH`,
-  available in your `$PATH`, then install the `neovim` Python package systemwide: >
+  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.
 

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
+-		Alias for stdin (standard input).
-		mode is to be used.
+		Example: >
-
+			echo text | nvim - file
-		Starting in Normal mode: >
+<		"text" is read into buffer 1, "file" is opened as buffer 2.
-			nvim -
+		In most cases (except -s, -es, |--embed|, --headless) if stdin
-<		Start editing a new buffer, which is filled with text
+		is not a TTY then it is read as text, so "-" is implied: >
-		that is read from stdin.  The commands that would normally be
+			echo text | nvim file
-		read from stdin will now be read from stderr.  Example: >
-			find . -name "*.c" -print | nvim -
 <		The buffer will be marked modified, because it contains text
-		that needs to be saved.  Except when in readonly mode, then
+		that needs to be saved (except for readonly |-R| mode).
-		the buffer is not marked modified.  Example: >
+
-			ls | nvim -R -
+		To read stdin as Normal commands use |-s| with "-": >
-<		Starting in Ex mode: >
+			echo "ifoo" | nvim -s -
-			nvim -e -
+<		To read stdin as Ex commands use |-es| or |-e|: >
-			nvim -E
+			echo "echo getpid()" | nvim -e - -V1
-<		Start editing in |silent-mode|.
+<		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*
+							*-es* *-Es*
--s		Silent or batch mode.  Only when "-s" is preceded by the "-e"
+-es							*-s-ex* *silent-mode*
-		argument.  Otherwise see |-s|, which does take an argument
+-Es		Silent or batch mode: execute Ex commands from a file instead
-		while this use of "-s" doesn't.  To be used when Vim is used
+		of a terminal.  Special case of |-s| (which takes an argument
-		to execute Ex commands from a file instead of a terminal.
+		while "-es" doesn't).  Disables most prompts, messages,
-		Switches off most prompts and informative messages.  Also
+		warnings and errors.
-		warnings and error messages.  The output of these commands is
+		Output of these commands is displayed (to stdout):
-		displayed (to stdout):
 			:print
 			:list
 			:number
 			:set      to display option values.
-		When 'verbose' is non-zero messages are printed (for
+		When 'verbose' is set messages are printed to stderr, e.g.: >
-		debugging, to stderr).
+			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
+-s {scriptin}	Read script file {scriptin}, interpreting characters as
-		file are interpreted as if you had typed them.  The same can
+		Normal-mode input.  The same can be done with ":source!": >
-		be done with the command ":source! {scriptin}".  If the end
+			:source! {scriptin}
-		of the file is reached before the editor exits, further
+<		Reads from stdin if {scriptin} is "-": >
-		characters are read from the keyboard.  Only works when not
+			echo "ifoo" | nvim -s -
-		started in Ex mode, see |-s-ex|.  See also |complex-repeat|.
+<		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.
+--headless 	Do not start the default UI, so stdio can be used as an
-                See |channel-stdio| for how to use stdio for other purposes
+		arbitrary communication channel. |channel-stdio|
-                instead.
+
-		See also |silent-mode|, which does start a (limited) UI.
+		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
+	nvim --help >file
 
-From inside Vim: >
+From inside Nvim: >
 
-	:read !vim --help
+	:read !nvim --help
-
-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.
 
 ==============================================================================
 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*
+LOG FILE					*$NVIM_LOG_FILE*
-
+Besides 'debug' and 'verbose', Nvim keeps a general log file for internal
-							      *$NVIM_LOG_FILE*
+debugging, plugins and RPC clients. >
-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: >
 	: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|.

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 existing update kinds. Clients must be prepared to ignore such extensions,
-to be forward-compatible. |api-contract|
+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.

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}".

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
+- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for configuration.
-  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,16 +118,62 @@ by Nvim developers.
 
 FEATURES ~
 
-"Outline": Type |gO| in |:Man| and |:help| pages to see a document outline.
+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).
 
-|META| (ALT) chords are recognized, even in the terminal. Any |<M-| mapping
+Commands:
-will work. Some examples: <M-1>, <M-2>, <M-BS>, <M-Del>, <M-Ins>, <M-/>,
+  |:checkhealth|
-<M-\>, <M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ...
+  |:cquit| can use [count] to set the exit code
-META chords are case-sensitive: <M-a> and <M-A> are two different keycodes.
+  |:drop| is always available
+  |:Man| is available by default, with many improvements such as completion
+  |:tchdir| tab-local |current-directory|
 
-Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
+Events:
-(even in the terminal). Specifically, the following are known to work:
+  |DirChanged|
-  <C-Tab>, <C-S-Tab>, <C-BS>, <C-S-BS>, <C-Enter>, <C-S-Enter>
+  |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|
+  |hl-Substitute|
+  |hl-TermCursor|
+  |hl-TermCursorNC|
+  |hl-Whitespace| highlights 'listchars' whitespace
+
+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-_|
@@ -145,70 +192,20 @@ Variables:
   |v:progpath| is always absolute ("full")
   |v:windowid| is always available (for use by external UIs)
 
-Commands:
-  |:checkhealth|
-  |:drop| is available on all platforms
-  |: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|
-
-Highlight groups:
-  |hl-NormalNC| highlights non-current windows
-  |hl-MsgSeparator| highlights separator for scrolled messages
-  |hl-QuickFixLine|
-  |hl-Substitute|
-  |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).
-
 ==============================================================================
 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"
+certain features removed/added at compile-time. |feature-compile|
-build was the only Vim release type (except Nvim is smaller than Vim's "HUGE"
-build).
 
 If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
-are always available and may be used simultaneously in separate plugins.  The
+are always available and may be used simultaneously. See |provider-python|.
-`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.
 
 |:!| 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'*
+Aliases:
-Nvim is always "non-compatible" with Vi.
+  ex        (alias for "nvim -e")
-  ":set nocompatible" is ignored
+  exim      (alias for "nvim -E")
-  ":set compatible" is an error
+  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'*
+Commands:
-Ed-compatible mode:
+  :fixdel
-  ":set noedcompatible" is ignored
+  :helpfind
-  ":set edcompatible" is an error
+  :mode (no longer accepts an argument)
+  :open
+  :Print
+  :shell
+  :smile
+  :tearoff
 
-			*t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI*
+Compile-time features:
-Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure
+  EBCDIC
-terminal capabilities. Instead Nvim treats the terminal as any other UI. For
+  Emacs tags support
-example, 'guicursor' sets the terminal cursor style if possible.
+  X11 integration (see |x11-selection|)
 
-			*:set-termcap*
+Options:
-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'
-
-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()
-
-Other 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
+Test functions:
-removed: gvim, gex, gview, rgvim, rgview
+  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()
 
-"Easy mode" (eview, evim, nvim -y)
+TUI:
-"(g)vimdiff" (alias for "(g)nvim -d" |diff-mode|)
+			  *t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI*
-"Vi mode" (nvim -v)
+  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.
 
-The ability to start nvim via the following aliases has been removed in favor
+			  *termcap*
-of just using their command line arguments:
+  Nvim never uses the termcap database, only |terminfo| and |builtin-terms|.
 
-  ex        nvim -e
+			  *xterm-8bit* *xterm-8-bit*
-  exim      nvim -E
+  Xterm can be run in a mode where it uses true 8-bit CSI.  Supporting this
-  view      nvim -R
+  requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8
-  rvim      nvim -Z
+  mode, as the 8-bit CSI character has to be written differently in each case.
-  rview     nvim -RZ
+  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:

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>.
 ///

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.

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;
   }

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