From 09dffb9db7d16496e55e86f78ab60241533d86f6 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 9 Oct 2022 08:21:52 -0400 Subject: [PATCH] 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 --- CMakeLists.txt | 3 +- CONTRIBUTING.md | 28 ++- LICENSE.txt | 5 +- MAINTAIN.md | 88 +++++----- runtime/doc/api.txt | 27 ++- runtime/doc/builtin.txt | 20 +-- runtime/doc/deprecated.txt | 232 ++++++++++++------------- runtime/doc/develop.txt | 87 ++++++---- runtime/doc/index.txt | 2 +- runtime/doc/lua.txt | 290 ++++++++++++------------------- runtime/doc/luaref.txt | 16 +- runtime/doc/nvim.txt | 39 +++-- runtime/doc/options.txt | 83 ++++----- runtime/doc/provider.txt | 16 ++ runtime/doc/repeat.txt | 68 ++++---- runtime/doc/starting.txt | 26 +-- runtime/doc/vim_diff.txt | 3 + runtime/lua/vim/_editor.lua | 21 +-- scripts/bump-deps.sh | 6 +- scripts/gen_help_html.lua | 14 +- scripts/gen_vimdoc.py | 6 +- src/clint.py | 35 +--- src/nvim/api/buffer.c | 4 + src/nvim/api/window.c | 4 +- src/nvim/hashtab.c | 2 +- src/nvim/terminal.c | 13 +- test/functional/api/vim_spec.lua | 2 +- test/functional/helpers.lua | 1 - 28 files changed, 559 insertions(+), 582 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 78da39b211..6a25e1de8d 100644 --- 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3adf13318..03fe48fed7 100644 --- 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 diff --git a/LICENSE.txt b/LICENSE.txt index c1b8286c4b..a772829aa3 100644 --- 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 ==== diff --git a/MAINTAIN.md b/MAINTAIN.md index 36ba07593d..d65337f92b 100644 --- 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 diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 6ffef22ec3..f92ef26399 100644 --- 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 diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index ad757981b0..344abe557c 100644 --- 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") diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index bb8b24f5bf..8fcd0fc1d0 100644 --- 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 ~ -** Use instead. -** Use instead. +KEYCODES +- ** Use instead. +- ** Use 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-* -*:menu-special* <> notation is always enabled. -*:map-* -*: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-* *:menu-special* *:map-* *: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: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index ebb0dfeb4e..14b66a0736 100644 --- 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 `
`  for code samples.
+- Use `
` 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 `
`  for code samples.
+- Use `
` 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:
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 8dd3d708a3..7318bc7f34 100644
--- 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 [].
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 801664a670..29e0508f60 100644
--- 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
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index 5387900d16..ffbb405804 100644
--- 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*
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index 513d27ccad..203f57024c 100644
--- 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
 
 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  
     endif
-<
+
 For a more granular approach use |exists()|:
 >
     if exists(':tnoremap')
         tnoremap  
     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:
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 837c3e7652..522819a320 100644
--- 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)
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 782bd19441..99ec84c625 100644
--- 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*
 
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index b84274cc9e..21945dc499 100644
--- 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.
 
-
 	: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*
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 2c18398598..baa60f431f 100644
--- 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.
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 8c6585a941..62b755d64b 100644
--- 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 *"`)
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index ef1a07b267..28e5897aa9 100644
--- 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
diff --git a/scripts/bump-deps.sh b/scripts/bump-deps.sh
index 85c7f72700..e725608b39 100755
--- 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= ]"
+  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."
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 540caa2ae3..13601b91f5 100644
--- 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%s'):format(ws(), url_encode(tagname), cssclass, trimmed)
+    local el = in_heading and 'span' or 'code'
+    local s = ('%s<%s class="%s">%s'):format(ws(), url_encode(tagname), el, cssclass, trimmed, el)
     if in_heading and prev ~= 'tag' then
       -- Start the  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 {
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 2612260226..3ee9d8b5dd 100755
--- 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',
 }
 
 
diff --git a/src/clint.py b/src/clint.py
index 1a355e0218..4829a50887 100755
--- 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] ...
 
   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.
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 6f8cad3e33..51fedb302a 100644
--- 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
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index aaff00d640..08dcc113da 100644
--- 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
diff --git a/src/nvim/hashtab.c b/src/nvim/hashtab.c
index 32d67621db..1ebac603c2 100644
--- 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.
diff --git a/src/nvim/terminal.c b/src/nvim/terminal.c
index e54a1c8334..50574b292d 100644
--- 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;
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index 909ff80837..af6cee7e90 100644
--- 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,,')
diff --git a/test/functional/helpers.lua b/test/functional/helpers.lua
index 4fcc190dee..723d2ccfa4 100644
--- 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, ...)