From c58f91c035db09358c282f2a908e2aea4287785e Mon Sep 17 00:00:00 2001 From: Doug Kearns Date: Sun, 12 Oct 2025 15:31:11 +0000 Subject: [PATCH] runtime(doc): Whitespace updates Use double sentence spacing and wrap lines at 'textwidth'. Code examples and tables were not wrapped unless this had already been done locally. closes: #18453 Signed-off-by: Doug Kearns Signed-off-by: Christian Brabandt --- runtime/doc/autocmd.txt | 49 +-- runtime/doc/builtin.txt | 643 ++++++++++++++++++++------------------- runtime/doc/change.txt | 64 ++-- runtime/doc/channel.txt | 64 ++-- runtime/doc/cmdline.txt | 27 +- runtime/doc/debug.txt | 34 +-- runtime/doc/debugger.txt | 8 +- runtime/doc/diff.txt | 13 +- runtime/doc/digraph.txt | 4 +- runtime/doc/editing.txt | 54 ++-- runtime/doc/eval.txt | 106 +++---- runtime/doc/filetype.txt | 39 +-- runtime/doc/gui.txt | 20 +- runtime/doc/gui_x11.txt | 4 +- runtime/doc/helphelp.txt | 12 +- runtime/doc/if_cscop.txt | 4 +- runtime/doc/if_lua.txt | 101 +++--- runtime/doc/if_mzsch.txt | 47 +-- runtime/doc/if_perl.txt | 18 +- runtime/doc/if_pyth.txt | 73 ++--- runtime/doc/if_ruby.txt | 26 +- runtime/doc/if_tcl.txt | 17 +- runtime/doc/indent.txt | 75 ++--- runtime/doc/insert.txt | 85 +++--- runtime/doc/intro.txt | 12 +- runtime/doc/map.txt | 60 ++-- runtime/doc/mbyte.txt | 12 +- runtime/doc/message.txt | 2 +- runtime/doc/mlang.txt | 4 +- runtime/doc/motion.txt | 49 +-- runtime/doc/netbeans.txt | 38 +-- runtime/doc/options.txt | 60 ++-- runtime/doc/os_amiga.txt | 6 +- runtime/doc/os_haiku.txt | 22 +- runtime/doc/os_mac.txt | 4 +- runtime/doc/os_mint.txt | 4 +- runtime/doc/os_qnx.txt | 6 +- runtime/doc/os_vms.txt | 60 ++-- runtime/doc/os_win32.txt | 12 +- runtime/doc/pattern.txt | 19 +- runtime/doc/popup.txt | 26 +- runtime/doc/print.txt | 9 +- runtime/doc/quickfix.txt | 171 ++++++----- runtime/doc/recover.txt | 4 +- runtime/doc/repeat.txt | 92 +++--- runtime/doc/sign.txt | 105 +++---- runtime/doc/spell.txt | 21 +- runtime/doc/sponsor.txt | 4 +- runtime/doc/starting.txt | 30 +- runtime/doc/syntax.txt | 317 +++++++++---------- runtime/doc/tabpage.txt | 6 +- runtime/doc/tagsrch.txt | 27 +- runtime/doc/term.txt | 19 +- runtime/doc/terminal.txt | 91 +++--- runtime/doc/testing.txt | 66 ++-- runtime/doc/textprop.txt | 12 +- runtime/doc/tips.txt | 10 +- runtime/doc/undo.txt | 23 +- runtime/doc/userfunc.txt | 4 +- runtime/doc/various.txt | 31 +- runtime/doc/vi_diff.txt | 7 +- runtime/doc/visual.txt | 14 +- runtime/doc/wayland.txt | 7 +- runtime/doc/windows.txt | 20 +- 64 files changed, 1576 insertions(+), 1497 deletions(-) diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 24dbca49cc..134d914772 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1,4 +1,4 @@ -*autocmd.txt* For Vim version 9.1. Last change: 2025 Sep 14 +*autocmd.txt* For Vim version 9.1. Last change: 2025 Oct 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -236,7 +236,7 @@ autocmds. *:autocmd-verbose* When 'verbose' is non-zero, listing an autocommand will also display where it -was last defined. Example: > +was last defined. Example: > :verbose autocmd BufEnter FileExplorer BufEnter @@ -344,7 +344,8 @@ Name triggered by ~ |GUIEnter| after starting the GUI successfully |GUIFailed| after starting the GUI failed |TermResponse| after the terminal response to |t_RV| is received -|TermResponseAll| after the terminal response to |t_RV| and others is received +|TermResponseAll| after the terminal response to |t_RV| and others is + received |QuitPre| when using `:quit`, before deciding whether to exit |ExitPre| when using a command that may make Vim exit @@ -381,7 +382,8 @@ Name triggered by ~ |FocusGained| Vim got input focus |FocusLost| Vim lost input focus |CursorHold| the user doesn't press a key for a while -|CursorHoldI| the user doesn't press a key for a while in Insert mode +|CursorHoldI| the user doesn't press a key for a while in Insert + mode |CursorMoved| the cursor was moved in Normal mode |CursorMovedC| the cursor was moved in the |Command-line| |CursorMovedI| the cursor was moved in Insert mode @@ -566,7 +568,8 @@ BufWinEnter After a buffer is displayed in a window. This since it reloads that buffer. Does not happen for a terminal window, because it starts in Terminal-Job mode and Normal mode - commands won't work. Use |TerminalOpen| instead. + commands won't work. Use |TerminalOpen| + instead. *BufWinLeave* BufWinLeave Before a buffer is removed from a window. Not when it's still visible in another window. @@ -679,7 +682,7 @@ ColorScheme After loading a color scheme. |:colorscheme| Not triggered if the color scheme is not found. The pattern is matched against the - colorscheme name. can be used for the + colorscheme name. can be used for the name of the actual file where this option was set, and for the new colorscheme name. @@ -748,7 +751,7 @@ CursorHold When the user doesn't press a key for the time triggered. |q| ** Internally the autocommand is triggered by the - key. In an expression mapping + key. In an expression mapping |getchar()| may see this character. Note: Interactive commands cannot be used for @@ -1014,7 +1017,7 @@ InsertLeave Just after leaving Insert mode. Also when using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. *KeyInputPre* KeyInputPre Just before a key is processed after mappings - have been applied. The pattern is matched + have been applied. The pattern is matched against a string that indicates the current mode, which is the same as what is returned by `mode(1)`. @@ -1046,7 +1049,7 @@ MenuPopup Just before showing the popup menu (under the c Command line tl Terminal *ModeChanged* -ModeChanged After changing the mode. The pattern is +ModeChanged After changing the mode. The pattern is matched against `'old_mode:new_mode'`, for example match against `*:c*` to simulate |CmdlineEnter|. @@ -1082,7 +1085,7 @@ OptionSet After setting an option. The pattern is |v:option_oldlocal| is only set when |:set| or |:setlocal| or a |modeline| was used to set - the option. Similarly |v:option_oldglobal| is + the option. Similarly |v:option_oldglobal| is only set when |:set| or |:setglobal| was used. This does not set ||, you could use @@ -1090,10 +1093,10 @@ OptionSet After setting an option. The pattern is Note that when setting a |global-local| string option with |:set|, then |v:option_old| is the - old global value. However, for all other kinds - of options (local string options, global-local - number options, ...) it is the old local - value. + old global value. However, for all other + kinds of options (local string options, + global-local number options, ...) it is the + old local value. OptionSet is not triggered on startup and for the 'key' option for obvious reasons. @@ -1105,7 +1108,7 @@ OptionSet After setting an option. The pattern is Note: It's a bad idea to reset an option during this autocommand, this may break a - plugin. You can always use `:noa` to prevent + plugin. You can always use `:noa` to prevent triggering this autocommand. When using |:set| in the autocommand the event @@ -1130,7 +1133,7 @@ QuickFixCmdPre Before a quickfix command is run (|:make|, *QuickFixCmdPost* QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix command is run, before jumping to the first - location. For |:cfile| and |:lfile| commands + location. For |:cfile| and |:lfile| commands it is run after the error file is read and before moving to the first error. See |QuickFixCmdPost-example|. @@ -1174,7 +1177,7 @@ SafeState When nothing is pending, going to wait for the screen was scrolled for messages. *SafeStateAgain* SafeStateAgain Like SafeState but after processing any - messages and invoking callbacks. This may be + messages and invoking callbacks. This may be triggered often, don't do something that takes time. @@ -1278,12 +1281,12 @@ TermChanged After the value of 'term' has changed. Useful settings. Executed for all loaded buffers. *TerminalOpen* TerminalOpen Just after a terminal buffer was created, with - `:terminal` or |term_start()|. This event is + `:terminal` or |term_start()|. This event is triggered even if the buffer is created without a window, with the ++hidden option. *TerminalWinOpen* TerminalWinOpen Just after a terminal buffer was created, with - `:terminal` or |term_start()|. This event is + `:terminal` or |term_start()|. This event is triggered only if the buffer is created with a window. Can be used to set window local options for the terminal window. @@ -1480,7 +1483,7 @@ WinLeave Before leaving a window. If the window to be Not used for ":qa" or ":q" when exiting Vim. *WinNewPre* -WinNewPre Before creating a new window. Triggered +WinNewPre Before creating a new window. Triggered before commands that modify window layout by creating a split. Not done when creating tab pages and for the @@ -1789,8 +1792,8 @@ option will not cause any commands to be executed. After applying the autocommands the modelines are processed, so that their settings overrule the settings from autocommands, like what happens when - editing a file. This is skipped when the - argument is present. You probably want to use + editing a file. This is skipped when the + argument is present. You probably want to use for events that are not used when loading a buffer, such as |User|. Processing modelines is also skipped when no @@ -1802,7 +1805,7 @@ option will not cause any commands to be executed. loaded buffer. The current buffer is done last. Note that [fname] is used to select the autocommands, - not the buffers to which they are applied. Example: > + not the buffers to which they are applied. Example: > augroup mine autocmd! autocmd FileType * echo expand('') diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 46450685aa..f36688832a 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1,4 +1,4 @@ -*builtin.txt* For Vim version 9.1. Last change: 2025 Oct 01 +*builtin.txt* For Vim version 9.1. Last change: 2025 Oct 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -889,7 +889,7 @@ append({lnum}, {text}) *append()* appendbufline({buf}, {lnum}, {text}) *appendbufline()* Like |append()| but append the text in buffer {buf}. - This function works only for loaded buffers. First call + This function works only for loaded buffers. First call |bufload()| if needed. For the use of {buf}, see |bufname()|. @@ -903,7 +903,7 @@ appendbufline({buf}, {lnum}, {text}) *appendbufline()* In |Vim9| script an error is given for an invalid {lnum}. If {buf} is not a valid buffer or {lnum} is not valid, an - error message is given. Example: > + error message is given. Example: > :let failed = appendbufline(13, 0, "# THE START") < However, when {text} is an empty list then no error is given for an invalid {lnum}, since {lnum} isn't actually used. @@ -1036,19 +1036,19 @@ autocmd_add({acmds}) *autocmd_add()* If this item is specified, then the "pattern" item is ignored. cmd Ex command to execute for this autocmd event - event autocmd event name. Refer to |autocmd-events|. + event autocmd event name. Refer to |autocmd-events|. This can be either a String with a single event name or a List of event names. - group autocmd group name. Refer to |autocmd-groups|. + group autocmd group name. Refer to |autocmd-groups|. If this group doesn't exist then it is created. If not specified or empty, then the default group is used. nested boolean flag, set to v:true to add a nested autocmd. Refer to |autocmd-nested|. once boolean flag, set to v:true to add an autocmd - which executes only once. Refer to + which executes only once. Refer to |autocmd-once|. - pattern autocmd pattern string. Refer to + pattern autocmd pattern string. Refer to |autocmd-patterns|. If "bufnr" item is present, then this item is ignored. This can be a String with a single pattern or a List of @@ -1057,7 +1057,8 @@ autocmd_add({acmds}) *autocmd_add()* commands associated with the specified autocmd event and group and add the {cmd}. This is useful to avoid adding the same command - multiple times for an autocmd event in a group. + multiple times for an autocmd event in a + group. Returns v:true on success and v:false on failure. Examples: > @@ -1080,21 +1081,21 @@ autocmd_delete({acmds}) *autocmd_delete()* The {acmds} argument is a List where each item is a Dict with the following optional items: - bufnr buffer number to delete a buffer-local autocmd. - If this item is specified, then the "pattern" - item is ignored. + bufnr buffer number to delete a buffer-local + autocmd. If this item is specified, then the + "pattern" item is ignored. cmd Ex command for this autocmd event - event autocmd event name. Refer to |autocmd-events|. + event autocmd event name. Refer to |autocmd-events|. If '*' then all the autocmd events in this group are deleted. - group autocmd group name. Refer to |autocmd-groups|. + group autocmd group name. Refer to |autocmd-groups|. If not specified or empty, then the default group is used. nested set to v:true for a nested autocmd. Refer to |autocmd-nested|. once set to v:true for an autocmd which executes - only once. Refer to |autocmd-once|. - pattern autocmd pattern string. Refer to + only once. Refer to |autocmd-once|. + pattern autocmd pattern string. Refer to |autocmd-patterns|. If "bufnr" item is present, then this item is ignored. @@ -1128,22 +1129,22 @@ autocmd_delete({acmds}) *autocmd_delete()* autocmd_get([{opts}]) *autocmd_get()* - Returns a |List| of autocmds. If {opts} is not supplied, then + Returns a |List| of autocmds. If {opts} is not supplied, then returns the autocmds for all the events in all the groups. The optional {opts} Dict argument supports the following items: - group Autocmd group name. If specified, returns only - the autocmds defined in this group. If the - specified group doesn't exist, results in an - error message. If set to an empty string, + group Autocmd group name. If specified, returns + only the autocmds defined in this group. If + the specified group doesn't exist, results in + an error message. If set to an empty string, then the default autocmd group is used. - event Autocmd event name. If specified, returns only - the autocmds defined for this event. If set - to "*", then returns autocmds for all the + event Autocmd event name. If specified, returns + only the autocmds defined for this event. If + set to "*", then returns autocmds for all the events. If the specified event doesn't exist, results in an error message. - pattern Autocmd pattern. If specified, returns only + pattern Autocmd pattern. If specified, returns only the autocmds defined for this pattern. A combination of the above three times can be supplied in {opts}. @@ -1155,11 +1156,12 @@ autocmd_get([{opts}]) *autocmd_get()* event Autocmd event name. group Autocmd group name. nested Boolean flag, set to v:true for a nested - autocmd. See |autocmd-nested|. + autocmd. See |autocmd-nested|. once Boolean flag, set to v:true, if the autocmd - will be executed only once. See |autocmd-once|. + will be executed only once. See |autocmd-once|. pattern Autocmd pattern. For a buffer-local - autocmd, this will be of the form "". + autocmd, this will be of the form + "". If there are multiple commands for an autocmd event in a group, then separate items are returned for each command. @@ -1510,7 +1512,7 @@ bufnr([{buf} [, {create}]]) *bufnr()* {create} argument is present and TRUE, a new, unlisted, buffer is created and its number is returned. Example: > let newbuf = bufnr('Scratch001', 1) -< Using an empty name uses the current buffer. To create a new +< Using an empty name uses the current buffer. To create a new buffer with an empty name use |bufadd()|. bufnr("$") is the last buffer: > @@ -1698,7 +1700,8 @@ char2nr({string} [, {utf8}]) *char2nr()* Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 -< When {utf8} is omitted or zero, the current 'encoding' is used. +< When {utf8} is omitted or zero, the current 'encoding' is + used. Example for "utf-8": > char2nr("á") returns 225 char2nr("á"[0]) returns 195 @@ -1763,7 +1766,7 @@ charidx({string}, {idx} [, {countcc} [, {utf16}]]) index in the String {expr} instead of as the byte index. Returns -1 if the arguments are invalid or if there are less - than {idx} bytes. If there are exactly {idx} bytes the length + than {idx} bytes. If there are exactly {idx} bytes the length of the string in characters is returned. An error is given and -1 is returned if the first argument is @@ -1855,7 +1858,7 @@ cmdcomplete_info() *cmdcomplete_info()* completion began. pum_visible |TRUE| if popup menu is visible. See |pumvisible()|. - matches List of all completion candidates. Each item + matches List of all completion candidates. Each item is a string. selected Selected item index. First index is zero. Index is -1 if no item is selected (showing @@ -1877,7 +1880,7 @@ col({expr} [, {winid}]) *col()* When {expr} is "$", it means the end of the cursor line, so the result is the number of bytes in the cursor line plus one. Additionally {expr} can be [lnum, col]: a |List| with the line - and column number. Most useful when the column is "$", to get + and column number. Most useful when the column is "$", to get the last column of a specific line. When "lnum" or "col" is out of range then col() returns zero. @@ -1914,7 +1917,7 @@ col({expr} [, {winid}]) *col()* complete({startcol}, {matches}) *complete()* *E785* - Set the matches for Insert mode completion. Can only be + Set the matches for Insert mode completion. Can only be used in Insert mode. Typically invoked from a mapping with CTRL-R = (see |i_CTRL-R|), but may also be called from a || or || mapping. It does not work after @@ -2001,12 +2004,13 @@ complete_info([{what}]) *complete_info()* See |complete_info_mode| for the values. pum_visible |TRUE| if popup menu is visible. See |pumvisible()|. - items List of all completion candidates. Each item + items List of all completion candidates. Each item is a dictionary containing the entries "word", - "abbr", "menu", "kind", "info" and "user_data". + "abbr", "menu", "kind", "info" and + "user_data". See |complete-items|. matches Same as "items", but only returns items that - are matching current query. If both "matches" + are matching current query. If both "matches" and "items" are in "what", the returned list will still be named "items", but each item will have an additional "match" field. @@ -2045,7 +2049,7 @@ complete_info([{what}]) *complete_info()* {what} are silently ignored. To get the position and size of the popup menu, see - |pum_getpos()|. It's also available in |v:event| during the + |pum_getpos()|. It's also available in |v:event| during the |CompleteChanged| event. Returns an empty |Dictionary| on error. @@ -2065,13 +2069,13 @@ complete_info([{what}]) *complete_info()* complete_match([{lnum}, {col}]) *complete_match()* Searches backward from the given position and returns a List - of matches according to the 'isexpand' option. When no + of matches according to the 'isexpand' option. When no arguments are provided, uses the current cursor position. Each match is represented as a List containing [startcol, trigger_text] where: - startcol: column position where completion should start, - or -1 if no trigger position is found. For multi-character + or -1 if no trigger position is found. For multi-character triggers, returns the column of the first character. - trigger_text: the matching trigger string from 'isexpand', or empty string if no match was found or when using the @@ -2228,7 +2232,7 @@ count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706* When {ic} is given and it's |TRUE| then case is ignored. When {comp} is a string then the number of not overlapping - occurrences of {expr} is returned. Zero is returned when + occurrences of {expr} is returned. Zero is returned when {expr} is an empty string. Can also be used as a |method|: > @@ -2322,7 +2326,7 @@ cursor({list}) debugbreak({pid}) *debugbreak()* Specifically used to interrupt a program being debugged. It will cause process {pid} to get a SIGTRAP. Behavior for other - processes is undefined. See |terminal-debugger|. + processes is undefined. See |terminal-debugger|. {only available on MS-Windows} Returns |TRUE| if successfully interrupted the program. @@ -2397,13 +2401,13 @@ deletebufline({buf}, {first} [, {last}]) *deletebufline()* If {last} is omitted then delete line {first} only. On success 0 is returned, on failure 1 is returned. - This function works only for loaded buffers. First call + This function works only for loaded buffers. First call |bufload()| if needed. For the use of {buf}, see |bufname()| above. - {first} and {last} are used like with |getline()|. Note that - when using |line()| this refers to the current buffer. Use "$" + {first} and {last} are used like with |getline()|. Note that + when using |line()| this refers to the current buffer. Use "$" to refer to the last line in buffer {buf}. Can also be used as a |method|: > @@ -2640,7 +2644,7 @@ digraph_setlist({digraphlist}) *digraph_setlist()* echoraw({string}) *echoraw()* Output {string} as-is, including unprintable characters. - This can be used to output a terminal code. For example, to + This can be used to output a terminal code. For example, to disable modifyOtherKeys: > call echoraw(&t_TE) < and to enable it again: > @@ -2673,7 +2677,7 @@ empty({expr}) *empty()* environ() *environ()* - Return all of environment variables as dictionary. You can + Return all of environment variables as dictionary. You can check if an environment variable exists like this: > :echo has_key(environ(), 'HOME') < Note that the variable name may be CamelCase; to ignore case @@ -3157,21 +3161,21 @@ feedkeys({string} [, {mode}]) *feedkeys()* {string}. To include special keys into {string}, use double-quotes - and "\..." notation |expr-quote|. For example, - feedkeys("\") simulates pressing of the key. But + and "\..." notation |expr-quote|. For example, + feedkeys("\") simulates pressing of the key. But feedkeys('\') pushes 5 characters. A special code that might be useful is , it exits the wait for a character without doing anything. ** {mode} is a String, which can contain these character flags: - 'm' Remap keys. This is default. If {mode} is absent, + 'm' Remap keys. This is default. If {mode} is absent, keys are remapped. 'n' Do not remap keys. 't' Handle keys as if typed; otherwise they are handled as if coming from a mapping. This matters for undo, opening folds, etc. 'L' Lowlevel input. Only works for Unix or when using the - GUI. Keys are used as if they were coming from the + GUI. Keys are used as if they were coming from the terminal. Other flags are not used. *E980* When a CTRL-C interrupts and 't' is included it sets the internal "got_int" flag. @@ -3191,7 +3195,7 @@ feedkeys({string} [, {mode}]) *feedkeys()* legacy script syntax applies, "s:var" does not work, etc. Note that if the string being fed sets a script context this still applies. - '!' When used with 'x' will not end Insert mode. Can be + '!' When used with 'x' will not end Insert mode. Can be used in a test when a timer is set to exit Insert mode a little later. Useful for testing CursorHoldI. @@ -3204,7 +3208,7 @@ feedkeys({string} [, {mode}]) *feedkeys()* filecopy({from}, {to}) *filecopy()* - Copy the file pointed to by the name {from} to {to}. The + Copy the file pointed to by the name {from} to {to}. The result is a Number, which is |TRUE| if the file was copied successfully, and |FALSE| when it failed. If a file with name {to} already exists, it will fail. @@ -3265,7 +3269,7 @@ filter({expr1}, {expr2}) *filter()* of the current item. For a |Dictionary| |v:key| has the key of the current item and for a |List| |v:key| has the index of the current item. For a |Blob| |v:key| has the index of the - current byte. For a |String| |v:key| has the index of the + current byte. For a |String| |v:key| has the index of the current character. Examples: > call filter(mylist, 'v:val !~ "OLD"') @@ -3307,8 +3311,8 @@ filter({expr1}, {expr2}) *filter()* or a new |Blob| or |String|. When an error is encountered while evaluating {expr2} no further items in {expr1} are processed. - When {expr2} is a Funcref errors inside a function are ignored, - unless it was defined with the "abort" flag. + When {expr2} is a Funcref errors inside a function are + ignored, unless it was defined with the "abort" flag. Can also be used as a |method|: > mylist->filter(expr2) @@ -3588,7 +3592,7 @@ foldtextresult({lnum}) *foldtextresult()* foreach({expr1}, {expr2}) *foreach()* *E1525* {expr1} must be a |List|, |Tuple|, |String|, |Blob| or |Dictionary|. - For each item in {expr1} execute {expr2}. {expr1} is not + For each item in {expr1} execute {expr2}. {expr1} is not modified; its values may be, as with |:lockvar| 1. |E741| See |map()| and |filter()| to modify {expr1}. @@ -3598,7 +3602,7 @@ foreach({expr1}, {expr2}) *foreach()* *E1525* of the current item. For a |Dictionary| |v:key| has the key of the current item and for a |List| or a |Tuple| |v:key| has the index of the current item. For a |Blob| |v:key| has the - index of the current byte. For a |String| |v:key| has the + index of the current byte. For a |String| |v:key| has the index of the current character. Examples: > call foreach(mylist, 'used[v:val] = true') @@ -3619,8 +3623,8 @@ foreach({expr1}, {expr2}) *foreach()* *E1525* Returns {expr1} in all cases. When an error is encountered while executing {expr2} no further items in {expr1} are processed. - When {expr2} is a Funcref errors inside a function are ignored, - unless it was defined with the "abort" flag. + When {expr2} is a Funcref errors inside a function are + ignored, unless it was defined with the "abort" flag. Can also be used as a |method|: > mylist->foreach(expr2) @@ -3672,7 +3676,7 @@ funcref({name} [, {arglist}] [, {dict}]) *funcref()* It only works for an autoloaded function if it has already been loaded (to avoid mistakenly loading the autoload script when only intending to use the function name, use |function()| - instead). {name} cannot be a builtin function. + instead). {name} cannot be a builtin function. Returns 0 on error. Can also be used as a |method|: > @@ -3688,7 +3692,7 @@ function({name} [, {arglist}] [, {dict}]) {name} can also be a Funcref or a partial. When it is a partial the dict stored in it will be used and the {dict} - argument is not allowed. E.g.: > + argument is not allowed. E.g.: > let FuncWithArg = function(dict.Func, [arg]) let Broken = function(dict.Func, [arg], dict) < @@ -3697,8 +3701,8 @@ function({name} [, {arglist}] [, {dict}]) same function. When {arglist} or {dict} is present this creates a partial. - That means the argument list and/or the dictionary is stored in - the Funcref and will be used when the Funcref is called. + That means the argument list and/or the dictionary is stored + in the Funcref and will be used when the Funcref is called. The arguments are passed to the function in front of other arguments, but after any argument from |method|. Example: > @@ -3732,7 +3736,7 @@ function({name} [, {arglist}] [, {dict}]) call Callback('one', 'two', 'name') < The Dictionary is only useful when calling a "dict" function. - In that case the {dict} is passed in as "self". Example: > + In that case the {dict} is passed in as "self". Example: > function Callback() dict echo "called for " .. self.name endfunction @@ -4004,12 +4008,14 @@ getcellpixels() *getcellpixels()* Returns a |List| of terminal cell pixel size. List format is [xpixel, ypixel]. - Only works on Unix (terminal and gVim) and Windows (gVim only). + Only works on Unix (terminal and gVim) and Windows (gVim + only). Returns [] on other systems or on failure. - Note that there could be variations across different terminals. + Note that there could be variations across different + terminals. On macOS, system Terminal.app returns sizes in points (before - Retina scaling), whereas third-party terminals return raw pixel - sizes (post Retina scaling). + Retina scaling), whereas third-party terminals return raw + pixel sizes (post Retina scaling). Return type: list @@ -4024,8 +4030,8 @@ getcellwidths() *getcellwidths()* getchangelist([{buf}]) *getchangelist()* - Returns the |changelist| for the buffer {buf}. For the use - of {buf}, see |bufname()| above. If buffer {buf} doesn't + Returns the |changelist| for the buffer {buf}. For the use + of {buf}, see |bufname()| above. If buffer {buf} doesn't exist, an empty list is returned. The returned list contains two entries: a list with the change @@ -4036,7 +4042,7 @@ getchangelist([{buf}]) *getchangelist()* coladd column offset for 'virtualedit' lnum line number If buffer {buf} is the current buffer, then the current - position refers to the position in the list. For other + position refers to the position in the list. For other buffers, it is set to the length of the list. Can also be used as a |method|: > @@ -4143,7 +4149,7 @@ getchar([{expr} [, {opts}]]) *getchar()* :endfunction < You may also receive synthetic characters, such as - ||. Often you will want to ignore this and get + ||. Often you will want to ignore this and get another character: > :function GetKey() : let c = getchar() @@ -4176,7 +4182,7 @@ getcharmod() *getcharmod()* getcharpos({expr}) *getcharpos()* - Get the position for String {expr}. Same as |getpos()| but the + Get the position for String {expr}. Same as |getpos()| but the column number in the returned List is a character index instead of a byte index. If |getpos()| returns a very large column number, equal to @@ -4300,7 +4306,7 @@ getcmdscreenpos() *getcmdscreenpos()* getcmdtype() *getcmdtype()* - Return the current command-line type. Possible return values + Return the current command-line type. Possible return values are: : normal Ex command > debug mode command |debug-mode| @@ -4318,15 +4324,15 @@ getcmdtype() *getcmdtype()* getcmdwintype() *getcmdwintype()* - Return the current |command-line-window| type. Possible return - values are the same as |getcmdtype()|. Returns an empty string + Return the current |command-line-window| type. Possible return + values are the same as |getcmdtype()|. Returns an empty string when not in the command-line window. Return type: |String| getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* - Return a list of command-line completion matches. The String + Return a list of command-line completion matches. The String {type} argument specifies what for. The following completion types are supported: @@ -4383,10 +4389,10 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* If the optional {filtered} flag is set to 1, then 'wildignore' is applied to filter the results. Otherwise all the matches - are returned. The 'wildignorecase' option always applies. + are returned. The 'wildignorecase' option always applies. If the 'wildoptions' option contains 'fuzzy', then fuzzy - matching is used to get the completion matches. Otherwise + matching is used to get the completion matches. Otherwise regular expression matching is used. Thus this function follows the user preference, what happens on the command line. If you do not want this you can make 'wildoptions' empty @@ -4423,8 +4429,8 @@ getcurpos([{winid}]) cursor vertically. After |$| command it will be a very large number equal to |v:maxcol|. Also see |getcursorcharpos()| and |getpos()|. - The first "bufnum" item is always zero. The byte position of - the cursor is returned in 'col'. To get the character + The first "bufnum" item is always zero. The byte position of + the cursor is returned in 'col'. To get the character position, use |getcursorcharpos()|. The optional {winid} argument can specify the window. It can @@ -4472,7 +4478,7 @@ getcwd([{winnr} [, {tabnr}]]) *getcwd()* directory. See also |haslocaldir()|. With {winnr} and {tabnr} return the local current directory of - the window in the specified tab page. If {winnr} is -1 return + the window in the specified tab page. If {winnr} is -1 return the working directory of the tabpage. If {winnr} is zero use the current window, if {tabnr} is zero use the current tabpage. @@ -4679,19 +4685,19 @@ getloclist({nr} [, {what}]) *getloclist()* 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. Otherwise, same as |getqflist()|. If the optional {what} dictionary argument is supplied, then - returns the items listed in {what} as a dictionary. Refer to + returns the items listed in {what} as a dictionary. Refer to |getqflist()| for the supported items in {what}. In addition to the items supported by |getqflist()| in {what}, the following item is supported by |getloclist()|: filewinid id of the window used to display files - from the location list. This field is + from the location list. This field is applicable only when called from a - location list window. See + location list window. See |location-list-file-window| for more details. @@ -4852,7 +4858,7 @@ getpos({expr}) *getpos()* For getting the cursor position see |getcurpos()|. The column number in the returned List is the byte position - within the line. To get the character position in the line, + within the line. To get the character position in the line, use |getcharpos()|. Note that for '< and '> Visual mode matters: when it is "V" @@ -4898,7 +4904,7 @@ getqflist([{what}]) *getqflist()* any type. When there is no error list or it's empty, an empty list is - returned. Quickfix list entries with a non-existing buffer + returned. Quickfix list entries with a non-existing buffer number are returned with "bufnr" set to zero (Note: some functions accept buffer number zero for the alternate buffer, you may need to explicitly check for zero). @@ -4911,12 +4917,12 @@ getqflist([{what}]) *getqflist()* :endfor < If the optional {what} dictionary argument is supplied, then - returns only the items listed in {what} as a dictionary. The + returns only the items listed in {what} as a dictionary. The following string items are supported in {what}: changedtick get the total number of changes made to the list |quickfix-changedtick| context get the |quickfix-context| - efm errorformat to use when parsing "lines". If + efm errorformat to use when parsing "lines". If not present, then the 'errorformat' option value is used. id get information for the quickfix list with @@ -4930,24 +4936,24 @@ getqflist([{what}]) *getqflist()* lines parse a list of lines using 'efm' and return the resulting entries. Only a |List| type is accepted. The current quickfix list is not - modified. See |quickfix-parse|. + modified. See |quickfix-parse|. nr get information for this quickfix list; zero means the current quickfix list and "$" means the last quickfix list qfbufnr number of the buffer displayed in the quickfix - window. Returns 0 if the quickfix buffer is - not present. See |quickfix-buffer|. + window. Returns 0 if the quickfix buffer is + not present. See |quickfix-buffer|. size number of entries in the quickfix list title get the list title |quickfix-title| winid get the quickfix |window-ID| all all of the above quickfix properties - Non-string items in {what} are ignored. To get the value of a + Non-string items in {what} are ignored. To get the value of a particular item, set it to zero. If "nr" is not present then the current quickfix list is used. If both "nr" and a non-zero "id" are specified, then the list specified by "id" is used. To get the number of lists in the quickfix stack, set "nr" to - "$" in {what}. The "nr" value in the returned dictionary + "$" in {what}. The "nr" value in the returned dictionary contains the quickfix stack size. When "lines" is specified, all the other items except "efm" are ignored. The returned dictionary contains the entry @@ -4956,22 +4962,23 @@ getqflist([{what}]) *getqflist()* The returned dictionary contains the following entries: changedtick total number of changes made to the list |quickfix-changedtick| - context quickfix list context. See |quickfix-context| + context quickfix list context. See |quickfix-context| If not present, set to "". - id quickfix list ID |quickfix-ID|. If not + id quickfix list ID |quickfix-ID|. If not present, set to 0. - idx index of the quickfix entry in the list. If not - present, set to 0. - items quickfix list entries. If not present, set to + idx index of the quickfix entry in the list. If + not present, set to 0. + items quickfix list entries. If not present, set to an empty list. - nr quickfix list number. If not present, set to 0 + nr quickfix list number. If not present, set to + 0 qfbufnr number of the buffer displayed in the quickfix - window. If not present, set to 0. - size number of entries in the quickfix list. If not - present, set to 0. - title quickfix list title text. If not present, set + window. If not present, set to 0. + size number of entries in the quickfix list. If + not present, set to 0. + title quickfix list title text. If not present, set to "". - winid quickfix |window-ID|. If not present, set to 0 + winid quickfix |window-ID|. If not present, set to 0 Examples (See also |getqflist-examples|): > :echo getqflist({'all': 1}) @@ -4996,7 +5003,7 @@ getreg([{regname} [, 1 [, {list}]]]) *getreg()* argument is ignored, thus you can always give it. If {list} is present and |TRUE|, the result type is changed - to |List|. Each list item is one text line. Use it if you care + to |List|. Each list item is one text line. Use it if you care about zero bytes possibly present inside register: without third argument both NLs and zero bytes are represented as NLs (see |NL-used-for-Nul|). @@ -5170,7 +5177,7 @@ getscriptinfo([{opts}]) *getscriptinfo()* The optional Dict argument {opts} supports the following optional items: - name Script name match pattern. If specified, + name Script name match pattern. If specified, and "sid" is not specified, information about scripts with a name that match the pattern "name" are returned. @@ -5224,7 +5231,7 @@ getstacktrace() *getstacktrace()* gettabinfo([{tabnr}]) *gettabinfo()* If {tabnr} is not specified, then information about all the - tab pages is returned as a |List|. Each List item is a + tab pages is returned as a |List|. Each List item is a |Dictionary|. Otherwise, {tabnr} specifies the tab page number and information about that one is returned. If the tab page does not exist an empty List is returned. @@ -5290,16 +5297,17 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* gettagstack([{winnr}]) *gettagstack()* - The result is a Dict, which is the tag stack of window {winnr}. + The result is a Dict, which is the tag stack of window + {winnr}. {winnr} can be the window number or the |window-ID|. When {winnr} is not specified, the current window is used. When window {winnr} doesn't exist, an empty Dict is returned. The returned dictionary contains the following entries: - curidx Current index in the stack. When at + curidx Current index in the stack. When at top of the stack, set to (length + 1). Index of bottom of the stack is 1. - items List of items in the stack. Each item + items List of items in the stack. Each item is a dictionary containing the entries described below. length Number of entries in the stack. @@ -5310,9 +5318,9 @@ gettagstack([{winnr}]) *gettagstack()* from cursor position before the tag jump. See |getpos()| for the format of the returned list. - matchnr current matching tag number. Used when - multiple matching tags are found for a - name. + matchnr current matching tag number. Used + when multiple matching tags are found + for a name. tagname name of the tag See |tagstack| for more information about the tag stack. @@ -5417,7 +5425,7 @@ getwinpos([{timeout}]) *getwinpos()* getwinposx() *getwinposx()* The result is a Number, which is the X coordinate in pixels of - the left hand side of the GUI Vim window. Also works for an + the left hand side of the GUI Vim window. Also works for an xterm (uses a timeout of 100 msec). The result will be -1 if the information is not available (e.g. on the Wayland backend). @@ -5460,7 +5468,7 @@ glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* 'wildignorecase' always applies. When {list} is present and it is |TRUE| the result is a |List| - with all matching files. The advantage of using a List is, + with all matching files. The advantage of using a List is, you also get filenames containing newlines correctly. Otherwise the result is a String and when there are several matches, they are separated by characters. @@ -5530,10 +5538,10 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) 'suffixes' affect the ordering of matches. When {list} is present and it is |TRUE| the result is a |List| - with all matching files. The advantage of using a List is, you - also get filenames containing newlines correctly. Otherwise - the result is a String and when there are several matches, - they are separated by characters. Example: > + with all matching files. The advantage of using a List is, + you also get filenames containing newlines correctly. + Otherwise the result is a String and when there are several + matches, they are separated by characters. Example: > :echo globpath(&rtp, "syntax/c.vim", 0, 1) < {alllinks} is used as with |glob()|. @@ -5804,24 +5812,24 @@ hlget([{name} [, {resolve}]]) *hlget()* cleared boolean flag, set to v:true if the highlight group attributes are cleared or not yet specified. See |highlight-clear|. - cterm cterm attributes. See |highlight-cterm|. + cterm cterm attributes. See |highlight-cterm|. ctermbg cterm background color. See |highlight-ctermbg|. ctermfg cterm foreground color. See |highlight-ctermfg|. ctermul cterm underline color. See |highlight-ctermul|. default boolean flag, set to v:true if the highlight - group link is a default link. See + group link is a default link. See |highlight-default|. font highlight group font. See |highlight-font|. - gui gui attributes. See |highlight-gui|. + gui gui attributes. See |highlight-gui|. guibg gui background color. See |highlight-guibg|. guifg gui foreground color. See |highlight-guifg|. guisp gui special color. See |highlight-guisp|. id highlight group ID. linksto linked highlight group name. See |:highlight-link|. - name highlight group name. See |group-name|. + name highlight group name. See |group-name|. start start terminal keycode. See |highlight-start|. stop stop terminal keycode. See |highlight-stop|. term term attributes. See |highlight-term|. @@ -5845,7 +5853,7 @@ hlget([{name} [, {resolve}]]) *hlget()* hlset({list}) *hlset()* Creates or modifies the attributes of a List of highlight groups. Each item in {list} is a dictionary containing the - attributes of a highlight group. See |hlget()| for the list of + attributes of a highlight group. See |hlget()| for the list of supported items in this dictionary. In addition to the items described in |hlget()|, the following @@ -5947,16 +5955,16 @@ iconv({string}, {from}, {to}) *iconv()* id({item}) *id()* The result is a unique String associated with the {item} and - not with the {item}'s contents. It is only valid while the - {item} exists and is referenced. It is valid only in the - instance of vim that produces the result. The whole idea is + not with the {item}'s contents. It is only valid while the + {item} exists and is referenced. It is valid only in the + instance of vim that produces the result. The whole idea is that `id({item})` does not change if the contents of {item} - changes. This is useful as a `key` for creating an identity + changes. This is useful as a `key` for creating an identity dictionary, rather than one based on equals. This operation does not reference {item} and there is no - function to convert the `id` to the {item}. It may be useful to - have a map of `id` to {item}. The following > + function to convert the `id` to the {item}. It may be useful to + have a map of `id` to {item}. The following > var referenceMap: dict var id = item->id() referenceMap[id] = item @@ -5964,7 +5972,7 @@ id({item}) *id()* way to get the {item} from the `id`. {item} may be a List, Tuple, Dictionary, Object, Job, Channel - or Blob. If the item is not a permitted type, or it is a null + or Blob. If the item is not a permitted type, or it is a null value, then an empty String is returned. Can also be used as a |method|: > @@ -6160,7 +6168,8 @@ inputrestore() *inputrestore()* Restore typeahead that was saved with a previous |inputsave()|. Should be called the same number of times inputsave() is called. Calling it more often is harmless though. - Returns TRUE when there is nothing to restore, FALSE otherwise. + Returns TRUE when there is nothing to restore, FALSE + otherwise. Return type: |Number| @@ -6259,10 +6268,11 @@ invert({expr}) *invert()* isabsolutepath({path}) *isabsolutepath()* The result is a Number, which is |TRUE| when {path} is an absolute path. - On Unix, a path is considered absolute when it starts with '/'. - On MS-Windows, it is considered absolute when it starts with an - optional drive prefix and is followed by a '\' or '/'. UNC paths - are always absolute. + On Unix, a path is considered absolute when it starts with + '/'. + On MS-Windows, it is considered absolute when it starts with + an optional drive prefix and is followed by a '\' or '/'. UNC + paths are always absolute. Example: > echo isabsolutepath('/usr/share/') " 1 echo isabsolutepath('./foobar') " 0 @@ -6408,7 +6418,7 @@ js_encode({expr}) *js_encode()* [1,,{one:1},,] ~ While json_encode() would produce: [1,null,{"one":1},null] ~ - This encoding is valid for JavaScript. It is more efficient + This encoding is valid for JavaScript. It is more efficient than JSON, especially when using an array with optional items. Can also be used as a |method|: > @@ -6427,7 +6437,7 @@ json_decode({string}) *json_decode()* *E491* - Integer keys are accepted in objects, e.g. {1:2} is the same as {"1":2}. - More floating point numbers are recognized, e.g. "1." for - "1.0", or "001.2" for "1.2". Special floating point values + "1.0", or "001.2" for "1.2". Special floating point values "Infinity", "-Infinity" and "NaN" (capitalization ignored) are accepted. - Leading zeroes in integer numbers are ignored, e.g. "012" @@ -6690,7 +6700,8 @@ list2str({list} [, {utf8}]) *list2str()* join(map(list, {nr, val -> nr2char(val)}), '') < |str2list()| does the opposite. - When {utf8} is omitted or zero, the current 'encoding' is used. + When {utf8} is omitted or zero, the current 'encoding' is + used. When {utf8} is TRUE, always return UTF-8 characters. With UTF-8 composing characters work as expected: > list2str([97, 769]) returns "á" @@ -6725,7 +6736,7 @@ list2tuple({list}) *list2tuple()* listener_add({callback} [, {buf} [, {unbuffered}]]) *listener_add()* Add a callback function that will be invoked when changes have been made to buffer {buf}. - {buf} refers to a buffer name or number. For the accepted + {buf} refers to a buffer name or number. For the accepted values, see |bufname()|. When {buf} is omitted the current buffer is used. Returns a unique ID that can be passed to |listener_remove()|. @@ -6791,16 +6802,16 @@ listener_add({callback} [, {buf} [, {unbuffered}]]) *listener_add()* Because of the third trigger reason for triggering a callback listed above, the line numbers passed to the callback are not - guaranteed to be valid. If this is a problem then make + guaranteed to be valid. If this is a problem then make {unbuffered} |TRUE|. When {unbuffered} is |TRUE| the {callback} is invoked for every - single change. The changes list only holds a single dictionary - and the "start", "end" and "added" values in the dictionary are - the same as the corresponding callback arguments. The line - numbers are valid when the callback is invoked, but later - changes may make them invalid, thus keeping a copy for later - might not work. + single change. The changes list only holds a single + dictionary and the "start", "end" and "added" values in the + dictionary are the same as the corresponding callback + arguments. The line numbers are valid when the callback is + invoked, but later changes may make them invalid, thus keeping + a copy for later might not work. The {callback} is invoked with the text locked, see |textlock|. If you do need to make changes to the buffer, use @@ -6827,7 +6838,7 @@ listener_flush([{buf}]) *listener_flush()* Invoke listener callbacks for buffer {buf}. If there are no pending changes then no callbacks are invoked. - {buf} refers to a buffer name or number. For the accepted + {buf} refers to a buffer name or number. For the accepted values, see |bufname()|. When {buf} is omitted the current buffer is used. @@ -6890,7 +6901,7 @@ log10({expr}) *log10()* luaeval({expr} [, {expr}]) *luaeval()* Evaluate Lua expression {expr} and return its result converted - to Vim data structures. Second {expr} may hold additional + to Vim data structures. Second {expr} may hold additional argument accessible as _A inside first {expr}. Strings are returned as they are. Boolean objects are converted to numbers. @@ -6927,7 +6938,7 @@ map({expr1}, {expr2}) *map()* of the current item. For a |Dictionary| |v:key| has the key of the current item and for a |List| |v:key| has the index of the current item. For a |Blob| |v:key| has the index of the - current byte. For a |String| |v:key| has the index of the + current byte. For a |String| |v:key| has the index of the current character. Example: > :call map(mylist, '"> " .. v:val .. " <"') @@ -6945,7 +6956,7 @@ map({expr1}, {expr2}) *map()* accepts one argument, but with a Vim9 lambda you get "E1106: One argument too many", the number of arguments must match. - The function must return the new value of the item. Example + The function must return the new value of the item. Example that changes each value by "key-value": > func KeyValue(key, val) return a:key .. '-' .. a:val @@ -6966,8 +6977,8 @@ map({expr1}, {expr2}) *map()* or a new |Blob| or |String|. When an error is encountered while evaluating {expr2} no further items in {expr1} are processed. - When {expr2} is a Funcref errors inside a function are ignored, - unless it was defined with the "abort" flag. + When {expr2} is a Funcref errors inside a function are + ignored, unless it was defined with the "abort" flag. Can also be used as a |method|: > mylist->map(expr2) @@ -6980,8 +6991,8 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {dict} is omitted or zero: Return the rhs of mapping {name} in mode {mode}. The returned String has special characters translated like in the output of the ":map" command - listing. When {dict} is TRUE a dictionary is returned, see - below. To get a list of all mappings see |maplist()|. + listing. When {dict} is TRUE a dictionary is returned, see + below. To get a list of all mappings see |maplist()|. When there is no mapping for {name}, an empty String is returned if {dict} is FALSE, otherwise returns an empty Dict. @@ -7020,7 +7031,7 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* "script" 1 if mapping was defined with