diff runtime/doc/eval.txt @ 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 cb0ca75f0c26
children 8a095d343c59
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