docs: lsp, options, promptbuf

Close #37630
Close #37682
Close #37762
Close #37785

Co-authored-by: Daniel Schmitt <d.schmitt@lansoftware.de>
Co-authored-by: Duane Hilton <duane9@gmail.com>
Co-authored-by: NeOzay <colpaert.benoit@gmail.com>
Co-authored-by: Yi Ming <ofseed@foxmail.com>
Co-authored-by: "Justin M. Keyes" <justinkz@gmail.com>

BUILD.md

@@ -70,6 +70,18 @@ make distclean
 make deps
 ```
 
+### PUC Lua
+
+To build with "PUC Lua" instead of LuaJit:
+
+    make CMAKE_EXTRA_FLAGS="-DPREFER_LUA=ON" DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_LUAJIT=OFF -DUSE_BUNDLED_LUA=ON"
+
+### Build options
+
+View the full list of CMake options defined in this project:
+
+    cmake -B build -LH
+
 ## Building on Windows
 
 ### Windows / MSVC

CONTRIBUTING.md

@@ -235,7 +235,7 @@ See [#549][549] for more details.
 The Lua [`runtime/lua/vim/_core/`](./runtime/lua/vim/_core/) modules are
 precompiled to bytecode, so changes won't be usable unless you (1) rebuild Nvim
 or (2) start Nvim with `--luamod-dev` and `$VIMRUNTIME`. For example try adding
-a function to `runtime/lua/vim/editor.lua`, then:
+a function to `runtime/lua/vim/_core/editor.lua`, then:
 
 ```bash
 VIMRUNTIME=./runtime ./build/bin/nvim --luamod-dev

MAINTAIN.md

@@ -116,12 +116,7 @@ should be stated explicitly and publicly.
 Third-party dependencies
 ------------------------
 
-For some dependencies we maintain temporary "forks", which are simply private
-branches with a few extra patches, while we wait for the upstream project to
-merge the patches. This is done instead of maintaining the patches as (fragile)
-CMake `PATCH_COMMAND` steps.
-
-These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`.
+"Bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`.
 Some can be auto-bumped by `scripts/bump_deps.lua`.
 
 * [LuaJIT](https://github.com/LuaJIT/LuaJIT)
@@ -136,9 +131,10 @@ Some can be auto-bumped by `scripts/bump_deps.lua`.
 * [libiconv](https://ftp.gnu.org/pub/gnu/libiconv)
 * [lua-compat](https://github.com/keplerproject/lua-compat-5.3)
 * [tree-sitter](https://github.com/tree-sitter/tree-sitter)
-* [unibilium](https://github.com/neovim/unibilium)
-    * The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch.
 * [treesitter parsers](https://github.com/neovim/neovim/blob/7e97c773e3ba78fcddbb2a0b9b0d572c8210c83e/cmake.deps/deps.txt#L47-L62)
+* (Deprecated) [unibilium](https://github.com/neovim/unibilium)
+    * The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch.
+    * **Note:** unibilium is NOT required. See [BUILD.md](./BUILD.md#build-without-unibilium) to build Nvim without unibilium.
 
 ### Vendored dependencies
 

runtime/doc/channel.txt

@@ -189,7 +189,7 @@ normally only do that in a newly created buffer: >vim
 The user can edit and input text at the end of the buffer. Pressing Enter in
 the input section invokes the |prompt_setcallback()| callback, which is
 typically expected to process the prompt and show results by appending to the
-buffer. To input multiline text, use Shift-<Enter> to add a new line without
+buffer. To input multiline text, use *Shift-<Enter>* to add a new line without
 submitting the prompt, or just |put| or |paste| multiline text.
 
 Only the section starting with the mark |':| of the buffer (after the prompt)

runtime/doc/dev.txt

@@ -365,7 +365,7 @@ Where possible, these patterns apply to _both_ Lua and the API:
   If `opts` is omitted (or `nil`) it returns the current configuration.
   - Example: See |vim.diagnostic.config()|.
 - "Enable" ("toggle") interface and behavior:
-  - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the
+  - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control
     the "global" enablement of a feature.
     - `is_enabled(nil)` and `is_enabled({buf=nil})`, likewise, query the
       global state of the feature.

runtime/doc/dev_arch.txt

@@ -154,8 +154,8 @@ API
 
                                                         *dev-api-fast*
 API functions and Vimscript "eval" functions may be marked as |api-fast| which
-means they are safe to call in Lua callbacks and other scenarios. A functions
-CANNOT be marked as "fast" if could trigger `os_breakcheck()`, which may
+means they are safe to call in Lua callbacks and other scenarios. A function
+CANNOT be marked as "fast" if it could trigger `os_breakcheck()`, which may
 "yield" the current execution and start a new execution of code not expecting
 this:
 - accidentally recursing into a function not expecting this.

runtime/doc/dev_style.txt

@@ -6,7 +6,7 @@
 
 Nvim style guide                                        *dev-style*
 
-Style guidelines for developers working Nvim's source code.
+Style guidelines for developers working on Nvim's source code.
 
 License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/
 

runtime/doc/dev_test.txt

@@ -349,17 +349,26 @@ GUIDELINES
   files.
   - `#define` constants must be rewritten `const` or `enum` so they can be
     "visible" to the tests.
-- Use `pending()` to skip tests
-  ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
-  Do not silently skip the test with `if-else`. If a functional test depends on
-  some external factor (e.g. the existence of `md5sum` on `$PATH`), _and_ you
-  can't mock or fake the dependency, then skip the test via `pending()` if the
-  external factor is missing. This ensures that the _total_ test-count
-  (success + fail + error + pending) is the same in all environments.
+- Use `pending()` or `t.skip()` to skip tests.
+  - Example: https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18
+  - Note: If a test is skipped because of a non-actionable reason, we don't
+    want it to appear in the "pending" list. Include "N/A" in the skip
+    description, then it won't be added to the "pending" list. For example, if
+    a test is skipped because it's running on a non-LuaJit system, including
+    it in the "pending" list is just noise. Thus, its pending reason should
+    say "N/A": >
+    pending('N/A: missing LuaJIT FFI')
+<
+  - Do not silently skip the test with `if-else`. If a functional test depends
+    on some external factor (e.g. the existence of `md5sum` on `$PATH`), _and_
+    you can't mock or fake the dependency, then skip the test via `pending()`
+    if the external factor is missing. This ensures that the _total_
+    test-count (success + fail + error + pending) is the same in all
+    environments.
     - Note: `pending()` is ignored if it is missing an argument, unless it is
       [contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
       Provide empty function argument if the `pending()` call is outside `it()`
-      ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
+      Example: https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18
 
 WHERE TESTS GO
 
@@ -502,7 +511,7 @@ Number; !must be defined to function properly):
 
 - `NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level:
   - `0` disables tracing (the fastest, but you get no data if tests crash and
-    there no core dump was generated),
+    no core dump was generated),
   - `1` leaves only C function calls and returns in the trace (faster than
     recording everything),
   - `2` records all function calls, returns and executed Lua source lines.

runtime/doc/lsp.txt

@@ -56,7 +56,14 @@ Follow these steps to get LSP features:
    a |lsp-root_markers| file so the workspace can be recognized.
 5. Check that LSP is active ("attached") for the buffer: >vim
      :checkhealth vim.lsp
-6. (Optional) Configure keymaps and autocommands to use LSP features.
+6. Please note that certain LSP features are disabled by default,
+   you may choose to enable them manually. See:
+     - |lsp-codelens|
+     - |lsp-document_color|
+     - |lsp-linked_editing_range|
+     - |lsp-inlay_hint|
+     - |lsp-inline_completion|
+7. (Optional) Configure keymaps and autocommands to use LSP features.
    |lsp-attach|
 
 ==============================================================================
@@ -657,18 +664,16 @@ LspProgress                                                       *LspProgress*
     Redraw the statusline whenever an LSP progress message arrives: >vim
         autocmd LspProgress * redrawstatus
 <
-    Tell the parent terminal to indicate progress using a native progress
-    indicator (requires a supporting terminal): >lua
-        vim.api.nvim_create_autocmd('LspProgress', {
-          callback = function(ev)
+    Emit a |progress-message| on LSP progress events: >lua
+        vim.api.nvim_create_autocmd('LspProgress', { buffer = buf, callback = function(ev)
             local value = ev.data.params.value
-            if value.kind == 'begin' then
-              vim.api.nvim_ui_send('\027]9;4;1;0\027\\')
-            elseif value.kind == 'end' then
-              vim.api.nvim_ui_send('\027]9;4;0\027\\')
-            elseif value.kind == 'report' then
-              vim.api.nvim_ui_send(string.format('\027]9;4;1;%d\027\\', value.percentage or 0))
-            end
+            vim.api.nvim_echo({ { value.message or 'done' } }, false, {
+              id = 'lsp',
+              kind = 'progress',
+              title = value.title,
+              status = value.kind ~= 'end' and 'running' or 'success',
+              percent = value.percentage,
+            })
           end,
         })
 <

runtime/doc/lua-plugin.txt

@@ -142,7 +142,8 @@ initialization may be useful in specific cases:
 Keep in mind that this approach requires users to call `setup` in order to
 use your plugin, even if the default configuration is enough for them.
 Consider carefully whether your plugin benefits from combined `setup()` pattern
-before adopting it.
+before adopting it. This article chronicles the history and tradeoffs of
+`setup()`: https://mrcjkb.dev/posts/2023-08-22-setup.html
 
 NOTE: A well designed plugin has minimal impact on startup time. See also
 |lua-plugin-lazy|.

runtime/doc/map.txt

@@ -1581,7 +1581,7 @@ supports incremental command preview:
 	        preview_ns,
 	        'Substitute',
 	        {line1 + i - 2, start_idx - 1},
-	        {line1 + i - 2, end_idx},
+	        {line1 + i - 2, end_idx}
 	      )
 
 	      -- Add lines and set highlights in the preview buffer
@@ -1601,7 +1601,7 @@ supports incremental command preview:
 	          preview_ns,
 	          'Substitute',
 	          {preview_buf_line, #prefix + start_idx - 1},
-	          {preview_buf_line, #prefix + end_idx},
+	          {preview_buf_line, #prefix + end_idx}
 	        )
 	        preview_buf_line = preview_buf_line + 1
 	      end

runtime/doc/news.txt

@@ -41,7 +41,7 @@ TREESITTER
 
 UI
 
-• `progress` attribute removed form |ui-messages| msg_show event
+• `progress` attribute removed from |ui-messages| msg_show event
 
 VIMSCRIPT
 
@@ -255,7 +255,7 @@ LSP
   https://microsoft.github.io/language-server-protocol/specification/#textDocument_colorPresentation
 • The `textDocument/diagnostic` request now includes the previous id in its
   parameters.
-• |vim.lsp.enable()| start/stops clients as necessary. And detaches
+• |vim.lsp.enable()| start/stops clients as necessary and detaches
   non-applicable LSP clients.
 • |vim.lsp.is_enabled()| checks if a LSP config is enabled (without
   "resolving" it).
@@ -314,7 +314,7 @@ LUA
 • |vim.hl.range()| now allows multiple timed highlights.
 • |vim.tbl_extend()| and |vim.tbl_deep_extend()| now accept a function behavior argument.
 • |vim.fs.root()| can define "equal priority" via nested lists.
-• |vim.version.range()| output can be converted to human-readable string with |tostring()|.
+• |vim.version.range()| output can be converted to a human-readable string with |tostring()|.
 • |vim.version.intersect()| computes intersection of two version ranges.
 • |Iter:take()| and |Iter:skip()| now optionally accept predicates.
 • Built-in plugin manager |vim.pack|
@@ -359,17 +359,17 @@ PERFORMANCE
   additional constraints for improved correctness and resistance to
   backtracking edge cases.
 • |i_CTRL-R| inserts named/clipboard registers literally, 10x speedup.
+• LSP `textDocument/semanticTokens/range` is supported, which requests tokens
+  for the viewport (visible screen) only.
 
 PLUGINS
 
 • Customize :checkhealth by handling a `FileType checkhealth` event.
   |health-usage|
-
 • Simplify Python provider setup to a single step: `uv tool install pynvim`
   Nvim will detect the plugin's location without user configuration, even if
   unrelated Python virtual environments are activated.
   |provider-python|
-
 • |:checkhealth| now checks for an available |vim.ui.open()| handler.
 
 STARTUP
@@ -407,6 +407,7 @@ UI
   • "Error detected while processing:" changed to "Error in:".
   • "Error executing Lua:" changed to "Lua:".
 • 'busy' status is shown in default statusline with symbol ◐
+• Cursor shape indicates when it is behind an unfocused floating window.
 • Improved LSP signature help rendering.
 • Multigrid UIs can call nvim_input_mouse with grid 0 to let Nvim decide the grid.
 

runtime/lua/vim/health/health.lua

@@ -621,6 +621,8 @@ local function check_sysinfo()
       [[
     ## Problem
 
+    Describe the problem (concisely).
+
     ## Steps to reproduce
 
     ```

runtime/lua/vim/lsp.lua

@@ -198,7 +198,7 @@ end
 --- provide the root dir, or LSP will not be activated for the buffer. Thus a `root_dir()` function
 --- can dynamically decide per-buffer whether to activate (or skip) LSP.
 --- See example at |vim.lsp.enable()|.
---- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string))
+--- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string)) #
 ---
 --- [lsp-root_markers]()
 --- Filename(s) (".git/", "package.json", …) used to decide the workspace root. Unused if `root_dir`

runtime/scripts/optwin.lua

@@ -29,7 +29,6 @@ local options_list = {
     { 'autochdir', N_ 'change to directory of file in buffer' },
     { 'wrapscan', N_ 'search commands wrap around the end of the buffer' },
     { 'incsearch', N_ 'show match for partly typed search command' },
-    { 'magic', N_ 'change the way backslashes are used in search patterns' },
     { 'regexpengine', N_ 'select the default regexp engine used' },
     { 'ignorecase', N_ 'ignore case when using a search pattern' },
     { 'smartcase', N_ "override 'ignorecase' when pattern has upper case characters" },
@@ -438,7 +437,6 @@ local options_list = {
     { 'eventignorewin', N_ 'list of autocommand events which are to be ignored in a window' },
     { 'loadplugins', N_ 'load plugin scripts when starting up' },
     { 'exrc', N_ 'enable reading .vimrc/.exrc/.gvimrc in the current directory' },
-    { 'gdefault', N_ 'use the \'g\' flag for ":substitute"' },
     { 'maxfuncdepth', N_ 'maximum depth of function calls' },
     { 'sessionoptions', N_ 'list of words that specifies what to put in a session file' },
     { 'viewoptions', N_ 'list of words that specifies what to save for :mkview' },

src/nvim/message.h

@@ -37,7 +37,7 @@ EXTERN bool msg_ext_skip_flush INIT( = false);
 EXTERN bool msg_ext_append INIT( = false);
 /// Set to true when previous message should be overwritten.
 EXTERN bool msg_ext_overwrite INIT( = false);
-/// Set to true to avoid setting "verbose" kind for last set messages.
+/// Set to true to avoid setting "verbose" kind for "last set" messages.
 EXTERN bool msg_ext_skip_verbose INIT( = false);
 
 /// allocated grid for messages. Used unless ext_messages is active.

test/functional/lua/fs_spec.lua

@@ -731,7 +731,7 @@ describe('vim.fs', function()
       vim.uv.fs_rmdir('Xtest_fs-rm')
     end)
 
-    it('works with symlink', function()
+    it('symlink', function()
       -- File
       vim.uv.fs_symlink('Xtest_fs-rm/file-to-link', 'Xtest_fs-rm/file-as-link')
       vim.fs.rm('Xtest_fs-rm/file-as-link')

test/functional/lua/ui_spec.lua

@@ -109,7 +109,7 @@ describe('vim.ui', function()
       eq(true, exec_lua('return (nil == result)'))
     end)
 
-    it('can return opts.cacelreturn when aborted with ESC with cancelreturn opt #18144', function()
+    it('can return opts.cancelreturn when aborted with ESC with cancelreturn opt #18144', function()
       feed(':lua result = "on_confirm not called"<cr>')
       feed(':lua vim.ui.input({ cancelreturn = "CANCEL" }, function(input) result = input end)<cr>')
       feed('Inputted Text<esc>')

test/functional/plugin/optwin_spec.lua

@@ -68,10 +68,12 @@ describe('optwin.lua', function()
       'secure',
       'prompt',
       'edcompatible',
+      'gdefault',
       'guioptions',
       'guitablabel',
       'guitabtooltip',
       'insertmode',
+      'magic',
       'mouseshape',
       'imcmdline',
       'imdisable',