docs: various #12823

- increase python line-length limit from 88 => 100. - gen_help_html: fix bug in "tag" case (tbl_count => tbl_contains) ref #15632 fix #18215 fix #18479 fix #20527 fix #20532 Co-authored-by: Ben Weedon <ben@weedon.email>
2024-09-17 20:58:20 -04:00 · 2022-10-09 08:21:52 -04:00 · 2022-10-09 08:21:52 -04:00 · 09dffb9db7
commit 09dffb9db7
parent de7be43acc
28 changed files with 559 additions and 582 deletions
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -1,6 +1,7 @@
 # CMAKE REFERENCE
 #   intro: https://codingnest.com/basic-cmake/
 #   best practices (3.0+): https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1
+#   pitfalls: https://izzys.casa/2019/02/everything-you-never-wanted-to-know-about-cmake/

 # Version should match the tested CMAKE_URL in .github/workflows/ci.yml.
 cmake_minimum_required(VERSION 3.10)
@ -637,7 +638,7 @@ include(InstallHelpers)
 add_glob_targets(
  TARGET lintpy
  COMMAND ${FLAKE8_PRG}
-  FLAGS --max-line-length 88
+  FLAGS --max-line-length 100
  GLOB_DIRS contrib scripts src test
  GLOB_PAT *.py
  TOUCH_STRATEGY SINGLE
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -30,9 +30,9 @@ Reporting problems
 Developer guidelines
 --------------------

- Read `:help dev` if you are working on Nvim core.
- Read `:help dev-ui` if you are developing a UI.
- Read `:help dev-api-client` if you are developing an API client.
+- Read [:help dev](https://neovim.io/doc/user/develop.html#dev) if you are working on Nvim core.
+- Read [:help dev-ui](https://neovim.io/doc/user/develop.html#dev-ui) if you are developing a UI.
+- Read [:help dev-api-client](https://neovim.io/doc/user/develop.html#dev-api-client) if you are developing an API client.
 - Install `ninja` for faster builds of Nvim.
  ```
  sudo apt-get install ninja-build
@ -47,21 +47,19 @@ Pull requests (PRs)
 - Your PR must include [test coverage][run-tests].
 - Avoid cosmetic changes to unrelated files in the same commit.
 - Use a [feature branch][git-feature-branch] instead of the master branch.
- Use a **rebase workflow** for small PRs.
-  - After addressing review comments, it's fine to rebase and force-push.
- Use a **merge workflow** for big, high-risk PRs.
+- Use a _rebase workflow_ for small PRs.
+  - After addressing review comments, it's fine to force-push.
+- Use a _merge workflow_ (as opposed to "rebase") for big, high-risk PRs.
  - Merge `master` into your PR when there are conflicts or when master
    introduces breaking changes.
-  - Use the `ri` git alias:
-    ```
-    [alias]
-    ri = "!sh -c 't=\"${1:-master}\"; s=\"${2:-HEAD}\"; mb=\"$(git merge-base \"$t\" \"$s\")\"; if test \"x$mb\" = x ; then o=\"$t\"; else lm=\"$(git log -n1 --merges \"$t..$s\" --pretty=%H)\"; if test \"x$lm\" = x ; then o=\"$mb\"; else o=\"$lm\"; fi; fi; test $# -gt 0 && shift; test $# -gt 0 && shift; git rebase --interactive \"$o\" \"$@\"'"
-    ```
-    This avoids unnecessary rebases yet still allows you to combine related
-    commits, separate monolithic commits, etc.
  - Do not edit commits that come before the merge commit.
- During a squash/fixup, use `exec make -C build unittest` between each
-  pick/edit/reword.
+
+### Merging to master
+
+For maintainers: when a PR is ready to merge to master,
+
+- prefer _Squash Merge_ for "single-commit PRs" (when the PR has only one meaningful commit).
+- prefer _Merge_ for "multi-commit PRs" (when the PR has multiple meaningful commits).

 ### Stages: Draft and Ready for review

--- a/LICENSE.txt
+++ b/LICENSE.txt
@ -196,10 +196,11 @@ The externally maintained libraries used by Neovim are:
  - libtermkey: MIT license
  - libuv. Copyright Joyent, Inc. and other Node contributors. Node.js license.
  - libvterm: MIT license
+  - lua-cjson: MIT license
  - lua-compat: MIT license
  - tree-sitter: MIT license
-  - xdiff: LGPL license
-  - lua-cjson: MIT license
+  - unibilium: LGPL v3
+  - xdiff: LGPL v2

 ====

--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@ -12,23 +12,23 @@ General guidelines
 * Use automation to solve problems
 * Never break the API... but sometimes break the UI

-Ticket triage
-------------
+Issue triage
+------------

 In practice we haven't found a way to forecast more precisely than "next" and
 "after next". So there are usually one or two (at most) planned milestones:

- Next bugfix-release (1.0.x)
- Next feature-release (1.x.0)
+* Next bugfix-release (1.0.x)
+* Next feature-release (1.x.0)

 The forecasting problem might be solved with an explicit priority system (like
 Bram's todo.txt). Meanwhile the Neovim priority system is defined by:

- PRs nearing completion.
- Issue labels. E.g. the `+plan` label increases the ticket's priority merely
+* PRs nearing completion.
+* Issue labels. E.g. the `+plan` label increases the ticket's priority merely
  for having a plan written down: it is _closer to completion_ than tickets
  without a plan.
- Comment activity or new information.
+* Comment activity or new information.

 Anything that isn't in the next milestone, and doesn't have a finished PR—is
 just not something you care very much about, by construction. Post-release you
@ -50,46 +50,56 @@ has a major bug:
 1. Fix the bug on `master`.
 2. Cherry-pick the fix to `release-x.y`.
 3. Cut a release from `release-x.y`.
-    - Run `./scripts/release.sh`
-    - Update (force-push) the remote `stable` tag.
-    - The [CI job](https://github.com/neovim/neovim/blob/3d45706478cd030c3ee05b4f336164bb96138095/.github/workflows/release.yml#L11-L13)
-      will update the release assets based on the `stable` tag.
+    * Run `./scripts/release.sh`
+    * Update (force-push) the remote `stable` tag.
+    * The [CI job](https://github.com/neovim/neovim/blob/3d45706478cd030c3ee05b4f336164bb96138095/.github/workflows/release.yml#L11-L13)
+      will update the release assets and force-push to the `stable` tag.

-The neovim repository includes a backport [github action](https://github.com/zeebe-io/backport-action).
-In order to trigger the action, a PR must be labeled with a label matching the
-form `backport release-0.X`.
+### Release automation
+
+Neovim automation includes a [backport bot](https://github.com/zeebe-io/backport-action).
+Trigger the action by labeling a PR with `backport release-X.Y`. See `.github/workflows/backport.yml`.

 Third-party dependencies
--------------
+------------------------

-These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/CMakeLists.txt`:
-  - [Lua](https://www.lua.org/download.html)
-  - [LuaJIT](https://github.com/LuaJIT/LuaJIT)
-  - [Luv](https://github.com/luvit/luv)
-  - [libtermkey](https://github.com/neovim/libtermkey)
-  - [libuv](https://github.com/libuv/libuv)
-  - [libvterm](http://www.leonerd.org.uk/code/libvterm/)
-  - [lua-compat](https://github.com/keplerproject/lua-compat-5.3)
-  - [tree-sitter](https://github.com/tree-sitter/tree-sitter)
+These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/CMakeLists.txt`.
+Some can be auto-bumped by `scripts/bump-deps.sh`.

-`scripts/bump-dep.sh` is a script that can automate this process for `LuaJIT`, `Luv`, `libuv` & `tree-sitter`. See usage guide:
-  - Run `./scripts/bump-deps.sh --dep Luv --version 1.43.0-0` to update a dependency.
-  See `./scripts/bump-deps.sh -h` for more detailed usage
-  - Run `./scripts/bump-deps.sh --pr` to create a pr
-  To generate the default PR title and body, the script uses the most recent commit (not in `master`) with prefix `build(deps): `
+* [LuaJIT](https://github.com/LuaJIT/LuaJIT)
+* [Lua](https://www.lua.org/download.html)
+* [Luv](https://github.com/luvit/luv)
+* [gettext](https://ftp.gnu.org/pub/gnu/gettext/)
+* [libiconv](https://ftp.gnu.org/pub/gnu/libiconv)
+* [libtermkey](https://github.com/neovim/libtermkey)
+* [libuv](https://github.com/libuv/libuv)
+* [libvterm](http://www.leonerd.org.uk/code/libvterm/)
+* [lua-compat](https://github.com/keplerproject/lua-compat-5.3)
+* [msys2](https://github.com/msys2/MINGW-packages) (for mingw Windows build)
+    * Changes to mingw can [break our mingw build](https://github.com/msys2/MINGW-packages/issues/9946).
+* [tree-sitter](https://github.com/tree-sitter/tree-sitter)
+* [unibilium](https://github.com/neovim/unibilium)

-These dependencies are "vendored" (inlined), we need to update the sources manually:
-  - [libmpack](https://github.com/libmpack/libmpack)
-  - [xdiff](https://github.com/git/git/tree/master/xdiff)
-  - [lua-cjson](https://github.com/openresty/lua-cjson)
-  - [Klib](https://github.com/attractivechaos/klib)
-  - [inspect.lua](https://github.com/kikito/inspect.lua)
+### Vendored dependencies

-We also maintain some forks, particularly for Windows, if we are waiting on upstream changes:
-https://github.com/neovim/neovim/wiki/Deps
+These dependencies are "vendored" (inlined), we must update the sources manually:
+
+* `src/mpack/`: [libmpack](https://github.com/libmpack/libmpack)
+    * send improvements upstream!
+* `src/xdiff/`: [xdiff](https://github.com/git/git/tree/master/xdiff)
+* `src/cjson/`: [lua-cjson](https://github.com/openresty/lua-cjson)
+* `src/nvim/lib/`: [Klib](https://github.com/attractivechaos/klib)
+* `runtime/lua/vim/inspect.lua`: [inspect.lua](https://github.com/kikito/inspect.lua)
+* `src/nvim/tui/terminfo_defs.h`: terminfo definitions
+    * Run `scripts/update_terminfo.sh` to update these definitions.
+* [treesitter parsers](https://github.com/neovim/neovim/blob/fcc24e43e0b5f9d801a01ff2b8f78ce8c16dd551/cmake.deps/CMakeLists.txt#L197-L210)
+
+### Forks
+
+We may maintain forks, if we are waiting on upstream changes: https://github.com/neovim/neovim/wiki/Deps

 See also
 --------

- https://github.com/neovim/neovim/issues/862
- https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt
+* https://github.com/neovim/neovim/issues/862
+* https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@ -231,6 +231,15 @@ As Nvim evolves the API may change in compliance with this CONTRACT:
  - Existing items will not be removed (after release).
 - Deprecated functions will not be removed until Nvim version 2.0

+"Private" interfaces are NOT covered by this contract:
+
+- Undocumented (not in :help) functions or events of any kind
+- nvim__x ("double underscore") functions
+
+The idea is "versionless evolution", in the words of Rich Hickey:
+- Relaxing a requirement should be a compatible change.
+- Strengthening a promise should be a compatible change.
+
 ==============================================================================
 Global events                                               *api-global-events*

@ -649,7 +658,7 @@ nvim_chan_send({chan}, {data})                              *nvim_chan_send()*

    Attributes: ~
        |RPC| only
-        |vim.api| only
+        Lua |vim.api| only

    Parameters: ~
      • {chan}  id of the channel
@ -2097,7 +2106,7 @@ nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
    buffer/window currently, like |termopen()|.

    Attributes: ~
-        |vim.api| only
+        Lua |vim.api| only

    Parameters: ~
      • {buffer}  Buffer handle, or 0 for current buffer
@ -2356,6 +2365,9 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
      • {strict_indexing}  Whether out-of-bounds should be an error.
      • {replacement}      Array of lines to use as replacement

+    See also: ~
+        |nvim_buf_set_text()|
+
                                                         *nvim_buf_set_mark()*
 nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
    Sets a named mark in the given buffer, all marks are allowed
@ -2414,6 +2426,9 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
      • {end_col}      Ending column (byte offset) on last line, exclusive
      • {replacement}  Array of lines to use as replacement

+    See also: ~
+        |nvim_buf_set_lines()|
+
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
    Sets a buffer-scoped (b:) variable

@ -2714,7 +2729,7 @@ nvim_set_decoration_provider({ns_id}, {*opts})
    quite dubious for the moment.

    Attributes: ~
-        |vim.api| only
+        Lua |vim.api| only

    Parameters: ~
      • {ns_id}  Namespace id from |nvim_create_namespace()|
@ -2738,7 +2753,7 @@ nvim_win_call({window}, {fun})                               *nvim_win_call()*
    Calls a function with window as temporary current window.

    Attributes: ~
-        |vim.api| only
+        Lua |vim.api| only

    Parameters: ~
      • {window}  Window handle, or 0 for current window
@ -2782,7 +2797,9 @@ nvim_win_get_buf({window})                                *nvim_win_get_buf()*
        Buffer handle

 nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
-    Gets the (1,0)-indexed cursor position in the window. |api-indexing|
+    Gets the (1,0)-indexed, buffer-relative cursor position for a given window
+    (different windows showing the same buffer have independent cursor
+    positions). |api-indexing|

    Parameters: ~
      • {window}  Window handle, or 0 for current window
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@ -3806,15 +3806,15 @@ has({feature})	Returns 1 if {feature} is supported, 0 otherwise.  The
 		{feature} argument is a feature name like "nvim-0.2.1" or
 		"win32", see below.  See also |exists()|.

-		If the code has a syntax error, then Nvim may skip the rest
-		of the line and miss |:endif|. >
-	if has('feature') | let x = this->breaks->without->the->feature | endif
-<
-		Put |:if| and |:endif| on separate lines to avoid the
-		syntax error. >
-	if has('feature')
-	  let x = this->breaks->without->the->feature
-	endif
+		To get the system name use |vim.loop|.os_uname() in Lua: >
+			:lua print(vim.loop.os_uname().sysname)
+
+<		If the code has a syntax error then Vimscript may skip the
+		rest of the line.  Put |:if| and |:endif| on separate lines to
+		avoid the syntax error: >
+			if has('feature')
+			  let x = this->breaks->without->the->feature
+			endif
 <
 		Vim's compile-time feature-names (prefixed with "+") are not
 		recognized because Nvim is always compiled with all possible
@ -7783,7 +7783,7 @@ stdpath({what})					*stdpath()* *E6100*
 		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, swap, undo, |shada|.

 		Example: >
 			:echo stdpath("config")
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@ -10,159 +10,149 @@ The items listed below are deprecated: they will be removed in the future.
 They should not be used in new scripts, and old scripts should be updated.

 ==============================================================================
+Deprecated features

-API ~
-*nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
-*nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
-*nvim_command_output()*		Use |nvim_exec()| instead.
-*nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
+API
+- *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
+- *nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
+- *nvim_command_output()*	Use |nvim_exec()| instead.
+- *nvim_execute_lua()*		Use |nvim_exec_lua()| instead.

-Commands ~
-*:rv*
-*:rviminfo*		Deprecated alias to |:rshada| command.
-*:wv*
-*:wviminfo*		Deprecated alias to |:wshada| command.
+COMMANDS
+- *:rv* *:rviminfo*		Deprecated alias to |:rshada| command.
+- *:wv* *:wviminfo*		Deprecated alias to |:wshada| command.

-Environment Variables ~
-*$NVIM_LISTEN_ADDRESS*	Deprecated way to
-			* set the server name (use |--listen| instead)
-			* get the server name (use |v:servername| instead)
-			* detect a parent Nvim (use |$NVIM| instead)
-			Unset by |terminal| and |jobstart()| (unless explicitly
-			given by the "env" option). Ignored if --listen is given.
+ENVIRONMENT VARIABLES
+- *$NVIM_LISTEN_ADDRESS*
+  - Deprecated way to:
+    - set the server name (use |--listen| or |serverstart()| instead)
+    - get the server name (use |v:servername| instead)
+    - detect a parent Nvim (use |$NVIM| instead)
+  - Ignored if --listen is given.
+  - Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
+    option. Example: >
+	call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername  } })
+<

-Events ~
-*BufCreate*		Use |BufAdd| instead.
-*EncodingChanged*	Never fired; 'encoding' is always "utf-8".
-*FileEncoding*		Never fired; equivalent to |EncodingChanged|.
-*GUIEnter*		Never fired; use |UIEnter| instead.
-*GUIFailed*		Never fired.
+EVENTS
+- *BufCreate*		Use |BufAdd| instead.
+- *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
+- *FileEncoding*	Never fired; equivalent to |EncodingChanged|.
+- *GUIEnter*		Never fired; use |UIEnter| instead.
+- *GUIFailed*		Never fired.

-Keycodes ~
-*<MouseDown>*		Use <ScrollWheelUp> instead.
-*<MouseUp>*		Use <ScrollWheelDown> instead.
+KEYCODES
+- *<MouseDown>*		Use <ScrollWheelUp> instead.
+- *<MouseUp>*		Use <ScrollWheelDown> instead.

-Functions ~
-*buffer_exists()*	Obsolete name for |bufexists()|.
-*buffer_name()*		Obsolete name for |bufname()|.
-*buffer_number()*	Obsolete name for |bufnr()|.
-*file_readable()*	Obsolete name for |filereadable()|.
-*health#report_error*	Use Lua |vim.health.report_error()| instead.
-*health#report_info*	Use Lua |vim.health.report_info()| instead.
-*health#report_ok*	Use Lua |vim.health.report_ok()| instead.
-*health#report_start*	Use Lua |vim.health.report_start()| instead.
-*health#report_warn*	Use Lua |vim.health.report_warn()| instead.
-*highlight_exists()*	Obsolete name for |hlexists()|.
-*highlightID()*		Obsolete name for |hlID()|.
-*inputdialog()*		Use |input()| instead.
-*jobclose()*		Obsolete name for |chanclose()|
-*jobsend()*		Obsolete name for |chansend()|
-*last_buffer_nr()*	Obsolete name for bufnr("$").
-*rpcstop()*		Deprecated. Instead use |jobstop()| to stop any job,
-			or chanclose(id, "rpc") to close RPC communication
+FUNCTIONS
+- *buffer_exists()*	Obsolete name for |bufexists()|.
+- *buffer_name()*	Obsolete name for |bufname()|.
+- *buffer_number()*	Obsolete name for |bufnr()|.
+- *file_readable()*	Obsolete name for |filereadable()|.
+- *health#report_error*	Use Lua |vim.health.report_error()| instead.
+- *health#report_info*	Use Lua |vim.health.report_info()| instead.
+- *health#report_ok*	Use Lua |vim.health.report_ok()| instead.
+- *health#report_start*	Use Lua |vim.health.report_start()| instead.
+- *health#report_warn*	Use Lua |vim.health.report_warn()| instead.
+- *highlight_exists()*	Obsolete name for |hlexists()|.
+- *highlightID()*	Obsolete name for |hlID()|.
+- *inputdialog()*	Use |input()| instead.
+- *jobclose()*		Obsolete name for |chanclose()|
+- *jobsend()*		Obsolete name for |chansend()|
+- *last_buffer_nr()*	Obsolete name for bufnr("$").
+- *rpcstop()*		Use |jobstop()| instead to stop any job, or
+			`chanclose(id, "rpc")` to close RPC communication
 			without stopping the job. Use chanclose(id) to close
 			any socket.

-Highlights ~
-
-*hl-VertSplit*		Use |hl-WinSeparator| instead.
-
-LSP Diagnostics ~
+HIGHLIGHTS
+- *hl-VertSplit*	Use |hl-WinSeparator| instead.

+LSP DIAGNOSTICS
 For each of the functions below, use the corresponding function in
 |vim.diagnostic| instead (unless otherwise noted). For example, use
 |vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|.

-*vim.lsp.diagnostic.clear()*		Use |vim.diagnostic.hide()| instead.
-*vim.lsp.diagnostic.disable()*
-*vim.lsp.diagnostic.display()*		Use |vim.diagnostic.show()| instead.
-*vim.lsp.diagnostic.enable()*
-*vim.lsp.diagnostic.get()*
-*vim.lsp.diagnostic.get_all()*		Use |vim.diagnostic.get()| instead.
-*vim.lsp.diagnostic.get_count()*	Use |vim.diagnostic.get()| instead.
-*vim.lsp.diagnostic.get_line_diagnostics()*
-					Use |vim.diagnostic.get()| instead.
-*vim.lsp.diagnostic.get_next()*
-*vim.lsp.diagnostic.get_next_pos()*
-*vim.lsp.diagnostic.get_prev()*
-*vim.lsp.diagnostic.get_prev_pos()*
-*vim.lsp.diagnostic.get_virtual_text_chunks_for_line()*
-				No replacement. Use options provided by
-				|vim.diagnostic.config()| to customize
-				virtual text.
-*vim.lsp.diagnostic.goto_next()*
-*vim.lsp.diagnostic.goto_prev()*
-*vim.lsp.diagnostic.redraw()*		Use |vim.diagnostic.show()| instead.
-*vim.lsp.diagnostic.reset()*
-*vim.lsp.diagnostic.save()*		Use |vim.diagnostic.set()| instead.
-*vim.lsp.diagnostic.set_loclist()*	Use |vim.diagnostic.setloclist()| instead.
-*vim.lsp.diagnostic.set_qflist()*	Use |vim.diagnostic.setqflist()| instead.
-
-The following have been replaced by |vim.diagnostic.open_float()|.
-
-*vim.lsp.diagnostic.show_line_diagnostics()*
-*vim.lsp.diagnostic.show_position_diagnostics()*
+- *vim.lsp.diagnostic.clear()*		Use |vim.diagnostic.hide()| instead.
+- *vim.lsp.diagnostic.disable()*
+- *vim.lsp.diagnostic.display()*	Use |vim.diagnostic.show()| instead.
+- *vim.lsp.diagnostic.enable()*
+- *vim.lsp.diagnostic.get()*
+- *vim.lsp.diagnostic.get_all()*	Use |vim.diagnostic.get()| instead.
+- *vim.lsp.diagnostic.get_count()*	Use |vim.diagnostic.get()| instead.
+- *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead.
+- *vim.lsp.diagnostic.get_next()*
+- *vim.lsp.diagnostic.get_next_pos()*
+- *vim.lsp.diagnostic.get_prev()*
+- *vim.lsp.diagnostic.get_prev_pos()*
+- *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* No replacement. Use
+  options provided by |vim.diagnostic.config()| to customize virtual text.
+- *vim.lsp.diagnostic.goto_next()*
+- *vim.lsp.diagnostic.goto_prev()*
+- *vim.lsp.diagnostic.redraw()*		Use |vim.diagnostic.show()| instead.
+- *vim.lsp.diagnostic.reset()*
+- *vim.lsp.diagnostic.save()*		Use |vim.diagnostic.set()| instead.
+- *vim.lsp.diagnostic.set_loclist()*	Use |vim.diagnostic.setloclist()| instead.
+- *vim.lsp.diagnostic.set_qflist()*	Use |vim.diagnostic.setqflist()| instead.
+- *vim.lsp.diagnostic.show_line_diagnostics()* Use |vim.diagnostic.open_float()| instead.
+- *vim.lsp.diagnostic.show_position_diagnostics()* Use |vim.diagnostic.open_float()| instead.

 The following are deprecated without replacement. These functions are moved
 internally and are no longer exposed as part of the API. Instead, use
 |vim.diagnostic.config()| and |vim.diagnostic.show()|.

-*vim.lsp.diagnostic.set_signs()*
-*vim.lsp.diagnostic.set_underline()*
-*vim.lsp.diagnostic.set_virtual_text()*
+- *vim.lsp.diagnostic.set_signs()*
+- *vim.lsp.diagnostic.set_underline()*
+- *vim.lsp.diagnostic.set_virtual_text()*

-LSP Functions ~
-
-*vim.lsp.util.diagnostics_to_items()*	Use |vim.diagnostic.toqflist()| instead.
-*vim.lsp.util.set_qflist()*		Use |setqflist()| instead.
-*vim.lsp.util.set_loclist()*		Use |setloclist()| instead.
-*vim.lsp.buf_get_clients()*		Use |vim.lsp.get_active_clients()| with
+LSP FUNCTIONS
+- *vim.lsp.range_code_action*		Use |vim.lsp.buf.code_action()| with
+					the `range` parameter.
+- *vim.lsp.util.diagnostics_to_items()*	Use |vim.diagnostic.toqflist()| instead.
+- *vim.lsp.util.set_qflist()*		Use |setqflist()| instead.
+- *vim.lsp.util.set_loclist()*		Use |setloclist()| instead.
+- *vim.lsp.buf_get_clients()*		Use |vim.lsp.get_active_clients()| with
                                        {buffer = bufnr} instead.
-*vim.lsp.buf.formatting()*		Use |vim.lsp.buf.format()| with
+- *vim.lsp.buf.formatting()*		Use |vim.lsp.buf.format()| with
 					{async = true} instead.
-*vim.lsp.buf.range_formatting()*	Use |vim.lsp.formatexpr()|
+- *vim.lsp.buf.range_formatting()*	Use |vim.lsp.formatexpr()|
 					or |vim.lsp.buf.format()| instead.

-Lua ~
-*vim.register_keystroke_callback()* Use |vim.on_key()| instead.
+LUA
+- *vim.register_keystroke_callback()* 	Use |vim.on_key()| instead.

-Modifiers ~
-*cpo-<*
-*:menu-<special>*
-*:menu-special*		<> notation is always enabled.
-*:map-<special>*
-*:map-special*		<> notation is always enabled.
+NORMAL COMMANDS
+- *]f* *[f*		Same as "gf".

-Normal commands ~
-*]f*
-*[f*			Same as "gf".
-
-Options ~
-*'cscopeverbose'*	Enabled by default. Use |:silent| instead.
-*'exrc'* *'ex'*		Security risk: downloaded files could include
+OPTIONS
+- *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special*
+  `<>` notation is always enabled.
+- *'cscopeverbose'*	Enabled by default. Use |:silent| instead.
+- *'exrc'* *'ex'*	Security risk: downloaded files could include
 			a malicious .nvimrc or .exrc file. See 'secure'.
 			Recommended alternative: define an autocommand in your
 			|vimrc| to set options for a matching directory.
-'gd'
-'gdefault'		Enables the |:substitute| flag 'g' by default.
-*'fe'*			'fenc'+'enc' before Vim 6.0; no longer used.
-*'highlight'* *'hl'*	Names of builtin |highlight-groups| cannot be changed.
-*'langnoremap'*		Deprecated alias to 'nolangremap'.
-'sessionoptions'	Flags "unix", "slash" are ignored and always enabled.
-*'vi'*
-'viewoptions'		Flags "unix", "slash" are ignored and always enabled.
-*'viminfo'*		Deprecated alias to 'shada' option.
-*'viminfofile'*		Deprecated alias to 'shadafile' option.
+- 'gdefault'		Enables the |:substitute| flag 'g' by default.
+- *'fe'*		'fenc'+'enc' before Vim 6.0; no longer used.
+- *'highlight'* *'hl'*	Names of builtin |highlight-groups| cannot be changed.
+- *'langnoremap'*	Deprecated alias to 'nolangremap'.
+- 'sessionoptions'	Flags "unix", "slash" are ignored and always enabled.
+- *'vi'*
+- 'viewoptions'		Flags "unix", "slash" are ignored and always enabled.
+- *'viminfo'*		Deprecated alias to 'shada' option.
+- *'viminfofile'*	Deprecated alias to 'shadafile' option.

-UI extensions~
-*ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
+UI EXTENSIONS
+- *ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
 			by the `ext_wildmenu` |ui-option|. Emits these events:
-				["wildmenu_show", items]
-				["wildmenu_select", selected]
-				["wildmenu_hide"]
+			- `["wildmenu_show", items]`
+			- `["wildmenu_select", selected]`
+			- `["wildmenu_hide"]`

-Variables~
-*b:terminal_job_pid*	PID of the top-level process in a |:terminal|.
+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:
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@ -131,6 +131,7 @@ DOCUMENTATION						*dev-doc*
  (docstrings, user manual, website materials, newsletters, …). Don't mince
  words. Personality and flavor, used sparingly, are welcome--but in general,
  optimize for the reader's time and energy: be "precise yet concise".
+    - See https://developers.google.com/style/tone
    - Prefer the active voice: "Foo does X", not "X is done by Foo".
 - Vim differences:
    - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
@ -144,11 +145,11 @@ DOCUMENTATION						*dev-doc*
    - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
      in prose if possible.
 - Docstrings: do not start parameter descriptions with "The" or "A" unless it
-  is critical to avoid ambiguity.
-      GOOD: >
-      /// @param dirname Path fragment before `pend`
-<      BAD: >
-      /// @param dirname The path fragment before `pend`
+  is critical to avoid ambiguity. >
+    GOOD:
+    /// @param dirname Path fragment before `pend`
+    BAD:
+    /// @param dirname The path fragment before `pend`
 <

 Documentation format ~
@ -180,7 +181,7 @@ Docstring format:
  `@note`, `@param`, `@returns`
 - Limited markdown is supported.
  - List-items start with `-` (useful to nest or "indent")
- Use `<pre>`  for code samples.
+- Use `<pre>` for code samples.

 Example: the help for |nvim_open_win()| is generated from a docstring defined
 in src/nvim/api/win_config.c like this: >
@ -218,7 +219,7 @@ Docstring format:
  `---@see`, `---@param`, `---@returns`
 - Limited markdown is supported.
  - List-items start with `-` (useful to nest or "indent")
- Use `<pre>`  for code samples.
+- Use `<pre>` for code samples.

 Example: the help for |vim.paste()| is generated from a docstring decorating
 vim.paste in runtime/lua/vim/_editor.lua like this: >
@ -251,7 +252,8 @@ LUA							*dev-lua*

 API							*dev-api*

-Use this template to name new RPC |API| functions:
+Use this format to name new RPC |API| functions:
+
    nvim_{thing}_{action}_{arbitrary-qualifiers}

 If the function acts on an object then {thing} is the name of that object
@ -260,37 +262,50 @@ If the function acts on an object then {thing} is the name of that object
 with a {thing} that groups functions under a common concept).

 Use existing common {action} names if possible:
-    add     Append to, or insert into, a collection
-    create  Create a new thing
-    del     Delete a thing (or group of things)
-    exec    Execute code
-    get     Get a thing (or group of things by query)
-    list    Get all things
-    set     Set a thing (or group of things)
+    - add       Append to, or insert into, a collection
+    - call      Call a function
+    - create    Create a new (non-trivial) thing
+    - del       Delete a thing (or group of things)
+    - eval      Evaluate an expression
+    - exec      Execute code
+    - fmt       Format
+    - get       Get things (often by a query)
+    - open      Open
+    - parse     Parse something into a structured form
+    - set       Set a thing (or group of things)

-Use existing common {thing} names if possible:
-    buf     Buffer
-    pos     Position
-    tab     Tabpage
-    win     Window
+Do NOT use these deprecated verbs:
+    - list      Redundant with "get"

-Use consistent names for {thing} in all API functions. E.g. a buffer is called
+Use consistent names for {thing} (nouns) in API functions: buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.
+    - buf       Buffer
+    - chan      |channel|
+    - cmd       Command
+    - cmdline   Command-line UI or input
+    - fn        Function
+    - hl        Highlight
+    - pos       Position
+    - proc      System process
+    - tabpage   Tabpage
+    - win       Window
+
+Do NOT use these deprecated nouns:
+    - buffer
+    - command
+    - window

 Example:
-    `nvim_get_current_line` acts on the global editor state; the common
-    {action} "get" is used but {thing} is omitted.
+    `nvim_get_keymap('v')` operates in a global context (first parameter is not
+    a Buffer). The "get" {action} indicates that it gets anything matching the
+    given filter parameter. There is no need for a "list" action because
+    `nvim_get_keymap('')` (i.e., empty filter) returns all items.

 Example:
-    `nvim_buf_add_highlight` acts on a `Buffer` object (the first parameter)
-    and uses the common {action} "add".
+    `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
+    and uses the "del" {action}.

-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:
+Use this format to name new API events:
    nvim_{thing}_{event}_event

 Example:
@ -332,10 +347,10 @@ a good name: it's idiomatic and unambiguous. If the package is named "neovim",
 it confuses users, and complicates documentation and discussions.

 Examples of API-client package names:
-        GOOD: nvim-racket
-        GOOD: pynvim
-        BAD:  python-client
-        BAD:  neovim
+- GOOD: nvim-racket
+- GOOD: pynvim
+- BAD:  python-client
+- BAD:  neovim

 API client implementation guidelines ~

@ -401,4 +416,4 @@ Use the "on_" prefix to name event handlers and also the interface for
 a confused collection of naming conventions for these related concepts.


- vim:tw=78:ts=8:noet:ft=help:norl:
+ vim:tw=78:ts=8:sw=4:et:ft=help:norl:
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@ -1120,7 +1120,7 @@ to terminal mode.
 You found it, Arthur!				*holy-grail*

 ==============================================================================
-6. EX commands					*ex-cmd-index* *:index*
+6. EX commands				*ex-commands* *ex-cmd-index* *:index*

 This is a brief but complete listing of all the ":" commands, without
 mentioning any arguments.  The optional part of the command name is inside [].
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@ -11,30 +11,126 @@ Lua engine                                                           *lua* *Lua*
 ==============================================================================
 INTRODUCTION                                                       *lua-intro*

-The Lua 5.1 language is builtin and always available. Try this command to get
-an idea of what lurks beneath: >
+The Lua 5.1 script engine is builtin and always available. Try this command to
+get an idea of what lurks beneath: >

    :lua print(vim.inspect(package.loaded))
+
+Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
+"editor stdlib" (|builtin-functions| and |Ex-commands|) and the |API|, all of
+which can be used from Lua code (|lua-vimscript| |vim.api|). Together these
+"namespaces" form the Nvim programming interface.
+
+The |:source| and |:runtime| commands can run Lua scripts. Lua modules can be
+loaded with `require('name')`, which by convention usually returns a table.
+See |lua-require| for how Nvim finds and loads Lua modules.
+
+See this page for more insight into Nvim Lua:
+    https://github.com/nanotee/nvim-lua-guide
+
+                                                                  *lua-compat*
+Lua 5.1 is the permanent interface for Nvim Lua.  Plugins need only consider
+Lua 5.1, not worry about forward-compatibility with future Lua versions.  If
+Nvim ever ships with Lua 5.4+, a Lua 5.1 compatibility shim will be provided
+so that old plugins continue to work transparently.
+
+------------------------------------------------------------------------------
+LUA CONCEPTS AND IDIOMS                                         *lua-concepts*
+
+Lua is very simple: this means that, while there are some quirks, once you
+internalize those quirks, everything works the same everywhere. Scopes
+(closures) in particular are very consistent, unlike JavaScript or most other
+languages.
+
+Lua has three fundamental mechanisms—one for "each major aspect of
+programming": tables, closures, and coroutines.
+https://www.lua.org/doc/cacm2018.pdf
+- Tables are the "object" or container datastructure: they represent both
+  lists and maps, you can extend them to represent your own datatypes and
+  change their behavior using |luaref-metatable| (like Python's "datamodel").
+- EVERY scope in Lua is a closure: a function is a closure, a module is
+  a closure, a `do` block (|luaref-do|) is a closure--and they all work the
+  same. A Lua module is literally just a big closure discovered on the "path"
+  (where your modules are found: |package.cpath|).
+- Stackful coroutines enable cooperative multithreading, generators, and
+  versatile control for both Lua and its host (Nvim).
+
+                                                           *lua-call-function*
+Lua functions can be called in multiple ways. Consider the function: >
+    local foo = function(a, b)
+        print("A: ", a)
+        print("B: ", b)
+    end
+
+The first way to call this function is: >
+    foo(1, 2)
+    -- ==== Result ====
+    -- A: 1
+    -- B: 2
+
+This way of calling a function is familiar from most scripting languages.
+In Lua, any missing arguments are passed as `nil`. Example: >
+    foo(1)
+    -- ==== Result ====
+    -- A: 1
+    -- B: nil
+
+Furthermore it is not an error if extra parameters are passed, they are just
+discarded.
+
+It is also allowed to omit the parentheses (only) if the function takes
+exactly one string (`"foo"`) or table literal (`{1,2,3}`). The latter is often
+used to approximate the "named parameters" feature of languages like Python
+("kwargs" or "keyword args"). Example: >
+    local func_with_opts = function(opts)
+        local will_do_foo = opts.foo
+        local filename = opts.filename
+
+        ...
+    end
+
+    func_with_opts { foo = true, filename = "hello.world" }
 <
-Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the
-"editor stdlib" (|builtin-functions| and Ex commands) and the |API|, all of
-which can be used from Lua code. A good overview of using Lua in neovim is
-given by https://github.com/nanotee/nvim-lua-guide.
+There is nothing special going on here except that parentheses are treated as
+whitespace. But visually, this small bit of sugar gets reasonably close to
+a "keyword args" interface.

-The |:source| and |:runtime| commands can run Lua scripts as well as Vim
-scripts. Lua modules can be loaded with `require('name')`, which
-conventionally returns a table but can return any value.
+It is of course also valid to call the function with parentheses: >

-See |lua-require| for details on how Nvim finds and loads Lua modules.
-See |lua-require-example| for an example of how to write and use a module.
+    func_with_opts({ foo = true, filename = "hello.world" })
+<
+Nvim tends to prefer the keyword args style.
+
+------------------------------------------------------------------------------
+LUA PATTERNS                                                    *lua-patterns*
+
+Lua intentionally does not support regular expressions, instead it has limited
+"patterns" which avoid the performance pitfalls of extended regex.
+|luaref-patterns|
+
+Examples using |string.match()|: >
+
+    print(string.match("foo123bar123", "%d+"))
+    -- 123
+
+    print(string.match("foo123bar123", "[^%d]+"))
+    -- foo
+
+    print(string.match("foo123bar123", "[abc]+"))
+    -- ba
+
+    print(string.match("foo.bar", "%.bar"))
+    -- .bar
+
+For more complex matching you can use Vim regex from Lua via |vim.regex()|.

 ==============================================================================
 IMPORTING LUA MODULES                                            *lua-require*

 Modules are searched for under the directories specified in 'runtimepath', in
-the order they appear. Any `.` in the module name is treated as a directory
-separator when searching. For a module `foo.bar`, each directory is searched
-for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`. If no files are found,
+the order they appear.  Any "." in the module name is treated as a directory
+separator when searching.  For a module `foo.bar`, each directory is searched
+for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`.  If no files are found,
 the directories are searched again for a shared library with a name matching
 `lua/foo/bar.?`, where `?` is a list of suffixes (such as `so` or `dll`) derived from
 the initial value of |package.cpath|. If still no files are found, Nvim falls
@ -48,8 +144,7 @@ documentation at https://www.lua.org/manual/5.1/manual.html#pdf-require.

 For example, if 'runtimepath' is `foo,bar` and |package.cpath| was
 `./?.so;./?.dll` at startup, `require('mod')` searches these paths in order
-and loads the first module found:
-
+and loads the first module found ("first wins"):
    foo/lua/mod.lua
    foo/lua/mod/init.lua
    bar/lua/mod.lua
@ -59,9 +154,10 @@ and loads the first module found:
    bar/lua/mod.so
    bar/lua/mod.dll

+                                                        *lua-package-path*
 Nvim automatically adjusts |package.path| and |package.cpath| according to the
 effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is
-changed. |package.path| is adjusted by simply appending `/lua/?.lua` and
+changed. `package.path` is adjusted by simply appending `/lua/?.lua` and
 `/lua/?/init.lua` to each directory from 'runtimepath' (`/` is actually the
 first character of `package.config`).

@ -121,163 +217,6 @@ Note:
  plugins using shell, which will not work with paths containing semicolons,
  it is better to not have them in 'runtimepath' at all.

-==============================================================================
-Lua Syntax Information                                       *lua-syntax-help*
-
-While Lua has a simple syntax, there are a few things to understand,
-particularly when looking at the documentation above.
-
-                                                    *lua-syntax-call-function*
-
-Lua functions can be called in multiple ways. Consider the function: >
-
-    local example_func = function(a, b)
-        print("A is: ", a)
-        print("B is: ", b)
-    end
-<
-The first way to call this function is: >
-
-    example_func(1, 2)
-    -- ==== Result ====
-    -- A is: 1
-    -- B is: 2
-<
-This way of calling a function is familiar from most scripting languages.
-In Lua, it's important to understand that any function arguments that are
-not supplied are automatically set to `nil`. For example: >
-
-    example_func(1)
-    -- ==== Result ====
-    -- A is: 1
-    -- B is: nil
-<
-Additionally, if any extra parameters are passed, they are discarded
-completely.
-
-In Lua, it is also possible to omit the parentheses (only) if the function
-takes a single string or table literal (`"foo"` or "`{1,2,3}`", respectively).
-The latter is most often used to approximate "keyword-style" arguments with a
-single dictionary, for example: >
-
-    local func_with_opts = function(opts)
-        local will_do_foo = opts.foo
-        local filename = opts.filename
-
-        ...
-    end
-
-    func_with_opts { foo = true, filename = "hello.world" }
-<
-In this style, each "parameter" is passed via keyword. It is still valid
-to call the function in the standard style: >
-
-    func_with_opts({ foo = true, filename = "hello.world" })
-<
-But often in the documentation, you will see the former rather than the
-latter style due to its brevity.
-
-==============================================================================
-Lua Patterns                                                    *lua-patterns*
-
-For performance reasons, Lua does not support regular expressions natively.
-Instead, the Lua `string` standard library allows manipulations using a
-restricted set of "patterns", see |luaref-patterns|.
-
-Examples (`string.match` extracts the first match): >
-
-    print(string.match("foo123bar123", "%d+"))
-    -- -> 123
-
-    print(string.match("foo123bar123", "[^%d]+"))
-    -- -> foo
-
-    print(string.match("foo123bar123", "[abc]+"))
-    -- -> ba
-
-    print(string.match("foo.bar", "%.bar"))
-    -- -> .bar
-
-For more complex matching, Vim regular expressions can be used from Lua
-through |vim.regex()|.
-
------------------------------------------------------------------------------
-LUA PLUGIN EXAMPLE                                       *lua-require-example*
-
-The following example plugin adds a command `:MakeCharBlob` which transforms
-current buffer into a long `unsigned char` array. Lua contains transformation
-function in a module `lua/charblob.lua` which is imported in
-`autoload/charblob.vim` (`require("charblob")`). Example plugin is supposed
-to be put into any directory from 'runtimepath', e.g. `~/.config/nvim` (in
-this case `lua/charblob.lua` means `~/.config/nvim/lua/charblob.lua`).
-
-autoload/charblob.vim: >
-
-    function charblob#encode_buffer()
-      call setline(1, luaeval(
-      \    'require("charblob").encode(unpack(_A))',
-      \    [getline(1, '$'), &textwidth, '  ']))
-    endfunction
-<
-plugin/charblob.vim: >
-
-    if exists('g:charblob_loaded')
-      finish
-    endif
-    let g:charblob_loaded = 1
-
-    command MakeCharBlob :call charblob#encode_buffer()
-<
-lua/charblob.lua: >
-
-    local function charblob_bytes_iter(lines)
-      local init_s = {
-        next_line_idx = 1,
-        next_byte_idx = 1,
-        lines = lines,
-      }
-      local function next(s, _)
-        if lines[s.next_line_idx] == nil then
-          return nil
-        end
-        if s.next_byte_idx > #(lines[s.next_line_idx]) then
-          s.next_line_idx = s.next_line_idx + 1
-          s.next_byte_idx = 1
-          return ('\n'):byte()
-        end
-        local ret = lines[s.next_line_idx]:byte(s.next_byte_idx)
-        if ret == ('\n'):byte() then
-          ret = 0  -- See :h NL-used-for-NUL.
-        end
-        s.next_byte_idx = s.next_byte_idx + 1
-        return ret
-      end
-      return next, init_s, nil
-    end
-
-    local function charblob_encode(lines, textwidth, indent)
-      local ret = {
-        'const unsigned char blob[] = {',
-        indent,
-      }
-      for byte in charblob_bytes_iter(lines) do
-        --                .- space + number (width 3) + comma
-        if #(ret[#ret]) + 5 > textwidth then
-          ret[#ret + 1] = indent
-        else
-          ret[#ret] = ret[#ret] .. ' '
-        end
-        ret[#ret] = ret[#ret] .. (('%3u,'):format(byte))
-      end
-      ret[#ret + 1] = '};'
-      return ret
-    end
-
-    return {
-      bytes_iter = charblob_bytes_iter,
-      encode = charblob_encode,
-    }
-<
 ==============================================================================
 COMMANDS                                                        *lua-commands*

@ -1053,6 +992,7 @@ LUA-VIMSCRIPT BRIDGE                                           *lua-vimscript*

 Nvim Lua provides an interface to Vimscript variables and functions, and
 editor commands and options.
+
 See also https://github.com/nanotee/nvim-lua-guide.

 vim.call({func}, {...})                                           *vim.call()*
@ -1436,7 +1376,7 @@ deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
      • {backtrace}    boolean|nil Prints backtrace. Defaults to true.

 inspect({object}, {options})                                   *vim.inspect()*
-    Return a human-readable representation of the given object.
+    Gets a human-readable representation of the given object.

    See also: ~
        https://github.com/kikito/inspect.lua
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@ -4852,7 +4852,7 @@ Lua is discussed in these references:
   "Proc. of V Brazilian Symposium on Programming Languages" (2001) B-14-B-28.

 ==============================================================================
-B  COPYRIGHT & LICENSES                                       *luaref-copyright*
+B  COPYRIGHT AND LICENSES                                     *luaref-copyright*

 This help file has the same copyright and license as Lua 5.1 and the Lua 5.1
 manual:
@ -4869,13 +4869,13 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.

-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.

 ==============================================================================
 C  LUAREF DOC                 *luarefvim* *luarefvimdoc* *luaref-help* *luaref-doc*
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@ -1,10 +1,10 @@
 *nvim.txt*	Nvim


-			    NVIM REFERENCE MANUAL
+                            NVIM REFERENCE MANUAL


-Nvim							   *nvim* *nvim-intro*
+Nvim                                                       *nvim* *nvim-intro*

 Nvim is based on Vim by Bram Moolenaar.

@ -14,13 +14,13 @@ If you are new to Vim, try the 30-minute tutorial: >
    :Tutor<Enter>

 Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim
-(especially editor and VimL features) is maintained where possible. See
+(especially editor and Vimscript features) is maintained where possible. See
 |vim-differences| for the complete reference of differences from Vim.

-				      Type |gO| to see the table of contents.
+                                      Type |gO| to see the table of contents.

 ==============================================================================
-Transitioning from Vim				*nvim-from-vim*
+Transitioning from Vim                          *nvim-from-vim*

 1. To start the transition, create your |init.vim| (user config) file: >

@ -38,32 +38,37 @@ Transitioning from Vim				*nvim-from-vim*
 See |provider-python| and |provider-clipboard| for additional software you
 might need to use some features.

-Your Vim configuration might not be entirely Nvim-compatible.
-See |vim-differences| for the full list of changes.
-
-The |'ttymouse'| option, for example, was removed from Nvim (mouse support
-should work without it). If you use the same |vimrc| for Vim and Nvim,
-consider guarding |'ttymouse'| in your configuration like so:
+Your Vim configuration might not be entirely Nvim-compatible (see
+|vim-differences|). For example the |'ttymouse'| option was removed from Nvim,
+because mouse support is always enabled if possible. If you use the same
+|vimrc| for Vim and Nvim you could guard |'ttymouse'| in your configuration
+like so:
 >
    if !has('nvim')
        set ttymouse=xterm2
    endif
-<
-Conversely, if you have Nvim specific configuration items, you could do
-this:
+
+And for Nvim-specific configuration, you can do this:
 >
    if has('nvim')
        tnoremap <Esc> <C-\><C-n>
    endif
-<
+
 For a more granular approach use |exists()|:
 >
    if exists(':tnoremap')
        tnoremap <Esc> <C-\><C-n>
    endif
-<
+
 Now you should be able to explore Nvim more comfortably. Check |nvim-features|
 for more information.

+                                                        *portable-config*
+Because Nvim follows the XDG |base-directories| standard, configuration on
+Windows is stored in ~/AppData instead of ~/.config. But you can still share
+the same Nvim configuration on all of your machines, by creating
+~/AppData/Local/nvim/init.vim containing just this line: >
+    source ~/.config/nvim/init.vim
+
 ==============================================================================
- vim:tw=78:ts=8:noet:ft=help:norl:
+ vim:tw=78:ts=8:et:ft=help:norl:
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@ -4948,10 +4948,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 	  indent/	indent scripts |indent-expression|
 	  keymap/	key mapping files |mbyte-keymap|
 	  lang/		menu translations |:menutrans|
+	  lua/		|Lua| plugins
 	  menu.vim	GUI menus |menu.vim|
 	  pack/		packages |:packadd|
+	  parser/	|treesitter| syntax parsers
 	  plugin/	plugin scripts |write-plugin|
 	  print/	files for printing |postscript-print-encoding|
+	  query/	|treesitter| queries
 	  rplugin/	|remote-plugin| scripts
 	  spell/	spell checking files |spell|
 	  syntax/	syntax files |mysyntaxfile|
@ -4972,20 +4975,20 @@ A jump table for the options with a short description can be found at |Q_op|.
 	   but are not part of the Nvim distribution. XDG_DATA_DIRS defaults
 	   to /usr/local/share/:/usr/share/, so system administrators are
 	   expected to install site plugins to /usr/share/nvim/site.
-	5. Applications state home directory, for files that contain your
-	   session state (eg. backupdir, viewdir, undodir, etc).
+	5. Session state directory, for state data such as swap, backupdir,
+	   viewdir, undodir, etc.
 	   Given by `stdpath("state")`.  |$XDG_STATE_HOME|
-	6. $VIMRUNTIME, for files distributed with Neovim.
+	6. $VIMRUNTIME, for files distributed with Nvim.
 							*after-directory*
 	7, 8, 9, 10. In after/ subdirectories of 1, 2, 3 and 4, with reverse
-	   ordering.  This is for preferences to overrule or add to the 
+	   ordering.  This is for preferences to overrule or add to the
 	   distributed defaults or system-wide settings (rarely needed).

-							*rtp-packages*
-	"start" packages will additionally be used to search for runtime files
-	after these, but package entries are not visible in `:set rtp`.
-	See |runtime-search-path| for more information. "opt" packages
-	will be explicitly added to &rtp when |:packadd| is used.
+							*packages-runtimepath*
+	"start" packages will also be searched (|runtime-search-path|) for
+	runtime files after these, though such packages are not explicitly
+	reported in &runtimepath. But "opt" packages are explicitly added to
+	&runtimepath by |:packadd|.

 	Note that, unlike 'path', no wildcards like "**" are allowed.  Normal
 	wildcards are allowed, but can significantly slow down searching for
@ -4995,18 +4998,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Example: >
 		:set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
 <	This will use the directory "~/vimruntime" first (containing your
-	personal Vim runtime files), then "/mygroup/vim" (shared between a
-	group of people) and finally "$VIMRUNTIME" (the distributed runtime
-	files).
-	You probably should always include $VIMRUNTIME somewhere, to use the
-	distributed runtime files.  You can put a directory before $VIMRUNTIME
-	to find files which replace a distributed runtime files.  You can put
-	a directory after $VIMRUNTIME to find files which add to distributed
-	runtime files.
-	When Vim is started with |--clean| the home directory entries are not
-	included.
-	This option cannot be set from a |modeline| or in the |sandbox|, for
-	security reasons.
+	personal Nvim runtime files), then "/mygroup/vim", and finally
+	"$VIMRUNTIME" (the default runtime files).
+	You can put a directory before $VIMRUNTIME to find files which replace
+	distributed runtime files.  You can put a directory after $VIMRUNTIME
+	to find files which add to distributed runtime files.
+
+	With |--clean| the home directory entries are not included.

 						*'scroll'* *'scr'*
 'scroll' 'scr'		number	(default: half the window height)
@ -6795,28 +6793,31 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'verbose'* *'vbs'*
 'verbose' 'vbs'		number	(default 0)
 			global
-	When bigger than zero, Vim will give messages about what it is doing.
-	Currently, these messages are given:
-	>= 1	Lua assignments to options, mappings, etc.
-	>= 2	When a file is ":source"'ed and when the shada file is read or written..
-	>= 3	UI info, terminal capabilities
-	>= 4	Shell commands.
-	>= 5	Every searched tags file and include file.
-	>= 8	Files for which a group of autocommands is executed.
-	>= 9	Every executed autocommand.
-	>= 11	Finding items in a path
-	>= 12	Every executed function.
-	>= 13	When an exception is thrown, caught, finished, or discarded.
-	>= 14	Anything pending in a ":finally" clause.
-	>= 15	Every executed Ex command from a script (truncated at 200
-		characters).
-	>= 16	Every executed Ex command.
+	Sets the verbosity level.  Also set by |-V| and |:verbose|.

-	This option can also be set with the "-V" argument.  See |-V|.
-	This option is also set by the |:verbose| command.
+	Tracing of options in Lua scripts is activated at level 1; Lua scripts
+	are not traced with verbose=0, for performance.

-	When the 'verbosefile' option is set then the verbose messages are not
-	displayed.
+	If greater than or equal to a given level, Nvim produces the following
+	messages:
+
+	Level   Messages ~
+	----------------------------------------------------------------------
+	1	Lua assignments to options, mappings, etc.
+	2	When a file is ":source"'ed, or |shada| file is read or written.
+	3	UI info, terminal capabilities.
+	4	Shell commands.
+	5	Every searched tags file and include file.
+	8	Files for which a group of autocommands is executed.
+	9	Executed autocommands.
+	11	Finding items in a path.
+	12	Vimscript function calls.
+	13	When an exception is thrown, caught, finished, or discarded.
+	14	Anything pending in a ":finally" clause.
+	15	Ex commands from a script (truncated at 200 characters).
+	16	Ex commands.
+
+	If 'verbosefile' is set then the verbose messages are not displayed.

 						*'verbosefile'* *'vfile'*
 'verbosefile' 'vfile'	string	(default empty)
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@ -236,6 +236,22 @@ The "copy" function stores a list of lines and the register type. The "paste"
 function returns the clipboard as a `[lines, regtype]` list, where `lines` is
 a list of lines and `regtype` is a register type conforming to |setreg()|.

+							      *clipboard-wsl*
+For Windows WSL, try this g:clipboard definition:
+>
+    let g:clipboard = {
+                \   'name': 'WslClipboard',
+                \   'copy': {
+                \      '+': 'clip.exe',
+                \      '*': 'clip.exe',
+                \    },
+                \   'paste': {
+                \      '+': 'powershell.exe -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
+                \      '*': 'powershell.exe -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
+                \   },
+                \   'cache_enabled': 0,
+                \ }
+
 ==============================================================================
 Paste 							*provider-paste* *paste*

--- a/runtime/doc/repeat.txt
+++ b/runtime/doc/repeat.txt
@ -498,22 +498,33 @@ Rationale:
 ==============================================================================
 Using Vim packages					*packages*

-A Vim package is a directory that contains one or more plugins.  The
-advantages over normal plugins:
- A package can be downloaded as an archive and unpacked in its own directory.
-  Thus the files are not mixed with files of other plugins.  That makes it
-  easy to update and remove.
- A package can be a git, mercurial, etc. repository.  That makes it really
-  easy to update.
- A package can contain multiple plugins that depend on each other.
- A package can contain plugins that are automatically loaded on startup and
-  ones that are only loaded when needed with `:packadd`.
+A Vim "package" is a directory that contains |plugin|s.  Compared to normal
+plugins, a package can...
+- be downloaded as an archive and unpacked in its own directory, so the files
+  are not mixed with files of other plugins.
+- be a git, mercurial, etc. repository, thus easy to update.
+- contain multiple plugins that depend on each other.
+- contain plugins that are automatically loaded on startup ("start" packages,
+  located in "pack/*/start/*") and ones that are only loaded when needed with
+  |:packadd| ("opt" packages, located in "pack/*/opt/*").

+							*runtime-search-path*
+Nvim searches for |:runtime| files in:
+	1. all paths in 'runtimepath'
+	2. all "pack/*/start/*" dirs
+
+Note that the "pack/*/start/*" paths are not explicitly included in
+'runtimepath', so they will not be reported by ":set rtp" or "echo &rtp".
+Scripts can use |nvim_list_runtime_paths()| to list all used directories, and
+|nvim_get_runtime_file()| to query for specific files or sub-folders within
+the runtime path. Example: >
+	" List all runtime dirs and packages with Lua paths.
+	:echo nvim_get_runtime_file("lua/", v:true)

 Using a package and loading automatically ~

-Let's assume your Vim files are in the "~/.local/share/nvim/site" directory
-and you want to add a package from a zip archive "/tmp/foopack.zip":
+Let's assume your Nvim files are in "~/.local/share/nvim/site" and you want to
+add a package from a zip archive "/tmp/foopack.zip":
 	% mkdir -p ~/.local/share/nvim/site/pack/foo
 	% cd ~/.local/share/nvim/site/pack/foo
 	% unzip /tmp/foopack.zip
@ -526,28 +537,17 @@ You would now have these files under ~/.local/share/nvim/site:
 	pack/foo/start/foobar/syntax/some.vim
 	pack/foo/opt/foodebug/plugin/debugger.vim

-							*runtime-search-path*
-When runtime files are searched for, first all paths in 'runtimepath' are
-searched, then all "pack/*/start/*" dirs are searched. However, package entries
-are not visible in `:set rtp` or `echo &rtp`, as the final concatenated path
-would be too long and get truncated. To list all used directories, use
-|nvim_list_runtime_paths()|. In addition |nvim_get_runtime_file()| can be used
-to query for specific files or sub-folders within the runtime path. For
-instance to list all runtime dirs and packages with lua paths, use >
+On startup after processing your |config|, Nvim scans all directories in
+'packpath' for plugins in "pack/*/start/*", then loads the plugins.

-    :echo nvim_get_runtime_file("lua/", v:true)
+In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and load
+it.

-<When Vim starts up, after processing your .vimrc, it scans all directories in
-'packpath' for plugins under the "pack/*/start" directory, and all the plugins
-are loaded.
-
-In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and load it.
-
-If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will
+If the "foobar" plugin kicks in and sets the 'filetype' to "some", Nvim will
 find the syntax/some.vim file, because its directory is in the runtime search
 path.

-Vim will also load ftdetect files, if there are any.
+Nvim will also load ftdetect files, if there are any.

 Note that the files under "pack/foo/opt" are not loaded automatically, only the
 ones under "pack/foo/start".  See |pack-add| below for how the "opt" directory
@ -589,12 +589,12 @@ This searches for "pack/*/opt/foodebug" in 'packpath' and will find
 it.

 This could be done if some conditions are met.  For example, depending on
-whether Vim supports a feature or a dependency is missing.
+whether Nvim supports a feature or a dependency is missing.

 You can also load an optional plugin at startup, by putting this command in
 your |config|: >
 	:packadd! foodebug
-The extra "!" is so that the plugin isn't loaded if Vim was started with
+The extra "!" is so that the plugin isn't loaded if Nvim was started with
 |--noplugin|.

 It is perfectly normal for a package to only have files in the "opt"
@ -606,7 +606,7 @@ Where to put what ~
 Since color schemes, loaded with `:colorscheme`, are found below
 "pack/*/start" and "pack/*/opt", you could put them anywhere.  We recommend
 you put them below "pack/*/opt", for example
-".vim/pack/mycolors/opt/dark/colors/very_dark.vim".
+"~/.config/nvim/pack/mycolors/opt/dark/colors/very_dark.vim".

 Filetype plugins should go under "pack/*/start", so that they are always
 found.  Unless you have more than one plugin for a file type and want to
@ -684,8 +684,8 @@ found automatically.  Your package would have these files:
 <	pack/foo/start/lib/autoload/foolib.vim >
 		func foolib#getit()

-This works, because start packages will be used to look for autoload files,
-when sourcing the plugins.
+This works, because start packages will be searchd for autoload files, when
+sourcing the plugins.

 ==============================================================================
 Debugging scripts					*debug-scripts*
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@ -143,12 +143,11 @@ argument.
 		these commands, independently from "-c" commands.

 							*-S*
-S {file}	The {file} will be sourced after the first file has been read.
-		This is an easy way to do the equivalent of: >
+-S {file}	Vimscript or Lua (".lua") {file} will be |:source|d after the
+		first file has been read. Equivalent to: >
 			-c "source {file}"
-<		It can be mixed with "-c" arguments and repeated like "-c".
-		The limit of 10 "-c" arguments applies here as well.
-		{file} cannot start with a "-".
+<		Can be repeated like "-c", subject to the same limit of 10
+		"-c" arguments. {file} cannot start with a "-".

 -S		Works like "-S Session.vim".  Only when used as the last
 		argument or when another "-" option follows.
@ -203,13 +202,14 @@ argument.
 		send commands. >
 			printf "foo\n" | nvim -Es +"%print"

-<		Output of these commands is displayed (to stdout):
-			:print
+<		These commands display on stdout:
 			:list
 			:number
-			:set      (to display option values)
-		When 'verbose' is set messages are printed to stderr. >
-			echo foo | nvim -V1 -es
+			:print
+			:set
+		With |:verbose| or 'verbose', other commands display on stderr: >
+			nvim -es +":verbose echo 'foo'"
+			nvim -V1 -es +foo

 <		User |config| is skipped (unless given with |-u|).
 		Swap file is skipped (like |-n|).
@ -443,9 +443,9 @@ accordingly, proceeding as follows:
 						*VIMINIT* *EXINIT* *$MYVIMRC*
     b. Locations searched for initializations, in order of preference:
 	-  $VIMINIT environment variable (Ex command line).
-	-  User |config|: $XDG_CONFIG_HOME/nvim/init.vim.
-	-  Other config: {dir}/nvim/init.vim where {dir} is any directory
-	   in $XDG_CONFIG_DIRS.
+	-  User |config|: $XDG_CONFIG_HOME/nvim/init.vim (or init.lua).
+	-  Other config: {dir}/nvim/init.vim (or init.lua) where {dir} is any
+	   directory in $XDG_CONFIG_DIRS.
 	-  $EXINIT environment variable (Ex command line).
 	|$MYVIMRC| is set to the first valid location unless it was already
 	set or when using $VIMINIT.
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@ -643,6 +643,9 @@ Options:
  *'ttytype'* *'tty'*
  weirdinvert

+Performance:
+  Folds are not updated during insert-mode.
+
 Startup:
  --literal (file args are always literal; to expand wildcards on Windows, use
    |:n| e.g. `nvim +"n *"`)
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@ -12,21 +12,8 @@
 -- Guideline: "If in doubt, put it in the runtime".
 --
 -- Most functions should live directly in `vim.`, not in submodules.
-- The only "forbidden" names are those claimed by legacy `if_lua`:
--    $ vim
--    :lua for k,v in pairs(vim) do print(k) end
--    buffer
--    open
--    window
--    lastline
--    firstline
--    type
--    line
--    eval
--    dict
--    beep
--    list
--    command
+--
+-- Compatibility with Vim's `if_lua` is explicitly a non-goal.
 --
 -- Reference (#6580):
 --    - https://github.com/luafun/luafun
@ -120,9 +107,7 @@ function vim._os_proc_children(ppid)
  return children
 end

-- TODO(ZyX-I): Create compatibility layer.
-
--- Return a human-readable representation of the given object.
+--- Gets a human-readable representation of the given object.
 ---
 ---@see https://github.com/kikito/inspect.lua
 ---@see https://github.com/mpeterv/vinspect
--- a/scripts/bump-deps.sh
+++ b/scripts/bump-deps.sh
@ -17,9 +17,13 @@ BASENAME="$(basename "${0}")"
 readonly BASENAME

 usage() {
-  echo "Bump Neovim dependencies"
+  echo "Bump Nvim dependencies"
  echo
  echo "Usage:  ${BASENAME} [ -h | --pr | --branch=<dep> | --dep=<dependency> ]"
+  echo "    Update a dependency:"
+  echo "        ./scripts/bump-deps.sh --dep Luv --version 1.43.0-0"
+  echo "    Create a PR:"
+  echo "        ./scripts/bump-deps.sh --pr"
  echo
  echo "Options:"
  echo "    -h                    show this message and exit."
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@ -33,6 +33,7 @@ local spell_dict = {
  NeoVim = 'Nvim',
  neovim = 'Nvim',
  lua = 'Lua',
+  VimL = 'Vimscript',
 }

 local M = {}
@ -42,7 +43,9 @@ local M = {}
 local new_layout = {
  ['api.txt'] = true,
  ['channel.txt'] = true,
+  ['deprecated.txt'] = true,
  ['develop.txt'] = true,
+  ['lua.txt'] = true,
  ['luaref.txt'] = true,
  ['news.txt'] = true,
  ['nvim.txt'] = true,
@ -158,8 +161,8 @@ local function is_noise(line, noise_lines)
    or line:find('%s*%*?[a-zA-Z]+%.txt%*?%s+N?[vV]im%s*$')
    -- modeline
    -- Example: "vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:"
-    or line:find('^%s*vi[m]%:.*ft=help')
-    or line:find('^%s*vi[m]%:.*filetype=help')
+    or line:find('^%s*vim?%:.*ft=help')
+    or line:find('^%s*vim?%:.*filetype=help')
    or line:find('[*>]local%-additions[*<]')
  ) then
    -- table.insert(stats.noise_lines, getbuflinestr(root, opt.buf, 0))
@ -457,7 +460,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
    if root:has_error() then
      return text
    end
-    local in_heading = vim.tbl_count({'h1', 'h2', 'h3'}, parent)
+    local in_heading = vim.tbl_contains({'h1', 'h2', 'h3'}, parent)
    local cssclass = (not in_heading and get_indent(node_text()) > 8) and 'help-tag-right' or 'help-tag'
    local tagname = node_text(root:child(1))
    if vim.tbl_count(stats.first_tags) < 2 then
@ -465,7 +468,8 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
      table.insert(stats.first_tags, tagname)
      return ''
    end
-    local s = ('%s<a name="%s"></a><span class="%s">%s</span>'):format(ws(), url_encode(tagname), cssclass, trimmed)
+    local el = in_heading and 'span' or 'code'
+    local s = ('%s<a name="%s"></a><%s class="%s">%s</%s>'):format(ws(), url_encode(tagname), el, cssclass, trimmed, el)
    if in_heading and prev ~= 'tag' then
      -- Start the <span> container for tags in a heading.
      -- This makes "justify-content:space-between" right-align the tags.
@ -762,7 +766,7 @@ local function gen_css(fname)
    }
    .toc {
      /* max-width: 12rem; */
-      height: 95%;  /* Scroll if there are too many items. https://github.com/neovim/neovim.github.io/issues/297 */
+      height: 85%;  /* Scroll if there are too many items. https://github.com/neovim/neovim.github.io/issues/297 */
      overflow: auto;  /* Scroll if there are too many items. https://github.com/neovim/neovim.github.io/issues/297 */
    }
    .toc > div {
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@ -2,9 +2,7 @@
 """Generates Nvim :help docs from C/Lua docstrings, using Doxygen.

 Also generates *.mpack files. To inspect the *.mpack structure:
-
-    :new | put=v:lua.vim.inspect(msgpackparse(readfile('runtime/doc/api.mpack')))
-
+    :new | put=v:lua.vim.inspect(v:lua.vim.mpack.unpack(readfile('runtime/doc/api.mpack','B')))

 Flow:
    main
@ -287,7 +285,7 @@ annotation_map = {
    'FUNC_API_FAST': '|api-fast|',
    'FUNC_API_CHECK_TEXTLOCK': 'not allowed when |textlock| is active',
    'FUNC_API_REMOTE_ONLY': '|RPC| only',
-    'FUNC_API_LUA_ONLY': '|vim.api| only',
+    'FUNC_API_LUA_ONLY': 'Lua |vim.api| only',
 }


--- a/src/clint.py
+++ b/src/clint.py
@ -1,5 +1,7 @@
 #!/usr/bin/env python3
 #
+# https://github.com/cpplint/cpplint
+#
 # Copyright (c) 2009 Google Inc. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@ -29,15 +31,9 @@

 """Lints C files in the Neovim source tree.

-The goal of this script is to identify places in the code that *may*
-be in non-compliance with Neovim style.  It does not attempt to fix
-up these problems -- the point is to educate.  It does also not
-attempt to find all problems, or to ensure that everything it does
-find is legitimately a problem.
-
-In particular, we can get very confused by /* and // inside strings!
-We do a small hack, which is to ignore //'s with "'s after them on the
-same line, but it is far from perfect (in either direction).
+This can get very confused by /* and // inside strings! We do a small hack,
+which is to ignore //'s with "'s after them on the same line, but it is far
+from perfect (in either direction).
 """


@ -61,25 +57,10 @@ Syntax: clint.py [--verbose=#] [--output=vs7] [--filter=-x,+y,...]
        <file> [file] ...

  The style guidelines this tries to follow are those in
-    http://neovim.io/develop/style-guide.xml
+    https://neovim.io/doc/user/dev_style.html#dev-style

-  Note: This is Google's cpplint.py modified for use with the Neovim project,
-  which follows the Google C++ coding convention except with the following
-  modifications:
-
-   * Function names are lower_case.
-   * Struct and enum names that are not typedef-ed are struct lower_case and
-     enum lower_case.
-   * The opening brace for functions appear on the next line.
-   * All control structures must always use braces.
-
-  Neovim is a C project. As a result, for .c and .h files, the following rules
-  are suppressed:
-
-   * [whitespace/braces] { should almost always be at the end of the previous
-     line
-   * [build/include] Include the directory when naming .h files
-   * [runtime/int] Use int16_t/int64_t/etc, rather than the C type.
+  Note: This is Google's https://github.com/cpplint/cpplint modified for use
+  with the Neovim project.

  Every problem is given a confidence score from 1-5, with 5 meaning we are
  certain of the problem, and 1 meaning it could be a legitimate construct.
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@ -355,6 +355,8 @@ static bool check_string_array(Array arr, bool disallow_nl, Error *err)
 /// Out-of-bounds indices are clamped to the nearest valid value, unless
 /// `strict_indexing` is set.
 ///
+/// @see |nvim_buf_set_text()|
+///
 /// @param channel_id
 /// @param buffer           Buffer handle, or 0 for current buffer
 /// @param start            First line index
@ -527,6 +529,8 @@ end:
 ///
 /// Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines.
 ///
+/// @see |nvim_buf_set_lines()|
+///
 /// @param channel_id
 /// @param buffer           Buffer handle, or 0 for current buffer
 /// @param start_row        First line index
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@ -51,7 +51,9 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
  win_set_buf(window, buffer, false, err);
 }

-/// Gets the (1,0)-indexed cursor position in the window. |api-indexing|
+/// Gets the (1,0)-indexed, buffer-relative cursor position for a given window
+/// (different windows showing the same buffer have independent cursor
+/// positions). |api-indexing|
 ///
 /// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
--- a/src/nvim/hashtab.c
+++ b/src/nvim/hashtab.c
@ -194,7 +194,7 @@ void hash_debug_results(void)
 #endif  // ifdef HT_DEBUG
 }

-/// Add item for key "key" to hashtable "ht".
+/// Add (empty) item for key `key` to hashtable `ht`.
 ///
 /// @param key Pointer to the key for the new item. The key has to be contained
 ///            in the new item (@see hashitem_T). Must not be NULL.
--- a/src/nvim/terminal.c
+++ b/src/nvim/terminal.c
@ -111,9 +111,9 @@ struct terminal {
  //  - receive data from libvterm as a result of key presses.
  char textbuf[0x1fff];

-  ScrollbackLine **sb_buffer;       // Scrollback buffer storage for libvterm
-  size_t sb_current;                // number of rows pushed to sb_buffer
-  size_t sb_size;                   // sb_buffer size
+  ScrollbackLine **sb_buffer;       // Scrollback storage.
+  size_t sb_current;                // Lines stored in sb_buffer.
+  size_t sb_size;                   // Capacity of sb_buffer.
  // "virtual index" that points to the first sb_buffer row that we need to
  // push to the terminal buffer when refreshing the scrollback. When negative,
  // it actually points to entries that are no longer in sb_buffer (because the
@ -154,7 +154,7 @@ static VTermScreenCallbacks vterm_screen_callbacks = {
  .movecursor  = term_movecursor,
  .settermprop = term_settermprop,
  .bell        = term_bell,
-  .sb_pushline = term_sb_push,
+  .sb_pushline = term_sb_push,  // Called before a line goes offscreen.
  .sb_popline  = term_sb_pop,
 };

@ -952,7 +952,10 @@ static int term_bell(void *data)
  return 1;
 }

-// Scrollback push handler (from pangoterm).
+/// Scrollback push handler: called just before a line goes offscreen (and libvterm will forget it),
+/// giving us a chance to store it.
+///
+/// Code adapted from pangoterm.
 static int term_sb_push(int cols, const VTermScreenCell *cells, void *data)
 {
  Terminal *term = data;
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@ -2277,7 +2277,7 @@ describe('API', function()
      eq({'a', '', 'b'}, meths.list_runtime_paths())
      meths.set_option('runtimepath', ',a,b')
      eq({'', 'a', 'b'}, meths.list_runtime_paths())
-      -- trailing , is ignored, use ,, if you really really want $CWD
+      -- Trailing "," is ignored. Use ",," if you really really want CWD.
      meths.set_option('runtimepath', 'a,b,')
      eq({'a', 'b'}, meths.list_runtime_paths())
      meths.set_option('runtimepath', 'a,b,,')
--- a/test/functional/helpers.lua
+++ b/test/functional/helpers.lua
@ -275,7 +275,6 @@ function module.command(cmd)
  module.request('nvim_command', cmd)
 end

-
 -- Use for commands which expect nvim to quit.
 -- The first argument can also be a timeout.
 function module.expect_exit(fn_or_timeout, ...)