docs: vim_diff.txt

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:

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|
+- API                             |API|
-Job control			|job-control|
+- Job control                     |job-control|
-LSP framework			|lsp|
+- LSP framework                   |lsp|
-Lua scripting			|lua|
+- Lua scripting                   |lua|
-Parsing engine			|treesitter|
+- Parsing engine                  |treesitter|
-Providers
+- Providers
-  Clipboard			|provider-clipboard|
+  - Clipboard                     |provider-clipboard|
-  Node.js plugins		|provider-nodejs|
+  - Node.js plugins               |provider-nodejs|
-  Python plugins		|provider-python|
+  - Python plugins                |provider-python|
-  Ruby plugins			|provider-ruby|
+  - Ruby plugins                  |provider-ruby|
-Remote plugins			|remote-plugin|
+- Remote plugins                  |remote-plugin|
-Shared data			|shada|
+- Shared data                     |shada|
-Terminal emulator		|terminal|
+- Terminal emulator               |terminal|
-Vimscript parser		|nvim_parse_expression()|
+- UI                              |ui| |--listen| |--server|
-XDG base directories		|xdg|
+- 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
+- Nvim always includes ALL features, in contrast to Vim (which ships various
-  various combinations of 100+ optional features). Think of it as a leaner
+  combinations of 100+ optional features).  |feature-compile| Think of it as
-  version of Vim's "HUGE" build. This reduces surface area for bugs, and
+  a leaner version of Vim's "HUGE" build. This reduces surface area for bugs,
-  removes a common source of confusion and friction for users.
+  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*
+Changed features					 *nvim-changed*
 
-Nvim always builds with all features, in contrast to Vim which may have
+This section lists various low-level details about other behavior changes.
-certain features removed/added at compile-time. |feature-compile|
-
-Some Vim features were changed in Nvim, and vice versa.
-
-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.
 
 |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*
+Missing legacy features					 *nvim-missing*
 
-Some legacy Vim features are not yet implemented:
+These legacy Vim features are not yet implemented:
-
-- *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*
 
 *: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 *"`)