doc [ci skip] #10177

ref #10278 #10279 #10353

9 files changed, 57 insertions, 55 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index b56240353f..c58215dce6 100644
--- a/runtime/doc/deprecated.txt
+++ b/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.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index afbe4f2661..2fb61e3092 100644
--- a/runtime/doc/eval.txt
+++ b/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.
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index b8d520e6e5..cbc19a63a2 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -365,21 +365,38 @@ 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()))
 
 ------------------------------------------------------------------------------
-VIM.LOOP							*lua-loop*
+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 %". >
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index aba0571dc0..983d04b3bf 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/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
-variables:
+Terminal buffers maintain some buffer-local variables and options. The values
+are initialized before TermOpen, so you can use them in a local 'statusline'.
+Example: >
+    :autocmd TermOpen * setlocal statusline=%{b:term_title}
 
-- *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.
+- *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
 
-These variables are initialized before TermOpen, so you can use them in
-a local 'statusline'. Example: >
-    :autocmd TermOpen * setlocal statusline=%{b:term_title}
-<
 ==============================================================================
-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
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 53581179b6..8e06a1ee6e 100644
--- a/runtime/doc/options.txt
+++ b/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
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index d3d9303d3c..cbfcfa4010 100644
--- a/runtime/doc/quickref.txt
+++ b/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)
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 2a230d9449..6e68753292 100644
--- a/runtime/doc/starting.txt
+++ b/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)
-		    "_nvimrc" (for Win32)
-	-  The file "_nvimrc" (for Unix)
-		    ".nvimrc" (for Win32)
-	-  The file ".exrc"  (for Unix)
-		    "_exrc"  (for Win32)
+	-  The file ".nvimrc"
+	-  The file ".exrc"
 
 4. Enable filetype and indent plugins.
 	This does the same as the commands: >
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 2b6afcbdbc..c7fcd698db 100644
--- a/runtime/doc/various.txt
+++ b/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
-			cleared first.
-			Useful to update the screen halfway through executing
-			a script or function (or a mapping if 'lazyredraw'
-			set).
+:redr[aw][!]		Redraws pending screen updates now, or the entire
+			screen if "!" is included.  To CLEAR the screen use
+			|:mode| or |CTRL-L|.
+			Useful to update the screen during a script or
+			function (or a mapping if 'lazyredraw' set).
 
 						*:redraws* *:redrawstatus*
-:redraws[tatus][!]	Redraw the status line of the current window.  When !
-			is included all status lines are redrawn.
-			Useful to update the status line(s) when 'statusline'
-			includes an item that doesn't cause automatic
-			updating.
+:redraws[tatus][!]	Redraws the status line of the current window, or all
+			status lines if "!" is included.
+			Useful if 'statusline' includes an item that doesn't
+			cause automatic updating.
 
 							*N<Del>*
 <Del>			When entering a number: Remove the last digit.
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 63ffd91bfc..243060a617 100644
--- a/runtime/doc/windows.txt
+++ b/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