Merge remote-tracking branch 'upstream/master' into userreg

12 files changed, 413 insertions, 213 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index a388592981..89baf84c86 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -750,7 +750,7 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
                 • highlights: (boolean) Return highlight information.
                 • use_winbar: (boolean) Evaluate winbar instead of statusline.
                 • use_tabline: (boolean) Evaluate tabline instead of
-                  statusline. When |TRUE|, {winid} is ignored. Mutually
+                  statusline. When true, {winid} is ignored. Mutually
                   exclusive with {use_winbar}.
 
     Return: ~
@@ -759,7 +759,7 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
         • width: (number) Display width of the statusline.
         • highlights: Array containing highlight information of the
           statusline. Only included when the "highlights" key in {opts} is
-          |TRUE|. Each element of the array is a |Dictionary| with these keys:
+          true. Each element of the array is a |Dictionary| with these keys:
           • start: (number) Byte index (0-based) of first character that uses
             the highlight.
           • group: (string) Name of highlight group.
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 0be9e9b9d1..a2e15142e7 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -400,6 +400,7 @@ setbufvar({buf}, {varname}, {val})	set {varname} in buffer {buf} to {val}
 setcellwidths({list})		none	set character cell width overrides
 setcharpos({expr}, {list})	Number	set the {expr} position to {list}
 setcharsearch({dict})		Dict	set character search from {dict}
+setcmdline({str} [, {pos}])	Number	set command-line
 setcmdpos({pos})		Number	set cursor position in command-line
 setcursorcharpos({list})	Number	move cursor to position in {list}
 setenv({name}, {val})		none	set environment variable
@@ -784,7 +785,8 @@ browsedir({title}, {initdir})
 		browsing is not possible, an empty string is returned.
 
 bufadd({name})						*bufadd()*
-		Add a buffer to the buffer list with String {name}.
+		Add a buffer to the buffer list with name {name} (must be a
+		String).
 		If a buffer for file {name} already exists, return that buffer
 		number.  Otherwise return the buffer number of the newly
 		created buffer.  When {name} is an empty string then a new
@@ -835,7 +837,8 @@ bufload({buf})						*bufload()*
 		Ensure the buffer {buf} is loaded.  When the buffer name
 		refers to an existing file then the file is read.  Otherwise
 		the buffer will be empty.  If the buffer was already loaded
-		then there is no change.
+		then there is no change.  If the buffer is not related to a
+		file the no file is read (e.g., when 'buftype' is "nofile").
 		If there is an existing swap file for the file of the buffer,
 		there will be no dialog, the buffer will be loaded anyway.
 		The {buf} argument is used like with |bufexists()|.
@@ -1027,7 +1030,7 @@ chanclose({id} [, {stream}])				*chanclose()*
 		are closed. If the channel is a pty, this will then close the
 		pty master, sending SIGHUP to the job process.
 		For a socket, there is only one stream, and {stream} should be
-		ommited.
+		omitted.
 
 chansend({id}, {data})					*chansend()*
 		Send data to channel {id}. For a job, it writes it to the
@@ -1136,6 +1139,9 @@ chdir({dir})						*chdir()*
 			   " ... do some work
 			   call chdir(save_dir)
 			endif
+
+<		Can also be used as a |method|: >
+			GetDir()->chdir()
 <
 cindent({lnum})						*cindent()*
 		Get the amount of indent for line {lnum} according the C
@@ -1526,6 +1532,18 @@ cursor({list})
 		Can also be used as a |method|: >
 			GetCursorPos()->cursor()
 
+debugbreak({pid})					*debugbreak()*
+		Specifically used to interrupt a program being debugged.  It
+		will cause process {pid} to get a SIGTRAP.  Behavior for other
+		processes is undefined. See |terminal-debugger|.
+		{Sends a SIGINT to a process {pid} other than MS-Windows}
+
+		Returns |TRUE| if successfully interrupted the program.
+		Otherwise returns |FALSE|.
+
+		Can also be used as a |method|: >
+			GetPid()->debugbreak()
+
 deepcopy({expr} [, {noref}])				*deepcopy()* *E698*
 		Make a copy of {expr}.  For Numbers and Strings this isn't
 		different from using {expr} directly.
@@ -1967,18 +1985,6 @@ exp({expr})						*exp()*
 		Can also be used as a |method|: >
 			Compute()->exp()
 
-debugbreak({pid})					*debugbreak()*
-		Specifically used to interrupt a program being debugged.  It
-		will cause process {pid} to get a SIGTRAP.  Behavior for other
-		processes is undefined. See |terminal-debugger|.
-		{Sends a SIGINT to a process {pid} other than MS-Windows}
-
-		Returns |TRUE| if successfully interrupted the program.
-		Otherwise returns |FALSE|.
-
-		Can also be used as a |method|: >
-			GetPid()->debugbreak()
-
 expand({string} [, {nosuf} [, {list}]])				*expand()*
 		Expand wildcards and the following special keywords in 
 		{string}.  'wildignorecase' applies.
@@ -2010,6 +2016,8 @@ expand({string} [, {nosuf} [, {list}]])				*expand()*
 					a function
 			<SID>		"<SNR>123_"  where "123" is the
 					current script ID  |<SID>|
+			<script>	sourced script file, or script file
+					where the current function was defined
 			<stack>		call stack
 			<cword>		word under the cursor
 			<cWORD>		WORD under the cursor
@@ -2043,6 +2051,9 @@ expand({string} [, {nosuf} [, {list}]])				*expand()*
 		is not defined, an empty string is used.  Using "%:p" in a
 		buffer with no name, results in the current directory, with a
 		'/' added.
+		When 'verbose' is set then expanding '%', '#' and <> items
+		will result in an error message if the argument cannot be
+		expanded.
 
 		When {string} does not start with '%', '#' or '<', it is
 		expanded like a file name is expanded on the command line.
@@ -2870,7 +2881,8 @@ getcmdcompltype()					*getcmdcompltype()*
 		Only works when the command line is being edited, thus
 		requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
 		See |:command-completion| for the return string.
-		Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
+		Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
+		|setcmdline()|.
 		Returns an empty string when completion is not defined.
 
 getcmdline()						*getcmdline()*
@@ -2879,7 +2891,8 @@ getcmdline()						*getcmdline()*
 		|c_CTRL-R_=|.
 		Example: >
 			:cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
-<		Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
+<		Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
+		|setcmdline()|.
 		Returns an empty string when entering a password or using
 		|inputsecret()|.
 
@@ -2889,7 +2902,8 @@ getcmdpos()						*getcmdpos()*
 		Only works when editing the command line, thus requires use of
 		|c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
 		Returns 0 otherwise.
-		Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
+		Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
+		|setcmdline()|.
 
 getcmdscreenpos()					*getcmdscreenpos()*
 		Return the screen position of the cursor in the command line
@@ -2898,7 +2912,8 @@ getcmdscreenpos()					*getcmdscreenpos()*
 		Only works when editing the command line, thus requires use of
 		|c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
 		Returns 0 otherwise.
-		Also see |getcmdpos()|, |setcmdpos()|.
+		Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and
+		|setcmdline()|.
 
 getcmdtype()						*getcmdtype()*
 		Return the current command-line type. Possible return values
@@ -4963,7 +4978,7 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
 		highlighted matches. The dict can have the following members:
 
 			conceal	    Special character to show instead of the
-				    match (only for |hl-Conceal| highlighed
+				    match (only for |hl-Conceal| highlighted
 				    matches, see |:syn-cchar|)
 			window	    Instead of the current window use the
 				    window with this number or window ID.
@@ -6417,8 +6432,10 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])
 		starts in column zero and then matches before the cursor are
 		skipped.  When the 'c' flag is present in 'cpo' the next
 		search starts after the match.  Without the 'c' flag the next
-		search starts one column further.  This matters for
-		overlapping matches.
+		search starts one column after the start of the match.  This
+		matters for overlapping matches.  See |cpo-c|.  You can also
+		insert "\ze" to change where the match ends, see  |/\ze|.
+
 		When searching backwards and the 'z' flag is given then the
 		search starts in column zero, thus no match in the current
 		line will be found (unless wrapping around the end of the
@@ -6900,6 +6917,16 @@ setcharsearch({dict})					*setcharsearch()*
 		Can also be used as a |method|: >
 			SavedSearch()->setcharsearch()
 
+setcmdline({str} [, {pos}])					*setcmdline()*
+		Set the command line to {str} and set the cursor position to
+		{pos}.
+		If {pos} is omitted, the cursor is positioned after the text.
+		Returns 0 when successful, 1 when not editing the command
+		line.
+
+		Can also be used as a |method|: >
+			GetText()->setcmdline()
+
 setcmdpos({pos})					*setcmdpos()*
 		Set the cursor position in the command line to byte position
 		{pos}.  The first position is 1.
@@ -6912,8 +6939,8 @@ setcmdpos({pos})					*setcmdpos()*
 		before inserting the resulting text.
 		When the number is too big the cursor is put at the end of the
 		line.  A number smaller than one has undefined results.
-		Returns FALSE when successful, TRUE when not editing the
-		command line.
+		Returns 0 when successful, 1 when not editing the command
+		line.
 
 		Can also be used as a |method|: >
 			GetPos()->setcmdpos()
@@ -7697,14 +7724,13 @@ stdpath({what})					*stdpath()* *E6100*
 		config       String  User configuration directory. |init.vim|
 		                     is stored here.
 		config_dirs  List    Other configuration directories.
-		data         String  User data directory. The |shada-file|
-		                     is stored here.
+		data         String  User data directory.
 		data_dirs    List    Other data directories.
 		log          String  Logs directory (for use by plugins too).
 		run          String  Run directory: temporary, local storage
 				     for sockets, named pipes, etc.
 		state        String  Session state directory: storage for file
-				     drafts, undo, shada, etc.
+				     drafts, undo, |shada|, etc.
 
 		Example: >
 			:echo stdpath("config")
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 29eff75bfa..f19671e713 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -881,7 +881,7 @@ Note: these are typed literally, they are not special keys!
 		   file name of the sourced file.  *E498*
 		   When executing a function, is replaced with the call stack,
 		   as with <stack> (this is for backwards compatibility, using
-		   <stack> is preferred).
+		   <stack> or <script> is preferred).
 		   Note that filename-modifiers are useless when <sfile> is
 		   not used inside a script.
 							*:<stack>* *<stack>*
@@ -891,6 +891,12 @@ Note: these are typed literally, they are not special keys!
 		   ".." in between items.  E.g.:
 		   "function {function-name1}[{lnum}]..{function-name2}[{lnum}]"
 		   If there is no call stack you get error *E489* .
+							*:<script>* *<script>*
+	<script>   When executing a `:source` command, is replaced with the file
+		   name of the sourced file.  When executing a function, is
+		   replaced with the file name of the script where it is
+		   defined.
+		   If the file name cannot be determined you get error *E1274* .
 							*:<slnum>* *<slnum>*
 	<slnum>	   When executing a `:source` command, is replaced with the
 		   line number.  *E842*
diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt
index 1a1d8e30b0..c5411b5f16 100644
--- a/runtime/doc/indent.txt
+++ b/runtime/doc/indent.txt
@@ -979,25 +979,38 @@ indentation: >
 PYTHON							*ft-python-indent*
 
 The amount of indent can be set for the following situations.  The examples
-given are the defaults.  Note that the variables are set to an expression, so
-that you can change the value of 'shiftwidth' later.
+given are the defaults.  Note that the dictionary values are set to an
+expression, so that you can change the value of 'shiftwidth' later.
 
 Indent after an open paren: >
-	let g:pyindent_open_paren = 'shiftwidth() * 2'
+	let g:python_indent.open_paren = 'shiftwidth() * 2'
 Indent after a nested paren: >
-	let g:pyindent_nested_paren = 'shiftwidth()'
+	let g:python_indent.nested_paren = 'shiftwidth()'
 Indent for a continuation line: >
-	let g:pyindent_continue = 'shiftwidth() * 2'
+	let g:python_indent.continue = 'shiftwidth() * 2'
+
+By default, the closing paren on a multiline construct lines up under the first
+non-whitespace character of the previous line.
+If you prefer that it's lined up under the first character of the line that
+starts the multiline construct, reset this key: >
+	let g:python_indent.closed_paren_align_last_line = v:false
 
 The method uses |searchpair()| to look back for unclosed parentheses.  This
 can sometimes be slow, thus it timeouts after 150 msec.  If you notice the
 indenting isn't correct, you can set a larger timeout in msec: >
-	let g:pyindent_searchpair_timeout = 500
+	let g:python_indent.searchpair_timeout = 500
 
 If looking back for unclosed parenthesis is still too slow, especially during
 a copy-paste operation, or if you don't need indenting inside multi-line
 parentheses, you can completely disable this feature: >
-	let g:pyindent_disable_parentheses_indenting = 1
+	let g:python_indent.disable_parentheses_indenting = 1
+
+For backward compatibility, these variables are also supported: >
+	g:pyindent_open_paren
+	g:pyindent_nested_paren
+	g:pyindent_continue
+	g:pyindent_searchpair_timeout
+	g:pyindent_disable_parentheses_indenting
 
 
 R								*ft-r-indent*
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 7fc0daa0ca..3393a1a1fd 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -126,13 +126,14 @@ FAQ                                                     *lsp-faq*
      "after/ftplugin/python.vim".
 
 - Q: How do I run a request synchronously (e.g. for formatting on file save)?
-  A: Use the `_sync` variant of the function provided by |lsp-buf|, if it
-     exists.
+  A: Check if the function has an `async` parameter and set the value to
+  false.
 
      E.g. code formatting: >
 
      " Auto-format *.rs (rust) files prior to saving them
-     autocmd BufWritePre *.rs lua vim.lsp.buf.formatting_sync(nil, 1000)
+     " (async = false is the default for format)
+     autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
 
 <
                                                            *lsp-vs-treesitter*
@@ -468,7 +469,7 @@ LspCodeLens
     |nvim_buf_set_extmark()|.
 
 LspCodeLensSeparator                                 *hl-LspCodeLensSeparator*
-    Used to color the separator between two or more code lens.
+    Used to color the separator between two or more code lenses.
 
                                                      *lsp-highlight-signature*
 
@@ -825,7 +826,7 @@ start({config}, {opts})                                      *vim.lsp.start()*
                     re-uses a client if name and root_dir matches.
 
     Return: ~
-        (number) client_id
+        (number|nil) client_id
 
 start_client({config})                                *vim.lsp.start_client()*
     Starts and initializes a client with the given configuration.
@@ -835,9 +836,16 @@ start_client({config})                                *vim.lsp.start_client()*
     The following parameters describe fields in the {config} table.
 
     Parameters: ~
-        {cmd}                (required, string or list treated like
-                             |jobstart()|) Base command that initiates the LSP
-                             client.
+        {cmd}                (table|string|fun(dispatchers: table):table)
+                             command string or list treated like |jobstart|.
+                             The command must launch the language server
+                             process. `cmd` can also be a function that
+                             creates an RPC client. The function receives a
+                             dispatchers table and must return a table with
+                             the functions `request`, `notify`, `is_closing`
+                             and `terminate` See |vim.lsp.rpc.request| and
+                             |vim.lsp.rpc.notify| For TCP there is a built-in
+                             rpc client factory: |vim.lsp.rpc.connect|
         {cmd_cwd}            (string, default=|getcwd()|) Directory to launch
                              the `cmd` process. Not related to `root_dir`.
         {cmd_env}            (table) Environment flags to pass to the LSP on
@@ -1890,6 +1898,17 @@ should_log({level})                                 *vim.lsp.log.should_log()*
 ==============================================================================
 Lua module: vim.lsp.rpc                                              *lsp-rpc*
 
+connect({host}, {port})                                *vim.lsp.rpc.connect()*
+    Create a LSP RPC client factory that connects via TCP to the given host
+    and port
+
+    Parameters: ~
+        {host}  (string)
+        {port}  (number)
+
+    Return: ~
+        (function)
+
 format_rpc_error({err})                       *vim.lsp.rpc.format_rpc_error()*
     Constructs an error message from an LSP error object.
 
@@ -1904,7 +1923,7 @@ notify({method}, {params})                              *vim.lsp.rpc.notify()*
 
     Parameters: ~
         {method}  (string) The invoked LSP method
-        {params}  (table): Parameters for the invoked LSP method
+        {params}  (table|nil): Parameters for the invoked LSP method
 
     Return: ~
         (bool) `true` if notification could be sent, `false` if not
@@ -1915,7 +1934,8 @@ request({method}, {params}, {callback}, {notify_reply_callback})
 
     Parameters: ~
         {method}                 (string) The invoked LSP method
-        {params}                 (table) Parameters for the invoked LSP method
+        {params}                 (table|nil) Parameters for the invoked LSP
+                                 method
         {callback}               (function) Callback to invoke
         {notify_reply_callback}  (function|nil) Callback to invoke as soon as
                                  a request is no longer pending
@@ -1962,11 +1982,8 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
         Methods:
         • `notify()` |vim.lsp.rpc.notify()|
         • `request()` |vim.lsp.rpc.request()|
-
-        Members:
-        • {pid} (number) The LSP server's PID.
-        • {handle} A handle for low-level interaction with the LSP server
-          process |vim.loop|.
+        • `is_closing()` returns a boolean indicating if the RPC is closing.
+        • `terminate()` terminates the RPC client.
 
 
 ==============================================================================
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 42f3a5e432..499b3f9a6f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -881,6 +881,22 @@ vim.str_byteindex({str}, {index} [, {use_utf16}])        *vim.str_byteindex()*
     An {index} in the middle of a UTF-16 sequence is rounded upwards to
     the end of that sequence.
 
+vim.iconv({str}, {from}, {to}[, {opts}])                        *vim.iconv()*
+        The result is a String, which is the text {str} converted from
+        encoding {from} to encoding {to}. When the conversion fails `nil` is
+        returned.  When some characters could not be converted they
+        are replaced with "?".
+        The encoding names are whatever the iconv() library function
+        can accept, see ":Man 3 iconv".
+
+        Parameters: ~
+            {str}   (string) Text to convert
+            {from}  (string) Encoding of {str}
+            {to}    (string) Target encoding
+
+        Returns: ~
+            Converted string if conversion succeeds, `nil` otherwise.
+
 vim.schedule({callback})                                      *vim.schedule()*
     Schedules {callback} to be invoked soon by the main event-loop. Useful
     to avoid |textlock| or other temporary restrictions.
@@ -1075,17 +1091,13 @@ vim.env                                                              *vim.env*
         print(vim.env.TERM)
 <
 
+                                                                 *lua-options*
                                                              *lua-vim-options*
-                                                                 *lua-vim-opt*
                                                                  *lua-vim-set*
-                                                            *lua-vim-optlocal*
                                                             *lua-vim-setlocal*
 
-In Vimscript, there is a way to set options |set-option|. In Lua, the
-corresponding method is `vim.opt`.
-
-`vim.opt` provides several conveniences for setting and controlling options
-from within Lua.
+Vim options can be accessed through |vim.o|, which behaves like Vimscript
+|:set|.
 
     Examples: ~
 
@@ -1094,62 +1106,145 @@ from within Lua.
             `set number`
 
         In Lua:
-            `vim.opt.number = true`
+            `vim.o.number = true`
+
+    To set a string value:
+        In Vimscript:
+            `set wildignore=*.o,*.a,__pycache__`
+
+        In Lua:
+            `vim.o.wildignore = '*.o,*.a,__pycache__'`
+
+Similarly, there exist |vim.bo| and |vim.wo| for setting buffer-local and
+window-local options, respectively, similarly to |:setlocal|. There is also
+|vim.go| that only sets the global value of a |global-local| option, see
+|:setglobal|. The following table summarizes this relation.
+
+    lua            command      global_value       local_value ~
+vim.o           :set                set                set
+vim.bo/vim.wo   :setlocal            -                 set
+vim.go          :setglobal          set                 -
+
+
+vim.o                                                                  *vim.o*
+    Get or set editor options, like |:set|. Invalid key is an error.
+
+    Example: >
+        vim.o.cmdheight = 4
+        print(vim.o.columns)
+        print(vim.o.foo)     -- error: invalid key
+<
+vim.go                                                                *vim.go*
+    Get or set an |option|. Invalid key is an error.
+
+    This is a wrapper around |nvim_set_option_value()| and
+    |nvim_get_option_value()|.
+
+    NOTE: This is different from |vim.o| because this ONLY sets the global
+    option, which generally produces confusing behavior for options with
+    |global-local| values.
+
+    Example: >
+        vim.go.cmdheight = 4
+        print(vim.go.columns)
+        print(vim.go.bar)     -- error: invalid key
+<
+vim.bo[{bufnr}]                                                                *vim.bo*
+    Get or set buffer-scoped |local-options| for the buffer with number {bufnr}.
+    If [{bufnr}] is omitted, use the current buffer. Invalid {bufnr} or key is
+    an error.
+
+    This is a wrapper around |nvim_set_option_value()| and
+    |nvim_get_option_value()| with `opts = {scope = local, buf = bufnr}` .
+
+    Example: >
+        local bufnr = vim.api.nvim_get_current_buf()
+        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+        print(vim.bo.comments)
+        print(vim.bo.baz)                 -- error: invalid key
+<
+vim.wo[{winid}]                                                                *vim.wo*
+    Get or set window-scoped |local-options| for the window with handle {winid}.
+    If [{winid}] is omitted, use the current window. Invalid {winid} or key
+    is an error.
+
+    This is a wrapper around |nvim_set_option_value()| and
+    |nvim_get_option_value()| with `opts = {scope = local, win = winid}` .
+
+    Example: >
+        local winid = vim.api.nvim_get_current_win()
+        vim.wo[winid].number = true    -- same as vim.wo.number = true
+        print(vim.wo.foldmarker)
+        print(vim.wo.quux)             -- error: invalid key
+<
+
+
+
+                                                                          *lua-vim-opt*
+                                                                     *lua-vim-optlocal*
+                                                                    *lua-vim-optglobal*
+                                                                              *vim.opt*
+
+
+A special interface |vim.opt| exists for conveniently interacting with list-
+and map-style option from Lua: It allows accessing them as Lua tables and
+offers object-oriented method for adding and removing entries.
+
+    Examples: ~
 
-    To set an array of values:
+    The following methods of setting a list-style option are equivalent:
         In Vimscript:
             `set wildignore=*.o,*.a,__pycache__`
 
-        In Lua, there are two ways you can do this now. One is very similar to
-        the Vimscript form:
-            `vim.opt.wildignore = '*.o,*.a,__pycache__'`
+        In Lua using `vim.o`:
+            `vim.o.wildignore = '*.o,*.a,__pycache__'`
 
-        However, vim.opt also supports a more elegent way of setting
-        list-style options by using lua tables:
+        In Lua using `vim.opt`:
             `vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }`
 
     To replicate the behavior of |:set+=|, use: >
 
-        -- vim.opt supports appending options via the "+" operator
-        vim.opt.wildignore = vim.opt.wildignore + { "*.pyc", "node_modules" }
-
-        -- or using the `:append(...)` method
         vim.opt.wildignore:append { "*.pyc", "node_modules" }
 <
     To replicate the behavior of |:set^=|, use: >
 
-        -- vim.opt supports prepending options via the "^" operator
-        vim.opt.wildignore = vim.opt.wildignore ^ { "new_first_value" }
-
-        -- or using the `:prepend(...)` method
         vim.opt.wildignore:prepend { "new_first_value" }
 <
     To replicate the behavior of |:set-=|, use: >
 
-        -- vim.opt supports removing options via the "-" operator
-        vim.opt.wildignore = vim.opt.wildignore - { "node_modules" }
-
-        -- or using the `:remove(...)` method
         vim.opt.wildignore:remove { "node_modules" }
 <
-    To set a map of values:
+    The following methods of setting a map-style option are equivalent:
         In Vimscript:
             `set listchars=space:_,tab:>~`
 
-        In Lua:
+        In Lua using `vim.o`:
+            `vim.o.listchars = 'space:_,tab:>~'`
+
+        In Lua using `vim.opt`:
             `vim.opt.listchars = { space = '_', tab = '>~' }`
 
 
+Note that |vim.opt| returns an `Option` object, not the value of the option,
+which is accessed through |Option:get()|:
+
+    Examples: ~
+
+    The following methods of getting a list-style option are equivalent:
+        In Vimscript:
+            `echo wildignore`
+
+        In Lua using `vim.o`:
+            `print(vim.o.wildignore)`
+
+        In Lua using `vim.opt`:
+            `vim.pretty_print(vim.opt.wildignore:get())`
+
+
 In any of the above examples, to replicate the behavior |setlocal|, use
 `vim.opt_local`. Additionally, to replicate the behavior of |setglobal|, use
 `vim.opt_global`.
-                                                                     *vim.opt*
-
-|vim.opt| returns an Option object.
-
-For example: `local listchar_object = vim.opt.listchars`
 
-An `Option` has the following methods:
 
 
                                                                *vim.opt:get()*
@@ -1162,7 +1257,7 @@ Option:get()
     the values as entries in the array: >
         vim.cmd [[set wildignore=*.pyc,*.o]]
 
-        print(vim.inspect(vim.opt.wildignore:get()))
+        vim.pretty_print(vim.opt.wildignore:get())
         -- { "*.pyc", "*.o", }
 
         for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
@@ -1175,7 +1270,7 @@ Option:get()
     the names as keys and the values as entries: >
         vim.cmd [[set listchars=space:_,tab:>~]]
 
-        print(vim.inspect(vim.opt.listchars:get()))
+        vim.pretty_print(vim.opt.listchars:get())
         --  { space = "_", tab = ">~", }
 
         for char, representation in pairs(vim.opt.listchars:get()) do
@@ -1186,7 +1281,7 @@ Option:get()
     as keys and `true` as entries. >
         vim.cmd [[set formatoptions=njtcroql]]
 
-        print(vim.inspect(vim.opt.formatoptions:get()))
+        vim.pretty_print(vim.opt.formatoptions:get())
         -- { n = true, j = true, c = true, ... }
 
         local format_opts = vim.opt.formatoptions:get()
@@ -1222,71 +1317,6 @@ Option:remove(value)
         `vim.opt.wildignore = vim.opt.wildignore - '*.pyc'`
 
 
-In general, using `vim.opt` will provide the expected result when the user is
-used to interacting with editor |options| via `set`. There are still times
-where the user may want to set particular options via a shorthand in Lua,
-which is where |vim.o|, |vim.bo|, |vim.wo|, and |vim.go| come into play.
-
-The behavior of |vim.o|, |vim.bo|, |vim.wo|, and |vim.go| is designed to
-follow that of |:set|, |:setlocal|, and |:setglobal| which can be seen in the
-table below:
-
-    lua            command      global_value       local_value ~
-vim.o           :set                set                set
-vim.bo/vim.wo   :setlocal            -                 set
-vim.go          :setglobal          set                 -
-
-vim.o                                                                  *vim.o*
-    Get or set editor options, like |:set|. Invalid key is an error.
-
-    Example: >
-        vim.o.cmdheight = 4
-        print(vim.o.columns)
-        print(vim.o.foo)     -- error: invalid key
-<
-vim.go                                                                *vim.go*
-    Get or set an |option|. Invalid key is an error.
-
-    This is a wrapper around |nvim_set_option_value()| and
-    |nvim_get_option_value()|.
-
-    NOTE: This is different from |vim.o| because this ONLY sets the global
-    option, which generally produces confusing behavior for options with
-    |global-local| values.
-
-    Example: >
-        vim.go.cmdheight = 4
-        print(vim.go.columns)
-        print(vim.go.bar)     -- error: invalid key
-<
-vim.bo[{bufnr}]                                                                *vim.bo*
-    Get or set buffer-scoped |local-options| for the buffer with number {bufnr}.
-    If [{bufnr}] is omitted, use the current buffer. Invalid {bufnr} or key is
-    an error.
-
-    This is a wrapper around |nvim_set_option_value()| and
-    |nvim_get_option_value()| with `opts = {scope = local, buf = bufnr}` .
-
-    Example: >
-        local bufnr = vim.api.nvim_get_current_buf()
-        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
-        print(vim.bo.comments)
-        print(vim.bo.baz)                 -- error: invalid key
-<
-vim.wo[{winid}]                                                                *vim.wo*
-    Get or set window-scoped |local-options| for the window with handle {winid}.
-    If [{winid}] is omitted, use the current window. Invalid {winid} or key
-    is an error.
-
-    This is a wrapper around |nvim_set_option_value()| and
-    |nvim_get_option_value()| with `opts = {scope = local, win = winid}` .
-
-    Example: >
-        local winid = vim.api.nvim_get_current_win()
-        vim.wo[winid].number = true    -- same as vim.wo.number = true
-        print(vim.wo.foldmarker)
-        print(vim.wo.quux)             -- error: invalid key
-<
 ==============================================================================
 Lua module: vim                                                      *lua-vim*
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 6637464460..6a8ab21d74 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2454,28 +2454,30 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'fillchars'* *'fcs'*
 'fillchars' 'fcs'	string	(default "")
 			global or local to window |global-local|
-	Characters to fill the statuslines and vertical separators.
-	It is a comma-separated list of items:
+	Characters to fill the statuslines, vertical separators and special
+	lines in the window.
+	It is a comma-separated list of items.  Each item has a name, a colon
+	and the value of that item:
 
 	  item		default		Used for ~
-	  stl:c		' ' or '^'	statusline of the current window
-	  stlnc:c	' ' or '='	statusline of the non-current windows
-	  wbr:c		' '		window bar
-	  horiz:c	'─' or '-'	horizontal separators |:split|
-	  horizup:c	'┴' or '-'	upwards facing horizontal separator
-	  horizdown:c	'┬' or '-'	downwards facing horizontal separator
-	  vert:c	'│' or '|'	vertical separators |:vsplit|
-	  vertleft:c	'┤' or '|'	left facing vertical separator
-	  vertright:c	'├' or '|'	right facing vertical separator
-	  verthoriz:c	'┼' or '+'	overlapping vertical and horizontal
+	  stl		' ' or '^'	statusline of the current window
+	  stlnc		' ' or '='	statusline of the non-current windows
+	  wbr		' '		window bar
+	  horiz		'─' or '-'	horizontal separators |:split|
+	  horizup	'┴' or '-'	upwards facing horizontal separator
+	  horizdown	'┬' or '-'	downwards facing horizontal separator
+	  vert		'│' or '|'	vertical separators |:vsplit|
+	  vertleft	'┤' or '|'	left facing vertical separator
+	  vertright	'├' or '|'	right facing vertical separator
+	  verthoriz	'┼' or '+'	overlapping vertical and horizontal
 					separator
-	  fold:c	'·' or '-'	filling 'foldtext'
-	  foldopen:c	'-'		mark the beginning of a fold
-	  foldclose:c	'+'		show a closed fold
-	  foldsep:c	'│' or '|'      open fold middle marker
-	  diff:c	'-'		deleted lines of the 'diff' option
-	  msgsep:c	' '		message separator 'display'
-	  eob:c		'~'		empty lines at the end of a buffer
+	  fold		'·' or '-'	filling 'foldtext'
+	  foldopen	'-'		mark the beginning of a fold
+	  foldclose	'+'		show a closed fold
+	  foldsep	'│' or '|'      open fold middle marker
+	  diff		'-'		deleted lines of the 'diff' option
+	  msgsep	' '		message separator 'display'
+	  eob		'~'		empty lines at the end of a buffer
 
 	Any one that is omitted will fall back to the default.  For "stl" and
 	"stlnc" the space will be used when there is highlighting, '^' or '='
@@ -2500,19 +2502,19 @@ A jump table for the options with a short description can be found at |Q_op|.
 
 	The highlighting used for these items:
 	  item		highlight group ~
-	  stl:c		StatusLine		|hl-StatusLine|
-	  stlnc:c	StatusLineNC		|hl-StatusLineNC|
-	  wbr:c		WinBar			|hl-WinBar| or |hl-WinBarNC|
-	  horiz:c	WinSeparator		|hl-WinSeparator|
-	  horizup:c	WinSeparator		|hl-WinSeparator|
-	  horizdown:c	WinSeparator		|hl-WinSeparator|
-	  vert:c	WinSeparator		|hl-WinSeparator|
-	  vertleft:c	WinSeparator		|hl-WinSeparator|
-	  vertright:c	WinSeparator		|hl-WinSeparator|
-	  verthoriz:c	WinSeparator		|hl-WinSeparator|
-	  fold:c	Folded			|hl-Folded|
-	  diff:c	DiffDelete		|hl-DiffDelete|
-	  eob:c		EndOfBuffer		|hl-EndOfBuffer|
+	  stl		StatusLine		|hl-StatusLine|
+	  stlnc		StatusLineNC		|hl-StatusLineNC|
+	  wbr		WinBar			|hl-WinBar| or |hl-WinBarNC|
+	  horiz		WinSeparator		|hl-WinSeparator|
+	  horizup	WinSeparator		|hl-WinSeparator|
+	  horizdown	WinSeparator		|hl-WinSeparator|
+	  vert		WinSeparator		|hl-WinSeparator|
+	  vertleft	WinSeparator		|hl-WinSeparator|
+	  vertright	WinSeparator		|hl-WinSeparator|
+	  verthoriz	WinSeparator		|hl-WinSeparator|
+	  fold		Folded			|hl-Folded|
+	  diff		DiffDelete		|hl-DiffDelete|
+	  eob		EndOfBuffer		|hl-EndOfBuffer|
 
 		*'fixendofline'* *'fixeol'* *'nofixendofline'* *'nofixeol'*
 'fixendofline' 'fixeol'	boolean	(default on)
@@ -6989,15 +6991,18 @@ A jump table for the options with a short description can be found at |Q_op|.
 				*'wildmenu'* *'wmnu'* *'nowildmenu'* *'nowmnu'*
 'wildmenu' 'wmnu'	boolean	(default on)
 			global
-	Enables "enhanced mode" of command-line completion. When user hits
-	<Tab> (or 'wildchar') to invoke completion, the possible matches are
-	shown in a menu just above the command-line (see 'wildoptions'), with
-	the first match highlighted (overwriting the statusline).  Keys that
-	show the previous/next match (<Tab>/CTRL-P/CTRL-N) highlight the
-	match.
+	When 'wildmenu' is on, command-line completion operates in an enhanced
+	mode.  On pressing 'wildchar' (usually <Tab>) to invoke completion,
+	the possible matches are shown.
+	When 'wildoptions' contains "pum", then the completion matches are
+	shown in a popup menu.  Otherwise they are displayed just above the
+	command line, with the first match highlighted (overwriting the status
+	line, if there is one).
+	Keys that show the previous/next match, such as <Tab> or
+	CTRL-P/CTRL-N, cause the highlight to move to the appropriate match.
 	'wildmode' must specify "full": "longest" and "list" do not start
 	'wildmenu' mode. You can check the current mode with |wildmenumode()|.
-	The menu is canceled when a key is hit that is not used for selecting
+	The menu is cancelled when a key is hit that is not used for selecting
 	a completion.
 
 	While the menu is active these keys have special meanings:
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index b74611633f..6fcf292513 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -181,16 +181,16 @@ Vim will only load the first syntax file found, assuming that it sets
 b:current_syntax.
 
 
-NAMING CONVENTIONS		    *group-name* *{group-name}* *E669* *W18*
+NAMING CONVENTIONS		    *group-name* *{group-name}* *E669* *E5248*
 
 A syntax group name is to be used for syntax items that match the same kind of
 thing.  These are then linked to a highlight group that specifies the color.
 A syntax group name doesn't specify any color or attributes itself.
 
-The name for a highlight or syntax group must consist of ASCII letters, digits
-and the underscore.  As a regexp: "[a-zA-Z0-9_]*".  However, Vim does not give
-an error when using other characters.  The maximum length of a group name is
-about 200 bytes.  *E1249*
+The name for a highlight or syntax group must consist of ASCII letters,
+digits, underscores, periods and `@` characters.  As a regexp it is
+`[a-zA-Z0-9_.@]*`. The maximum length of a group name is about 200 bytes.
+*E1249*
 
 To be able to allow each user to pick their favorite set of colors, there must
 be preferred names for highlight groups that are common for many languages.
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 52531a1525..2c6c9e4ed8 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -323,16 +323,34 @@ for a buffer with this code: >
     local query2 = [[ ... ]]
     highlighter:set_query(query2)
 
-As mentioned above the supported predicate is currently only `eq?`. `match?`
-predicates behave like matching always fails. As an addition a capture which
-begin with an upper-case letter like `@WarningMsg` will map directly to this
-highlight group, if defined. Also if the predicate begins with upper-case and
-contains a dot only the part before the first will be interpreted as the
-highlight group. As an example, this warns of a binary expression with two
+
+                                             *lua-treesitter-highlight-groups*
+The capture names, with `@` included, are directly usable as highlight groups.
+A fallback system is implemented, so that more specific groups fallback to
+more generic ones. For instance, in a language that has separate doc
+comments, `@comment.doc` could be used. If this group is not defined, the
+highlighting for an ordinary `@comment` is used. This way, existing color
+schemes already work out of the box, but it is possible to add
+more specific variants for queries that make them available.
+
+As an additional rule, captures highlights can always be specialized by
+language, by appending the language name after an additional dot. For
+instance, to highlight comments differently per language: >
+
+    hi @comment.c guifg=Blue
+    hi @comment.lua @guifg=DarkBlue
+    hi link @comment.doc.java String
+<
+It is possible to use custom highlight groups. As an example, if we
+define the `@warning` group: >
+
+    hi link @warning WarningMsg
+<
+the following query warns of a binary expression with two
 identical identifiers, highlighting both as |hl-WarningMsg|: >
 
-    ((binary_expression left: (identifier) @WarningMsg.left right: (identifier) @WarningMsg.right)
-     (eq? @WarningMsg.left @WarningMsg.right))
+    ((binary_expression left: (identifier) @warning.left right: (identifier) @warning.right)
+     (eq? @warning.left @warning.right))
 <
 Treesitter Highlighting Priority            *lua-treesitter-highlight-priority*
 
@@ -352,6 +370,27 @@ attribute: >
 ==============================================================================
 Lua module: vim.treesitter                               *lua-treesitter-core*
 
+                                                  *get_captures_at_position()*
+get_captures_at_position({bufnr}, {row}, {col})
+    Gets a list of captures for a given cursor position
+
+    Parameters: ~
+        {bufnr}  (number) The buffer number
+        {row}    (number) The position row
+        {col}    (number) The position column
+
+    Return: ~
+        (table) A table of captures
+
+get_node_range({node_or_range})                             *get_node_range()*
+    Get the node's range or unpack a range table
+
+    Parameters: ~
+        {node_or_range}  (table)
+
+    Return: ~
+        start_row, start_col, end_row, end_col
+
 get_parser({bufnr}, {lang}, {opts})                             *get_parser()*
     Gets the parser for this bufnr / ft combination.
 
@@ -374,6 +413,34 @@ get_string_parser({str}, {lang}, {opts})                 *get_string_parser()*
         {lang}  The language of this string
         {opts}  Options to pass to the created language tree
 
+is_ancestor({dest}, {source})                                  *is_ancestor()*
+    Determines whether a node is the ancestor of another
+
+    Parameters: ~
+        {dest}    (table) the possible ancestor
+        {source}  (table) the possible descendant node
+
+    Return: ~
+        (boolean) True if dest is an ancestor of source
+
+is_in_node_range({node}, {line}, {col})                   *is_in_node_range()*
+    Determines whether (line, col) position is in node range
+
+    Parameters: ~
+        {node}  Node defining the range
+        {line}  A line (0-based)
+        {col}   A column (0-based)
+
+node_contains({node}, {range})                               *node_contains()*
+    Determines if a node contains a range
+
+    Parameters: ~
+        {node}   (table) The node
+        {range}  (table) The range
+
+    Return: ~
+        (boolean) True if the node contains the range
+
 
 ==============================================================================
 Lua module: vim.treesitter.language                      *treesitter-language*
@@ -387,16 +454,20 @@ inspect_language({lang})                                  *inspect_language()*
     Parameters: ~
         {lang}  The language.
 
-require_language({lang}, {path}, {silent})                *require_language()*
+                                                          *require_language()*
+require_language({lang}, {path}, {silent}, {symbol_name})
     Asserts that the provided language is installed, and optionally provide a
     path for the parser
 
     Parsers are searched in the `parser` runtime directory.
 
     Parameters: ~
-        {lang}    The language the parser should parse
-        {path}    Optional path the parser is located at
-        {silent}  Don't throw an error if language not found
+        {lang}         (string) The language the parser should parse
+        {path}         (string|nil) Optional path the parser is located at
+        {silent}       (boolean|nil) Don't throw an error if language not
+                       found
+        {symbol_name}  (string|nil) Internal symbol name for the language to
+                       load
 
 
 ==============================================================================
@@ -423,12 +494,16 @@ add_predicate({name}, {handler}, {force})                    *add_predicate()*
         {handler}  the handler function to be used signature will be (match,
                    pattern, bufnr, predicate)
 
-get_node_text({node}, {source})                              *get_node_text()*
+get_node_text({node}, {source}, {opts})                      *get_node_text()*
     Gets the text corresponding to a given node
 
     Parameters: ~
-        {node}    the node
-        {source}  The buffer or string from which the node is extracted
+        {node}    (table) The node
+        {source}  (table) The buffer or string from which the node is
+                  extracted
+        {opts}    (table) Optional parameters.
+                  • concat: (boolean default true) Concatenate result in a
+                    string
 
 get_query({lang}, {query_name})                                  *get_query()*
     Returns the runtime query {query_name} for {lang}.
@@ -676,6 +751,17 @@ LanguageTree:language_for_range({self}, {range})
         {range}  A text range, see |LanguageTree:contains|
         {self}
 
+                                         *LanguageTree:named_node_for_range()*
+LanguageTree:named_node_for_range({self}, {range}, {opts})
+    Gets the smallest named node that contains {range}
+
+    Parameters: ~
+        {range}                   (table) A text range
+        {opts}                    (table) Options table
+        {opts.ignore_injections}  (boolean) (default true) Ignore injected
+                                  languages.
+        {self}
+
 LanguageTree:parse({self})                              *LanguageTree:parse()*
     Parses all defined regions using a treesitter parser for the language this
     tree represents. This will run the injection query for this language to
@@ -736,6 +822,17 @@ LanguageTree:source({self})                            *LanguageTree:source()*
     Parameters: ~
         {self}
 
+                                               *LanguageTree:tree_for_range()*
+LanguageTree:tree_for_range({self}, {range}, {opts})
+    Gets the tree that contains {range}
+
+    Parameters: ~
+        {range}                   (table) A text range
+        {opts}                    (table) Options table
+        {opts.ignore_injections}  (boolean) (default true) Ignore injected
+                                  languages.
+        {self}
+
 LanguageTree:trees({self})                              *LanguageTree:trees()*
     Returns all trees this language tree contains. Does not include child
     languages.
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 0c907bfb68..76c2f8454f 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -872,6 +872,7 @@ Command line:					*command-line-functions*
 	getcmdpos()		get position of the cursor in the command line
 	getcmdscreenpos()	get screen position of the cursor in the
 				command line
+	setcmdline()		set the current command line
 	setcmdpos()		set position of the cursor in the command line
 	getcmdtype()		return the current command-line type
 	getcmdwintype()		return the current command-line window type
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 53effa1443..0011cd9821 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -390,6 +390,9 @@ Highlight groups:
   using |n| or |N|
   |hl-CursorLine| is low-priority unless foreground color is set
   |hl-VertSplit| superseded by |hl-WinSeparator|
+  Highlight groups names are allowed to contain the characters `.` and `@`.
+  It is an error to define a highlight group with a name that doesn't match
+  the regexp `[a-zA-Z0-9_.@]*` (see |group-name|).
 
 Macro/|recording| behavior
   Replay of a macro recorded during :lmap produces the same actions as when it
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 7355cec522..2627068a14 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -163,6 +163,8 @@ CTRL-W v						*CTRL-W_v*
 		3. 'eadirection' isn't "ver", and
 		4. one of the other windows is wider than the current or new
 		   window.
+		If N was given make the new window N columns wide, if
+		possible.
 		Note: In other places CTRL-Q does the same as CTRL-V, but here
 		it doesn't!