doc

Closes #4777

runtime/doc/eval.txt

@@ -2507,11 +2507,9 @@ capture({command})					*capture()*
 			echo capture(['echon "foo"', 'echon "bar"'])
 <			foobar
 		This function is not available in the |sandbox|.
-		Note: {command}s run as if prepended with |:silent| (output is
+		Note: {command} executes as if prepended with |:silent|
-		captured, but not displayed).  If multiple capture() calls are
+		(output is collected, but not displayed).  If nested, an outer
-		nested, the outer capture() will not catch the command output
+		capture() will not observe the output of inner calls.
-		of the inner capture(); the inner capture will not cancel the
-		outer.
 		Note: Text attributes (highlights) are not captured.
 
 ceil({expr})							*ceil()*
@@ -2847,6 +2845,13 @@ dictwatcheradd({dict}, {pattern}, {callback})		      *dictwatcheradd()*
 		After this is called, every change on {dict} and on keys
 		matching {pattern} will result in {callback} being invoked.
 
+		For example, to watch all global variables: >
+			silent! call dictwatcherdel(g:, '*', 'OnDictChanged')
+			function! OnDictChanged(d,k,z)
+			  echomsg string(a:k) string(a:z)
+			endfunction
+			call dictwatcheradd(g:, '*', 'OnDictChanged')
+<
 		For now {pattern} only accepts very simple patterns that can
 		contain a '*' at the end of the string, in which case it will
 		match every key that begins with the substring before the '*'.
@@ -2857,7 +2862,7 @@ dictwatcheradd({dict}, {pattern}, {callback})		      *dictwatcheradd()*
 
 		- The dictionary being watched.
 		- The key which changed.
-		- A dictionary containg the new and old values for the key.
+		- A dictionary containing the new and old values for the key.
 
 		The type of change can be determined by examining the keys
 		present on the third argument:
@@ -4325,9 +4330,8 @@ jobsend({job}, {data})					{Nvim} *jobsend()*
 < 		will send "abc<NL>123<NUL>456<NL>".
 
 jobstart({cmd}[, {opts}])				{Nvim} *jobstart()*
-		Spawns {cmd} as a job.  If {cmd} is a |List|, it will be run
+		Spawns {cmd} as a job.  If {cmd} is a |List| it is run
-		directly.  If {cmd} is a |string|, it will be roughly 
+		directly.  If {cmd} is a |String| it is processed like this: >
-		equivalent to >
 		  :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}'])
 <		NOTE: read |shell-unquoting| before constructing any lists 
 		with 'shell' or 'shellcmdflag' options.  The above call is 
@@ -4335,9 +4339,9 @@ jobstart({cmd}[, {opts}])				{Nvim} *jobstart()*
 		and do split taking quotes into account.
 
 		{opts} is a dictionary with these keys:
-		  on_stdout: stdout event handler
+		  on_stdout: stdout event handler (function name or |Funcref|)
-		  on_stderr: stderr event handler
+		  on_stderr: stderr event handler (function name or |Funcref|)
-		  on_exit  : exit event handler
+		  on_exit  : exit event handler (function name or |Funcref|)
 		  cwd      : Working directory of the job; defaults to
 		             |current-directory|.
 		  pty      : If set, the job will be connected to a new pseudo
@@ -4351,17 +4355,12 @@ jobstart({cmd}[, {opts}])				{Nvim} *jobstart()*
 			     when nvim exits. If the process dies before
 			     nvim exits, on_exit will still be invoked.
 
-		Either funcrefs or function names can be passed as event
+		{opts} is passed as |self| to the callback; the caller may
-		handlers. The {opts} object is also used as the "self"
+		pass arbitrary data by setting other keys.
-		argument for the callback, so the caller may pass arbitrary
-		data by setting other key.(see |Dictionary-function| for more
-		information).
 		Returns:
-		  - The job ID on success, which is used by |jobsend()| and
+		  - job ID on success, used by |jobsend()| and |jobstop()|
-		    |jobstop()|
+		  - 0 on invalid arguments or if the job table is full
-		  - 0 when the job table is full or on invalid arguments
+		  - -1 if {cmd}[0] is not executable.
-		  - -1 when {cmd}[0] is not executable.  Will never fail if
-		    {cmd} is a string unless 'shell' is not executable.
 		See |job-control| for more information.
 
 jobstop({job})						{Nvim} *jobstop()*

runtime/doc/job_control.txt

@@ -40,7 +40,7 @@ for details.
 Job control is achieved by calling a combination of the |jobstart()|,
 |jobsend()| and |jobstop()| functions. Here's an example:
 >
-    function s:JobHandler(job_id, data, event)
+    function! s:JobHandler(job_id, data, event)
       if a:event == 'stdout'
         let str = self.shell.' stdout: '.join(a:data)
       elseif a:event == 'stderr'
@@ -84,6 +84,19 @@ Here's what is happening:
      program.
   2: The event type, which is "stdout", "stderr" or "exit".
 
+  Note: Buffered stdout/stderr data which has not been flushed by the sender
+        will not trigger the "stdout" callback (but if the process ends, the
+        "exit" callback will be triggered).
+        For example, "ruby -e" buffers output, so small strings will be
+        buffered unless "auto-flushing" ($stdout.sync=true) is enabled. >
+          function! Receive(job_id, data, event)
+            echom printf('%s: %s',a:event,string(a:data))
+          endfunction
+          call jobstart(['ruby', '-e',
+            \ '$stdout.sync = true; 5.times do sleep 1 and puts "Hello Ruby!" end'],
+            \ {'on_stdout': 'Receive'})
+<       https://github.com/neovim/neovim/issues/1592
+
 The options dictionary is passed as the "self" variable to the callback
 function. Here's a more object-oriented version of the above:
 >

runtime/doc/vim_diff.txt

@@ -70,6 +70,7 @@ Job control			|job-control|
 Remote plugins			|remote-plugin|
 Python plugins			|provider-python|
 Clipboard integration		|provider-clipboard|
+XDG support
 
 
 OTHER FEATURES ~
@@ -96,6 +97,9 @@ Options:
 Commands:
   |:CheckHealth|
 
+Functions:
+  |capture()|
+
 Events:
   |TabNew|
   |TabNewEntered|
@@ -121,6 +125,11 @@ are always available and may be used simultaneously in separate plugins.  The
 `neovim` pip package must be installed to use Python plugins in Nvim (see
 |provider-python|).
 
+|:!| and |system()| do not support "interactive" commands; use |:terminal| for
+that instead. Terminal Vim supports interactive |:!| and |system()|, but gui
+Vim does not. See ":help gui-pty" in Vim:
+   http://vimdoc.sourceforge.net/htmldoc/gui_x11.html#gui-pty
+
 |mkdir()| behaviour changed:
 1. Assuming /tmp/foo does not exist and /tmp can be written to
    mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar