docs #20986

- https://github.com/neovim/tree-sitter-vimdoc v1.2.4 eliminates most
  errors in pi_netrw.txt, so we can remove that workaround from
  ignore_parse_error().
- improved codeblock

9 files changed, 114 insertions, 112 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index decd3ca7d3..6659e9b79b 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3228,89 +3228,54 @@ nvim_create_augroup({name}, {*opts})                   *nvim_create_augroup()*
         |autocmd-groups|
 
 nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
-    Create an |autocommand|
-
-    The API allows for two (mutually exclusive) types of actions to be
-    executed when the autocommand triggers: a callback function (Lua or
-    Vimscript), or a command (like regular autocommands).
-
-    Example using callback: >lua
-        -- Lua function
-        local myluafun = function() print("This buffer enters") end
-
-        -- Vimscript function name (as a string)
-        local myvimfun = "g:MyVimFunction"
+    Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string).
 
+    Example using Lua callback: >lua
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
-          callback = myluafun,  -- Or myvimfun
+          callback = function(ev)
+            print(string.format('event fired: s', vim.inspect(ev)))
+          end
         })
 <
 
-    Lua functions receive a table with information about the autocmd event as
-    an argument. To use a function which itself accepts another (optional)
-    parameter, wrap the function in a lambda: >lua
-        -- Lua function with an optional parameter.
-        -- The autocmd callback would pass a table as argument but this
-        -- function expects number|nil
-        local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
-
-        vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-          pattern = {"*.c", "*.h"},
-          callback = function() myluafun() end,
-        })
-<
-
-    Example using command: >lua
+    Example using an Ex command as the handler: >lua
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
           command = "echo 'Entering a C or C++ file'",
         })
 <
 
-    Example values for pattern: >lua
-      pattern = "*.py"
-      pattern = { "*.py", "*.pyi" }
-<
-
-    Note: The `pattern` is passed to callbacks and commands as a literal string; environment
-    variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
-    |expand()| such variables explicitly: >lua
+    Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like
+    "$HOME" and "~" must be expanded explicitly: >lua
       pattern = vim.fn.expand("~") .. "/some/path/*.py"
 <
 
-    Example values for event: >lua
-      event = "BufWritePre"
-      event = {"CursorHold", "BufWritePre", "BufWritePost"}
-<
-
     Parameters: ~
-      • {event}  (string|array) The event or events to register this
-                 autocommand
-      • {opts}   Dictionary of autocommand options:
-                 • group (string|integer) optional: the autocommand group name
-                   or id to match against.
-                 • pattern (string|array) optional: pattern or patterns to
-                   match literally against |autocmd-pattern|.
-                 • buffer (integer) optional: buffer number for buffer local
+      • {event}  (string|array) Event(s) that will trigger the handler
+                 (`callback` or `command`).
+      • {opts}   Options dict:
+                 • group (string|integer) optional: autocommand group name or
+                   id to match against.
+                 • pattern (string|array) optional: pattern(s) to match
+                   literally |autocmd-pattern|.
+                 • buffer (integer) optional: buffer number for buffer-local
                    autocommands |autocmd-buflocal|. Cannot be used with
                    {pattern}.
-                 • desc (string) optional: description of the autocommand.
-                 • callback (function|string) optional: if a string, the name
-                   of a Vimscript function to call when this autocommand is
-                   triggered. Otherwise, a Lua function which is called when
-                   this autocommand is triggered. Cannot be used with
-                   {command}. Lua callbacks can return true to delete the
-                   autocommand; in addition, they accept a single table
-                   argument with the following keys:
-                   • id: (number) the autocommand id
-                   • event: (string) the name of the event that triggered the
-                     autocommand |autocmd-events|
-                   • group: (number|nil) the autocommand group id, if it
-                     exists
-                   • match: (string) the expanded value of |<amatch>|
-                   • buf: (number) the expanded value of |<abuf>|
-                   • file: (string) the expanded value of |<afile>|
+                 • desc (string) optional: description (for documentation and
+                   troubleshooting).
+                 • callback (function|string) optional: Lua function (or
+                   Vimscript function name, if string) called when the
+                   event(s) is triggered. Lua callback can return true to
+                   delete the autocommand, and receives a table argument with
+                   these keys:
+                   • id: (number) autocommand id
+                   • event: (string) name of the triggered event
+                     |autocmd-events|
+                   • group: (number|nil) autocommand group id, if any
+                   • match: (string) expanded value of |<amatch>|
+                   • buf: (number) expanded value of |<abuf>|
+                   • file: (string) expanded value of |<afile>|
                    • data: (any) arbitrary data passed to
                      |nvim_exec_autocmds()|
 
@@ -3322,7 +3287,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                    autocommands |autocmd-nested|.
 
     Return: ~
-        Integer id of the created autocommand.
+        Autocommand id (number)
 
     See also: ~
         |autocommand|
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 9336321d73..ff48ae3e26 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -28,11 +28,9 @@ The Neo bits of Nvim should make it a better Vim, without becoming a
 completely different editor.
 - In matters of taste, prefer Vim/Unix tradition. If there is no relevant
   Vim/Unix tradition, consider the "common case".
-- A feature that people do not know about is a useless feature.  Don't add
-  obscure features, or at least add hints in documentation that they exist.
-- There is no limit to the features that can be added.  Selecting new features
-  is based on (1) what users ask for, (2) how much effort it takes to
-  implement and (3) someone actually implementing it.
+- There is no limit to the features that can be added.  Select new features
+  based on (1) what users ask for, (2) how much effort it takes to implement
+  and (3) someone actually implementing it.
 - Backwards compatibility is a feature.  The RPC API in particular should
   never break.
 
@@ -48,7 +46,7 @@ NVIM IS... WELL DOCUMENTED				*design-documented*
 
 NVIM IS... FAST AND SMALL				*design-speed-size*
 
-Keep Nvim small and fast.
+Keep Nvim small and fast. This directly affects versatility and usability.
 - Computers are becoming faster and bigger each year.  Vim can grow too, but
   no faster than computers are growing.  Keep Vim usable on older systems.
 - Many users start Vim from a shell very often.  Startup time must be short.
@@ -57,7 +55,8 @@ Keep Nvim small and fast.
 - Don't forget that some people use Vim over a slow connection.  Minimize the
   communication overhead.
 - Vim is a component among other components.  Don't turn it into a massive
-  application, but have it work well together with other programs.
+  application, but have it work well together with other programs
+  ("composability").
 
 
 NVIM IS... MAINTAINABLE					*design-maintain*
@@ -250,13 +249,25 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
 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. Thus avoid specialized
-  objects; tables or values are usually better.
+  pseudo-OOP designs. Plugin authors just want functions to call, not a big,
+  fancy inheritance hierarchy.
+- Avoid requiring or returning special objects in the Nvim stdlib. Plain
+  tables or values are easier to serialize, easier to construct from literals,
+  easier to inspect and print, and inherently compatible with all Lua plugins.
+  (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
 
 
 API							*dev-api*
 
+- Avoid "mutually exclusive" parameters--via constraints or limitations, if
+  necessary. For example nvim_create_autocmd() has mutually exclusive
+  "callback" and "command" args; but the "command" arg could be eliminated by
+  simply not supporting Vimscript function names, and treating a string
+  "callback" arg as an Ex command (which can call Vimscript functions). The
+  "buffer" arg could also be eliminated by treating a number "pattern" as
+  a buffer number.
+
+                                                              *dev-api-naming*
 Use this format to name new RPC |API| functions:
 
     nvim_{thing}_{action}_{arbitrary-qualifiers}
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index 3cfc3429de..13b953ed60 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -423,9 +423,8 @@ Note that such expressions are only supported in places where a filename is
 expected as an argument to an Ex-command.
 
 							*++opt* *[++opt]*
-The [++opt] argument can be used to force the value of 'fileformat',
-'fileencoding' or 'binary' to a value for one command, and to specify the
-behavior for bad characters.  The form is: >
+The [++opt] argument can be used to set some options for one command, and to
+specify the behavior for bad characters.  The form is: >
 	++{optname}
 Or: >
 	++{optname}={value}
@@ -436,13 +435,11 @@ Where {optname} is one of:	    *++ff* *++enc* *++bin* *++nobin* *++edit*
     bin    or  binary	    sets 'binary'
     nobin  or  nobinary	    resets 'binary'
     bad			    specifies behavior for bad characters
-    edit		    for |:read| only: keep option values as if editing
-			    a file
-    p			    creates the parent directory (or directories) of
-			    a filename if they do not exist
+    edit		    for |:read|: keeps options as if editing a file
+    p			    for |:write|: creates the file's parent directory
 
-{value} cannot contain white space.  It can be any valid value for these
-options.  Examples: >
+{value} cannot contain whitespace.  It can be any valid value for the options.
+Examples: >
 	:e ++ff=unix
 This edits the same file again with 'fileformat' set to "unix". >
 
@@ -452,9 +449,24 @@ This writes the current buffer to "newfile" in latin1 format.
 The message given when writing a file will show "[converted]" when
 'fileencoding' or the value specified with ++enc differs from 'encoding'.
 
-There may be several ++opt arguments, separated by white space.  They must all
+There may be several ++opt arguments, separated by whitespace.  They must all
 appear before any |+cmd| argument.
 
+								*++p*
+The "++p" flag creates the parent directory of the file if it does not exist.
+For example if you edit "foo/bar/file.txt", the ":write ++p" command creates
+"foo/bar/" if necessary before writing the file. >
+
+	:edit foo/bar/file.txt
+	:write ++p
+
+If you want :write (without "++p") to always create missing parent
+directories, add this autocmd to your config: >
+
+	" Auto-create parent directories (except for URIs "://").
+	au BufWritePre,FileWritePre * if @% !~# '\(://\)' | call mkdir(expand('<afile>:p:h'), 'p') | endif
+<
+
 								*++bad*
 The argument of "++bad=" specifies what happens with characters that can't be
 converted and illegal bytes.  It can be one of three things:
@@ -895,11 +907,13 @@ Note: When the 'write' option is off, you are not able to write any file.
 					*E502* *E503* *E504* *E505*
 					*E512* *E514* *E667* *E949*
 :w[rite] [++opt]	Write the whole buffer to the current file.  This is
-			the normal way to save changes to a file.  It fails
-			when the 'readonly' option is set or when there is
-			another reason why the file can't be written.
-			For ++opt see |++opt|, but only ++bin, ++nobin, ++ff
-			and ++enc are effective.
+			the normal way to save changes to a file.  Fails when
+			'readonly' is set or when there is another reason why
+			the file can't be written, such as when the parent
+			directory doesn't exist (use |++p| to avoid that).
+			For ++opt see |++opt|, but only ++p, ++bin, ++nobin,
+			++ff and ++enc are effective.
+
 
 :w[rite]! [++opt]	Like ":write", but forcefully write when 'readonly' is
 			set or there is another reason why writing was
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index c989b67b96..61d540a3dd 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1708,13 +1708,13 @@ v:charconvert_to
 
 					*v:cmdarg* *cmdarg-variable*
 v:cmdarg	This variable is used for two purposes:
-		1. The extra arguments given to a file read/write command.
-		   Currently these are "++enc=" and "++ff=".  This variable is
-		   set before an autocommand event for a file read/write
-		   command is triggered.  There is a leading space to make it
-		   possible to append this variable directly after the
-		   read/write command.  Note: The "+cmd" argument isn't
-		   included here, because it will be executed anyway.
+		1. The extra arguments ("++p", "++enc=", "++ff=") given to
+		   a file read/write command.  This is set before an
+		   autocommand event for a file read/write command is
+		   triggered.  There is a leading space to make it possible to
+		   append this variable directly after the read/write command.
+		   Note: "+cmd" isn't included here, because it will be
+		   executed anyway.
 		2. When printing a PostScript file with ":hardcopy" this is
 		   the argument for the ":hardcopy" command.  This can be used
 		   in 'printexpr'.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 37a0a8c076..89a6e89511 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -325,7 +325,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
       },
     }
 <
-  or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`:
+  or if using "nvim-lspconfig", you can use the {handlers} key of `setup()`:
   >lua
 
     require('lspconfig').rust_analyzer.setup {
@@ -1340,9 +1340,7 @@ start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
     |vim.lsp.buf_attach_client()|. To opt-out of semantic highlighting with a
     server that supports it, you can delete the semanticTokensProvider table
     from the {server_capabilities} of your client in your |LspAttach| callback
-    or your configuration's `on_attach` callback.
-
-    >lua
+    or your configuration's `on_attach` callback. >lua
 
        client.server_capabilities.semanticTokensProvider = nil
 <
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index 4946779a7c..ef407922da 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -24,8 +24,8 @@ Transitioning from Vim                          *nvim-from-vim*
 
 1. To start the transition, create your |init.vim| (user config) file: >vim
 
-    :call mkdir(stdpath('config'), 'p')
     :exe 'edit '.stdpath('config').'/init.vim'
+    :write ++p
 
 2. Add these contents to the file: >vim
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 8f2feb416b..5375d971f0 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -176,7 +176,7 @@ a |provider| which transparently uses shell commands to communicate with the
 system clipboard or any other clipboard "backend".
 
 To ALWAYS use the clipboard for ALL operations (instead of interacting with
-the '+' and/or '*' registers explicitly): >vim
+the "+" and/or "*" registers explicitly): >vim
     set clipboard+=unnamedplus
 
 See 'clipboard' for details and options.
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 6a2e74eaf5..5c1725a1f8 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -127,7 +127,7 @@ nvim_cmdwin:
 ==============================================================================
 3. New Features						       *nvim-features*
 
-MAJOR COMPONENTS ~
+MAJOR COMPONENTS
 
 API				|API|
 Job control			|job-control|
@@ -145,7 +145,7 @@ Terminal emulator		|terminal|
 Vimscript parser		|nvim_parse_expression()|
 XDG base directories		|xdg|
 
-USER EXPERIENCE  ~
+USER EXPERIENCE
 
 Working intuitively and consistently is a major goal of Nvim.
 
@@ -176,7 +176,7 @@ Some features are built in that otherwise required external plugins:
 
 - Highlighting the yanked region, see |lua-highlight|.
 
-ARCHITECTURE ~
+ARCHITECTURE
 
 External plugins run in separate processes. |remote-plugin| This improves
 stability and allows those plugins to work without blocking the editor. Even
@@ -187,7 +187,7 @@ Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
 features and bug fixes, and other projects benefit from improvements to libuv
 by Nvim developers.
 
-FEATURES ~
+FEATURES
 
 Command-line highlighting:
   The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
@@ -206,6 +206,7 @@ Commands:
   |:match| can be invoked before highlight group is defined
   |:source| works with Lua
   User commands can support |:command-preview| to show results as you type
+  |:write| with "++p" flag creates parent directories.
 
 Events:
   |RecordingEnter|
@@ -226,6 +227,7 @@ Functions:
   |stdpath()|
   |system()|, |systemlist()| can run {cmd} directly (without 'shell')
   |matchadd()| can be called before highlight group is defined
+  |writefile()| with "p" flag creates parent directories.
 
 Highlight groups:
   |highlight-blend| controls blend level for a highlight group
@@ -277,7 +279,20 @@ Variables:
   |v:windowid| is always available (for use by external UIs)
 
 ==============================================================================
-4. Changed features					 *nvim-features-changed*
+4. Upstreamed features					 *nvim-upstreamed*
+
+These Nvim features were later integrated into Vim.
+
+- 'fillchars' flags: "eob"
+- 'wildoptions' flags: "pum" enables popupmenu for wildmode completion
+- |<Cmd>|
+- |WinClosed|
+- |WinScrolled|
+- |:sign-define| "numhl" argument
+- |:source| works with anonymous (no file) scripts
+
+==============================================================================
+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|
@@ -499,7 +514,7 @@ Working directory (Vim implemented some of these later than Nvim):
   working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
 ==============================================================================
-5. Missing legacy features				 *nvim-features-missing*
+6. Missing legacy features				 *nvim-features-missing*
 
 Some legacy Vim features are not yet implemented:
 
@@ -512,7 +527,7 @@ Some legacy Vim features are not yet implemented:
 *:gvim*
 
 ==============================================================================
-6. Removed features					 *nvim-features-removed*
+7. Removed features					 *nvim-features-removed*
 
 These Vim features were intentionally removed from Nvim.
 
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index 83b414bf87..11e62ee793 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -495,7 +495,6 @@ local M = {}
 --- delete the semanticTokensProvider table from the {server_capabilities} of
 --- your client in your |LspAttach| callback or your configuration's
 --- `on_attach` callback.
----
 --- <pre>lua
 ---   client.server_capabilities.semanticTokensProvider = nil
 --- </pre>