diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/autocmd.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/cmdline.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/deprecated.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 41 | ||||
| -rw-r--r-- | runtime/doc/diff.txt | 8 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 15 | ||||
| -rw-r--r-- | runtime/doc/ft_sql.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/index.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/job_control.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 35 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/quickfix.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/spell.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/starting.txt | 12 | ||||
| -rw-r--r-- | runtime/doc/usr_08.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/usr_09.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 24 | ||||
| -rw-r--r-- | runtime/doc/visual.txt | 2 |
18 files changed, 88 insertions, 84 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 03e182cb33..960148d506 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -798,9 +798,10 @@ QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix *QuitPre* QuitPre When using `:quit`, `:wq` or `:qall`, before deciding whether it closes the current window - or quits Vim. Can be used to close any - non-essential window if the current window is - the last ordinary window. + or quits Vim. For `:wq` the buffer is written + before QuitPre is triggered. Can be used to + close any non-essential window if the current + window is the last ordinary window. See also |ExitPre|, ||WinClosed|. *RemoteReply* RemoteReply When a reply from a Vim that functions as diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 689fb1ecd2..70a465f636 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -1067,7 +1067,7 @@ in Normal mode and Insert mode. It is possible to use ":", "/" and other commands that use the command-line, but it's not possible to open another command-line window then. There is no nesting. - *E11* + *E11* *E1188* The command-line window is not a normal window. It is not possible to move to another window or edit another buffer. All commands that would do this are disabled in the command-line window. Of course it _is_ possible to execute diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 3b5287ee44..861aed4884 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -14,6 +14,7 @@ updated. API ~ *nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead. +*nvim_buf_set_virtual_text()* Use |nvim_buf_set_extmark()| instead. *nvim_command_output()* Use |nvim_exec()| instead. *nvim_execute_lua()* Use |nvim_exec_lua()| instead. @@ -54,6 +55,8 @@ Functions ~ without stopping the job. Use chanclose(id) to close any socket. +Lua ~ +*vim.register_keystroke_callback()* Use |vim.on_key()| instead. Modifiers ~ *cpo-<* diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 60a3f870a9..14f35acce3 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -127,14 +127,20 @@ Sometimes a GUI or other application may want to force a provider to DOCUMENTATION *dev-doc* -- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document - differences from Vim; no other distinction is necessary. -- If a Vim feature is removed, delete its help section and move its tag to - |vim_diff.txt|. -- Move deprecated features to |deprecated.txt|. +- "Just say it". Avoid mushy, colloquial phrasing in all documentation + (docstrings, user manual, website materials, newsletters, …). Don't mince + words. Personality and flavor, used sparingly, are welcome--but in general, + optimize for the reader's time and energy: be "precise yet concise". + - Prefer the active voice: "Foo does X", not "X is done by Foo". +- Vim differences: + - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog + differences from Vim; no other distinction is necessary. + - If a Vim feature is removed, delete its help section and move its tag to + |vim_diff.txt|. +- Mention deprecated features in |deprecated.txt| and delete their old doc. - Use consistent language. - - "terminal" in a help tag always means "the embedded terminal emulator", not - "the user host terminal". + - "terminal" in a help tag always means "the embedded terminal emulator", + not "the user host terminal". - Use "tui-" to prefix help tags related to the host terminal, and "TUI" in prose if possible. - Docstrings: do not start parameter descriptions with "The" or "A" unless it @@ -222,13 +228,13 @@ LUA *dev-lua* - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or pseudo-OOP designs. Plugin authors just want functions to call, they don't - want to learn a big, fancy inheritance hierarchy. So we should avoid complex - objects: tables are usually better. + want to learn a big, fancy inheritance hierarchy. Thus avoid specialized + objects; tables or values are usually better. API *dev-api* -Use this template to name new API functions: +Use this template to name new RPC |API| functions: nvim_{thing}_{action}_{arbitrary-qualifiers} If the function acts on an object then {thing} is the name of that object @@ -356,4 +362,19 @@ External UIs are expected to implement these common features: published in this event. See also "mouse_on", "mouse_off". +NAMING *dev-naming* + +Naming is important. Consistent naming in the API and UI helps both users and +developers discover and intuitively understand related concepts ("families"), +and reduces cognitive burden. Discoverability encourages code re-use and +likewise avoids redundant, overlapping mechanisms, which reduces code +surface-area, and thereby minimizes bugs... + +Naming conventions ~ + +Use the "on_" prefix to name event handlers and also the interface for +"registering" such handlers (on_key). The dual nature is acceptable to avoid +a confused collection of naming conventions for these related concepts. + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index a9e2a0d522..6115a5d235 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -334,9 +334,11 @@ between file1 and file2: > The ">" is replaced with the value of 'shellredir'. -The output of "diff" must be a normal "ed" style diff or a unified diff. Do -NOT use a context diff. This example explains the format that Vim expects for -the "ed" style diff: > +The output of "diff" must be a normal "ed" style diff or a unified diff. A +context diff will NOT work. For a unified diff no context lines can be used. +Using "diff -u" will NOT work, use "diff -U0". + +This example explains the format that Vim expects for the "ed" style diff: > 1a2 > bbb diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 87240831a2..e6405145cd 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2368,6 +2368,7 @@ matchstr({expr}, {pat}[, {start}[, {count}]]) matchstrpos({expr}, {pat}[, {start}[, {count}]]) List {count}'th match of {pat} in {expr} max({expr}) Number maximum value of items in {expr} +menu_get({path} [, {modes}]) List description of |menus| matched by {path} min({expr}) Number minimum value of items in {expr} mkdir({name} [, {path} [, {prot}]]) Number create directory {name} @@ -5873,8 +5874,8 @@ jobwait({jobs}[, {timeout}]) *jobwait()* Waits for jobs and their |on_exit| handlers to complete. {jobs} is a List of |job-id|s to wait for. - {timeout} is the maximum waiting time in milliseconds, -1 - means forever. + {timeout} is the maximum waiting time in milliseconds. If + omitted or -1, wait forever. Timeout of 0 can be used to check the status of a job: > let running = jobwait([{job-id}], 0)[0] == -1 @@ -6400,7 +6401,7 @@ matcharg({nr}) *matcharg()* Highlighting matches using the |:match| commands are limited to three matches. |matchadd()| does not have this limitation. -matchdelete({id} [, {win}) *matchdelete()* *E802* *E803* +matchdelete({id} [, {win}]) *matchdelete()* *E802* *E803* Deletes a match with ID {id} previously defined by |matchadd()| or one of the |:match| commands. Returns 0 if successful, otherwise -1. See example for |matchadd()|. All matches can @@ -6479,7 +6480,7 @@ max({expr}) Return the maximum value of all items in {expr}. Can also be used as a |method|: > mylist->max() -menu_get({path}, {modes}) *menu_get()* +menu_get({path} [, {modes}]) *menu_get()* Returns a |List| of |Dictionaries| describing |menus| (defined by |:menu|, |:amenu|, …), including |hidden-menus|. @@ -8364,7 +8365,7 @@ sinh({expr}) *sinh()* Can also be used as a |method|: > Compute()->sinh() -sockconnect({mode}, {address}, {opts}) *sockconnect()* +sockconnect({mode}, {address} [, {opts}]) *sockconnect()* Connect a socket to an address. If {mode} is "pipe" then {address} should be the path of a named pipe. If {mode} is "tcp" then {address} should be of the form "host:port" where @@ -8376,7 +8377,7 @@ sockconnect({mode}, {address}, {opts}) *sockconnect()* |rpcrequest()| and |rpcnotify()| to communicate with a RPC socket. - {opts} is a dictionary with these keys: + {opts} is an optional dictionary with these keys: |on_data| : callback invoked when data was read from socket data_buffered : read socket data in |channel-buffered| mode. rpc : If set, |msgpack-rpc| will be used to communicate @@ -9275,7 +9276,7 @@ tanh({expr}) *tanh()* Can also be used as a |method|: > Compute()->tanh() - +< *timer_info()* timer_info([{id}]) Return a list with information about timers. diff --git a/runtime/doc/ft_sql.txt b/runtime/doc/ft_sql.txt index f38c8edbf3..53a99a9e1d 100644 --- a/runtime/doc/ft_sql.txt +++ b/runtime/doc/ft_sql.txt @@ -436,7 +436,7 @@ the space bar): replace the column list with the list of tables. - This allows you to quickly drill down into a table to view its columns and back again. - - <Right> and <Left> can be also be chosen via + - <Right> and <Left> can also be chosen via your |init.vim| > let g:ftplugin_sql_omni_key_right = '<Right>' let g:ftplugin_sql_omni_key_left = '<Left>' diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 69a13557d1..9a279ad880 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1608,7 +1608,7 @@ tag command action ~ |:tab| :tab create new tab when opening new window |:tag| :ta[g] jump to tag |:tags| :tags show the contents of the tag stack -|:tcd| :tcd change directory for tab page +|:tcd| :tc[d] change directory for tab page |:tchdir| :tch[dir] change directory for tab page |:terminal| :te[rminal] open a terminal buffer |:tfirst| :tf[irst] jump to first matching tag diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt index bf01e8e266..6a9d865c40 100644 --- a/runtime/doc/job_control.txt +++ b/runtime/doc/job_control.txt @@ -19,7 +19,7 @@ Job Id *job-id* Each job is identified by an integer id, unique for the life of the current Nvim session. Each job-id is a valid |channel-id|: they share the same "key space". Functions like |jobstart()| return job ids; functions like -|jobsend()|, |jobstop()|, |rpcnotify()|, and |rpcrequest()| take job ids. +|jobstop()|, |chansend()|, |rpcnotify()|, and |rpcrequest()| take job ids. Job stdio streams form a |channel| which can send and receive raw bytes or |msgpack-rpc| messages. @@ -28,7 +28,7 @@ Job stdio streams form a |channel| which can send and receive raw bytes or Usage *job-control-usage* To control jobs, use the "job…" family of functions: |jobstart()|, -|jobsend()|, |jobstop()|. +|jobstop()|, etc. Example: > diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index a44b2e42f5..5d600eae99 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -576,11 +576,11 @@ If you want to exclude visual selections from highlighting on yank, use vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* Highlights the yanked text. The fields of the optional dict {opts} control the highlight: - - {higroup} highlight group for yanked region (default `"IncSearch"`) + - {higroup} highlight group for yanked region (default |hl-IncSearch|) - {timeout} time in ms before highlight is cleared (default `150`) - {on_macro} highlight when executing macro (default `false`) - {on_visual} highlight when yanking visual selection (default `true`) - - {event} event structure (default `vim.v.event`) + - {event} event structure (default |v:event|) vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive}) *vim.highlight.range()* @@ -1243,37 +1243,6 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* Return: ~ region lua table of the form {linenr = {startcol,endcol}} - *vim.register_keystroke_callback()* -register_keystroke_callback({fn}, {ns_id}) - Register a lua {fn} with an {id} to be run after every - keystroke. - - If {fn} is nil, it removes the callback for the associated - {ns_id} - Note: - {fn} will not be cleared from |nvim_buf_clear_namespace()| - - Note: - {fn} will receive the keystrokes after mappings have been - evaluated - - Parameters: ~ - {fn} function: Function to call. It should take one - argument, which is a string. The string will contain - the literal keys typed. See |i_CTRL-V| - {ns_id} number? Namespace ID. If not passed or 0, will - generate and return a new namespace ID from - |nvim_create_namesapce()| - - Return: ~ - number Namespace ID associated with {fn} - - Note: - {fn} will be automatically removed if an error occurs - while calling. This is to prevent the annoying situation - of every keystroke erroring while trying to remove a - broken callback. - schedule_wrap({cb}) *vim.schedule_wrap()* Defers callback `cb` until the Nvim API is safe to call. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 475ccb66b3..d7bd91ad4f 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -6118,6 +6118,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'switchbuf' 'swb' string (default "uselast") global This option controls the behavior when switching between buffers. + Mostly for |quickfix| commands some values are also used for other + commands, as mentioned below. Possible values (comma separated list): useopen If included, jump to the first open window that contains the specified buffer (if there is one). diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 563fb0c962..9c1f584415 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -1333,7 +1333,8 @@ Basic items %o module name (finds a string) %l line number (finds a number) %c column number (finds a number representing character - column of the error, (1 <tab> == 1 character column)) + column of the error, byte index, a <tab> is 1 + character column) %v virtual column number (finds a number representing screen column of the error (1 <tab> == 8 screen columns)) diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 22d7cdf491..03c00c8495 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -1127,10 +1127,10 @@ flag to avoid lots of errors. CIRCUMFIX *spell-CIRCUMFIX* The CIRCUMFIX flag means a prefix and suffix must be added at the same time. -If a prefix has the CIRCUMFIX flag than only suffixes with the CIRCUMFIX flag +If a prefix has the CIRCUMFIX flag then only suffixes with the CIRCUMFIX flag can be added, and the other way around. -An alternative is to only specify the suffix, and give the that suffix two -flags: The required prefix and the NEEDAFFIX flag. |spell-NEEDAFFIX| +An alternative is to only specify the suffix, and give that suffix two flags: +the required prefix and the NEEDAFFIX flag. |spell-NEEDAFFIX| PFXPOSTPONE *spell-PFXPOSTPONE* diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index d6b54fbd01..87a48e6d2a 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -329,12 +329,12 @@ argument. -w{number} Set the 'window' option to {number}. *-w* --w {scriptout} All the characters that you type are recorded in the file - "scriptout", until you exit Vim. This is useful if you want - to create a script file to be used with "vim -s" or - ":source!". When the "scriptout" file already exists, new - characters are appended. See also |complex-repeat|. - {scriptout} cannot start with a digit. +-w {scriptout} All keys that you type are recorded in the file "scriptout", + until you exit Vim. Useful to create a script file to be used + with "vim -s" or ":source!". Appends to the "scriptout" file + if it already exists. {scriptout} cannot start with a digit. + See also |vim.on_key()|. + See also |complex-repeat|. *-W* -W {scriptout} Like -w, but do not append, overwrite an existing file. diff --git a/runtime/doc/usr_08.txt b/runtime/doc/usr_08.txt index 8e69307a94..8ccaa73006 100644 --- a/runtime/doc/usr_08.txt +++ b/runtime/doc/usr_08.txt @@ -235,7 +235,7 @@ windows like this: +----------------------------------+ Clearly the last one should be at the top. Go to that window (using CTRL-W w) -and the type this command: > +and then type this command: > CTRL-W K diff --git a/runtime/doc/usr_09.txt b/runtime/doc/usr_09.txt index 757d13e0f3..8084d13b5d 100644 --- a/runtime/doc/usr_09.txt +++ b/runtime/doc/usr_09.txt @@ -109,7 +109,7 @@ when the 'wrap' option has been reset (more about that later). When there are vertically split windows, only the windows on the right side will have a scrollbar. However, when you move the cursor to a window on the -left, it will be this one the that scrollbar controls. This takes a bit of +left, it will be this one that the scrollbar controls. This takes a bit of time to get used to. When you work with vertically split windows, consider adding a scrollbar on the left. This can be done with a menu item, or with the 'guioptions' option: diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 4b134926a2..a5fcef2800 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -6,16 +6,16 @@ Differences between Nvim and Vim *vim-differences* -Nvim differs from Vim in many ways, although editor and VimL features are -mostly identical. This document is a complete and centralized reference of -the differences. +Nvim differs from Vim in many ways, although editor and Vimscript (not +Vim9script) features are mostly identical. This document is a complete and +centralized reference of the differences. Type |gO| to see the table of contents. ============================================================================== 1. Configuration *nvim-config* -- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for configuration. +- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|. - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files. - Use `$XDG_DATA_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent session information. |shada| @@ -78,6 +78,8 @@ the differences. Default Mappings ~ *default-mappings* +Nvim creates the following default mappings at |startup|. You can disable any +of these in your config by simply removing the mapping, e.g. ":unmap Y". > nnoremap Y y$ nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<CR><C-L> @@ -101,17 +103,19 @@ nvim_cmdwin: MAJOR COMPONENTS ~ API |API| -Lua scripting |lua| Job control |job-control| -Remote plugins |remote-plugin| +LSP framework |lsp| +Lua scripting |lua| +Parsing engine |treesitter| Providers Clipboard |provider-clipboard| Node.js plugins |provider-nodejs| Python plugins |provider-python| Ruby plugins |provider-ruby| +Remote plugins |remote-plugin| Shared data |shada| -Embedded terminal |terminal| -VimL parser |nvim_parse_expression()| +Terminal emulator |terminal| +Vimscript parser |nvim_parse_expression()| XDG base directories |xdg| USER EXPERIENCE ~ @@ -160,7 +164,7 @@ FEATURES ~ Command-line highlighting: The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted - using a built-in VimL expression parser. |expr-highlight| + using a built-in Vimscript expression parser. |expr-highlight| *E5408* *E5409* |input()|, |inputdialog()| support custom highlighting. |input()-highlight| *g:Nvim_color_cmdline* @@ -413,7 +417,7 @@ TUI: UI/Display: |Visual| selection highlights the character at cursor. |visual-use| -VimL (Vim script) compatibility: +Vimscript compatibility: `count` does not alias to |v:count| `errmsg` does not alias to |v:errmsg| `shell_error` does not alias to |v:shell_error| diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index f7828f0289..111588e43a 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -419,7 +419,7 @@ abcdefghijklmnopqrstuvwxyz abcdefghijklmnSTRINGopqrstuvwxyz abc STRING defghijklmnopqrstuvwxyz -abcdef ghi STRING jklmnopqrstuvwxyz +abcdef ghi STRING jklmnopqrstuvwxyz abcdefghijklmnSTRINGopqrstuvwxyz 2. fo<C-v>3j$ASTRING<ESC> *v_b_A_example* |