doc [ci skip] #11656

CONTRIBUTING.md

@@ -65,10 +65,11 @@ Pull requests (PRs)
 Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request
 For Comment) and `[RDY]` (Ready).
 
-- `[RFC]` is assumed by default, i.e. you are requesting a review.
-- Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
-  is still in flux.
-- Add `[RDY]` if you are _done_ and only waiting on merge.
+1. `[RFC]` is assumed by default, **do not** put "RFC" in the PR title (it adds
+   noise to merge commit messages).
+2. Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
+   is still in flux.
+3. Add `[RDY]` to the PR title if you are _done_ and only waiting on merge.
 
 ### Commit messages
 

runtime/doc/api.txt

@@ -183,21 +183,17 @@ External programs (clients) can use the metadata to discover the API, using
 any of these approaches:
 
   1. Connect to a running Nvim instance and call |nvim_get_api_info()| via
-     msgpack-rpc. This is best for clients written in dynamic languages which
+     msgpack-RPC. This is best for clients written in dynamic languages which
      can define functions at runtime.
 
-  2. Start Nvim with the |--api-info| option. Useful for clients written in
-     statically-compiled languages.
-
-  3. Use the |api_info()| Vimscript function.
-
-Example: To get a human-readable list of API functions: >
-    :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
-<
-Example: To get a formatted dump of the API using python (requires the
-"pyyaml" and "msgpack-python" modules): >
-    nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
+  2. Start Nvim with |--api-info|. Useful for statically-compiled clients.
+     Example (requires Python "pyyaml" and "msgpack-python" modules): >
+     nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
 <
+  3. Use the |api_info()| Vimscript function. >
+     :lua print(vim.inspect(vim.fn.api_info()))
+<     Example using |filter()| to exclude non-deprecated API functions: >
+     :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 
 ==============================================================================
 API contract                                                     *api-contract*

runtime/doc/autocmd.txt

@@ -251,7 +251,6 @@ Name			triggered by ~
 
 	Buffers
 |BufAdd|		just after adding a buffer to the buffer list
-|BufCreate|		just after adding a buffer to the buffer list
 |BufDelete|		before deleting a buffer from the buffer list
 |BufWipeout|		before completely deleting a buffer
 
@@ -367,32 +366,29 @@ Name			triggered by ~
 
 The alphabetical list of autocommand events:		*autocmd-events-abc*
 
-							*BufCreate* *BufAdd*
-BufAdd or BufCreate		Just after creating a new buffer which is
+							*BufAdd*
+BufAdd				Just after creating a new buffer which is
 				added to the buffer list, or adding a buffer
-				to the buffer list.
-				Also used just after a buffer in the buffer
-				list has been renamed.
-				The BufCreate event is for historic reasons.
-				NOTE: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being created "<afile>".
+				to the buffer list, a buffer in the buffer
+				list was renamed.
+				Before |BufEnter|.
+				NOTE: Current buffer "%" may be different from
+				the buffer being created "<afile>".
 							*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: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being deleted "<afile>" and "<abuf>".
-				Don't change to another buffer, it will cause
-				problems.
+				NOTE: Current buffer "%" may be different from
+				the buffer being deleted "<afile>" and "<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, after the
-				BufReadPost autocommands.
+				After |BufAdd|.
+				After |BufReadPost|.
 							*BufFilePost*
 BufFilePost			After changing the name of the current buffer
 				with the ":file" or ":saveas" command.
@@ -405,9 +401,8 @@ BufHidden			Just before a buffer becomes hidden.  That is,
 				the buffer, but the buffer is not unloaded or
 				deleted.  Not used for ":qa" or ":q" when
 				exiting Vim.
-				NOTE: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being unloaded "<afile>".
+				NOTE: current buffer "%" may be different from
+				the buffer being unloaded "<afile>".
 							*BufLeave*
 BufLeave			Before leaving to another buffer.  Also when
 				leaving or closing the current window and the
@@ -418,9 +413,8 @@ 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: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being created "<afile>".
+				NOTE: Current buffer "%" may be different from
+				the buffer being created "<afile>".
 							*BufNewFile*
 BufNewFile			When starting to edit a file that doesn't
 				exist.  Can be used to read in a skeleton
@@ -451,13 +445,11 @@ BufUnload			Before unloading a buffer.  This is when the
 				may be after a BufWritePost and before a
 				BufDelete.  Also used for all buffers that are
 				loaded when Vim is going to exit.
-				NOTE: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being unloaded "<afile>".
-				Don't change to another buffer or window, it
-				will cause problems!
-				When exiting and v:dying is 2 or more this
-				event is not triggered.
+				NOTE: Current buffer "%" may be different from
+				the buffer being unloaded "<afile>".
+				Do not change to another buffer or window!
+				Not triggered when exiting and v:dying is 2 or
+				more.
 							*BufWinEnter*
 BufWinEnter			After a buffer is displayed in a window.  This
 				can be when the buffer is loaded (after
@@ -476,23 +468,20 @@ BufWinLeave			Before a buffer is removed from a window.
 				Not when it's still visible in another window.
 				Also triggered when exiting.  It's triggered
 				before BufUnload or BufHidden.
-				NOTE: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being unloaded "<afile>".
-				When exiting and v:dying is 2 or more this
-				event is not triggered.
+				NOTE: Current buffer "%" may be different from
+				the buffer being unloaded "<afile>".
+				Not triggered when exiting and v:dying is 2 or
+				more.
 							*BufWipeout*
 BufWipeout			Before completely deleting a buffer.  The
 				BufUnload and BufDelete events may be called
 				first (if the buffer was loaded and was in the
 				buffer list).  Also used just before a buffer
 				is renamed (also when it's not in the buffer
 				list).
-				NOTE: When this autocommand is executed, the
-				current buffer "%" may be different from the
-				buffer being deleted "<afile>".
-				Don't change to another buffer, it will cause
-				problems.
+				NOTE: Current buffer "%" may be different from
+				the buffer being deleted "<afile>".
+				Do not change to another buffer.
 						*BufWrite* *BufWritePre*
 BufWrite or BufWritePre		Before writing the whole buffer to a file.
 							*BufWriteCmd*

runtime/doc/deprecated.txt

@@ -28,6 +28,7 @@ Environment Variables ~
 			$NVIM_LISTEN_ADDRESS is ignored.
 
 Events ~
+*BufCreate*		Use |BufAdd| instead.
 *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
 *FileEncoding*		Never fired; equivalent to |EncodingChanged|.
 *GUIEnter*		Never fired; use |UIEnter| instead.

runtime/doc/eval.txt

@@ -2520,6 +2520,9 @@ and({expr}, {expr})					*and()*
 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()))
+
 append({lnum}, {text})					*append()*
 		When {text} is a |List|: Append each item of the |List| as a
 		text line below line {lnum} in the current buffer.
@@ -5453,35 +5456,41 @@ jobstart({cmd}[, {opts}])				*jobstart()*
 
 							*jobstart-options*
 		{opts} is a dictionary with these keys:
-		  |on_stdout|: stdout event handler (function name or |Funcref|)
-		  stdout_buffered : read stdout in |channel-buffered| mode.
-		  |on_stderr|: stderr event handler (function name or |Funcref|)
-		  stderr_buffered : read stderr in |channel-buffered| mode.
-		  |on_exit|  : exit event handler (function name or |Funcref|)
-		  cwd      : Working directory of the job; defaults to
-		             |current-directory|.
-		  env      : A dict of strings to append (or replace see
-		             |clear_env|) to the current environment.
-		  clear_env: If set, use the exact values passed in |env|
-		  rpc      : If set, |msgpack-rpc| will be used to communicate
-			     with the job over stdin and stdout. "on_stdout" is
-			     then ignored, but "on_stderr" can still be used.
-		  pty      : If set, the job will be connected to a new pseudo
-			     terminal and the job streams are connected to the
-			     master file descriptor. "on_stderr" is ignored,
-			     "on_stdout" receives all output.
-
-		  width    : (pty only) Width of the terminal screen
-		  height   : (pty only) Height of the terminal screen
-		  TERM     : (pty only) $TERM environment variable
-		  detach   : (non-pty only) Detach the job process: it will
-			     not be killed when Nvim exits. If the process
-			     exits before Nvim, "on_exit" will be invoked.
+		  clear_env:  (boolean) `env` defines the job environment
+			      exactly, instead of merging current environment.
+		  cwd:	      (string, default=|current-directory|) Working
+			      directory of the job.
+		  detach:     (boolean) Detach the job process: it will not be
+			      killed when Nvim exits. If the process exits
+			      before Nvim, `on_exit` will be invoked.
+		  env:	      (dict) Map of environment variable name:value
+			      pairs extending (or replacing if |clear_env|)
+			      the current environment.
+		  height:     (number) Height of the `pty` terminal.
+		  |on_exit|:    (function) Callback invoked when the job exits.
+		  |on_stdout|:  (function) Callback invoked when the job emits
+			      stdout data.
+		  |on_stderr|:  (function) Callback invoked when the job emits
+			      stderr data.
+		  pty:	      (boolean) Connect the job to a new pseudo
+			      terminal, and its streams to the master file
+			      descriptor. Then  `on_stderr` is ignored,
+			      `on_stdout` receives all output.
+		  rpc:	      (boolean) Use |msgpack-rpc| to communicate with
+			      the job over stdio. Then `on_stdout` is ignored,
+			      but `on_stderr` can still be used.
+		  stderr_buffered: (boolean) Collect data until EOF (stream closed)
+			      before invoking `on_stderr`. |channel-buffered|
+		  stdout_buffered: (boolean) Collect data until EOF (stream
+			      closed) before invoking `on_stdout`. |channel-buffered|
+		  TERM:	      (string) Sets the `pty` $TERM environment variable.
+		  width:      (number) Width of the `pty` terminal.
 
 		{opts} is passed as |self| dictionary to the callback; the
 		caller may set other keys to pass application-specific data.
+
 		Returns:
-		  - The channel ID on success
+		  - |channel-id| on success
 		  - 0 on invalid arguments
 		  - -1 if {cmd}[0] is not executable.
 		See also |job-control|, |channel|, |msgpack-rpc|.

runtime/doc/help.txt

@@ -137,6 +137,7 @@ Special issues ~
 
 Programming language support ~
 |indent.txt|	automatic indenting for C and other languages
+|lsp.txt|         Language Server Protocol (LSP)
 |syntax.txt|	syntax highlighting
 |filetype.txt|	settings done specifically for a type of file
 |quickfix.txt|	commands for a quick edit-compile-fix cycle
@@ -169,7 +170,7 @@ Versions ~
 Standard plugins ~
 |pi_gzip.txt|      Reading and writing compressed files
 |pi_health.txt|    Healthcheck framework
-|pi_matchit.txt|   Extended "%" matching
+|pi_matchit.txt|   Extended |%| matching
 |pi_msgpack.txt|   msgpack utilities
 |pi_netrw.txt|     Reading and writing files over a network
 |pi_paren.txt|     Highlight matching parens

runtime/doc/index.txt

@@ -10,7 +10,7 @@ short description.  The lists are sorted on ASCII value.
 Tip: When looking for certain functionality, use a search command.  E.g.,
 to look for deleting something, use: "/delete".
 
-For an overview of options see help.txt |option-list|.
+For an overview of options see |option-list|.
 For an overview of built-in functions see |functions|.
 For a list of Vim variables see |vim-variable|.
 For a complete listing of all help items see |help-tags|.

runtime/doc/lsp.txt

@@ -49,9 +49,9 @@ go-to-definition, hover, etc.  Example config: >
   nnoremap <silent> 1gD   <cmd>lua vim.lsp.buf.type_definition()<CR>
   nnoremap <silent> gr    <cmd>lua vim.lsp.buf.references()<CR>
 
-Nvim provides the vim.lsp.omnifunc 'omnifunc' handler which allows
-|i_CTRL-X_CTRL-O| to consume LSP completion features. Example config (note the
-use of |v:lua| to call Lua from Vimscript): >
+Nvim provides the |vim.lsp.omnifunc| 'omnifunc' handler which allows
+|i_CTRL-X_CTRL-O| to consume LSP completion. Example config (note the use of
+|v:lua| to call Lua from Vimscript): >
 
   " Use LSP omni-completion in Python files.
   autocmd Filetype python setlocal omnifunc=v:lua.vim.lsp.omnifunc
@@ -477,7 +477,23 @@ notify({...})                                               *vim.lsp.notify()*
                 TODO: Documentation
 
 omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
-                TODO: Documentation
+                Implements 'omnifunc' compatible LSP completion.
+
+                Parameters: ~
+                    {findstart}  0 or 1, decides behavior
+                    {base}       If findstart=0, text to match against
+
+                Return: ~
+                    (number) Decided by`findstart`:
+                    • findstart=0: column where the completion starts, or -2
+                      or -3
+                    • findstart=1: list of matches (actually just calls
+                      |complete()|)
+
+                See also: ~
+                    |complete-functions|
+                    |complete-items|
+                    |CompleteDone|
 
 on_error({code}, {err})                                   *vim.lsp.on_error()*
                 TODO: Documentation

runtime/doc/lua.txt

@@ -885,6 +885,16 @@ deepcopy({orig})                                              *vim.deepcopy()*
                 Return: ~
                     New table of copied keys and (nested) values.
 
+endswith({s}, {suffix})                                       *vim.endswith()*
+                Tests if `s` ends with `suffix` .
+
+                Parameters: ~
+                    {s}       (string) a string
+                    {suffix}  (string) a suffix
+
+                Return: ~
+                    (boolean) true if `suffix` is a suffix of s
+
 gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
                 Splits a string at each instance of a separator.
 
@@ -962,6 +972,16 @@ split({s}, {sep}, {plain})                                       *vim.split()*
                 See also: ~
                     |vim.gsplit()|
 
+startswith({s}, {prefix})                                   *vim.startswith()*
+                Tests if `s` starts with `prefix` .
+
+                Parameters: ~
+                    {s}       (string) a string
+                    {prefix}  (string) a prefix
+
+                Return: ~
+                    (boolean) true if `prefix` is a prefix of s
+
 tbl_add_reverse_lookup({o})                     *vim.tbl_add_reverse_lookup()*
                 Add the reverse lookup values to an existing table. For
                 example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A =

runtime/doc/tabpage.txt

@@ -190,6 +190,9 @@ gt					*i_CTRL-<PageDown>* *i_<C-PageDown>*
 {count}<C-PageDown>
 {count}gt	Go to tab page {count}.  The first tab page has number one.
 
+CTRL-<Tab>					*CTRL-<Tab>*
+CTRL-W g<Tab>					*g<Tab>* *CTRL-W_g<Tab>*
+g<Tab>		Go to previous (last accessed) tab page.
 
 :tabp[revious]				*:tabp* *:tabprevious* *gT* *:tabN*
 :tabN[ext]				*:tabNext* *CTRL-<PageUp>*

runtime/doc/vim_diff.txt

@@ -270,11 +270,6 @@ 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.
 
-*v:none* variable is absent.  In Vim it represents “no value” in “js” strings 
-like "[,]" parsed as "[v:none]" by |js_decode()|.
-
-*js_encode()* and *js_decode()* functions are also absent.
-
 Viminfo text files were replaced with binary (messagepack) ShaDa files.
 Additional differences:
 
@@ -443,6 +438,11 @@ Compile-time features:
   Emacs tags support
   X11 integration (see |x11-selection|)
 
+Eval:
+  *js_encode()*
+  *js_decode()*
+  *v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead.
+
 Highlight groups:
   *hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim
     supports 'winhighlight' window-local highlights.