patch 8.0.0896: cannot close a terminal window when the job ends
Problem: Cannot automaticlaly close a terminal window when the job ends.
Solution: Add the ++close argument to :term. Add the term_finish option to
term_start(). (Yasuhiro Matsumoto, closes #1950) Also add
++open.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 5c10562..a98958b 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -8054,9 +8054,14 @@
connected to the terminal. When I/O is connected to the
terminal then the callback function for that part is not used.
- There is one extra option:
- "term_name" name to use for the buffer name, instead of
- the command name.
+ There are two extra options:
+ "term_name" name to use for the buffer name, instead
+ of the command name.
+ "term_finish" What todo 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|.
{only available when compiled with the |+terminal| feature}
term_wait({buf} [, {time}]) *term_wait()*
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 6a1285f..14dab9d 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -1,4 +1,4 @@
-*terminal.txt* For Vim version 8.0. Last change: 2017 Aug 05
+*terminal.txt* For Vim version 8.0. Last change: 2017 Aug 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -36,7 +36,7 @@
Typing ~
-When the keyboard focus is in the terminal window, typed keys will be send to
+When the keyboard focus is in the terminal window, typed keys will be sent to
the job. This uses a pty when possible. You can click outside of the
terminal window to move keyboard focus elsewhere.
@@ -47,7 +47,8 @@
Special in the terminal window: *CTRL-W_.* *CTRL-W_N*
CTRL-W . send a CTRL-W to the job in the terminal
- CTRL-W N go to Terminal Normal mode, see |Terminal-mode|
+ CTRL-W N go to Terminal-Normal mode, see |Terminal-mode|
+ CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode|
CTRL-W " {reg} paste register {reg} *CTRL-W_quote*
Also works with the = register to insert the result of
evaluating an expression.
@@ -62,10 +63,8 @@
'termkey' N go to terminal Normal mode, see below
'termkey' CTRL-N same as CTRL-W N
*t_CTRL-\_CTRL-N*
-The special key combination CTRL-\ CTRL-N can be used to prefix one Normal
-mode command. This is especially useful for remote commands, when you don't
-know whether Vim currently has focus in a terminal window. Note that only one
-Normal mode command can be used.
+The special key combination CTRL-\ CTRL-N can be used to switch to Normal
+mode, just like this works in any other mode.
Size ~
@@ -76,7 +75,7 @@
Syntax ~
-:ter[minal] [command] *:ter* *:terminal*
+:[range]ter[minal] [options] [command] *:ter* *:terminal*
Open a new terminal window.
If [command] is provided run it as a job and connect
@@ -86,9 +85,27 @@
A new buffer will be created, using [command] or
'shell' as the name, prefixed with a "!". If a buffer
by this name already exists a number is added in
- parenthesis. E.g. if "gdb" exists the second terminal
+ parentheses. E.g. if "gdb" exists the second terminal
buffer will use "!gdb (1)".
+ If [range] is given it is used for the terminal size.
+ One number specifies the number of rows. Unless the
+ "vertical" modifier is used, then it is the number of
+ columns.
+
+ Two comma separated numbers are used as "rows,cols".
+ E.g. `:24,80gdb` opens a terminal with 24 rows and 80
+ columns. However, if the terminal window spans the
+ Vim window with, there is no vertical split, the Vim
+ window width is used.
+ *term++close* *term++open*
+ Supported [options] are:
+ ++close The terminal window will close
+ automatically when the job terminates.
+ ++open When the job terminates and no window
+ show it, a window will be opened.
+ Note that this can be interruptive.
+
When the buffer associated with the terminal is wiped out the job is killed,
similar to calling `job_stop(job, "kill")`
@@ -133,23 +150,26 @@
not when 'termsize' is "rowsXcols".
-Terminal Normal mode ~
+Terminal-Job and Terminal-Normal mode ~
*Terminal-mode*
When the job is running the contents of the terminal is under control of the
-job. That includes the cursor position. The terminal contents can change at
-any time.
+job. That includes the cursor position. Typed keys are sent to the job.
+The terminal contents can change at any time. This is called Terminal-Job
+mode.
-Use CTRL-W N (or 'termkey' N) to go to Terminal Normal mode. Now the contents
-of the terminal window is under control of Vim, the job output is suspended.
+Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the
+contents of the terminal window is under control of Vim, the job output is
+suspended. CTRL-\ CTRL-N does the same.
*E946*
-In this mode you can move the cursor around with the usual Vim commands,
-Visually mark text, yank text, etc. But you cannot change the contents of the
-buffer. The commands that would start insert mode, such as 'i' and 'a',
-return control of the window to the job. Any pending output will now be
-displayed.
+In Terminal-Normal mode you can move the cursor around with the usual Vim
+commands, Visually mark text, yank text, etc. But you cannot change the
+contents of the buffer. The commands that would start insert mode, such as
+'i' and 'a', return to Terminal-Job mode. The window will be updated to show
+the contents of the terminal.
-In Terminal mode the statusline and window title show "(Terminal)". If the
-job ends while in Terminal mode this changes to "(Terminal-finished)".
+In Terminal-Normal mode the statusline and window title show "(Terminal)". If
+the job ends while in Terminal-Normal mode this changes to
+"(Terminal-finished)".
Unix ~