doc [ci skip] #10177

ref #10278 #10279 #10353

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: https://salt.bountysource.com/teams/neovim

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,15 @@
+---
+name: Bug report
+about: Report a problem in Nvim
+title: ''
+labels: bug
+
+---
+
 <!-- Before reporting: search existing issues and check the FAQ. -->
 
 - `nvim --version`:
-- Vim (version: ) behaves differently?
+- `vim -u DEFAULTS` (version: ) behaves differently?
 - Operating system/version:
 - Terminal name/version:
 - `$TERM`:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Request an enhancement for Nvim
+title: ''
+labels: enhancement
+
+---
+
+<!-- Before reporting: search existing issues and check the FAQ. -->
+
+- `nvim --version`:
+- `vim -u DEFAULTS` (version: ) behaves differently?
+- Operating system/version:
+- Terminal name/version:
+- `$TERM`:
+
+### Steps to reproduce using `nvim -u NORC`
+
+```
+nvim -u NORC
+
+```
+
+### Actual behaviour
+
+### Expected behaviour
+

runtime/doc/deprecated.txt

@@ -58,6 +58,10 @@ Normal commands ~
 
 Options ~
 *'cscopeverbose'*	Enabled by default. Use |:silent| instead.
+*'exrc'* *'ex'*		Security risk: downloaded files could include
+			a malicious .nvimrc or .exrc file. See 'secure'.
+			Recommended alternative: define an autocommand in your
+			|vimrc| to set options for a matching directory.
 'gd'
 'gdefault'		Enables the |:substitute| flag 'g' by default.
 *'fe'*			'fenc'+'enc' before Vim 6.0; no longer used.

runtime/doc/eval.txt

@@ -5333,9 +5333,10 @@ jobwait({ids}[, {timeout}])				*jobwait()*
 
 		{ids} is a list of |job-id|s to wait for.
 		{timeout} is the maximum number of milliseconds to wait.
-		{timeout} of zero can be used to check if a job-id is valid,
-		without waiting.
 
+		Use zero {timeout} to check the status of a job: >
+			let exited = jobwait([{job-id}], 0)[0] >= 0
+<
 		During jobwait() callbacks for jobs not in the {ids} list may
 		be invoked. The screen will not redraw unless |:redraw| is
 		invoked by a callback.

runtime/doc/if_lua.txt

@@ -365,7 +365,7 @@ VIM.API							*lua-api*
 
 `vim.api` exposes the full Nvim |API| as a table of Lua functions.
 
-For example, to use the "nvim_get_current_line()" API function, call
+Example: to use the "nvim_get_current_line()" API function, call
 "vim.api.nvim_get_current_line()": >
 
     print(tostring(vim.api.nvim_get_current_line()))
@@ -375,11 +375,28 @@ VIM.LOOP							*lua-loop*
 
 `vim.loop` exposes all features of the Nvim event-loop.  This is a lower-level
 API that provides functionality for networking, filesystem, and process
-management.
+management.  Try this command to see available functions: >
+
+    :lua print(vim.inspect(vim.loop))
 
 See http://docs.libuv.org for complete documentation.
 See https://github.com/luvit/luv/tree/master/examples for examples.
 
+Note: it is not safe to directly invoke the Nvim API from `vim.loop`
+callbacks.  This will crash: >
+
+    local timer = vim.loop.new_timer()
+    timer:start(1000, 0, function()
+      vim.api.nvim_command('sleep 100m')  -- BROKEN, will crash.
+    end)
+
+Instead wrap the API call with |vim.schedule()|. >
+
+    local timer = vim.loop.new_timer()
+    timer:start(1000, 0, function()
+      vim.schedule(function() vim.api.nvim_command('sleep 100m') end)
+    end)
+
 Example: repeating timer
     1. Save this code to a file.
     2. Execute it with ":luafile %". >

runtime/doc/nvim_terminal_emulator.txt

@@ -117,21 +117,22 @@ higher precedence: it is applied after terminal colors are resolved.
 ==============================================================================
 Status Variables				*terminal-status*
 
-Terminal buffers maintain some information about the terminal in buffer-local
+Terminal buffers maintain some buffer-local variables and options. The values
-variables:
+are initialized before TermOpen, so you can use them in a local 'statusline'.
-
+Example: >
-- *b:term_title* The settable title of the terminal, typically displayed in
-  the window title or tab title of a graphical terminal emulator. Programs
-  running in the terminal can set this title via an escape sequence.
-- |'channel'| The nvim channel ID for the underlying PTY.
-  |chansend()| can be used to send input to the terminal.
-
-These variables are initialized before TermOpen, so you can use them in
-a local 'statusline'. Example: >
     :autocmd TermOpen * setlocal statusline=%{b:term_title}
-<
+
+- *b:term_title*  Terminal title (user-writable), typically displayed in the
+  window title or tab title of a graphical terminal emulator. Terminal
+  programs can set this by emitting an escape sequence.
+- |'channel'|  Terminal PTY |job-id|.  Can be used with |chansend()| to send
+  input to the terminal.
+
+Use |jobwait()| to check if the terminal job has finished: >
+    let exited = jobwait([&channel], 0)[0] >= 0
+
 ==============================================================================
-5. Debugging				*terminal-debug* *terminal-debugger*
+:Termdebug plugin				*terminal-debug*
 
 The Terminal debugging plugin can be used to debug a program with gdb and view
 the source code in a Vim window.  Since this is completely contained inside

runtime/doc/options.txt

@@ -2134,22 +2134,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 	This option is reset when the 'paste' option is set and restored when
 	the 'paste' option is reset.
 
-					*'exrc'* *'ex'* *'noexrc'* *'noex'*
-'exrc' 'ex'		boolean (default off)
-			global
-	Enables the reading of .vimrc and .exrc in the current directory.
-	Setting this option is a potential security leak.  E.g., consider
-	unpacking a package or fetching files from github, a .vimrc in there
-	might be a trojan horse.  BETTER NOT SET THIS OPTION!
-	Instead, define an autocommand in your .vimrc to set options for a
-	matching directory.
-
-	If you do switch this option on you should also consider setting the
-	'secure' option (see |initialization|).
-	This option cannot be set from a |modeline| or in the |sandbox|, for
-	security reasons.
-	Also see |init.vim| and |gui-init|.
-
 				*'fileencoding'* *'fenc'* *E213*
 'fileencoding' 'fenc'	string (default: "")
 			local to buffer

runtime/doc/quickref.txt

@@ -38,7 +38,7 @@ N is used to indicate an optional count that can be given before the command.
 |l|	N  l		right (also: <Space> or <Right> key)
 |0|	   0		to first character in the line (also: <Home> key)
 |^|	   ^		to first non-blank character in the line
-|$|	N  $		to the last character in the line (N-1 lines lower)
+|$|	N  $		to the next EOL (end of line) position
 			   (also: <End> key)
 |g0|	   g0		to first character in screen line (differs from "0"
 			   when lines wrap)

runtime/doc/starting.txt

@@ -451,14 +451,10 @@ accordingly.  Vim proceeds in this order:
 	-  Environment variable $EXINIT, used as an Ex command line.
 
      c. If the 'exrc' option is on (which is NOT the default), the current
-	directory is searched for three files.  The first that exists is used,
+	directory is searched for two files.  The first that exists is used,
 	the others are ignored.
-	-  The file ".nvimrc" (for Unix)
+	-  The file ".nvimrc"
-		    "_nvimrc" (for Win32)
+	-  The file ".exrc"
-	-  The file "_nvimrc" (for Unix)
-		    ".nvimrc" (for Win32)
-	-  The file ".exrc"  (for Unix)
-		    "_exrc"  (for Win32)
 
 4. Enable filetype and indent plugins.
 	This does the same as the commands: >

runtime/doc/various.txt

@@ -12,22 +12,24 @@ Various commands					*various*
 1. Various commands					*various-cmds*
 
 							*CTRL-L*
-CTRL-L			Clear and redraw the screen.  The redraw may happen
+CTRL-L			Clears and redraws the screen.  The redraw may happen
 			later, after processing typeahead.
 
+							*:mod* *:mode*
+:mod[e]			Clears and redraws the screen.
+
 							*:redr* *:redraw*
-:redr[aw][!]		Redraw the screen right now.  When ! is included it is
+:redr[aw][!]		Redraws pending screen updates now, or the entire
-			cleared first.
+			screen if "!" is included.  To CLEAR the screen use
-			Useful to update the screen halfway through executing
+			|:mode| or |CTRL-L|.
-			a script or function (or a mapping if 'lazyredraw'
+			Useful to update the screen during a script or
-			set).
+			function (or a mapping if 'lazyredraw' set).
 
 						*:redraws* *:redrawstatus*
-:redraws[tatus][!]	Redraw the status line of the current window.  When !
+:redraws[tatus][!]	Redraws the status line of the current window, or all
-			is included all status lines are redrawn.
+			status lines if "!" is included.
-			Useful to update the status line(s) when 'statusline'
+			Useful if 'statusline' includes an item that doesn't
-			includes an item that doesn't cause automatic
+			cause automatic updating.
-			updating.
 
 							*N<Del>*
 <Del>			When entering a number: Remove the last digit.

runtime/doc/windows.txt

@@ -520,9 +520,6 @@ CTRL-W >	Increase current window width by N (default 1).
 :vertical res[ize] [N]			*:vertical-resize* *CTRL-W_bar*
 CTRL-W |	Set current window width to N (default: widest possible).
 
-						*:mod* *:mode*
-:mod[e]		Detects the screen size and redraws the screen.
-
 You can also resize a window by dragging a status line up or down with the
 mouse.  Or by dragging a vertical separator line left or right.  This only
 works if the version of Vim that is being used supports the mouse and the

src/nvim/main.c

@@ -146,11 +146,7 @@ void event_init(void)
   // early msgpack-rpc initialization
   msgpack_rpc_init_method_table();
   msgpack_rpc_helpers_init();
-  // Initialize input events
   input_init();
-  // Timer to wake the event loop if a timeout argument is passed to
-  // `event_poll`
-  // Signals
   signal_init();
   // finish mspgack-rpc initialization
   channel_init();
@@ -346,10 +342,8 @@ int main(int argc, char **argv)
     p_lpl = false;
   }
 
-  // give embedders a chance to set up nvim, by processing a request before
+  // Wait for UIs to set up Nvim or show early messages
-  // startup. This allows an external UI to show messages and prompts from
+  // and prompts (--cmd, swapfile dialog, …).
-  // --cmd and buffer loading (e.g. swap files)
-  bool early_ui = false;
   bool use_remote_ui = (embedded_mode && !headless_mode);
   bool use_builtin_ui = (!headless_mode && !embedded_mode && !silent_mode);
   if (use_remote_ui || use_builtin_ui) {
@@ -364,7 +358,6 @@ int main(int argc, char **argv)
     // prepare screen now, so external UIs can display messages
     starting = NO_BUFFERS;
     screenclear();
-    early_ui = true;
     TIME_MSG("initialized screen early for UI");
   }
 
@@ -461,7 +454,7 @@ int main(int argc, char **argv)
 
   setmouse();  // may start using the mouse
 
-  if (exmode_active || early_ui) {
+  if (exmode_active || use_remote_ui || use_builtin_ui) {
     // Don't clear the screen when starting in Ex mode, or when a UI might have
     // displayed messages.
     redraw_later(VALID);