From 1f4ad7808e0feb7cb93182dd010a61467a11e122 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 May 2026 13:00:52 -0400 Subject: [PATCH] docs: misc, window #39720 - formalize `window-number` similar to `tabpage-number`. - reference it from docs. --- runtime/doc/news.txt | 3 +- runtime/doc/options.txt | 2 +- runtime/doc/vimfn.txt | 112 +++++++++++++------------- runtime/doc/windows.txt | 19 ++--- runtime/lua/vim/_meta/options.gen.lua | 2 +- runtime/lua/vim/_meta/vimfn.gen.lua | 112 +++++++++++++------------- src/nvim/eval.lua | 112 +++++++++++++------------- src/nvim/options.lua | 2 +- 8 files changed, 176 insertions(+), 188 deletions(-) diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 251eaa7a3a..0490313736 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -185,8 +185,7 @@ LUA OPTIONS -• 'ttyfast' can be disabled during startup by setting the environment variable - `NVIM_NOTTYFAST` to disable automatic background detection. +• 'ttyfast' can be disabled during startup by setting |$NVIM_NOTTYFAST|. • 'scrolloffpad' allows vertically centering cursor at the end of file. • 'shortmess' flag |shm-u| silences undo/redo messages. • 'winpinned' prevents window from closing unless specifically targeted. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 7675584fe5..4469c88499 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -6458,7 +6458,7 @@ A jump table for the options with a short description can be found at |Q_op|. added without modifying code that reacts on mouse clicks on this label. Use |getmousepos()|.winid in the specified function to get the - corresponding window id of the clicked item. + corresponding |window-ID| of the clicked item. < - Where to truncate line if too long. Default is at the start. No width fields allowed. = - Separation point between alignment sections. Each section will diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 59c73fa0a6..e90c93dec0 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -163,8 +163,8 @@ argc([{winid}]) *argc()* If {winid} is not supplied, the argument list of the current window is used. If {winid} is -1, the global argument list is used. - Otherwise {winid} specifies the window of which the argument - list is used: either the window number or the window ID. + Otherwise {winid} (a |window-number| or |window-ID|) specifies + the window of which the argument list is used. Returns -1 if the {winid} argument is invalid. Parameters: ~ @@ -190,7 +190,7 @@ arglistid([{winnr} [, {tabnr}]]) *arglistid()* With {winnr} only use this window in the current tabpage. With {winnr} and {tabnr} use the window in the specified tab page. - {winnr} can be the window number or the |window-ID|. + {winnr} is a |window-number| or |window-ID|. Parameters: ~ • {winnr} (`integer?`) @@ -211,7 +211,7 @@ argv([{nr} [, {winid}]]) *argv()* < Without the {nr} argument, or when {nr} is -1, a |List| with the whole |arglist| is returned. - The {winid} argument specifies the window ID, see |argc()|. + The {winid} argument is a |window-ID|, see |argc()|. For the Vim command line arguments see |v:argv|. Returns an empty string if {nr}th argument is not present in @@ -782,7 +782,7 @@ bufwinnr({buf}) *bufwinnr()* resolving {buf}; only the current tabpage is checked and no-match semantics differ. - Like |bufwinid()| but return the window number instead of the + Like |bufwinid()| but returns a |window-number| instead of a |window-ID|. If buffer {buf} doesn't exist or there is no such window, -1 is returned. Example: >vim @@ -1148,8 +1148,8 @@ cindent({lnum}) *cindent()* clearmatches([{win}]) *clearmatches()* Clears all matches previously defined for the current window by |matchadd()| and the |:match| commands. - If {win} is specified, use the window with this number or - window ID instead of the current window. + If {win} is specified, use this |window-number| or |window-ID| + instead of the current window. Parameters: ~ • {win} (`integer?`) @@ -3690,10 +3690,10 @@ getcurpos([{winid}]) *getcurpos()* the cursor is returned in "col". To get the character position, use |getcursorcharpos()|. - The optional {winid} argument can specify the window. It can - be the window number or the |window-ID|. The last known - cursor position is returned, this may be invalid for the - current value of the buffer if it is not the current window. + The optional {winid} (|window-number| or |window-ID|) specifies + the window. The last known cursor position is returned, this + may be invalid for the current value of the buffer if it is not + the current window. If {winid} is invalid a list with zeroes is returned. This can be used to save and restore the cursor position: >vim @@ -3738,7 +3738,7 @@ getcwd([{winnr} [, {tabnr}]]) *getcwd()* getcwd(0) getcwd(0, 0) < If {winnr} is -1 it is ignored, only the tab is resolved. - {winnr} can be the window number or the |window-ID|. + {winnr} is a |window-number| or |window-ID|. If both {winnr} and {tabnr} are -1 the global working directory is returned. Note: When {tabnr} is -1 Vim returns an empty string to @@ -3878,8 +3878,8 @@ getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* Returns the |jumplist| for the specified window. Without arguments use the current window. - With {winnr} only use this window in the current tabpage. - {winnr} can also be a |window-ID|. + With {winnr} (|window-number| or |window-ID|) only use this + window in the current tabpage. With {winnr} and {tabnr} use the window in the specified tab page. If {winnr} or {tabnr} is invalid, an empty list is returned. @@ -3938,12 +3938,12 @@ getline({lnum} [, {end}]) *getline()* getloclist({nr} [, {what}]) *getloclist()* Returns a |List| with all the entries in the location list for - window {nr}. {nr} can be the window number or the |window-ID|. + window {nr} (|window-number| or |window-ID|). When {nr} is zero the current window is used. For a location list window, the displayed location list is - returned. For an invalid window number {nr}, an empty list is - returned. Otherwise, same as |getqflist()|. + returned. For an invalid {nr}, an empty list is returned. + Otherwise, same as |getqflist()|. If the optional {what} dictionary argument is supplied, then returns the items listed in {what} as a dictionary. Refer to @@ -4006,9 +4006,9 @@ getmatches([{win}]) *getmatches()* |getmatches()| is useful in combination with |setmatches()|, as |setmatches()| can restore a list of matches saved by |getmatches()|. - If {win} is specified, use the window with this number or - window ID instead of the current window. If {win} is invalid, - an empty list is returned. + If {win} is specified, use this |window-number| or |window-ID| + instead of the current window. If {win} is invalid, an empty + list is returned. Example: >vim echo getmatches() < > @@ -4566,7 +4566,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Note that {varname} must be the name without "w:". Tabs are numbered starting with one. For the current tabpage use |getwinvar()|. - {winnr} can be the window number or the |window-ID|. + {winnr} is a |window-number| or |window-ID|. When {winnr} is zero the current window is used. This also works for a global option, buffer-local option and window-local option, but it doesn't work for a global variable @@ -4591,8 +4591,8 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* (`any`) gettagstack([{winnr}]) *gettagstack()* - Returns the tag stack of window {winnr} as a Dict. - {winnr} can be the window number or the |window-ID|. + Returns the tag stack of window {winnr} (|window-number| or + |window-ID|) as a Dict. When {winnr} is not specified, the current window is used. When window {winnr} doesn't exist, an empty Dict is returned. @@ -4674,7 +4674,7 @@ getwininfo([{winid}]) *getwininfo()* wincol leftmost screen column of the window; "col" from |win_screenpos()| winid |window-ID| - winnr window number + winnr |window-number| winrow topmost screen line of the window; "row" from |win_screenpos()| @@ -4964,7 +4964,7 @@ haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* echo haslocaldir(0, 0) < With {winnr} use that window in the current tabpage. With {winnr} and {tabnr} use the window in that tabpage. - {winnr} can be the window number or the |window-ID|. + {winnr} is a |window-number| or |window-ID|. If {winnr} is -1 it is ignored, only the tab is resolved. Throw error if the arguments are invalid. |E5000| |E5001| |E5002| @@ -6604,8 +6604,8 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) conceal Special character to show instead of the match (only for |hl-Conceal| highlighted matches, see |:syn-cchar|) - window Instead of the current window use the - window with this number or window ID. + window Use this |window-number| or |window-ID| instead + of the current window. The number of matches is not limited, as it is the case with the |:match| commands. @@ -6756,8 +6756,7 @@ matchdelete({id} [, {win}]) *matchdelete()* *E802* *E or one of the |:match| commands. Returns 0 if successful, otherwise -1. See example for |matchadd()|. All matches can be deleted in one operation by |clearmatches()|. - If {win} is specified, use the window with this number or - window ID instead of the current window. + {win} (if given) is a |window-number| or |window-ID|. Parameters: ~ • {id} (`integer`) @@ -9504,12 +9503,12 @@ setline({lnum}, {text}) *setline()* (`any`) setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* - Create or replace or add to the location list for window {nr}. - {nr} can be the window number or the |window-ID|. + Create or replace or add to the location list for window {nr} + (|window-number| or |window-ID|). When {nr} is zero the current window is used. For a location list window, the displayed location list is - modified. For an invalid window number {nr}, -1 is returned. + modified. For an invalid {nr}, -1 is returned. Otherwise, same as |setqflist()|. Also see |location-list|. @@ -9533,8 +9532,7 @@ setmatches({list} [, {win}]) *setmatches()* current window. Returns 0 if successful, otherwise -1. All current matches are cleared before the list is restored. See example for |getmatches()|. - If {win} is specified, use the window with this number or - window ID instead of the current window. + {win} (if given) is a |window-number| or |window-ID|. Parameters: ~ • {list} (`vim.fn.getmatches.ret.item[]`) @@ -9824,7 +9822,7 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* {val}. Tabs are numbered starting with one. For the current tabpage use |setwinvar()|. - {winnr} can be the window number or the |window-ID|. + {winnr} is a |window-number| or |window-ID|. When {winnr} is zero the current window is used. This also works for a global or local buffer option, but it doesn't work for a global or local buffer variable. @@ -9845,8 +9843,8 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* (`any`) settagstack({nr}, {dict} [, {action}]) *settagstack()* - Modify the tag stack of the window {nr} using {dict}. - {nr} can be the window number or the |window-ID|. + Modify the tag stack of the window {nr} (|window-number| or + |window-ID|) using {dict}. For a list of supported items in {dict}, refer to |gettagstack()|. "curidx" takes effect before changing the tag @@ -12374,8 +12372,8 @@ virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* For a multi-byte character, the column number of the first byte in the character is returned. - The {winid} argument can be the window number or the - |window-ID|. If this is zero, then the current window is used. + {winid} is a |window-number| or |window-ID|. If zero, the + current window is used. Returns -1 if the window {winid} doesn't exist or the buffer line {lnum} or virtual column {col} is invalid. @@ -12521,10 +12519,9 @@ win_getid([{win} [, {tab}]]) *win_getid()* Get the |window-ID| for the specified window. When {win} is missing use the current window. - With {win} this is the window number. The top window has - number 1. - Without {tab} use the current tab, otherwise the tab with - number {tab}. The first tab has number one. + With {win} this is the |window-number|. + Without {tab} use the current tab, otherwise the + |tabpage-number| given by {tab}. Return zero if the window cannot be found. Parameters: ~ @@ -12547,8 +12544,8 @@ win_gettype([{nr}]) *win_gettype()* "unknown" window {nr} not found When {nr} is omitted return the type of the current window. - When {nr} is given return the type of this window by number or - |window-ID|. + When {nr} is given (|window-number| or |window-ID|) return the + type of that window. Also see the 'buftype' option. @@ -12562,8 +12559,7 @@ win_gotoid({expr}) *win_gotoid()* Lua: Prefer |nvim_set_current_win()|; invalid IDs error instead of returning FALSE. - Go to window with ID {expr}. This may also change the current - tabpage. + Go to |window-ID| {expr}. May change the current tabpage. Return TRUE if successful, FALSE if the window cannot be found. @@ -12578,8 +12574,8 @@ win_id2tabwin({expr}) *win_id2tabwin()* |nvim_win_get_number()| for valid windows; invalid IDs error instead of returning `[0, 0]`. - Return a list with the tab number and window number of window - with ID {expr}: [tabnr, winnr]. + Return [tabnr, winnr] for window with |window-ID| {expr}, where + tabnr is the |tabpage-number| and winnr is the |window-number|. Return [0, 0] if the window cannot be found. Parameters: ~ @@ -12592,7 +12588,7 @@ win_id2win({expr}) *win_id2win()* Lua: Prefer |nvim_win_get_number()| for valid windows; windows outside the current tabpage and invalid IDs differ. - Return the window number of window with ID {expr}. + Return the |window-number| of for the given |window-ID| {expr}. Return 0 if the window cannot be found in the current tabpage. Parameters: ~ @@ -12604,7 +12600,7 @@ win_id2win({expr}) *win_id2win()* win_move_separator({nr}, {offset}) *win_move_separator()* Move window {nr}'s vertical separator (i.e., the right border) by {offset} columns, as if being dragged by the mouse. {nr} - can be a window number or |window-ID|. A positive {offset} + is a |window-number| or |window-ID|. A positive {offset} moves right and a negative {offset} moves left. Moving a window's vertical separator will change the width of the window and the width of other windows adjacent to the vertical @@ -12625,8 +12621,8 @@ win_move_separator({nr}, {offset}) *win_move_separator()* win_move_statusline({nr}, {offset}) *win_move_statusline()* Move window {nr}'s status line (i.e., the bottom border) by - {offset} rows, as if being dragged by the mouse. {nr} can be - a window number or |window-ID|. A positive {offset} moves + {offset} rows, as if being dragged by the mouse. {nr} is a + |window-number| or |window-ID|. A positive {offset} moves down and a negative {offset} moves up. Moving a window's status line will change the height of the window and the height of other windows adjacent to the status line. The @@ -12649,8 +12645,8 @@ win_screenpos({nr}) *win_screenpos()* Return the screen position of window {nr} as a list with two numbers: [row, col]. The first window always has position [1, 1], unless there is a tabline, then it is [2, 1]. - {nr} can be the window number or the |window-ID|. Use zero - for the current window. + {nr} is a |window-number| or |window-ID|. Use zero for the + current window. Returns [0, 0] if the window cannot be found. Parameters: ~ @@ -12665,7 +12661,7 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* Unlike commands such as |:split|, no new windows are created (the |window-ID| of window {nr} is unchanged after the move). - Both {nr} and {target} can be window numbers or |window-ID|s. + Both {nr} and {target} are a |window-number| or |window-ID|. Both must be in the current tabpage. Returns zero for success, non-zero for failure. @@ -12690,8 +12686,8 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* winbufnr({nr}) *winbufnr()* Lua: Prefer |nvim_win_get_buf()|. - Returns the buffer number associated with window {nr}. - {nr} can be the window number or the |window-ID|. + Returns the buffer number associated with window {nr} + (|window-number| or |window-ID|). When {nr} is zero, the number of the buffer in the current window is returned. When window {nr} doesn't exist, -1 is returned. diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 10bd80e915..ff2884b267 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -78,15 +78,16 @@ Windows (especially floating windows) can have many other |api-win_config| properties such as "hide" and "fixed" which also affect behavior. *window-ID* *winid* *windowid* -Each window has a unique identifier called the window ID. This identifier -will not change within a Vim session. The |win_getid()| and |win_id2tabwin()| -functions can be used to convert between the window/tab number and the -identifier. There is also the window number, which may change whenever -windows are opened or closed, see |winnr()|. -The window number is only valid in one specific tab. The window ID is valid -across tabs. For most functions that take a window ID or a window number, the -window number only applies to the current tab, while the window ID can refer -to a window in any tab. +Each window has a unique identifier called the window ID, which is permanent +during the Nvim session. The |win_getid()| and |win_id2tabwin()| functions +convert between the window/tab "number" and the identifier. + *window-number* +Windows are also numbered according to their arrangement in a tabpage; this +window "number" is given by |winnr()| and may change whenever windows are +opened or closed. The window number is only valid in one specific tab, whereas +the window ID is valid globally, across tabs. For most functions that take +a window ID or a window number, the window number only applies to the current +tab, while the window ID can refer to a window in any tab. ============================================================================== diff --git a/runtime/lua/vim/_meta/options.gen.lua b/runtime/lua/vim/_meta/options.gen.lua index e85098cecd..e30178d579 100644 --- a/runtime/lua/vim/_meta/options.gen.lua +++ b/runtime/lua/vim/_meta/options.gen.lua @@ -6855,7 +6855,7 @@ vim.wo.stc = vim.wo.statuscolumn --- added without modifying code that reacts on mouse clicks on --- this label. --- Use `getmousepos()`.winid in the specified function to get the ---- corresponding window id of the clicked item. +--- corresponding `window-ID` of the clicked item. --- \< - Where to truncate line if too long. Default is at the start. --- No width fields allowed. --- = - Separation point between alignment sections. Each section will diff --git a/runtime/lua/vim/_meta/vimfn.gen.lua b/runtime/lua/vim/_meta/vimfn.gen.lua index 2cda894344..32f172943a 100644 --- a/runtime/lua/vim/_meta/vimfn.gen.lua +++ b/runtime/lua/vim/_meta/vimfn.gen.lua @@ -134,8 +134,8 @@ function vim.fn.appendbufline(buf, lnum, text) end --- If {winid} is not supplied, the argument list of the current --- window is used. --- If {winid} is -1, the global argument list is used. ---- Otherwise {winid} specifies the window of which the argument ---- list is used: either the window number or the window ID. +--- Otherwise {winid} (a |window-number| or |window-ID|) specifies +--- the window of which the argument list is used. --- Returns -1 if the {winid} argument is invalid. --- --- @param winid? integer @@ -157,7 +157,7 @@ function vim.fn.argidx() end --- With {winnr} only use this window in the current tabpage. --- With {winnr} and {tabnr} use the window in the specified tab --- page. ---- {winnr} can be the window number or the |window-ID|. +--- {winnr} is a |window-number| or |window-ID|. --- --- @param winnr? integer --- @param tabnr? integer @@ -175,7 +175,7 @@ function vim.fn.arglistid(winnr, tabnr) end --- vim @@ -992,8 +992,8 @@ function vim.fn.cindent(lnum) end --- Clears all matches previously defined for the current window --- by |matchadd()| and the |:match| commands. ---- If {win} is specified, use the window with this number or ---- window ID instead of the current window. +--- If {win} is specified, use this |window-number| or |window-ID| +--- instead of the current window. --- --- @param win? integer function vim.fn.clearmatches(win) end @@ -3295,10 +3295,10 @@ function vim.fn.getcompletiontype(pat) end --- the cursor is returned in "col". To get the character --- position, use |getcursorcharpos()|. --- ---- The optional {winid} argument can specify the window. It can ---- be the window number or the |window-ID|. The last known ---- cursor position is returned, this may be invalid for the ---- current value of the buffer if it is not the current window. +--- The optional {winid} (|window-number| or |window-ID|) specifies +--- the window. The last known cursor position is returned, this +--- may be invalid for the current value of the buffer if it is not +--- the current window. --- If {winid} is invalid a list with zeroes is returned. --- --- This can be used to save and restore the cursor position: >vim @@ -3336,7 +3336,7 @@ function vim.fn.getcursorcharpos(winid) end --- getcwd(0) --- getcwd(0, 0) --- vim --- echo getmatches() --- < > @@ -4101,7 +4101,7 @@ function vim.fn.gettabvar(tabnr, varname, def) end --- Note that {varname} must be the name without "w:". --- Tabs are numbered starting with one. For the current tabpage --- use |getwinvar()|. ---- {winnr} can be the window number or the |window-ID|. +--- {winnr} is a |window-number| or |window-ID|. --- When {winnr} is zero the current window is used. --- This also works for a global option, buffer-local option and --- window-local option, but it doesn't work for a global variable @@ -4123,8 +4123,8 @@ function vim.fn.gettabvar(tabnr, varname, def) end --- @return any function vim.fn.gettabwinvar(tabnr, winnr, varname, def) end ---- Returns the tag stack of window {winnr} as a Dict. ---- {winnr} can be the window number or the |window-ID|. +--- Returns the tag stack of window {winnr} (|window-number| or +--- |window-ID|) as a Dict. --- When {winnr} is not specified, the current window is used. --- When window {winnr} doesn't exist, an empty Dict is returned. --- @@ -4200,7 +4200,7 @@ function vim.fn.gettext(text) end --- wincol leftmost screen column of the window; --- "col" from |win_screenpos()| --- winid |window-ID| ---- winnr window number +--- winnr |window-number| --- winrow topmost screen line of the window; --- "row" from |win_screenpos()| --- @@ -4462,7 +4462,7 @@ function vim.fn.has_key(dict, key) end --- echo haslocaldir(0, 0) --- vim @@ -1311,8 +1311,8 @@ M.funcs = { desc = [=[ Clears all matches previously defined for the current window by |matchadd()| and the |:match| commands. - If {win} is specified, use the window with this number or - window ID instead of the current window. + If {win} is specified, use this |window-number| or |window-ID| + instead of the current window. ]=], name = 'clearmatches', @@ -4076,10 +4076,10 @@ M.funcs = { the cursor is returned in "col". To get the character position, use |getcursorcharpos()|. - The optional {winid} argument can specify the window. It can - be the window number or the |window-ID|. The last known - cursor position is returned, this may be invalid for the - current value of the buffer if it is not the current window. + The optional {winid} (|window-number| or |window-ID|) specifies + the window. The last known cursor position is returned, this + may be invalid for the current value of the buffer if it is not + the current window. If {winid} is invalid a list with zeroes is returned. This can be used to save and restore the cursor position: >vim @@ -4128,7 +4128,7 @@ M.funcs = { getcwd(0) getcwd(0, 0) vim echo getmatches() < > @@ -5017,7 +5017,7 @@ M.funcs = { Note that {varname} must be the name without "w:". Tabs are numbered starting with one. For the current tabpage use |getwinvar()|. - {winnr} can be the window number or the |window-ID|. + {winnr} is a |window-number| or |window-ID|. When {winnr} is zero the current window is used. This also works for a global option, buffer-local option and window-local option, but it doesn't work for a global variable @@ -5048,8 +5048,8 @@ M.funcs = { args = { 0, 1 }, base = 1, desc = [=[ - Returns the tag stack of window {winnr} as a Dict. - {winnr} can be the window number or the |window-ID|. + Returns the tag stack of window {winnr} (|window-number| or + |window-ID|) as a Dict. When {winnr} is not specified, the current window is used. When window {winnr} doesn't exist, an empty Dict is returned. @@ -5135,7 +5135,7 @@ M.funcs = { wincol leftmost screen column of the window; "col" from |win_screenpos()| winid |window-ID| - winnr window number + winnr |window-number| winrow topmost screen line of the window; "row" from |win_screenpos()| @@ -5447,7 +5447,7 @@ M.funcs = { echo haslocaldir(0, 0)