doc: *Terminal-mode* #6757

Closes #6756

runtime/doc/intro.txt

@@ -489,7 +489,7 @@ examples and use them directly.  Or type them literally, including the '<' and
 ==============================================================================
 5. Modes, introduction				*vim-modes-intro* *vim-modes*
 
-Vim has six BASIC modes:
+Vim has seven BASIC modes:
 
 					*Normal* *Normal-mode* *command-mode*
 Normal mode		In Normal mode you can enter all the normal editor
@@ -525,6 +525,13 @@ Ex mode			Like Command-line mode, but after entering a command
 			you remain in Ex mode.  Very limited editing of the
 			command line.  |Ex-mode|
 
+							*Terminal-mode*
+Terminal mode		In Terminal mode all input (except |c_CTRL-\_CTRL-N|)
+			is sent to the process running in the current
+			|terminal| buffer.
+			If the 'showmode' option is on "-- TERMINAL --" is shown
+			at the bottom of the window.
+
 There are six ADDITIONAL modes.  These are variants of the BASIC modes:
 
 				*Operator-pending* *Operator-pending-mode*

runtime/doc/nvim_terminal_emulator.txt

@@ -5,6 +5,7 @@
 
 
 Terminal emulator					   *terminal-emulator*
+							     *terminal-buffer*
 
 Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is
 presented as a special buffer type, asynchronously updated from the virtual
@@ -43,7 +44,7 @@ restarting the {cmd} when the session is loaded.
 ==============================================================================
 Input						     *terminal-emulator-input*
 
-To send input, enter terminal-mode using any command that would enter "insert
+To send input, enter |Terminal-mode| using any command that would enter "insert
 mode" in a normal buffer, such as |i| or |:startinsert|. In this mode all keys
 except <C-\><C-N> are sent to the underlying program. Use <C-\><C-N> to return
 to normal-mode. |CTRL-\_CTRL-N|

runtime/doc/various.txt

@@ -208,15 +208,20 @@ g8			Print the hex values of the bytes used in the
 :sh[ell]		Removed. |vim-differences| {Nvim}
 
 						  *:terminal* *:te*
-:te[rminal][!] {cmd}	Execute {cmd} with 'shell' in a |terminal-emulator|
-                        buffer.  Equivalent to: >
+:te[rminal][!] [{cmd}]	Execute {cmd} with 'shell' in a new |terminal| buffer.
+			Equivalent to: >
 			      :enew
 			      :call termopen('{cmd}')
 			      :startinsert
 <
-                        See |jobstart()|.
+			See |termopen()|.
 
-			To enter terminal mode automatically: >
+			Without {cmd}, start an interactive shell.
+
+			Creating the terminal buffer fails when changes have been
+			made to the current buffer, unless 'hidden' is set.
+
+			To enter |Terminal-mode| automatically: >
 			      autocmd BufEnter term://* startinsert
 			      autocmd BufLeave term://* stopinsert
 <