diff options
| -rw-r--r-- | runtime/doc/news.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 239 |
2 files changed, 124 insertions, 119 deletions
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 8b41f2d104..c6588fdeab 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -13,7 +13,7 @@ BREAKING CHANGES *news-breaking* The following changes may require adaptations in user config or plugins. -• Cscope support is now removed (see |cscope| and |nvim-features-removed|): +• Cscope support is now removed (see |cscope| and |nvim-removed|): - Commands removed: - `:cscope` - `:lcscope` @@ -34,7 +34,7 @@ The following changes may require adaptations in user config or plugins. See https://github.com/neovim/neovim/pull/20545 for more information. -• `:hardcopy` is now removed (see |hardcopy| and |nvim-features-removed|): +• `:hardcopy` is now removed (see |hardcopy| and |nvim-removed|): - Commands removed: - `:hardcopy` - Options removed: diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 97fc211c36..b274c02945 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -13,7 +13,7 @@ centralized reference of the differences. Type |gO| to see the table of contents. ============================================================================== -1. Configuration *nvim-config* +Configuration *nvim-config* - 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. @@ -21,7 +21,7 @@ centralized reference of the differences. session information. |shada| ============================================================================== -2. Defaults *nvim-defaults* +Defaults *nvim-defaults* - Filetype detection is enabled by default. This can be disabled by adding ":filetype off" to |init.vim|. @@ -78,7 +78,7 @@ centralized reference of the differences. - |g:vimsyn_embed| defaults to "l" to enable Lua highlighting -Default Mouse ~ +DEFAULT MOUSE *default-mouse* *disable-mouse* By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in @@ -102,7 +102,7 @@ To remove the "How-to disable mouse" menu item and the separator above it: >vim aunmenu PopUp.How-to\ disable\ mouse aunmenu PopUp.-1- < -Default Mappings ~ +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". @@ -115,7 +115,7 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y". xnoremap # y?\V<C-R>"<CR> nnoremap & :&&<CR> < -Default Autocommands ~ +DEFAULT AUTOCOMMANDS *default-autocmds* Default autocommands exist in the following groups. Use ":autocmd! {group}" to remove them and ":autocmd {group}" to see how they're defined. @@ -127,35 +127,36 @@ nvim_cmdwin: - CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|. ============================================================================== -3. New Features *nvim-features* +New Features *nvim-features* MAJOR COMPONENTS -API |API| -Job control |job-control| -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| -Terminal emulator |terminal| -Vimscript parser |nvim_parse_expression()| -XDG base directories |xdg| +- API |API| +- Job control |job-control| +- 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| +- Terminal emulator |terminal| +- UI |ui| |--listen| |--server| +- Vimscript parser |nvim_parse_expression()| +- XDG base directories |xdg| USER EXPERIENCE Working intuitively and consistently is a major goal of Nvim. *feature-compile* -- Nvim always includes ALL features, in contrast to Vim (which ships with - various combinations of 100+ optional features). Think of it as a leaner - version of Vim's "HUGE" build. This reduces surface area for bugs, and - removes a common source of confusion and friction for users. +- Nvim always includes ALL features, in contrast to Vim (which ships various + combinations of 100+ optional features). |feature-compile| Think of it as + a leaner version of Vim's "HUGE" build. This reduces surface area for bugs, + and removes a common source of confusion and friction for users. - Nvim avoids features that cannot be provided on all platforms; instead that is delegated to external plugins/extensions. E.g. the `-X` platform-specific @@ -173,6 +174,7 @@ backwards-compatibility cost. Some examples: - Directories for 'directory' and 'undodir' are auto-created. - Terminal features such as 'guicursor' are enabled where possible. +- Various "nvim" |cli-arguments| were redesigned. Some features are built in that otherwise required external plugins: @@ -180,6 +182,11 @@ Some features are built in that otherwise required external plugins: ARCHITECTURE +The Nvim UI is "decoupled" from the core editor: all UIs, including the +builtin |TUI| are just plugins that connect to a Nvim server (via |--server| +or |--embed|). Multiple Nvim UI clients can connect to the same Nvim editor +server. + External plugins run in separate processes. |remote-plugin| This improves stability and allows those plugins to work without blocking the editor. Even "legacy" Python and Ruby plugins which use the old Vim interfaces (|if_pyth|, @@ -191,7 +198,7 @@ by Nvim developers. FEATURES -Command-line highlighting: +Command-line: The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted using a built-in Vimscript expression parser. |expr-highlight| *E5408* *E5409* @@ -253,34 +260,105 @@ Input/Mappings: Normal commands: |gO| shows a filetype-defined "outline" of the current buffer. + |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|). Options: 'cpoptions' flags: |cpo-_| - 'guicursor' works in the terminal + 'diffopt' "linematch" feature + 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The + user is prompted whether to trust the file. 'fillchars' flags: "msgsep", "horiz", "horizup", "horizdown", "vertleft", "vertright", "verthoriz" 'foldcolumn' supports up to 9 dynamic/fixed columns + 'guicursor' works in the terminal (TUI) 'inccommand' shows interactive results for |:substitute|-like commands and |:command-preview| commands + 'jumpoptions' "stack" behavior + 'jumpoptions' "view" tries to restore the |mark-view| when moving through + the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. 'laststatus' global statusline support 'mousescroll' amount to scroll by when scrolling with a mouse 'pumblend' pseudo-transparent popupmenu 'scrollback' + 'shortmess' "F" flag does not affect output from autocommands 'signcolumn' supports up to 9 dynamic/fixed columns + 'statuscolumn' full control of columns using 'statusline' format + 'statusline' supports unlimited alignment sections 'tabline' %@Func@foo%X can call any function on mouse-click + 'ttimeout', 'ttimeoutlen' behavior was simplified 'winblend' pseudo-transparency in floating windows |api-floatwin| 'winhighlight' window-local highlights - 'diffopt' has the option `linematch`. + +Providers: + If a Python interpreter is available on your `$PATH`, |:python| and + |:python3| are always available. See |provider-python|. + +Shell: + Shell output (|:!|, |:make|, …) is always routed through the UI, so it + cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if + you want to mess up the screen :) + + Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|) + if there is too much output. No data is lost, this only affects display and + improves performance. |:terminal| output is never throttled. + + |:!| does not support "interactive" commands. Use |:terminal| instead. + (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) + + :!start is not special-cased on Windows. + + |system()| does not support writing/reading "backgrounded" commands. |E5677| Signs: Signs are removed if the associated line is deleted. +Startup: + |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. + |-E| and |-Es| read stdin as text (into buffer 1). + |-es| and |-Es| have improved behavior: + - Quits automatically, don't need "-c qa!". + - Skips swap-file dialog. + |-s| reads Normal commands from stdin if the script name is "-". + Reading text (instead of commands) from stdin |--|: + - works by default: "-" file is optional + - works in more cases: |-Es|, file args + +TUI: + *:set-termcap* + Start Nvim with 'verbose' level 3 to show terminal capabilities: > + nvim -V3 +< + *'term'* *E529* *E530* *E531* + 'term' reflects the terminal type derived from |$TERM| and other environment + checks. For debugging only; not reliable during startup. >vim + :echo &term +< "builtin_x" means one of the |builtin-terms| was chosen, because the expected + terminfo file was not found on the system. + + Nvim will use 256-colour capability on Linux virtual terminals. Vim uses + only 8 colours plus bright foreground on Linux VTs. + + Vim combines what is in its |builtin-terms| with what it reads from terminfo, + and has a 'ttybuiltin' setting to control how that combination works. Nvim + uses one or the other, it does not attempt to merge the two. + +UI/Display: + |Visual| selection highlights the character at cursor. |visual-use| + + messages: When showing messages longer than 'cmdheight', only + scroll the message lines, not the entire screen. The + separator line is decorated by |hl-MsgSeparator| and + the "msgsep" flag of 'fillchars'. *msgsep* + Variables: |v:progpath| is always absolute ("full") |v:windowid| is always available (for use by external UIs) +Vimscript: + |:redir| nested in |execute()| works. + ============================================================================== -4. Upstreamed features *nvim-upstreamed* +Upstreamed features *nvim-upstreamed* These Nvim features were later integrated into Vim. @@ -294,17 +372,9 @@ These Nvim features were later integrated into Vim. - 'statusline' supports unlimited alignment sections ============================================================================== -5. Changed features *nvim-features-changed* - -Nvim always builds with all features, in contrast to Vim which may have -certain features removed/added at compile-time. |feature-compile| - -Some Vim features were changed in Nvim, and vice versa. +Changed features *nvim-changed* -If a Python interpreter is available on your `$PATH`, |:python| and |:python3| -are always available and may be used simultaneously. See |provider-python|. - -|:redir| nested in |execute()| works. +This section lists various low-level details about other behavior changes. |mkdir()| behaviour changed: 1. Assuming /tmp/foo does not exist and /tmp can be written to @@ -345,7 +415,7 @@ are always available and may be used simultaneously. See |provider-python|. |json_encode()| behaviour slightly changed: now |msgpack-special-dict| values are accepted, but |v:none| is not. -Viminfo text files were replaced with binary (messagepack) ShaDa files. +Viminfo text files were replaced with binary (messagepack) |shada| files. Additional differences: - |shada-c| has no effect. @@ -387,7 +457,7 @@ Commands: |:wincmd| accepts a count. `:write!` does not show a prompt if the file was updated externally. -Command line completion: +Command-line: The meanings of arrow keys do not change depending on 'wildoptions'. Functions: @@ -424,46 +494,6 @@ Mappings: Motion: The |jumplist| avoids useless/phantom jumps. -Normal commands: - |Q| replays the last recorded macro instead of switching to Ex mode. - Instead |gQ| can be used to enter Ex mode. - -Options: - 'ttimeout', 'ttimeoutlen' behavior was simplified - 'jumpoptions' "stack" behavior - 'jumpoptions' "view" tries to restore the |mark-view| when moving through - the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. - 'shortmess' the "F" flag does not affect output from autocommands - 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is - prompted whether to trust the file. - -Shell: - Shell output (|:!|, |:make|, …) is always routed through the UI, so it - cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if - you want to mess up the screen :) - - Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|) - if there is too much output. No data is lost, this only affects display and - improves performance. |:terminal| output is never throttled. - - |:!| does not support "interactive" commands. Use |:terminal| instead. - (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) - - :!start is not special-cased on Windows. - - |system()| does not support writing/reading "backgrounded" commands. |E5677| - -Startup: - |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. - |-E| and |-Es| read stdin as text (into buffer 1). - |-es| and |-Es| have improved behavior: - - Quits automatically, don't need "-c qa!". - - Skips swap-file dialog. - |-s| reads Normal commands from stdin if the script name is "-". - Reading text (instead of commands) from stdin |--|: - - works by default: "-" file is optional - - works in more cases: |-Es|, file args - Syntax highlighting: syncolor.vim has been removed. Nvim now sets up default highlighting groups automatically for both light and dark backgrounds, regardless of whether or @@ -472,40 +502,13 @@ Syntax highlighting: after/syntax/syncolor.vim file should transition that file into a colorscheme. |:colorscheme| -TUI: - *:set-termcap* - Start Nvim with 'verbose' level 3 to show terminal capabilities: > - nvim -V3 -< - *'term'* *E529* *E530* *E531* - 'term' reflects the terminal type derived from |$TERM| and other environment - checks. For debugging only; not reliable during startup. >vim - :echo &term -< "builtin_x" means one of the |builtin-terms| was chosen, because the expected - terminfo file was not found on the system. - - Nvim will use 256-colour capability on Linux virtual terminals. Vim uses - only 8 colours plus bright foreground on Linux VTs. - - Vim combines what is in its |builtin-terms| with what it reads from terminfo, - and has a 'ttybuiltin' setting to control how that combination works. Nvim - uses one or the other, it does not attempt to merge the two. - -UI/Display: - |Visual| selection highlights the character at cursor. |visual-use| - - messages: When showing messages longer than 'cmdheight', only - scroll the message lines, not the entire screen. The - separator line is decorated by |hl-MsgSeparator| and - the "msgsep" flag of 'fillchars'. *msgsep* - 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| `this_session` does not alias to |v:this_session| -Working directory (Vim implemented some of these later than Nvim): +Working directory (Vim implemented some of these after Nvim): - |DirChanged| and |DirChangedPre| can be triggered when switching to another window or tab. - |getcwd()| and |haslocaldir()| may throw errors if the tab page or window @@ -516,20 +519,15 @@ Working directory (Vim implemented some of these later than Nvim): working directory. Use `getcwd(-1, -1)` to get the global working directory. ============================================================================== -6. Missing legacy features *nvim-features-missing* - -Some legacy Vim features are not yet implemented: +Missing legacy features *nvim-missing* -- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua" -- *if_mzscheme* -- |if_pyth|: *python-bindeval* *python-Function* are not supported -- *if_tcl* +These legacy Vim features are not yet implemented: *:gui* *:gvim* ============================================================================== -7. Removed features *nvim-features-removed* +Removed legacy features *nvim-removed* These Vim features were intentionally removed from Nvim. @@ -687,6 +685,13 @@ Options: Performance: Folds are not updated during insert-mode. +Providers: + +- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua". +- *if_mzscheme* +- |if_pyth|: *python-bindeval* *python-Function* are not supported. +- *if_tcl* + Startup: --literal (file args are always literal; to expand wildcards on Windows, use |:n| e.g. `nvim +"n *"`) |