--- 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 @@ output from the job, also  while editing
 
 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 @@ See |CTRL-W| for more commands.
 
 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 @@ the job.  For example:
 	'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 @@ See option 'termsize' for controlling th
 
 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 @@ Syntax ~
 			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 @@ terminal.  |term_setsize()| can be used 
 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 ~