changeset 17259:6dbb9b3c53e2 v8.1.1629

patch 8.1.1629: terminal function help is in the wrong file commit https://github.com/vim/vim/commit/6bf2c6264b5ebbe4981751840c5a8b69da08e744 Author: Bram Moolenaar <Bram@vim.org> Date: Thu Jul 4 17:12:09 2019 +0200 patch 8.1.1629: terminal function help is in the wrong file Problem: Terminal function help is in the wrong file. Solution: Move the function details to terminal.txt.
author Bram Moolenaar <Bram@vim.org>
date Thu, 04 Jul 2019 17:15:07 +0200
parents 078f4bb5e612
children 9d5a97ea1871
files runtime/doc/eval.txt runtime/doc/terminal.txt src/version.c
diffstat 3 files changed, 412 insertions(+), 402 deletions(-) [+]
line wrap: on
line diff
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 8.1.  Last change: 2019 Jun 22
+*eval.txt*	For Vim version 8.1.  Last change: 2019 Jul 04
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -8172,8 +8172,9 @@ setbufline({expr}, {lnum}, {text})			*se
 		{lnum} is used like with |setline()|.
 		This works like |setline()| for the specified buffer.
 
-		When {expr} is not a valid buffer or {lnum} is not valid then
-		1 is returned.  On success 0 is returned.
+		When {expr} is not a valid buffer, the buffer is not loaded or
+		{lnum} is not valid then 1 is returned.  On success 0 is
+		returned.
 
 setbufvar({expr}, {varname}, {val})			*setbufvar()*
 		Set option or local variable {varname} in buffer {expr} to
@@ -8734,9 +8735,9 @@ sign_jump({id}, {group}, {expr})
 <
 							*sign_place()*
 sign_place({id}, {group}, {name}, {expr} [, {dict}])
-		Place the sign defined as {name} at line {lnum} in file {expr}
-		and assign {id} and {group} to sign.  This is similar to the
-		|:sign-place| command.
+		Place the sign defined as {name} at line {lnum} in file or
+		buffer {expr} and assign {id} and {group} to sign.  This is
+		similar to the |:sign-place| command.
 
 		If the sign identifier {id} is zero, then a new identifier is
 		allocated.  Otherwise the specified number is used. {group} is
@@ -8750,9 +8751,9 @@ sign_place({id}, {group}, {name}, {expr}
 		values, see |bufname()|.
 
 		The optional {dict} argument supports the following entries:
-			lnum		line number in the buffer {expr} where
-					the sign is to be placed. For the
-					accepted values, see |line()|.
+			lnum		line number in the file or buffer
+					{expr} where the sign is to be placed.
+					For the accepted values, see |line()|.
 			priority	priority of the sign. See
 					|sign-priority| for more information.
 
@@ -9677,364 +9678,7 @@ tempname()					*tempname()* *temp-file-n
 		For MS-Windows forward slashes are used when the 'shellslash'
 		option is set or when 'shellcmdflag' starts with '-'.
 
-							*term_dumpdiff()*
-term_dumpdiff({filename}, {filename} [, {options}])
-		Open a new window displaying the difference between the two
-		files.  The files must have been created with
-		|term_dumpwrite()|.
-		Returns the buffer number or zero when the diff fails.
-		Also see |terminal-diff|.
-		NOTE: this does not work with double-width characters yet.
-
-		The top part of the buffer contains the contents of the first
-		file, the bottom part of the buffer contains the contents of
-		the second file.  The middle part shows the differences.
-		The parts are separated by a line of equals.
-
-		If the {options} argument is present, it must be a Dict with
-		these possible members:
-		   "term_name"	     name to use for the buffer name, instead
-				     of the first file name.
-		   "term_rows"	     vertical size to use for the terminal,
-				     instead of using 'termwinsize'
-		   "term_cols"	     horizontal size to use for the terminal,
-				     instead of using 'termwinsize'
-		   "vertical"	     split the window vertically
-		   "curwin"	     use the current window, do not split the
-				     window; fails if the current buffer
-				     cannot be |abandon|ed
-		   "bufnr"	     do not create a new buffer, use the
-				     existing buffer "bufnr".  This buffer
-				     must have been previously created with
-				     term_dumpdiff() or term_dumpload() and
-				     visible in a window.
-		   "norestore"	     do not add the terminal window to a
-				     session file
-
-		Each character in the middle part indicates a difference. If
-		there are multiple differences only the first in this list is
-		used:
-			X	different character
-			w	different width
-			f	different foreground color
-			b	different background color
-			a	different attribute
-			+	missing position in first file
-			-	missing position in second file
-
-		Using the "s" key the top and bottom parts are swapped.  This
-		makes it easy to spot a difference.
-
-							*term_dumpload()*
-term_dumpload({filename} [, {options}])
-		Open a new window displaying the contents of {filename}
-		The file must have been created with |term_dumpwrite()|.
-		Returns the buffer number or zero when it fails.
-		Also see |terminal-diff|.
-
-		For {options} see |term_dumpdiff()|.
-
-							*term_dumpwrite()*
-term_dumpwrite({buf}, {filename} [, {options}])
-		Dump the contents of the terminal screen of {buf} in the file
-		{filename}.  This uses a format that can be used with
-		|term_dumpload()| and |term_dumpdiff()|.
-		If the job in the terminal already finished an error is given:
-		*E958*
-		If {filename} already exists an error is given:	*E953*
-		Also see |terminal-diff|.
-
-		{options} is a dictionary with these optional entries:
-			"rows"		maximum number of rows to dump
-			"columns"	maximum number of columns to dump
-
-term_getaltscreen({buf})				*term_getaltscreen()*
-		Returns 1 if the terminal of {buf} is using the alternate
-		screen.
-		{buf} is used as with |term_getsize()|.
-		{only available when compiled with the |+terminal| feature}
-
-term_getansicolors({buf})				*term_getansicolors()*
-		Get the ANSI color palette in use by terminal {buf}.
-		Returns a List of length 16 where each element is a String
-		representing a color in hexadecimal "#rrggbb" format.
-		Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
-		If neither was used returns the default colors.
-
-		{buf} is used as with |term_getsize()|.  If the buffer does not
-		exist or is not a terminal window, an empty list is returned.
-		{only available when compiled with the |+terminal| feature and
-		with GUI enabled and/or the |+termguicolors| feature}
-
-term_getattr({attr}, {what})				*term_getattr()*
-		Given {attr}, a value returned by term_scrape() in the "attr"
-		item, return whether {what} is on.  {what} can be one of:
-			bold
-			italic
-			underline
-			strike
-			reverse
-		{only available when compiled with the |+terminal| feature}
-
-term_getcursor({buf})					*term_getcursor()*
-		Get the cursor position of terminal {buf}. Returns a list with
-		two numbers and a dictionary: [row, col, dict].
-
-		"row" and "col" are one based, the first screen cell is row
-		1, column 1.  This is the cursor position of the terminal
-		itself, not of the Vim window.
-
-		"dict" can have these members:
-		   "visible"	one when the cursor is visible, zero when it
-				is hidden.
-		   "blink"	one when the cursor is blinking, zero when it
-				is not blinking.
-		   "shape"	1 for a block cursor, 2 for underline and 3
-				for a vertical bar.
-		   "color"	color of the cursor, e.g. "green"
-
-		{buf} must be the buffer number of a terminal window. If the
-		buffer does not exist or is not a terminal window, an empty
-		list is returned.
-		{only available when compiled with the |+terminal| feature}
-
-term_getjob({buf})					*term_getjob()*
-		Get the Job associated with terminal window {buf}.
-		{buf} is used as with |term_getsize()|.
-		Returns |v:null| when there is no job.
-		{only available when compiled with the |+terminal| feature}
-
-term_getline({buf}, {row})				*term_getline()*
-		Get a line of text from the terminal window of {buf}.
-		{buf} is used as with |term_getsize()|.
-
-		The first line has {row} one.  When {row} is "." the cursor
-		line is used.  When {row} is invalid an empty string is
-		returned.
-
-		To get attributes of each character use |term_scrape()|.
-		{only available when compiled with the |+terminal| feature}
-
-term_getscrolled({buf})					*term_getscrolled()*
-		Return the number of lines that scrolled to above the top of
-		terminal {buf}.  This is the offset between the row number
-		used for |term_getline()| and |getline()|, so that: >
-			term_getline(buf, N)
-<		is equal to: >
-			getline(N + term_getscrolled(buf))
-<		(if that line exists).
-
-		{buf} is used as with |term_getsize()|.
-		{only available when compiled with the |+terminal| feature}
-
-term_getsize({buf})					*term_getsize()*
-		Get the size of terminal {buf}. Returns a list with two
-		numbers: [rows, cols].  This is the size of the terminal, not
-		the window containing the terminal.
-
-		{buf} must be the buffer number of a terminal window.  Use an
-		empty string for the current buffer.  If the buffer does not
-		exist or is not a terminal window, an empty list is returned.
-		{only available when compiled with the |+terminal| feature}
-
-term_getstatus({buf})					*term_getstatus()*
-		Get the status of terminal {buf}. This returns a comma
-		separated list of these items:
-			running		job is running
-			finished	job has finished
-			normal		in Terminal-Normal mode
-		One of "running" or "finished" is always present.
-
-		{buf} must be the buffer number of a terminal window. If the
-		buffer does not exist or is not a terminal window, an empty
-		string is returned.
-		{only available when compiled with the |+terminal| feature}
-
-term_gettitle({buf})					*term_gettitle()*
-		Get the title of terminal {buf}. This is the title that the
-		job in the terminal has set.
-
-		{buf} must be the buffer number of a terminal window. If the
-		buffer does not exist or is not a terminal window, an empty
-		string is returned.
-		{only available when compiled with the |+terminal| feature}
-
-term_gettty({buf} [, {input}])				*term_gettty()*
-		Get the name of the controlling terminal associated with
-		terminal window {buf}.  {buf} is used as with |term_getsize()|.
-
-		When {input} is omitted or 0, return the name for writing
-		(stdout). When {input} is 1 return the name for reading
-		(stdin). On UNIX, both return same name.
-		{only available when compiled with the |+terminal| feature}
-
-term_list()						*term_list()*
-		Return a list with the buffer numbers of all buffers for
-		terminal windows.
-		{only available when compiled with the |+terminal| feature}
-
-term_scrape({buf}, {row})				*term_scrape()*
-		Get the contents of {row} of terminal screen of {buf}.
-		For {buf} see |term_getsize()|.
-
-		The first line has {row} one.  When {row} is "." the cursor
-		line is used.  When {row} is invalid an empty string is
-		returned.
-
-		Return a List containing a Dict for each screen cell:
-		    "chars"	character(s) at the cell
-		    "fg"	foreground color as #rrggbb
-		    "bg"	background color as #rrggbb
-		    "attr"	attributes of the cell, use |term_getattr()|
-				to get the individual flags
-		    "width"	cell width: 1 or 2
-		{only available when compiled with the |+terminal| feature}
-
-term_sendkeys({buf}, {keys})				*term_sendkeys()*
-		Send keystrokes {keys} to terminal {buf}.
-		{buf} is used as with |term_getsize()|.
-
-		{keys} are translated as key sequences. For example, "\<c-x>"
-		means the character CTRL-X.
-		{only available when compiled with the |+terminal| feature}
-
-term_setansicolors({buf}, {colors})			*term_setansicolors()*
-		Set the ANSI color palette used by terminal {buf}.
-		{colors} must be a List of 16 valid color names or hexadecimal
-		color codes, like those accepted by |highlight-guifg|.
-		Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
-
-		The colors normally are:
-			0    black
-			1    dark red
-			2    dark green
-			3    brown
-			4    dark blue
-			5    dark magenta
-			6    dark cyan
-			7    light grey
-			8    dark grey
-			9    red
-			10   green
-			11   yellow
-			12   blue
-			13   magenta
-			14   cyan
-			15   white
-
-		These colors are used in the GUI and in the terminal when
-		'termguicolors' is set.  When not using GUI colors (GUI mode
-		or 'termguicolors'), the terminal window always uses the 16
-		ANSI colors of the underlying terminal.
-		{only available when compiled with the |+terminal| feature and
-		with GUI enabled and/or the |+termguicolors| feature}
-
-term_setkill({buf}, {how})				*term_setkill()*
-		When exiting Vim or trying to close the terminal window in
-		another way, {how} defines whether the job in the terminal can
-		be stopped.
-		When {how} is empty (the default), the job will not be
-		stopped, trying to exit will result in |E947|.
-		Otherwise, {how} specifies what signal to send to the job.
-		See |job_stop()| for the values.
-
-		After sending the signal Vim will wait for up to a second to
-		check that the job actually stopped.
-
-term_setrestore({buf}, {command})			*term_setrestore()*
-		Set the command to write in a session file to restore the job
-		in this terminal.  The line written in the session file is: >
-			terminal ++curwin ++cols=%d ++rows=%d {command}
-<		Make sure to escape the command properly.
-
-		Use an empty {command} to run 'shell'.
-		Use "NONE" to not restore this window.
-		{only available when compiled with the |+terminal| feature}
-
-term_setsize({buf}, {rows}, {cols})		*term_setsize()* *E955*
-		Set the size of terminal {buf}. The size of the window
-		containing the terminal will also be adjusted, if possible.
-		If {rows} or {cols} is zero or negative, that dimension is not
-		changed.
-
-		{buf} must be the buffer number of a terminal window.  Use an
-		empty string for the current buffer.  If the buffer does not
-		exist or is not a terminal window, an error is given.
-		{only available when compiled with the |+terminal| feature}
-
-term_start({cmd} [, {options}])			*term_start()*
-		Open a terminal window and run {cmd} in it.
-
-		{cmd} can be a string or a List, like with |job_start()|. The
-		string "NONE" can be used to open a terminal window without
-		starting a job, the pty of the terminal can be used by a
-		command like gdb.
-
-		Returns the buffer number of the terminal window.  If {cmd}
-		cannot be executed the window does open and shows an error
-		message.
-		If opening the window fails zero is returned.
-
-		{options} are similar to what is used for |job_start()|, see
-		|job-options|.  However, not all options can be used.  These
-		are supported:
-		   all timeout options
-		   "stoponexit", "cwd", "env"
-		   "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"
-		   "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
-		However, at least one of stdin, stdout or stderr must be
-		connected to the terminal.  When I/O is connected to the
-		terminal then the callback function for that part is not used.
-
-		There are extra options:
-		   "term_name"	     name to use for the buffer name, instead
-				     of the command name.
-		   "term_rows"	     vertical size to use for the terminal,
-				     instead of using 'termwinsize'
-		   "term_cols"	     horizontal size to use for the terminal,
-				     instead of using 'termwinsize'
-		   "vertical"	     split the window vertically; note that
-				     other window position can be defined with
-				     command modifiers, such as |:belowright|.
-		   "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
-		   "norestore"	     do not add the terminal window to a
-				     session file
-		   "term_kill"	     what to do when trying to close the
-				     terminal window, see |term_setkill()|
-		   "term_finish"     What to do when the job is finished:
-					"close": close any windows
-					"open": open window if needed
-				     Note that "open" can be interruptive.
-				     See |term++close| and |term++open|.
-		   "term_opencmd"    command to use for opening the window when
-				     "open" is used for "term_finish"; must
-				     have "%d" where the buffer number goes,
-				     e.g. "10split|buffer %d"; when not
-				     specified "botright sbuf %d" is used
-		   "eof_chars"	     Text to send after all buffer lines were
-				     written to the terminal.  When not set
-				     CTRL-D is used on MS-Windows. For Python
-				     use CTRL-Z or "exit()". For a shell use
-				     "exit".  A CR is always added.
-		   "ansi_colors"     A list of 16 color names or hex codes
-				     defining the ANSI palette used in GUI
-				     color modes.  See |g:terminal_ansi_colors|.
-		   "tty_type"	     (MS-Windows only): Specify which pty to
-				     use.  See 'termwintype' for the values.
-
-		{only available when compiled with the |+terminal| feature}
-
-term_wait({buf} [, {time}])					*term_wait()*
-		Wait for pending updates of {buf} to be handled.
-		{buf} is used as with |term_getsize()|.
-		{time} is how long to wait for updates to arrive in msec.  If
-		not set then 10 msec will be used.
-		{only available when compiled with the |+terminal| feature}
+term_ functions are documented here: |terminal-function-details|
 
 test_alloc_fail({id}, {countdown}, {repeat})		*test_alloc_fail()*
 		This is for testing: If the memory allocation with {id} is
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -1,4 +1,4 @@
-*terminal.txt*	For Vim version 8.1.  Last change: 2019 May 29
+*terminal.txt*	For Vim version 8.1.  Last change: 2019 Jul 04
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -12,35 +12,36 @@ The terminal feature is optional, use th
 If the result is "1" you have it.
 
 
-1. Basic use			|terminal-use|
-      Typing				|terminal-typing|
-      Size and color			|terminal-size-color|
-      Syntax				|:terminal|
-      Resizing				|terminal-resizing|
-      Terminal Modes			|Terminal-mode|
-      Cursor style			|terminal-cursor-style|
-      Session				|terminal-session|
-      Special keys			|terminal-special-keys|
-      Unix				|terminal-unix|
-      MS-Windows			|terminal-ms-windows|
-2. Terminal communication	|terminal-communication|
-      Vim to job: term_sendkeys()	|terminal-to-job|
-      Job to Vim: JSON API		|terminal-api|
-      Using the client-server feature	|terminal-client-server|
-3. Remote testing		|terminal-testing|
-4. Diffing screen dumps		|terminal-diff|
-      Writing a screen dump test for Vim  |terminal-dumptest|
-      Creating a screen dump		  |terminal-screendump|
-      Comparing screen dumps		  |terminal-diffscreendump|
-5. Debugging			|terminal-debug|
-      Starting				|termdebug-starting|
-      Example session			|termdebug-example|
-      Stepping through code		|termdebug-stepping|
-      Inspecting variables		|termdebug-variables|
-      Other commands			|termdebug-commands|
-      Prompt mode			|termdebug-prompt|
-      Communication			|termdebug-communication|
-      Customizing			|termdebug-customizing|
+1. Basic use				|terminal-use|
+      Typing					|terminal-typing|
+      Size and color				|terminal-size-color|
+      Command syntax				|:terminal|
+      Resizing					|terminal-resizing|
+      Terminal Modes				|Terminal-mode|
+      Cursor style				|terminal-cursor-style|
+      Session					|terminal-session|
+      Special keys				|terminal-special-keys|
+      Unix					|terminal-unix|
+      MS-Windows				|terminal-ms-windows|
+2. Terminal functions			|terminal-function-details|
+3. Terminal communication		|terminal-communication|
+      Vim to job: term_sendkeys()		|terminal-to-job|
+      Job to Vim: JSON API			|terminal-api|
+      Using the client-server feature		|terminal-client-server|
+4. Remote testing			|terminal-testing|
+5. Diffing screen dumps			|terminal-diff|
+      Writing a screen dump test for Vim  	|terminal-dumptest|
+      Creating a screen dump		  	|terminal-screendump|
+      Comparing screen dumps		  	|terminal-diffscreendump|
+6. Debugging				|terminal-debug|
+      Starting					|termdebug-starting|
+      Example session				|termdebug-example|
+      Stepping through code			|termdebug-stepping|
+      Inspecting variables			|termdebug-variables|
+      Other commands				|termdebug-commands|
+      Prompt mode				|termdebug-prompt|
+      Communication				|termdebug-communication|
+      Customizing				|termdebug-customizing|
 
 {only available when compiled with the |+terminal| feature}
 The terminal feature requires the |+job| and |+channel| features.
@@ -159,7 +160,7 @@ The |term_setansicolors()| function can 
 |term_getansicolors()| to get the currently used colors.
 
 
-Syntax ~
+Command syntax ~
 
 :[range]ter[minal] [options] [command]			*:ter* *:terminal*
 			Open a new terminal window.
@@ -426,8 +427,371 @@ ConPTY problems have been fixed "winpty"
 Environment variables are used to pass information to the running job:
     VIM_SERVERNAME	v:servername
 
+
 ==============================================================================
-2. Terminal communication			 *terminal-communication*
+2. Terminal functions				 *terminal-function-details*
+
+							*term_dumpdiff()*
+term_dumpdiff({filename}, {filename} [, {options}])
+		Open a new window displaying the difference between the two
+		files.  The files must have been created with
+		|term_dumpwrite()|.
+		Returns the buffer number or zero when the diff fails.
+		Also see |terminal-diff|.
+		NOTE: this does not work with double-width characters yet.
+
+		The top part of the buffer contains the contents of the first
+		file, the bottom part of the buffer contains the contents of
+		the second file.  The middle part shows the differences.
+		The parts are separated by a line of equals.
+
+		If the {options} argument is present, it must be a Dict with
+		these possible members:
+		   "term_name"	     name to use for the buffer name, instead
+				     of the first file name.
+		   "term_rows"	     vertical size to use for the terminal,
+				     instead of using 'termwinsize'
+		   "term_cols"	     horizontal size to use for the terminal,
+				     instead of using 'termwinsize'
+		   "vertical"	     split the window vertically
+		   "curwin"	     use the current window, do not split the
+				     window; fails if the current buffer
+				     cannot be |abandon|ed
+		   "bufnr"	     do not create a new buffer, use the
+				     existing buffer "bufnr".  This buffer
+				     must have been previously created with
+				     term_dumpdiff() or term_dumpload() and
+				     visible in a window.
+		   "norestore"	     do not add the terminal window to a
+				     session file
+
+		Each character in the middle part indicates a difference. If
+		there are multiple differences only the first in this list is
+		used:
+			X	different character
+			w	different width
+			f	different foreground color
+			b	different background color
+			a	different attribute
+			+	missing position in first file
+			-	missing position in second file
+
+		Using the "s" key the top and bottom parts are swapped.  This
+		makes it easy to spot a difference.
+
+							*term_dumpload()*
+term_dumpload({filename} [, {options}])
+		Open a new window displaying the contents of {filename}
+		The file must have been created with |term_dumpwrite()|.
+		Returns the buffer number or zero when it fails.
+		Also see |terminal-diff|.
+
+		For {options} see |term_dumpdiff()|.
+
+							*term_dumpwrite()*
+term_dumpwrite({buf}, {filename} [, {options}])
+		Dump the contents of the terminal screen of {buf} in the file
+		{filename}.  This uses a format that can be used with
+		|term_dumpload()| and |term_dumpdiff()|.
+		If the job in the terminal already finished an error is given:
+		*E958*
+		If {filename} already exists an error is given:	*E953*
+		Also see |terminal-diff|.
+
+		{options} is a dictionary with these optional entries:
+			"rows"		maximum number of rows to dump
+			"columns"	maximum number of columns to dump
+
+term_getaltscreen({buf})				*term_getaltscreen()*
+		Returns 1 if the terminal of {buf} is using the alternate
+		screen.
+		{buf} is used as with |term_getsize()|.
+		{only available when compiled with the |+terminal| feature}
+
+term_getansicolors({buf})				*term_getansicolors()*
+		Get the ANSI color palette in use by terminal {buf}.
+		Returns a List of length 16 where each element is a String
+		representing a color in hexadecimal "#rrggbb" format.
+		Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
+		If neither was used returns the default colors.
+
+		{buf} is used as with |term_getsize()|.  If the buffer does not
+		exist or is not a terminal window, an empty list is returned.
+		{only available when compiled with the |+terminal| feature and
+		with GUI enabled and/or the |+termguicolors| feature}
+
+term_getattr({attr}, {what})				*term_getattr()*
+		Given {attr}, a value returned by term_scrape() in the "attr"
+		item, return whether {what} is on.  {what} can be one of:
+			bold
+			italic
+			underline
+			strike
+			reverse
+		{only available when compiled with the |+terminal| feature}
+
+term_getcursor({buf})					*term_getcursor()*
+		Get the cursor position of terminal {buf}. Returns a list with
+		two numbers and a dictionary: [row, col, dict].
+
+		"row" and "col" are one based, the first screen cell is row
+		1, column 1.  This is the cursor position of the terminal
+		itself, not of the Vim window.
+
+		"dict" can have these members:
+		   "visible"	one when the cursor is visible, zero when it
+				is hidden.
+		   "blink"	one when the cursor is blinking, zero when it
+				is not blinking.
+		   "shape"	1 for a block cursor, 2 for underline and 3
+				for a vertical bar.
+		   "color"	color of the cursor, e.g. "green"
+
+		{buf} must be the buffer number of a terminal window. If the
+		buffer does not exist or is not a terminal window, an empty
+		list is returned.
+		{only available when compiled with the |+terminal| feature}
+
+term_getjob({buf})					*term_getjob()*
+		Get the Job associated with terminal window {buf}.
+		{buf} is used as with |term_getsize()|.
+		Returns |v:null| when there is no job.
+		{only available when compiled with the |+terminal| feature}
+
+term_getline({buf}, {row})				*term_getline()*
+		Get a line of text from the terminal window of {buf}.
+		{buf} is used as with |term_getsize()|.
+
+		The first line has {row} one.  When {row} is "." the cursor
+		line is used.  When {row} is invalid an empty string is
+		returned.
+
+		To get attributes of each character use |term_scrape()|.
+		{only available when compiled with the |+terminal| feature}
+
+term_getscrolled({buf})					*term_getscrolled()*
+		Return the number of lines that scrolled to above the top of
+		terminal {buf}.  This is the offset between the row number
+		used for |term_getline()| and |getline()|, so that: >
+			term_getline(buf, N)
+<		is equal to: >
+			getline(N + term_getscrolled(buf))
+<		(if that line exists).
+
+		{buf} is used as with |term_getsize()|.
+		{only available when compiled with the |+terminal| feature}
+
+term_getsize({buf})					*term_getsize()*
+		Get the size of terminal {buf}. Returns a list with two
+		numbers: [rows, cols].  This is the size of the terminal, not
+		the window containing the terminal.
+
+		{buf} must be the buffer number of a terminal window.  Use an
+		empty string for the current buffer.  If the buffer does not
+		exist or is not a terminal window, an empty list is returned.
+		{only available when compiled with the |+terminal| feature}
+
+term_getstatus({buf})					*term_getstatus()*
+		Get the status of terminal {buf}. This returns a comma
+		separated list of these items:
+			running		job is running
+			finished	job has finished
+			normal		in Terminal-Normal mode
+		One of "running" or "finished" is always present.
+
+		{buf} must be the buffer number of a terminal window. If the
+		buffer does not exist or is not a terminal window, an empty
+		string is returned.
+		{only available when compiled with the |+terminal| feature}
+
+term_gettitle({buf})					*term_gettitle()*
+		Get the title of terminal {buf}. This is the title that the
+		job in the terminal has set.
+
+		{buf} must be the buffer number of a terminal window. If the
+		buffer does not exist or is not a terminal window, an empty
+		string is returned.
+		{only available when compiled with the |+terminal| feature}
+
+term_gettty({buf} [, {input}])				*term_gettty()*
+		Get the name of the controlling terminal associated with
+		terminal window {buf}.  {buf} is used as with |term_getsize()|.
+
+		When {input} is omitted or 0, return the name for writing
+		(stdout). When {input} is 1 return the name for reading
+		(stdin). On UNIX, both return same name.
+		{only available when compiled with the |+terminal| feature}
+
+term_list()						*term_list()*
+		Return a list with the buffer numbers of all buffers for
+		terminal windows.
+		{only available when compiled with the |+terminal| feature}
+
+term_scrape({buf}, {row})				*term_scrape()*
+		Get the contents of {row} of terminal screen of {buf}.
+		For {buf} see |term_getsize()|.
+
+		The first line has {row} one.  When {row} is "." the cursor
+		line is used.  When {row} is invalid an empty string is
+		returned.
+
+		Return a List containing a Dict for each screen cell:
+		    "chars"	character(s) at the cell
+		    "fg"	foreground color as #rrggbb
+		    "bg"	background color as #rrggbb
+		    "attr"	attributes of the cell, use |term_getattr()|
+				to get the individual flags
+		    "width"	cell width: 1 or 2
+		{only available when compiled with the |+terminal| feature}
+
+term_sendkeys({buf}, {keys})				*term_sendkeys()*
+		Send keystrokes {keys} to terminal {buf}.
+		{buf} is used as with |term_getsize()|.
+
+		{keys} are translated as key sequences. For example, "\<c-x>"
+		means the character CTRL-X.
+		{only available when compiled with the |+terminal| feature}
+
+term_setansicolors({buf}, {colors})			*term_setansicolors()*
+		Set the ANSI color palette used by terminal {buf}.
+		{colors} must be a List of 16 valid color names or hexadecimal
+		color codes, like those accepted by |highlight-guifg|.
+		Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
+
+		The colors normally are:
+			0    black
+			1    dark red
+			2    dark green
+			3    brown
+			4    dark blue
+			5    dark magenta
+			6    dark cyan
+			7    light grey
+			8    dark grey
+			9    red
+			10   green
+			11   yellow
+			12   blue
+			13   magenta
+			14   cyan
+			15   white
+
+		These colors are used in the GUI and in the terminal when
+		'termguicolors' is set.  When not using GUI colors (GUI mode
+		or 'termguicolors'), the terminal window always uses the 16
+		ANSI colors of the underlying terminal.
+		{only available when compiled with the |+terminal| feature and
+		with GUI enabled and/or the |+termguicolors| feature}
+
+term_setkill({buf}, {how})				*term_setkill()*
+		When exiting Vim or trying to close the terminal window in
+		another way, {how} defines whether the job in the terminal can
+		be stopped.
+		When {how} is empty (the default), the job will not be
+		stopped, trying to exit will result in |E947|.
+		Otherwise, {how} specifies what signal to send to the job.
+		See |job_stop()| for the values.
+
+		After sending the signal Vim will wait for up to a second to
+		check that the job actually stopped.
+
+term_setrestore({buf}, {command})			*term_setrestore()*
+		Set the command to write in a session file to restore the job
+		in this terminal.  The line written in the session file is: >
+			terminal ++curwin ++cols=%d ++rows=%d {command}
+<		Make sure to escape the command properly.
+
+		Use an empty {command} to run 'shell'.
+		Use "NONE" to not restore this window.
+		{only available when compiled with the |+terminal| feature}
+
+term_setsize({buf}, {rows}, {cols})		*term_setsize()* *E955*
+		Set the size of terminal {buf}. The size of the window
+		containing the terminal will also be adjusted, if possible.
+		If {rows} or {cols} is zero or negative, that dimension is not
+		changed.
+
+		{buf} must be the buffer number of a terminal window.  Use an
+		empty string for the current buffer.  If the buffer does not
+		exist or is not a terminal window, an error is given.
+		{only available when compiled with the |+terminal| feature}
+
+term_start({cmd} [, {options}])			*term_start()*
+		Open a terminal window and run {cmd} in it.
+
+		{cmd} can be a string or a List, like with |job_start()|. The
+		string "NONE" can be used to open a terminal window without
+		starting a job, the pty of the terminal can be used by a
+		command like gdb.
+
+		Returns the buffer number of the terminal window.  If {cmd}
+		cannot be executed the window does open and shows an error
+		message.
+		If opening the window fails zero is returned.
+
+		{options} are similar to what is used for |job_start()|, see
+		|job-options|.  However, not all options can be used.  These
+		are supported:
+		   all timeout options
+		   "stoponexit", "cwd", "env"
+		   "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"
+		   "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
+		However, at least one of stdin, stdout or stderr must be
+		connected to the terminal.  When I/O is connected to the
+		terminal then the callback function for that part is not used.
+
+		There are extra options:
+		   "term_name"	     name to use for the buffer name, instead
+				     of the command name.
+		   "term_rows"	     vertical size to use for the terminal,
+				     instead of using 'termwinsize'
+		   "term_cols"	     horizontal size to use for the terminal,
+				     instead of using 'termwinsize'
+		   "vertical"	     split the window vertically; note that
+				     other window position can be defined with
+				     command modifiers, such as |:belowright|.
+		   "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
+		   "norestore"	     do not add the terminal window to a
+				     session file
+		   "term_kill"	     what to do when trying to close the
+				     terminal window, see |term_setkill()|
+		   "term_finish"     What to do when the job is finished:
+					"close": close any windows
+					"open": open window if needed
+				     Note that "open" can be interruptive.
+				     See |term++close| and |term++open|.
+		   "term_opencmd"    command to use for opening the window when
+				     "open" is used for "term_finish"; must
+				     have "%d" where the buffer number goes,
+				     e.g. "10split|buffer %d"; when not
+				     specified "botright sbuf %d" is used
+		   "eof_chars"	     Text to send after all buffer lines were
+				     written to the terminal.  When not set
+				     CTRL-D is used on MS-Windows. For Python
+				     use CTRL-Z or "exit()". For a shell use
+				     "exit".  A CR is always added.
+		   "ansi_colors"     A list of 16 color names or hex codes
+				     defining the ANSI palette used in GUI
+				     color modes.  See |g:terminal_ansi_colors|.
+		   "tty_type"	     (MS-Windows only): Specify which pty to
+				     use.  See 'termwintype' for the values.
+
+		{only available when compiled with the |+terminal| feature}
+
+term_wait({buf} [, {time}])					*term_wait()*
+		Wait for pending updates of {buf} to be handled.
+		{buf} is used as with |term_getsize()|.
+		{time} is how long to wait for updates to arrive in msec.  If
+		not set then 10 msec will be used.
+		{only available when compiled with the |+terminal| feature}
+
+==============================================================================
+3. Terminal communication			 *terminal-communication*
 
 There are several ways to communicate with the job running in a terminal:
 - Use |term_sendkeys()| to send text and escape sequences from Vim to the job.
@@ -534,7 +898,7 @@ In the job you can then do something lik
 This will open the file "some_file.c" and put the cursor on line 123.
 
 ==============================================================================
-3. Remote testing					*terminal-testing*
+4. Remote testing					*terminal-testing*
 
 Most Vim tests execute a script inside Vim.  For some tests this does not
 work, running the test interferes with the code being tested.  To avoid this
@@ -549,7 +913,7 @@ Functions ~
 
 
 ==============================================================================
-4. Diffing screen dumps					*terminal-diff*
+5. Diffing screen dumps					*terminal-diff*
 
 In some cases it can be bothersome to test that Vim displays the right
 characters on the screen.  E.g. with syntax highlighting.  To make this
@@ -650,7 +1014,7 @@ Alternatively, press "s" to swap the fir
 times so that you can spot the difference in the context of the text.
 
 ==============================================================================
-5. Debugging				*terminal-debug* *terminal-debugger*
+6. Debugging				*terminal-debug* *terminal-debugger*
 
 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
--- a/src/version.c
+++ b/src/version.c
@@ -778,6 +778,8 @@ static char *(features[]) =
 static int included_patches[] =
 {   /* Add new patch number below this line */
 /**/
+    1629,
+/**/
     1628,
 /**/
     1627,