Merge remote-tracking branch 'vim/master'

Author: splhack

runtime/doc/channel.txt

@@ -1,4 +1,4 @@
-*channel.txt*      For Vim version 7.4.  Last change: 2016 Feb 27
+*channel.txt*      For Vim version 7.4.  Last change: 2016 Mar 03
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -103,6 +103,11 @@ when opening the channel: >
 	let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
 	call ch_sendexpr(channel, 'hello!')
 
+When trying out channels it's useful to see what is going on.  You can tell
+Vim to write lines in log file: >
+	call ch_logfile('channellog', 'w')
+See |ch_logfile()|.
+
 ==============================================================================
 3. Opening a channel					*channel-open*
 
@@ -130,7 +135,8 @@ Use |ch_status()| to see if the channel could be opened.
 		overwritten.  Therefore set "mode" first and the part specific
 		mode later.
 
-		Note: when writing to a file or buffer NL mode is always used.
+		Note: when writing to a file or buffer and when reading from a
+		buffer NL mode is used by default.
 
 							*channel-callback*
 "callback"	A function that is called when a message is received that is
@@ -191,6 +197,10 @@ For example, the handler can be added or changed: >
     call ch_setoptions(channel, {'callback': callback})
 When "callback" is empty (zero or an empty string) the handler is removed.
 
+After a callback has been invoked Vim will update the screen and put the
+cursor back where it belongs.  Thus the callback should not need to do
+`:redraw`.
+
 The timeout can be changed: >
     call ch_setoptions(channel, {'timeout': msec})
 <
@@ -259,9 +269,9 @@ message, it must use the number zero:
 Then channel handler will then get {response} converted to Vim types.  If the
 channel does not have a handler the message is dropped.
 
-On read error or ch_close(), when using a socket, the string "DETACH" is sent,
-if still possible.  The channel will then be inactive. For a JSON and JS mode
-channel quotes are used around DETACH, otherwise there are no quotes.
+On read error or ch_close(), when using a socket with RAW or NL mode, the
+string "DETACH\n" is sent, if still possible.  The channel will then be
+inactive.
 
 It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS
 channel.  The caller is then completely responsible for correct encoding and
@@ -457,6 +467,22 @@ For example, to start a job and write its output in buffer "dummy": >
 			     \ {'out-io': 'buffer', 'out-name': 'dummy'})
 	sbuf dummy
 
+To run a job that reads from a buffer: >
+	let job = job_start({command},
+	    \ {'in-io': 'buffer', 'in-name': 'mybuffer'})
+<
+							*E915* *E918*
+The buffer is found by name, similar to |bufnr()|. The buffer must exist and
+be loaded when job_start() is called.
+
+By default this reads the whole buffer.  This can be changed with the "in-top"
+and "in-bot" options.
+
+TODO
+A special mode is when "in-top" is set to zero and "in-bot" is not set: The
+last-but-one line will be send to the job stdin.  This allows for editing the
+last line and sending it when pressing Enter.
+
 TODO:
 To run a job and read its output once it is done: >
 	let job = job_start({command}, {'exit-cb': 'MyHandler'})
@@ -470,7 +496,8 @@ To run a job and read its output once it is done: >
 9. Starting a job without a channel			*job-start-nochannel*
 
 To start another process without creating a channel: >
-    let job = job_start(command, {"in-io": "null", "out-io": "null"})
+    let job = job_start(command,
+    	\ {"in-io": "null", "out-io": "null", "err-io": "null"})
 
 This starts {command} in the background, Vim does not wait for it to finish.
 
@@ -538,7 +565,9 @@ TODO:						*job-term*
 "in-io": "null"		disconnect stdin  TODO
 "in-io": "pipe"		stdin is connected to the channel (default)
 "in-io": "file"		stdin reads from a file  TODO
-"in-io": "buffer"	stdin reads from a buffer  TODO
+"in-io": "buffer"	stdin reads from a buffer
+"in-top": number	when using "buffer": first line to send (default: 1)
+"in-bot": number	when using "buffer": last line to send (default: last)
 "in-name": "/path/file"	the name of he file or buffer to read from
 "in-buf": number	the number of the buffer to read from  TODO
 
@@ -551,7 +580,7 @@ TODO:						*job-term*
 "out-buf": number	the number of the buffer to write to  TODO
 
 						*job-err-io*
-"err-io": "out"		same as stdout  TODO
+"err-io": "out"		stderr messages to go to stdout
 "err-io": "null"	disconnect stderr  TODO
 "err-io": "pipe"	stderr is connected to the channel (default)
 "err-io": "file"	stderr writes to a file  TODO
@@ -562,6 +591,10 @@ TODO:						*job-term*
 When the IO mode is "buffer" and there is a callback, the text is appended to
 the buffer before invoking the callback.
 
+When using JS or JSON mode with "buffer", only messages with zero or negative
+ID will be added to the buffer, after decoding + encoding.  Messages with a
+positive number will be handled by a callback, commands are handled as usual.
+
 The name of the buffer is compared the full name of existing buffers.  If
 there is a match that buffer is used.  Otherwise a new buffer is created.
 Use an empty name to always create a new buffer.  |ch_getbufnr()| can then be

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 7.4.  Last change: 2016 Feb 27
+*eval.txt*	For Vim version 7.4.  Last change: 2016 Mar 03
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -2695,6 +2695,14 @@ confirm({msg} [, {choices} [, {default} [, {type}]]])
 
 ch_close({channel})						*ch_close()*
 		Close {channel}.  See |channel-close|.
+
+		Note that a channel is closed in three stages:
+		  - The I/O ends, log message: "Closing channel". There can
+		    still be queued messages to read or callbacks to invoke.
+		  - The readahead is cleared, log message: "Clearing channel".
+		    Some variables may still reference the channel.
+		  - The channel is freed, log message: "Freeing channel".
+
 		{only available when compiled with the |+channel| feature}
 
 ch_evalexpr({channel}, {expr} [, {options}])			*ch_evalexpr()*
@@ -2703,7 +2711,7 @@ ch_evalexpr({channel}, {expr} [, {options}])			*ch_evalexpr()*
 		with a raw channel.  See |channel-use|.
 								*E917*
 		{options} must be a Dictionary.  It must not have a "callback"
-		entry.
+		entry.  It can have a "timeout" entry.
 
 		ch_evalexpr() waits for a response and returns the decoded
 		expression.  When there is an error or timeout it returns an
@@ -2753,6 +2761,7 @@ ch_logfile({fname} [, {mode}])					*ch_logfile()*
 		The file is flushed after every message, on Unix you can use
 		"tail -f" to see what is going on in real time.
 
+
 ch_open({address} [, {options}])				*ch_open()*
 		Open a channel to {address}.  See |channel|.
 		Returns a Channel.  Use |ch_status()| to check for

runtime/doc/index.txt

@@ -1,4 +1,4 @@
-*index.txt*     For Vim version 7.4.  Last change: 2016 Feb 27
+*index.txt*     For Vim version 7.4.  Last change: 2016 Mar 04
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -1324,7 +1324,6 @@ tag	      command	      action ~
 |:lnfile|	:lnf[ile]	go to first location in next file
 |:lnoremap|	:ln[oremap]	like ":noremap!" but includes Lang-Arg mode
 |:loadkeymap|	:loadk[eymap]	load the following keymaps until EOF
-|:loadplugin|	:loadp[lugin]	load a plugin from 'packpath'
 |:loadview|	:lo[adview]	load view for current window from a file
 |:lockmarks|	:loc[kmarks]	following command keeps marks where they are
 |:lockvar|	:lockv[ar]	lock variables
@@ -1397,6 +1396,7 @@ tag	      command	      action ~
 |:ounmap|	:ou[nmap]	like ":unmap" but for Operator-pending mode
 |:ounmenu|	:ounme[nu]	remove menu for Operator-pending mode
 |:ownsyntax|	:ow[nsyntax]	set new local syntax highlight for this window
+|:packadd|	:pa[ckadd]	add a plugin from 'packpath'
 |:pclose|	:pc[lose]	close preview window
 |:pedit|	:ped[it]	edit file in the preview window
 |:perl|		:pe[rl]		execute Perl command

runtime/doc/repeat.txt

@@ -1,4 +1,4 @@
-*repeat.txt*    For Vim version 7.4.  Last change: 2016 Feb 26
+*repeat.txt*    For Vim version 7.4.  Last change: 2016 Mar 04
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -213,23 +213,31 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
 			about each searched file.
 			{not in Vi}
 
-							*:loadp* *:loadplugin*
-:loadp[lugin] {name}	Search for an optional plugin directory and source the
-			plugin files found.  It is similar to: >
-				:runtime pack/*/opt/{name}/plugin/*.vim
-<			However, `:loadplugin` uses 'packpath' instead of
-			'runtimepath'.  And the directory found is added to
-			'runtimepath'.
-
-			If you have a directory under 'packpath' that doesn't
-			actually have a plugin file, just create an empty one.
-			This will still add the directory to 'runtimepath'.
+							*:pa* *:packadd*
+:pa[ckadd][!] {name}	Search for an optional plugin directory in 'packpath'
+			and source any plugin files found.  The directory must
+			match:
+				pack/*/opt/{name} ~
+			The directory is added to 'runtimepath' if it wasn't
+			there yet.
 
 			Note that {name} is the directory name, not the name
 			of the .vim file.  If the "{name}/plugin" directory
 			contains more than one file they are all sourced.
 
-			Also see |load-plugin|.
+			If the filetype detection was not enabled yet (this
+			is usually done with a "syntax enable" or "filetype
+			on" command in your .vimrc file), this will also look
+			for "{name}/ftdetect/*.vim" files.
+
+			When the optional ! is added no plugin files or
+			ftdetect scripts are loaded, only the matching
+			directories are added to 'runtimepath'.  This is
+			useful in your .vimrc.  The plugins will then be
+			loaded during initialization, see |load-plugins|.
+
+			Also see |pack-add|.
+
 
 :scripte[ncoding] [encoding]		*:scripte* *:scriptencoding* *E167*
 			Specify the character encoding used in the script.
@@ -433,6 +441,12 @@ You would now have these files under ~/.vim:
 	pack/my/ever/always/syntax/always.vim
 	pack/my/opt/mydebug/plugin/debugger.vim
 
+If you don't have a package but a single plugin, you need to create the extra
+directory level:
+	% mkdir -p ~/.vim/pack/my/ever/always
+	% cd ~/.vim/pack/my/ever/always
+	% unzip /tmp/myplugin.zip
+
 When Vim starts up it scans all directories in 'packpath' for plugins under the
 "ever" directory and loads them.  When found that directory is added to
 'runtimepath'.
@@ -443,11 +457,11 @@ In the example Vim will find "my/ever/always/plugin/always.vim" and adds
 If the "always" plugin kicks in and sets the 'filetype' to "always", Vim will
 find the syntax/always.vim file, because its directory is in 'runtimepath'.
 
-Vim will also load ftdetect files, like with |:loadplugin|.
+Vim will also load ftdetect files, like with |:packadd|.
 
-							*load-plugin*
-To load an optional plugin from a pack use the `:loadplugin` command: >
-	:loadplugin mydebug
+							*pack-add*
+To load an optional plugin from a pack use the `:packadd` command: >
+	:packadd mydebug
 This could be done inside always.vim, if some conditions are met.
 Or you could add this command to your |.vimrc|.
 

runtime/doc/starting.txt

@@ -1,4 +1,4 @@
-*starting.txt*  For Vim version 7.4.  Last change: 2016 Feb 27
+*starting.txt*  For Vim version 7.4.  Last change: 2016 Mar 03
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -833,6 +833,8 @@ accordingly.  Vim proceeds in this order:
 	-  The user exrc file(s).  Same as for the user vimrc file, but with
 	   "vimrc" replaced by "exrc".  But only one of ".exrc" and "_exrc" is
 	   used, depending on the system.  And without the (*)!
+	-  You would usually have "syntax on" and/or "filetype on" commands,
+	   which trigger initializing filetype detection, see |syntax-loading|.
 
      d. 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,

runtime/doc/tags

@@ -2465,8 +2465,6 @@ $VIM_POSIX	vi_diff.txt	/*$VIM_POSIX*
 :lo	starting.txt	/*:lo*
 :loadk	mbyte.txt	/*:loadk*
 :loadkeymap	mbyte.txt	/*:loadkeymap*
-:loadp	repeat.txt	/*:loadp*
-:loadplugin	repeat.txt	/*:loadplugin*
 :loadview	starting.txt	/*:loadview*
 :loc	motion.txt	/*:loc*
 :lockmarks	motion.txt	/*:lockmarks*
@@ -2643,6 +2641,8 @@ $VIM_POSIX	vi_diff.txt	/*$VIM_POSIX*
 :ounmenu	gui.txt	/*:ounmenu*
 :ownsyntax	syntax.txt	/*:ownsyntax*
 :p	various.txt	/*:p*
+:pa	repeat.txt	/*:pa*
+:packadd	repeat.txt	/*:packadd*
 :pc	windows.txt	/*:pc*
 :pclose	windows.txt	/*:pclose*
 :pe	if_perl.txt	/*:pe*
@@ -4487,8 +4487,10 @@ E911	eval.txt	/*E911*
 E912	eval.txt	/*E912*
 E913	eval.txt	/*E913*
 E914	eval.txt	/*E914*
+E915	channel.txt	/*E915*
 E916	eval.txt	/*E916*
 E917	eval.txt	/*E917*
+E918	channel.txt	/*E918*
 E92	message.txt	/*E92*
 E93	windows.txt	/*E93*
 E94	windows.txt	/*E94*
@@ -7001,7 +7003,6 @@ list-repeat	windows.txt	/*list-repeat*
 lite.vim	syntax.txt	/*lite.vim*
 literal-string	eval.txt	/*literal-string*
 lnum-variable	eval.txt	/*lnum-variable*
-load-plugin	repeat.txt	/*load-plugin*
 load-plugins	starting.txt	/*load-plugins*
 load-vim-script	repeat.txt	/*load-vim-script*
 local-additions	help.txt	/*local-additions*
@@ -7667,6 +7668,7 @@ other-features	vi_diff.txt	/*other-features*
 out-cb	channel.txt	/*out-cb*
 out-timeout	channel.txt	/*out-timeout*
 p	change.txt	/*p*
+pack-add	repeat.txt	/*pack-add*
 packages	repeat.txt	/*packages*
 page-down	intro.txt	/*page-down*
 page-up	intro.txt	/*page-up*