Merge neovim#24116 from justinmk/doc

Author: justinmk

runtime/doc/api.txt

@@ -209,7 +209,7 @@ any of these approaches:
      nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
 <
   3. Use the |api_info()| Vimscript function. >vim
-     :lua print(vim.inspect(vim.fn.api_info()))
+     :lua vim.print(vim.fn.api_info())
 <     Example using |filter()| to exclude non-deprecated API functions: >vim
      :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 
@@ -2030,7 +2030,7 @@ whether a buffer is loaded.
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
     Activates buffer-update events on a channel, or as Lua callbacks.
 
-    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
+    Example (Lua): capture buffer updates in a global `events` variable (use "vim.print(events)" to see its contents): >lua
       events = {}
       vim.api.nvim_buf_attach(0, false, {
         on_lines=function(...) table.insert(events, {...}) end})
@@ -2554,7 +2554,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
       local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
       -- Get all marks in this buffer + namespace.
       local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-      print(vim.inspect(ms))
+      vim.print(ms)
 <
 
     Parameters: ~

runtime/doc/autocmd.txt

@@ -212,28 +212,27 @@ events.
 Nvim recognizes the following events.  Names are case-insensitive.
 
 							*BufAdd*
-BufAdd				Just after creating a new buffer which is
-				added to the buffer list, or adding a buffer
-				to the buffer list, a buffer in the buffer
-				list was renamed.
-				Not triggered for the initial buffers created
-				during startup.
+BufAdd				After adding a new buffer or existing unlisted
+				buffer to the buffer list (except during
+				startup, see |VimEnter|), or renaming a listed
+				buffer.
 				Before |BufEnter|.
-				NOTE: Current buffer "%" may be different from
-				the buffer being created "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 							*BufDelete*
 BufDelete			Before deleting a buffer from the buffer list.
 				The BufUnload may be called first (if the
 				buffer was loaded).
 				Also used just before a buffer in the buffer
 				list is renamed.
-				NOTE: Current buffer "%" may be different from
-				the buffer being deleted "<afile>" and "<abuf>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not change to another buffer.
 							*BufEnter*
-BufEnter			After entering a buffer.  Useful for setting
-				options for a file type.  Also executed when
-				starting to edit a buffer.
+BufEnter			After entering (visiting, switching-to) a new
+				or existing buffer. Useful for setting
+				filetype options.  Compare |BufNew| which
+				does not trigger for existing buffers.
 				After |BufAdd|.
 				After |BufReadPost|.
 							*BufFilePost*
@@ -248,8 +247,8 @@ BufHidden			Before a buffer becomes hidden: when there are
 				the buffer is not unloaded or deleted.
 
 				Not used for ":qa" or ":q" when exiting Vim.
-				NOTE: current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 							*BufLeave*
 BufLeave			Before leaving to another buffer.  Also when
 				leaving or closing the current window and the
@@ -260,12 +259,14 @@ BufLeave			Before leaving to another buffer.  Also when
 BufModifiedSet			After the `'modified'` value of a buffer has
 				been changed.
 							*BufNew*
-BufNew				Just after creating a new buffer.  Also used
-				just after a buffer has been renamed.  When
-				the buffer is added to the buffer list BufAdd
-				will be triggered too.
-				NOTE: Current buffer "%" may be different from
-				the buffer being created "<afile>".
+BufNew				After creating a new buffer (except during
+				startup, see |VimEnter|) or renaming an
+				existing buffer. Unlike |BufEnter|, visiting
+				(switching to) an existing buffer will not
+				trigger this again.
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
+				See also |BufAdd|, |BufNewFile|.
 							*BufNewFile*
 BufNewFile			When starting to edit a file that doesn't
 				exist.  Can be used to read in a skeleton
@@ -298,8 +299,8 @@ BufUnload			Before unloading a buffer, when the text in
 				Before BufDelete.
 				Triggers for all loaded buffers when Vim is
 				going to exit.
-				NOTE: Current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not switch buffers or windows!
 				Not triggered when exiting and v:dying is 2 or
 				more.
@@ -319,8 +320,8 @@ BufWinLeave			Before a buffer is removed from a window.
 				Not when it's still visible in another window.
 				Also triggered when exiting.
 				Before BufUnload, BufHidden.
-				NOTE: Current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Not triggered when exiting and v:dying is 2 or
 				more.
 							*BufWipeout*
@@ -330,8 +331,8 @@ BufWipeout			Before completely deleting a buffer.  The
 				buffer list).  Also used just before a buffer
 				is renamed (also when it's not in the buffer
 				list).
-				NOTE: Current buffer "%" may be different from
-				the buffer being deleted "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not change to another buffer.
 						*BufWrite* *BufWritePre*
 BufWrite or BufWritePre		Before writing the whole buffer to a file.
@@ -597,8 +598,8 @@ FileChangedShell		When Vim notices that the modification time of
 				prompt is not given.
 				|v:fcs_reason| indicates what happened. Set
 				|v:fcs_choice| to control what happens next.
-				NOTE: Current buffer "%" may be different from
-				the buffer that was changed "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>" and "<abuf>". |<buffer=abuf>|
 							*E246* *E811*
 				Cannot switch, jump to or delete buffers.
 				Non-recursive (event cannot trigger itself).

runtime/doc/builtin.txt

@@ -656,7 +656,7 @@ api_info()						*api_info()*
 		Returns Dictionary of |api-metadata|.
 
 		View it in a nice human-readable format: >
-		       :lua print(vim.inspect(vim.fn.api_info()))
+		       :lua vim.print(vim.fn.api_info())
 
 append({lnum}, {text})					*append()*
 		When {text} is a |List|: Append each item of the |List| as a
@@ -1939,7 +1939,7 @@ exists({expr})	The result is a Number, which is |TRUE| if {expr} is
 			$ENVNAME	environment variable (could also be
 					done by comparing with an empty
 					string)
-			*funcname	built-in function (see |functions|)
+			`*funcname`	built-in function (see |functions|)
 					or user defined function (see
 					|user-function|). Also works for a
 					variable that is a Funcref.
@@ -3019,7 +3019,7 @@ getcmdtype()						*getcmdtype()*
 		    /	forward search command
 		    ?	backward search command
 		    @	|input()| command
-		    -	|:insert| or |:append| command
+		    `-`	|:insert| or |:append| command
 		    =	|i_CTRL-R_=|
 		Only works when editing the command line, thus requires use of
 		|c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
@@ -3364,20 +3364,26 @@ getmatches([{win}])					*getmatches()*
 		If {win} is specified, use the window with this number or
 		window ID instead of the current window.  If {win} is invalid,
 		an empty list is returned.
-		Example: >
+		Example: >vim
 			:echo getmatches()
-<			[{"group": "MyGroup1", "pattern": "TODO",
+>
+ 			[{"group": "MyGroup1", "pattern": "TODO",
 			"priority": 10, "id": 1}, {"group": "MyGroup2",
-			"pattern": "FIXME", "priority": 10, "id": 2}] >
+			"pattern": "FIXME", "priority": 10, "id": 2}]
+>vim
 			:let m = getmatches()
 			:call clearmatches()
 			:echo getmatches()
-<			[] >
+>
+			[]
+>vim
 			:call setmatches(m)
 			:echo getmatches()
-<			[{"group": "MyGroup1", "pattern": "TODO",
+>
+			[{"group": "MyGroup1", "pattern": "TODO",
 			"priority": 10, "id": 1}, {"group": "MyGroup2",
-			"pattern": "FIXME", "priority": 10, "id": 2}] >
+			"pattern": "FIXME", "priority": 10, "id": 2}]
+>vim
 			:unlet m
 <
 getmousepos()						*getmousepos()*
@@ -8268,7 +8274,7 @@ string({expr})	Return {expr} converted to a String.  If {expr} is a Number,
 			Funcref		`function('name')`
 			Blob		0z00112233.44556677.8899
 			List		[item, item]
-			Dictionary	{key: value, key: value}
+			Dictionary	`{key: value, key: value}`
 		Note that in String values the ' character is doubled.
 		Also see |strtrans()|.
 		Note 2: Output format is mostly compatible with YAML, except

runtime/doc/change.txt

@@ -1490,7 +1490,7 @@ white space).  Three types of comments can be used:
   lines.  An example is this list with dashes.
 - Three-piece comments that have a start string, an end string, and optional
   lines in between.  The strings for the start, middle and end are different.
-  An example is the C style comment:
+  An example is the C style comment: >
 	/*
 	 * this is a C comment
 	 */
@@ -1565,20 +1565,20 @@ When you hit Return in a C-comment, Vim will insert the middle comment leader
 for the new line: " * ".  To close this comment you just have to type "/"
 before typing anything else on the new line.  This will replace the
 middle-comment leader with the end-comment leader and apply any specified
-alignment, leaving just " */".  There is no need to hit Backspace first.
+alignment, leaving just `" */"`.  There is no need to hit Backspace first.
 
 When there is a match with a middle part, but there also is a matching end
 part which is longer, the end part is used.  This makes a C style comment work
 without requiring the middle part to end with a space.
 
 Here is an example of alignment flags at work to make a comment stand out
-(kind of looks like a 1 too). Consider comment string: >
+(kind of looks like a 1 too). Consider comment string: >vim
 	:set comments=sr:/***,m:**,ex-2:******/
-<
+>
                                    /*** ~
                                      **<--right aligned from "r" flag ~
                                      ** ~
-offset 2 spaces for the "-2" flag--->** ~
+ offset 2 spaces for the "-2" flag-->** ~
                                    ******/ ~
 In this case, the first comment was typed, then return was pressed 4 times,
 then "/" was pressed to end the comment.
@@ -1741,10 +1741,10 @@ happens with formatting and auto-wrapping.  Opening a line after a line
 starting with "/*" or "*" and containing "*/", will cause no comment leader to
 be inserted, and the indent of the new line is taken from the line containing
 the start of the comment.
-E.g.:
-    /* ~
-     * Your typical comment. ~
-     */ ~
+E.g.: >
+    /*
+     * Your typical comment.
+     */
     The indent on this line is the same as the start of the above
     comment.
 

runtime/doc/cmdline.txt

@@ -100,7 +100,7 @@ CTRL-E or <End>					*c_CTRL-E* *c_<End>* *c_End*
 
 							*c_<MiddleMouse>*
 <MiddleMouse>	Paste the contents of the clipboard (for X11 the primary
-		selection).  This is similar to using CTRL-R *, but no CR
+		selection).  This is similar to using `CTRL-R *`, but no CR
 		characters are inserted between lines.
 
 CTRL-H						*c_<BS>* *c_CTRL-H* *c_BS*
@@ -190,8 +190,8 @@ CTRL-R CTRL-L				*c_CTRL-R_CTRL-L* *c_<C-R>_<C-L>*
 
 					*c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>*
 					*c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>*
-CTRL-R CTRL-R {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}
-CTRL-R CTRL-O {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}
+CTRL-R CTRL-R `{register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}`
+CTRL-R CTRL-O `{register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}`
 		Insert register or object under the cursor.  Works like
 		|c_CTRL-R| but inserts the text literally.  For example, if
 		register a contains "xy^Hz" (where ^H is a backspace),
@@ -1058,7 +1058,7 @@ But expansion is only done if there are any wildcards before expanding the
 '%', '#', etc..  This avoids expanding wildcards inside a file name.  If you
 want to expand the result of <cfile>, add a wildcard character to it.
 Examples: (alternate file name is "?readme?")
-	command		expands to  ~
+	command		expands to >
 	:e #		:e ?readme?
 	:e `ls #`	:e {files matching "?readme?"}
 	:e #.*		:e {files matching "?readme?.*"}
@@ -1230,6 +1230,6 @@ The character used for the pattern indicates the type of command-line:
 	?	backward search string
 	=	expression for "= |expr-register|
 	@	string for |input()|
-	-	text for |:insert| or |:append|
+	`-`	text for |:insert| or |:append|
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/deprecated.txt

@@ -130,11 +130,11 @@ LSP FUNCTIONS
 - *vim.lsp.util.set_qflist()*			Use |setqflist()| instead.
 - *vim.lsp.util.set_loclist()*			Use |setloclist()| instead.
 - *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_active_clients()| with
-						{buffer = bufnr} instead.
+						{buffer=bufnr} instead.
 - *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
-						{async = true} instead.
+						{async=true} instead.
 - *vim.lsp.buf.formatting_sync()*		Use |vim.lsp.buf.format()| with
-						{async = false} instead.
+						{async=false} instead.
 - *vim.lsp.buf.range_formatting()*		Use |vim.lsp.formatexpr()|
 						or |vim.lsp.buf.format()| instead.
 - *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| or access