terminal: 'scrollback'

Closes #2637

3 files changed, 50 insertions, 77 deletions

diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index f368e28911..0954dcb5a7 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -4,28 +4,19 @@
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
 
-Embedded terminal emulator				   *terminal-emulator*
+Terminal emulator					   *terminal-emulator*
 
-1. Introduction			|terminal-emulator-intro|
-2. Spawning			|terminal-emulator-spawning|
-3. Input			|terminal-emulator-input|
-4. Configuration		|terminal-emulator-configuration|
-5. Status Variables		|terminal-emulator-status|
+Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is
+presented as a special buffer type, asynchronously updated from the virtual
+terminal as data is received from the program connected to it.
 
-==============================================================================
-1. Introduction					     *terminal-emulator-intro*
-
-Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is
-presented as a special buffer type, asynchronously updated to mirror the
-virtual terminal display as data is received from the program connected to it.
-For most purposes, terminal buffers behave a lot like normal buffers with
-'nomodifiable' set.
-
-The implementation is powered by libvterm, a powerful abstract terminal
-emulation library. http://www.leonerd.org.uk/code/libvterm/
+Terminal buffers behave mostly like normal 'nomodifiable' buffers, except:
+- Plugins can set 'modifiable' to modify text, but lines cannot be deleted.
+- 'scrollback' controls how many off-screen lines are kept.
+- Terminal output is followed if the cursor is on the last line.
 
 ==============================================================================
-2. Spawning					  *terminal-emulator-spawning*
+Spawning					  *terminal-emulator-spawning*
 
 There are 3 ways to create a terminal buffer:
 
@@ -40,34 +31,27 @@ There are 3 ways to create a terminal buffer:
     Note: The "term://" pattern is handled by a BufReadCmd handler, so the
     |autocmd-nested| modifier is required to use it in an autocmd. >
         autocmd VimEnter * nested split term://sh
-<    This is only mentioned for reference; you should use the |:terminal|
-    command instead.
+<    This is only mentioned for reference; use |:terminal| instead.
 
 When the terminal spawns the program, the buffer will start to mirror the
-terminal display and change its name to `term://$CWD//$PID:$COMMAND`.
-Note that |:mksession| will "save" the terminal buffers by restarting all
-programs when the session is restored.
+terminal display and change its name to `term://{cwd}//{pid}:{cmd}`.
+The "term://..." scheme enables |:mksession| to "restore" a terminal buffer by
+restarting the {cmd} when the session is loaded.
 
 ==============================================================================
-3. Input					     *terminal-emulator-input*
-
-Sending input is possible by entering terminal mode, which is achieved by
-pressing any key that would enter insert mode in a normal buffer (|i| or |a|
-for example). The |:terminal| ex command will automatically enter terminal
-mode once it's spawned. While in terminal mode, Nvim will forward all keys to
-the underlying program. The only exception is the <C-\><C-n> key combo,
-which will exit back to normal mode.
-
-Terminal mode has its own namespace for mappings, which is accessed with the
-"t" prefix. It's possible to use terminal mappings to customize interaction
-with the terminal. For example, here's how to map <Esc> to exit terminal mode:
->
+Input						     *terminal-emulator-input*
+
+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|
+
+Terminal mode has its own |:tnoremap| namespace for mappings, this can be used
+to automate any terminal interaction. To map <Esc> to exit terminal mode: >
     :tnoremap <Esc> <C-\><C-n>
 <
-Navigating to other windows is only possible by exiting to normal mode, which
-can be cumbersome with <C-\><C-n> keys. To improve the navigation experience,
-you could use the following mappings:
->
+Navigating to other windows is only possible in normal mode. For convenience,
+you could use these mappings: >
     :tnoremap <A-h> <C-\><C-n><C-w>h
     :tnoremap <A-j> <C-\><C-n><C-w>j
     :tnoremap <A-k> <C-\><C-n><C-w>k
@@ -77,11 +61,9 @@ you could use the following mappings:
     :nnoremap <A-k> <C-w>k
     :nnoremap <A-l> <C-w>l
 <
-This configuration allows using `Alt+{h,j,k,l}` to navigate between windows no
-matter if they are displaying a normal buffer or a terminal buffer in terminal
-mode.
+Then you can use `Alt+{h,j,k,l}` to navigate between windows from any mode.
 
-Mouse input is also fully supported, and has the following behavior:
+Mouse input is supported, and has the following behavior:
 
 - If the program has enabled mouse events, the corresponding events will be
   forwarded to the program.
@@ -93,27 +75,23 @@ Mouse input is also fully supported, and has the following behavior:
   the terminal wont lose focus and the hovered window will be scrolled.
 
 ==============================================================================
-4. Configuration			     *terminal-emulator-configuration*
+Configuration				     *terminal-emulator-configuration*
+
+Options:		'scrollback'
+Events:			|TermOpen|, |TermClose|
+Highlight groups:	|hl-TermCursor|, |hl-TermCursorNC|
 
-Terminal buffers can be customized through the following global/buffer-local
-variables (set via the |TermOpen| autocmd):
+Terminal colors can be customized with these variables:
 
-- 'scrollback' option: Scrollback lines (output history) limit.
 - `{g,b}:terminal_color_$NUM`: The terminal color palette, where `$NUM` is the
   color index, between 0 and 255 inclusive. This setting only affects UIs with
   RGB capabilities; for normal terminals the color index is simply forwarded.
 
-The configuration variables are only processed when the terminal starts, which
-is why it needs to be done with the |TermOpen| autocmd or setting global
-variables before the terminal is started.
-
-There is also a corresponding |TermClose| event.
-
-The terminal cursor can be highlighted via |hl-TermCursor| and
-|hl-TermCursorNC|.
+The `{g,b}:terminal_color_$NUM` variables are processed only when the terminal
+starts (after |TermOpen|).
 
 ==============================================================================
-5. Status Variables				    *terminal-emulator-status*
+Status Variables				    *terminal-emulator-status*
 
 Terminal buffers maintain some information about the terminal in buffer-local
 variables:
@@ -126,11 +104,8 @@ variables:
 - *b:terminal_job_pid* The PID of the top-level process running in the
   terminal.
 
-These variables will have a value by the time the TermOpen autocmd runs, and
-will continue to have a value for the lifetime of the terminal buffer, making
-them suitable for use in 'statusline'. For example, to show the terminal title
-as the status line:
->
+These variables are initialized before TermOpen, so you can use them in
+a local 'statusline'. Example: >
     :autocmd TermOpen * setlocal statusline=%{b:term_title}
 <
 ==============================================================================
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 504363949b..25dca5fb51 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -4949,9 +4949,15 @@ A jump table for the options with a short description can be found at |Q_op|.
 	be used as the new value for 'scroll'.  Reset to half the window
 	height with ":set scroll=0".
 
-			*'scrollback'* *'scbk'* *'noscrollback'* *'noscbk'*
-'scrollback' 'scbk'	boolean  (default: 1000)
-			global or local to buffer |global-local|
+						*'scrollback'* *'scbk'*
+'scrollback' 'scbk'	number	(default: 1000
+				 in normal buffers: -1)
+			local to buffer
+	Maximum number of lines kept beyond the visible screen. Lines at the
+	top are deleted if new lines exceed this limit.
+	Only in |terminal-emulator| buffers. 'buftype'
+	-1 means "unlimited" for normal buffers, 100000 otherwise.
+	Minimum is 1.
 
 			*'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'*
 'scrollbind' 'scb'	boolean  (default off)
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 7d08a6f32a..9a2472e394 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -207,23 +207,15 @@ g8			Print the hex values of the bytes used in the
 :sh[ell]		Removed. |vim-differences| {Nvim}
 
 						  *:terminal* *:te*
-:te[rminal][!] {cmd}	Spawns {cmd} using the current value of 'shell' and
-			'shellcmdflag' in a new terminal buffer.  This is
-			equivalent to: >
-
+:te[rminal][!] {cmd}	Execute {cmd} with 'shell' in a |terminal-emulator|
+                        buffer.  Equivalent to: >
 			      :enew
 			      :call termopen('{cmd}')
 			      :startinsert
 <
-			If no {cmd} is given, 'shellcmdflag' will not be sent
-			to |termopen()|.
-
-			Like |:enew|, it will fail if the current buffer is
-			modified, but can be forced with "!".  See |termopen()|
-			and |terminal-emulator|.
+                        See |jobstart()|.
 
-			To switch to terminal mode automatically:
->
+			To enter terminal mode automatically: >
 			      autocmd BufEnter term://* startinsert
 <
 							*:!cmd* *:!* *E34*