From ca67ba3b668a1b9586b07d7edd1439d0d50da1bd Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 14 Mar 2026 22:18:08 +0100 Subject: [PATCH] docs: misc --- CONTRIBUTING.md | 9 +++---- runtime/doc/api.txt | 2 ++ runtime/doc/filetype.txt | 16 ++++++------- runtime/doc/news.txt | 2 +- runtime/doc/options.txt | 36 +++++++++++++++------------- runtime/lua/vim/_meta/api.lua | 2 ++ runtime/lua/vim/_meta/options.lua | 40 ++++++++++++++++++------------- src/nvim/api/win_config.c | 2 ++ src/nvim/options.lua | 36 +++++++++++++++------------- 9 files changed, 81 insertions(+), 64 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40d0bd713b..1af7434665 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,8 @@ Reporting problems Developer guidelines -------------------- +- New functionality should generally be implemented in Lua, not C. PRs [#37757](https://github.com/neovim/neovim/pull/37757), [#37831](https://github.com/neovim/neovim/pull/37831) + are excellent examples of this. - Read [:help dev-quickstart](https://neovim.io/doc/user/dev_tools.html#dev-quickstart) to see how to run tests and start hacking on the codebase. - Read [:help dev](https://neovim.io/doc/user/dev.html#dev) and [:help dev-doc][dev-doc-guide] if you are working on Nvim core. - Read [:help dev-ui](https://neovim.io/doc/user/dev.html#dev-ui) if you are developing a UI. @@ -195,7 +197,7 @@ Coding You can run the linter locally by: ```bash -make lint +make lint # or lintc, lintlua, lintquery, lintdoc ``` ### Style @@ -206,7 +208,6 @@ make lint ``` This will format changed C, Lua, and treesitter query files with all appropriate flags set. - - Style rules are (mostly) defined by `src/uncrustify.cfg` which tries to match the [style-guide]. To use the Nvim `gq` command with `uncrustify`: ```vim @@ -214,8 +215,8 @@ make lint setlocal formatprg=uncrustify\ -q\ -l\ C\ -c\ src/uncrustify.cfg\ --no-backup endif ``` -- There is also `.clang-format` which has drifted from the [style-guide], but - is available for reference. To use the Nvim `gq` command with `clang-format`: +- There is also `.clang-format` which is "mostly" aligned with uncrustify. + To use the Nvim `gq` command with `clang-format`: ```vim if !empty(findfile('.clang-format', ';')) setlocal formatprg=clang-format\ -style=file diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c094ef9b45..f2275befc4 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3982,6 +3982,8 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()* Reconfigures the layout and properties of a window. • Updates only the given keys; unspecified (`nil`) keys will not be changed. + • Can move a window to another tabpage. + • Can transform a window to/from a float. • Keys `row` / `col` / `relative` must be specified together. • Cannot move the last window in a tabpage to a different one. diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 5b3dae44f4..acdef58782 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -301,15 +301,15 @@ all loaded. For example, if this command: > set runtimepath -produces this output: +produces this output: > - runtimepath=/etc/vim,~/.config/nvim,/usr/local/share/vim/vim82 ~ + runtimepath=/etc/vim,~/.config/nvim,/usr/local/share/vim/vim82 -then Vim will load all plugins in these directories and below: +then Vim will load all plugins in these directories and below: > - /etc/vim/plugin/ ~ - ~/.config/nvim/plugin/ ~ - /usr/local/share/vim/vim82/plugin/ ~ + /etc/vim/plugin/ + ~/.config/nvim/plugin/ + /usr/local/share/vim/vim82/plugin/ Note that the last one is the value of $VIMRUNTIME which has been expanded. @@ -323,9 +323,9 @@ happens when Vim starts up by using the |-V| argument: > vim -V2 You will see a lot of messages, in between them is a remark about loading the -plugins. It starts with: +plugins. It starts with: > - Searching for "plugin/**/*.vim" in ~ + Searching for "plugin/**/*.vim" in There you can see where Vim looks for your plugin scripts. diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index a6c685d17e..f99e685bd2 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -168,7 +168,7 @@ API • |nvim_open_tabpage()| can open a new |tab-page|. • |nvim_open_win()| floating windows can show a 'statusline'. Plugins can use `style='minimal'` or `:setlocal statusline=` to hide the statusline. -• |nvim_win_set_config()| can move windows to other tab pages as floats. +• |nvim_win_set_config()| can move |floating-windows| to other tabpages. • Added experimental |nvim__exec_lua_fast()| to allow remote API clients to execute code while nvim is blocking for input. • |vim.secure.trust()| accepts `path` for the `allow` action. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index b6d61575cc..995229519b 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -6902,10 +6902,11 @@ A jump table for the options with a short description can be found at |Q_op|. *'title'* *'notitle'* 'title' boolean (default off) global - When on, the title of the window will be set to the value of - 'titlestring' (if it is not empty), or to: + If enabled, Nvim will update the (GUI or terminal) window title. The + format is configured by 'titlestring'. By default it looks like: > filename [+=-] (path) - Nvim - Where: +< + where: > filename the name of the file being edited - indicates the file cannot be modified, 'ma' off + indicates the file was modified @@ -6913,6 +6914,7 @@ A jump table for the options with a short description can be found at |Q_op|. =+ indicates the file is read-only and modified (path) is the path of the file being edited - Nvim the server name |v:servername| or "Nvim" +< *'titlelen'* 'titlelen' number (default 85) @@ -6938,32 +6940,32 @@ A jump table for the options with a short description can be found at |Q_op|. *'titlestring'* 'titlestring' string (default "") global - When this option is not empty, it will be used for the title of the - window. This happens only when the 'title' option is on. + Formats the window title, enabled by the 'title' option. - When this option contains printf-style '%' items, they will be - expanded according to the rules used for 'statusline'. If it contains - an invalid '%' format, the value is used as-is and no error or warning - will be given when the value is set. + Contains printf-style "%" items, expanded according to the rules of + 'statusline'. If a "%" format is invalid, it is used as-is and no + error will be given. - The default behaviour is equivalent to: >vim + The default (empty) behaviour is equivalent to: >vim set titlestring=%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim < - This option cannot be set in a modeline when 'modelineexpr' is off. - Example: >vim auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") set title titlestring=%<%F%=%l/%L-%P titlelen=70 -< The value of 'titlelen' is used to align items in the middle or right - of the available space. - Some people prefer to have the file name first: >vim +< The value of 'titlelen' is used to align items in the middle + or right of the available space. + + Example: to have the file name first: >vim set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) -< Note the use of "%{ }" and an expression to get the path of the file, - without the file name. The "%( %)" constructs are used to add a +< Note the use of "%{ }" and an expression to get the path of + the file, without the file name. The "%( %)" constructs add a separating space only when needed. + NOTE: Use of special characters in 'titlestring' may cause the display to be garbled (e.g., when it contains a CR or NL character). + This option cannot be set in a modeline when 'modelineexpr' is off. + *'ttimeout'* *'nottimeout'* 'ttimeout' boolean (default on) global diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 5c2e54f3ae..f8ba22ee6c 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -2507,6 +2507,8 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- Reconfigures the layout and properties of a window. --- --- - Updates only the given keys; unspecified (`nil`) keys will not be changed. +--- - Can move a window to another tabpage. +--- - Can transform a window to/from a float. --- - Keys `row` / `col` / `relative` must be specified together. --- - Cannot move the last window in a tabpage to a different one. --- diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index ab24f03595..e3989b243b 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -7479,10 +7479,14 @@ vim.o.tm = vim.o.timeoutlen vim.go.timeoutlen = vim.o.timeoutlen vim.go.tm = vim.go.timeoutlen ---- When on, the title of the window will be set to the value of ---- 'titlestring' (if it is not empty), or to: +--- If enabled, Nvim will update the (GUI or terminal) window title. The +--- format is configured by 'titlestring'. By default it looks like: +--- ``` --- filename [+=-] (path) - Nvim ---- Where: +--- ``` +--- +--- where: +--- ``` --- filename the name of the file being edited --- - indicates the file cannot be modified, 'ma' off --- + indicates the file was modified @@ -7490,6 +7494,8 @@ vim.go.tm = vim.go.timeoutlen --- =+ indicates the file is read-only and modified --- (path) is the path of the file being edited --- - Nvim the server name `v:servername` or "Nvim" +--- ``` +--- --- --- @type boolean vim.o.title = false @@ -7518,41 +7524,41 @@ vim.go.titlelen = vim.o.titlelen vim.o.titleold = "" vim.go.titleold = vim.o.titleold ---- When this option is not empty, it will be used for the title of the ---- window. This happens only when the 'title' option is on. +--- Formats the window title, enabled by the 'title' option. --- ---- When this option contains printf-style '%' items, they will be ---- expanded according to the rules used for 'statusline'. If it contains ---- an invalid '%' format, the value is used as-is and no error or warning ---- will be given when the value is set. +--- Contains printf-style "%" items, expanded according to the rules of +--- 'statusline'. If a "%" format is invalid, it is used as-is and no +--- error will be given. --- ---- The default behaviour is equivalent to: +--- The default (empty) behaviour is equivalent to: --- --- ```vim --- set titlestring=%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim --- ``` --- ---- This option cannot be set in a modeline when 'modelineexpr' is off. ---- --- Example: --- --- ```vim --- auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") --- set title titlestring=%<%F%=%l/%L-%P titlelen=70 --- ``` ---- The value of 'titlelen' is used to align items in the middle or right ---- of the available space. ---- Some people prefer to have the file name first: +--- The value of 'titlelen' is used to align items in the middle +--- or right of the available space. +--- +--- Example: to have the file name first: --- --- ```vim --- set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) --- ``` ---- Note the use of "%{ }" and an expression to get the path of the file, ---- without the file name. The "%( %)" constructs are used to add a +--- Note the use of "%{ }" and an expression to get the path of +--- the file, without the file name. The "%( %)" constructs add a --- separating space only when needed. +--- --- NOTE: Use of special characters in 'titlestring' may cause the display --- to be garbled (e.g., when it contains a CR or NL character). --- +--- This option cannot be set in a modeline when 'modelineexpr' is off. +--- --- @type string vim.o.titlestring = "" vim.go.titlestring = vim.o.titlestring diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c index 921a622c6e..b7235ab5cb 100644 --- a/src/nvim/api/win_config.c +++ b/src/nvim/api/win_config.c @@ -738,6 +738,8 @@ restore_curwin: /// Reconfigures the layout and properties of a window. /// /// - Updates only the given keys; unspecified (`nil`) keys will not be changed. +/// - Can move a window to another tabpage. +/// - Can transform a window to/from a float. /// - Keys `row` / `col` / `relative` must be specified together. /// - Cannot move the last window in a tabpage to a different one. /// diff --git a/src/nvim/options.lua b/src/nvim/options.lua index bbc66cde5e..461083dc28 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -9677,10 +9677,11 @@ local options = { cb = 'did_set_title_icon', defaults = false, desc = [=[ - When on, the title of the window will be set to the value of - 'titlestring' (if it is not empty), or to: + If enabled, Nvim will update the (GUI or terminal) window title. The + format is configured by 'titlestring'. By default it looks like: > filename [+=-] (path) - Nvim - Where: + < + where: > filename the name of the file being edited - indicates the file cannot be modified, 'ma' off + indicates the file was modified @@ -9688,6 +9689,7 @@ local options = { =+ indicates the file is read-only and modified (path) is the path of the file being edited - Nvim the server name |v:servername| or "Nvim" + < ]=], full_name = 'title', scope = { 'global' }, @@ -9735,31 +9737,31 @@ local options = { cb = 'did_set_titlestring', defaults = '', desc = [=[ - When this option is not empty, it will be used for the title of the - window. This happens only when the 'title' option is on. + Formats the window title, enabled by the 'title' option. - When this option contains printf-style '%' items, they will be - expanded according to the rules used for 'statusline'. If it contains - an invalid '%' format, the value is used as-is and no error or warning - will be given when the value is set. + Contains printf-style "%" items, expanded according to the rules of + 'statusline'. If a "%" format is invalid, it is used as-is and no + error will be given. - The default behaviour is equivalent to: >vim + The default (empty) behaviour is equivalent to: >vim set titlestring=%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim < - This option cannot be set in a modeline when 'modelineexpr' is off. - Example: >vim auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") set title titlestring=%<%F%=%l/%L-%P titlelen=70 - < The value of 'titlelen' is used to align items in the middle or right - of the available space. - Some people prefer to have the file name first: >vim + < The value of 'titlelen' is used to align items in the middle + or right of the available space. + + Example: to have the file name first: >vim set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) - < Note the use of "%{ }" and an expression to get the path of the file, - without the file name. The "%( %)" constructs are used to add a + < Note the use of "%{ }" and an expression to get the path of + the file, without the file name. The "%( %)" constructs add a separating space only when needed. + NOTE: Use of special characters in 'titlestring' may cause the display to be garbled (e.g., when it contains a CR or NL character). + + This option cannot be set in a modeline when 'modelineexpr' is off. ]=], full_name = 'titlestring', modelineexpr = true,