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.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 02c4491..24253d1 100644
--- 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 @@
{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_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 @@
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 @@
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