Merge remote-tracking branch 'vim/master'

Author: splhack

runtime/doc/cmdline.txt

@@ -830,6 +830,11 @@ Also see |`=|.
 Note: these are typed literally, they are not special keys!
 	<cword>    is replaced with the word under the cursor (like |star|)
 	<cWORD>    is replaced with the WORD under the cursor (see |WORD|)
+	<cexpr>    is replaced with the word under the cursor, including more
+		   to form a C expression.  E.g., when the cursor is on "arg"
+		   of "ptr->arg" then the result is "ptr->arg"; when the
+		   cursor is on "]" of "list[idx]" then the result is
+		   "list[idx]".  This is used for |v:beval_text|.
 	<cfile>    is replaced with the path name under the cursor (like what
 		   |gf| uses)
 	<afile>    When executing autocommands, is replaced with the file name

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 8.0.  Last change: 2017 Aug 13
+*eval.txt*	For Vim version 8.0.  Last change: 2017 Sep 11
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -1449,7 +1449,7 @@ v:beval_text	The text under or after the mouse pointer.  Usually a word as
 		but a dot and "->" before the position is included.  When on a
 		']' the text before it is used, including the matching '[' and
 		word before it.  When on a Visual area within one line the
-		highlighted text is used.
+		highlighted text is used.  Also see |<cexpr>|.
 		Only valid while evaluating the 'balloonexpr' option.
 
 					*v:beval_winnr* *beval_winnr-variable*
@@ -3301,7 +3301,7 @@ count({comp}, {expr} [, {ic} [, {start}]])			*count()*
 		When {ic} is given and it's |TRUE| then case is ignored.
 
 		When {comp} is a string then the number of not overlapping
-		occurences of {expr} is returned.
+		occurrences of {expr} is returned.
 
 
 							*cscope_connection()*
@@ -3467,7 +3467,7 @@ escape({string}, {chars})				*escape()*
 			:echo escape('c:\program files\vim', ' \')
 <		results in: >
 			c:\\program\ files\\vim
-<		Also see |shellescape()|.
+<		Also see |shellescape()| and |fnameescape()|.
 
 							*eval()*
 eval({string})	Evaluate {string} and return the result.  Especially useful to
@@ -3887,7 +3887,7 @@ float2nr({expr})					*float2nr()*
 		When the value of {expr} is out of range for a |Number| the
 		result is truncated to 0x7fffffff or -0x7fffffff (or when
 		64-bit Number support is enabled, 0x7fffffffffffffff or
-		-0x7fffffffffffffff.  NaN results in -0x80000000 (or when
+		-0x7fffffffffffffff).  NaN results in -0x80000000 (or when
 		64-bit Number support is enabled, -0x8000000000000000).
 		Examples: >
 			echo float2nr(3.95)
@@ -4657,12 +4657,12 @@ getqflist([{what}])					*getqflist()*
 		If "nr" is not present then the current quickfix list is used.
 		If both "nr" and a non-zero "id" are specified, then the list
 		specified by "id" is used.
-		To get the number of lists in the quickfix stack, set 'nr' to
-		'$' in {what}. The 'nr' value in the returned dictionary
+		To get the number of lists in the quickfix stack, set "nr" to
+		"$" in {what}. The "nr" value in the returned dictionary
 		contains the quickfix stack size.
-		When 'text' is specified, all the other items are ignored. The
-		returned dictionary contains the entry 'items' with the list
-		of entries.
+		When "lines" is specified, all the other items except "efm"
+		are ignored.  The returned dictionary contains the entry
+		"items" with the list of entries.
 		In case of error processing {what}, an empty dictionary is
 		returned.
 
@@ -6967,6 +6967,7 @@ setline({lnum}, {text})					*setline()*
 			:for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
 			:  call setline(n, l)
 			:endfor
+
 <		Note: The '[ and '] marks are not set.
 
 setloclist({nr}, {list}[, {action}[, {what}]])		*setloclist()*
@@ -7164,16 +7165,17 @@ setreg({regname}, {value} [, {options}])
 			:call setreg('a', "1\n2\n3", 'b5')
 
 <		This example shows using the functions to save and restore a
-		register (note: you may not reliably restore register value 
-		without using the third argument to |getreg()| as without it 
-		newlines are represented as newlines AND Nul bytes are 
-		represented as newlines as well, see |NL-used-for-Nul|). >
+		register: >
 			:let var_a = getreg('a', 1, 1)
 			:let var_amode = getregtype('a')
 			    ....
 			:call setreg('a', var_a, var_amode)
+<		Note: you may not reliably restore register value 
+		without using the third argument to |getreg()| as without it 
+		newlines are represented as newlines AND Nul bytes are
+		represented as newlines as well, see |NL-used-for-Nul|.
 
-<		You can also change the type of a register by appending
+		You can also change the type of a register by appending
 		nothing: >
 			:call setreg('a', '', 'al')
 
@@ -8145,7 +8147,7 @@ term_start({cmd}, {options})				*term_start()*
 		are supported:
 		   all timeout options
 		   "stoponexit"
-		   "out_cb", "err_cb"
+		   "callback", "out_cb", "err_cb"
 		   "exit_cb", "close_cb"
 		   "in_io", "in_top", "in_bot", "in_name", "in_buf"
 		   "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
@@ -8165,6 +8167,7 @@ term_start({cmd}, {options})				*term_start()*
 		   "curwin"	     use the current window, do not split the
 				     window; fails if the current buffer
 				     cannot be |abandon|ed
+		   "hidden"	     do not open a window
 		   "term_finish"     What to do when the job is finished:
 					"close": close any windows
 					"open": open window if needed
@@ -8562,7 +8565,7 @@ win_getid([{win} [, {tab}]])				*win_getid()*
 		Get the |window-ID| for the specified window.
 		When {win} is missing use the current window.
 		With {win} this is the window number.  The top window has
-		number 1.
+		number 1.  Use `win_getid(winnr())` for the current window.
 		Without {tab} use the current tab, otherwise the tab with
 		number {tab}.  The first tab has number one.
 		Return zero if the window cannot be found.

runtime/doc/map.txt

@@ -1415,6 +1415,8 @@ The valid escape sequences are
 	<line1>	The starting line of the command range.
 						*<line2>*
 	<line2>	The final line of the command range.
+						*<range>*
+	<range> The number of items in the command range: 0, 1 or 2
 						*<count>*
 	<count>	Any count supplied (as described for the '-range'
 		and '-count' attributes).

runtime/doc/quickfix.txt

@@ -44,6 +44,18 @@ From inside Vim an easy way to run a command and handle the output is with the
 The 'errorformat' option should be set to match the error messages from your
 compiler (see |errorformat| below).
 
+							*quickfix-ID*
+Each quickfix list has a unique identifier called the quickfix ID and this
+number will not change within a Vim session. The getqflist() function can be
+used to get the identifier assigned to a list.
+
+							*quickfix-ID*
+Each quickfix list has a unique identifier called the quickfix ID and this
+number will not change within a Vim session. The getqflist() function can be
+used to get the identifier assigned to a list. There is also a quickfix list
+number which may change whenever more than ten lists are added to a quickfix
+stack.
+
 						*location-list* *E776*
 A location list is a window-local quickfix list. You get one after commands
 like `:lvimgrep`, `:lgrep`, `:lhelpgrep`, `:lmake`, etc., which create a

runtime/doc/terminal.txt

@@ -1,4 +1,4 @@
-*terminal.txt*	For Vim version 8.0.  Last change: 2017 Aug 29
+*terminal.txt*	For Vim version 8.0.  Last change: 2017 Sep 10
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -30,11 +30,11 @@ This feature is for running a terminal emulator in a Vim window.  A job can be
 started connected to the terminal emulator. For example, to run a shell: >
      :term bash
 
-Or to run a debugger: >
-     :term gdb vim
+Or to run build command: >
+     :term make myprogram
 
 The job runs asynchronously from Vim, the window will be updated to show
-output from the job, also  while editing in any other window.
+output from the job, also while editing in another window.
 
 
 Typing ~
@@ -109,7 +109,8 @@ Syntax ~
 
 			If [range] is given the specified lines are used as
 			input for the job.  It will not be possible to type
-			keys in the terminal window.
+			keys in the terminal window.  For MS-Windows see the
+			++eof argument below.
 
 			Two comma separated numbers are used as "rows,cols".
 			E.g. `:24,80gdb` opens a terminal with 24 rows and 80
@@ -133,14 +134,15 @@ Syntax ~
 					height.
 			++cols={width}  Use {width} for the terminal window
 					width.
-			++eof={text}	when using [range], text to send after
-					the last line was written. The default
-					is to send CTRL-D.  A CR is appended.
+			++eof={text}	when using [range]: text to send after
+					the last line was written. Cannot
+					contain white space.  A CR is
+					appended.  For MS-Windows the default
+					is to send CTRL-D.
 					E.g. for a shell use "++eof=exit" and
 					for Python "++eof=exit()".  Special
 					codes can be used like with `:map`,
 					e.g. "<C-Z>" for CTRL-Z.
-					{only on MS-Windows}
 
 			If you want to use more options use the |term_start()|
 			function.
@@ -303,33 +305,104 @@ term_scrape()		inspect terminal screen
 3. Debugging					*terminal-debug*
 
 The Terminal debugging plugin can be used to debug a program with gdb and view
-the source code in a Vim window.
+the source code in a Vim window.  Since this is completely contained inside
+Vim this also works remotely over an ssh connection.
+
+
+Starting ~
 
 Load the plugin with this command: >
 	packadd termdebug
-
+<							*:Termdebug*
 To start debugging use `:TermDebug` folowed by the command name, for example: >
 	:TermDebug vim
 
 This opens two windows:
-- A terminal window in which "gdb vim" is executed.  Here you can directly
-  interact with gdb.
-- A terminal window for the executed program.  When "run" is used in gdb the
-  program I/O will happen in this window, so that it does not interfere with
-  controlling gdb.
-The current window is used to show the source code.  When gdb jumps to a
-source file location this window will display the code, if possible.  Values
-of variables can be inspected, breakpoints set and cleared, etc.
+gdb window	A terminal window in which "gdb vim" is executed.  Here you
+		can directly interact with gdb.  The buffer name is "!gdb".
+program window	A terminal window for the executed program.  When "run" is
+		used in gdb the program I/O will happen in this window, so
+		that it does not interfere with controlling gdb.  The buffer
+		name is "gdb program".
+
+The current window is used to show the source code.  When gdb pauses the
+source file location will be displayed, if possible.  A sign is used to
+highlight the current position (using highlight group debugPC).	 
+
+If the buffer in the current window is modified, another window will be opened
+to display the current gdb position.
+
+Focus the terminal of the executed program to interact with it.  This works
+the same as any command running in a terminal window.
+
+When the debugger ends, typically by typing "quit" in the gdb window, the two
+opened windows are closed.
+
+
+Stepping through code ~
+
+Put focus on the gdb window to type commands there.  Some common ones are:
+- CTRL-C    interrupt the program
+- next      execute the current line and stop at the next line
+- step      execute the current line and stop at the next statement, entering
+	    functions
+- finish    execute until leaving the current function
+- where     show the stack
+- frame N   go to the Nth stack frame
+- continue  continue execution
+
+In the window showing the source code some commands can used to control gdb:
+ :Break     set a breakpoint at the current line; a sign will be displayed
+ :Delete    delete a breakpoint at the current line
+ :Step	    execute the gdb "step" command
+ :Over      execute the gdb "next" command (:Next is a Vim command)
+ :Finish    execute the gdb "finish" command
+ :Continue  execute the gdb "continue" command
 
-When the debugger ends the two opened windows are closed.
+
+Inspecting variables ~
+
+ :Evaluate	    evaluate the expression under the cursor
+ K		    same
+ :Evaluate {expr}   evaluate {expr}
+ :'<,'>Evaluate	    evaluate the Visually selected text
+
+This is similar to using "print" in the gdb window.
+
+
+Other commands ~
+
+ :Gdb	       jump to the gdb window
+ :Program      jump to the window with the running program
+
+
+Communication ~
+
+There is another, hidden, buffer, which is used for Vim to communicate with
+gdb.  The buffer name is "gdb communication".  Do not delete this buffer, it
+will break the debugger.
 
 
 Customizing ~
 
-g:debugger	The debugger command.  Default "gdb".
+To change the name of the gdb command, set the "termdebugger" variable before
+invoking `:Termdebug`: >
+	let termdebugger = "mygdb"
+Only debuggers fully compatible with gdb will work.  Vim uses the GDB/MI
+interface.
+
+The color of the signs can be adjusted with these highlight groups:
+- debugPC		the current position
+- debugBreakpoint	a breakpoint
+
+The defaults are, when 'background' is "light":
+  hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
+  hi debugBreakpoint term=reverse ctermbg=red guibg=red
 
+When 'background' is "dark":
+  hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
+  hi debugBreakpoint term=reverse ctermbg=red guibg=red
 
-TODO
 
 
  vim:tw=78:ts=8:ft=help:norl: