doc: "terminal" always means "embedded terminal emulator"

- Prefer "TUI" where possible to refer to the host terminal.
- Remove obsolete tags and ancient TTY exposition.
- Establish "terminal" to consistently mean "terminal emulator" in all
  Nvim documentation. This removes the need for verbose qualifiers in
  tags and prose.

References #6280
References #6803

9 files changed, 54 insertions, 53 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 2a98d08c4e..fd2a7c2641 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -920,7 +920,7 @@ TermClose			When a terminal buffer ends.
 						 {Nvim} *TermOpen*
 TermOpen			When a terminal buffer is starting.  This can
 				be used to configure the terminal emulator by
-				setting buffer variables. |terminal-emulator|
+				setting buffer variables. |terminal|
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|
@@ -967,9 +967,9 @@ VimEnter			After doing all the startup stuff, including
 VimLeave			Before exiting Vim, just after writing the
 				.shada file.  Executed only once, like
 				VimLeavePre.
-				To detect an abnormal exit use |v:dying|.
-				When v:dying is 2 or more this event is not
-				triggered.
+<				Use |v:dying| to detect an abnormal exit.
+				Use |v:exiting| to get the exit code.
+				Not triggered if |v:dying| is 2 or more.
 							*VimLeavePre*
 VimLeavePre			Before exiting Vim, just before writing the
 				.shada file.  This is executed only once,
@@ -977,9 +977,9 @@ VimLeavePre			Before exiting Vim, just before writing the
 				happens to be the current buffer when exiting.
 				Mostly useful with a "*" pattern. >
 	:autocmd VimLeavePre * call CleanupStuff()
-<				To detect an abnormal exit use |v:dying|.
-				When v:dying is 2 or more this event is not
-				triggered.
+<				Use |v:dying| to detect an abnormal exit.
+				Use |v:exiting| to get the exit code.
+				Not triggered if |v:dying| is 2 or more.
 							*VimResized*
 VimResized			After the Vim window was resized, thus 'lines'
 				and/or 'columns' changed.  Not when starting
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 7fd1f90173..5d5523e73f 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -63,12 +63,6 @@ NVIM IS... WELL DOCUMENTED				*design-documented*
 - Documentation should be comprehensive and understandable.  Use examples.
 - Don't make the text unnecessarily long.  Less documentation means that an
   item is easier to find.
-- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document
-  differences from Vim. The {Nvim} annotation is also available
-  to mark a specific feature. No other distinction is necessary.
-- If a feature is removed, delete its doc entry and move its tag to
-  |vim_diff.txt|.
-- Move deprecated features to |deprecated.txt|.
 
 
 NVIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size*
@@ -113,7 +107,7 @@ include the kitchen sink... but it's good for plumbing."
 
 
 ==============================================================================
-Developer guidelines				        *dev-help*
+Developer guidelines				        *dev*
 
 
 JARGON	 						*dev-jargon*
@@ -192,6 +186,18 @@ defined if a valid external Python host is found. That works well with the
 Python host isn't installed then the plugin will "think" it is running in
 a Vim compiled without the |+python| feature.
 
+DOCUMENTATION						*dev-doc*
+
+- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document
+  differences from Vim; no other distinction is necessary.
+- If a Vim feature is removed, delete its help section and move its tag to
+  |vim_diff.txt|.
+- Move deprecated features to |deprecated.txt|.
+- Use consistent language.
+    - "terminal" in a help tag always means "the embedded terminal emulator", not
+      "the user host terminal".
+    - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
+      in prose if possible.
 
 API							*dev-api*
 
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index f4573d7617..dd8aec895d 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -7641,7 +7641,7 @@ termopen({cmd}[, {opts}])			{Nvim} *termopen()*
 		and `$TERM` is set to "xterm-256color".
 		Returns the same values as |jobstart()|.
 
-		See |terminal-emulator| for more information.
+		See |terminal| for more information.
 
 test_garbagecollect_now()			 *test_garbagecollect_now()*
 		Like garbagecollect(), but executed right away.  This must
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index 801ff75647..4527a14710 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -10,15 +10,18 @@ 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.
 
-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.
+Terminal buffers behave like normal buffers, except:
+- With 'modifiable', lines can be edited but not deleted.
+- 'scrollback' controls how many lines are kept.
+- Output is followed if the cursor is on the last line.
+- 'modified' is the default. You can set 'nomodified' to avoid a warning when
+  closing the terminal buffer.
+- 'bufhidden' defaults to "hide".
 
 				      Type <M-]> to see the table of contents.
 
 ==============================================================================
-Spawning					  *terminal-emulator-spawning*
+Start						*terminal-start*
 
 There are 3 ways to create a terminal buffer:
 
@@ -35,13 +38,12 @@ There are 3 ways to create a terminal buffer:
         autocmd VimEnter * nested split term://sh
 <    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}:{cmd}`.
-The "term://..." scheme enables |:mksession| to "restore" a terminal buffer by
-restarting the {cmd} when the session is loaded.
+When the terminal starts, the buffer contents are updated and the buffer is
+named in the form of `term://{cwd}//{pid}:{cmd}`. This naming scheme is used
+by |:mksession| to restore a terminal buffer (by restarting the {cmd}).
 
 ==============================================================================
-Input						     *terminal-emulator-input*
+Input						*terminal-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
@@ -83,9 +85,9 @@ Mouse input has the following behavior:
   the terminal wont lose focus and the hovered window will be scrolled.
 
 ==============================================================================
-Configuration				     *terminal-emulator-configuration*
+Configuration					*terminal-configuration*
 
-Options:		'scrollback'
+Options:		'modified', 'scrollback'
 Events:			|TermOpen|, |TermClose|
 Highlight groups:	|hl-TermCursor|, |hl-TermCursorNC|
 
@@ -99,17 +101,15 @@ global configuration.
 You can change the defaults with a TermOpen autocommand: >
 	au TermOpen * setlocal list
 
-Terminal colors can be customized with these variables:
+TERMINAL COLORS ~
 
-- `{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 `{g,b}:terminal_color_$NUM` variables are processed only when the terminal
-starts (after |TermOpen|).
+The `{g,b}:terminal_color_$NUM` variables control 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
+just forwarded. The variables are read only during |TermOpen|.
 
 ==============================================================================
-Status Variables				    *terminal-emulator-status*
+Status Variables				*terminal-status*
 
 Terminal buffers maintain some information about the terminal in buffer-local
 variables:
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 6406bfe03b..c6965648ef 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -4794,7 +4794,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			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'
+	Only in |terminal| buffers.
 	-1 means "unlimited" for normal buffers, 100000 otherwise.
 	Minimum is 1.
 
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index 38900dd826..d99f9b7160 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -4,7 +4,7 @@
                             NVIM REFERENCE MANUAL
 
 
-Terminal information
+Terminal UI						*tui*
 
 Nvim (except in |--headless| mode) uses information about the terminal you are
 using to present a built-in UI.  If that information is not correct, the
@@ -225,14 +225,7 @@ On Unix systems, three methods are tried to get the window size:
 If everything fails a default size of 24 lines and 80 columns is assumed.  If
 a window-resize signal is received the size will be set again.  If the window
 size is wrong you can use the 'lines' and 'columns' options to set the
-correct values.
-
-One command can be used to set the screen size:
-
-						*:mod* *:mode*
-:mod[e]
-
-Detects the screen size and redraws the screen.
+correct values. See |:mode|.
 
 ==============================================================================
 Slow and fast terminals				*slow-fast-terminal*
@@ -343,13 +336,12 @@ before using the mouse:
 	"g<RightMouse>" is "<C-RightMouse>	("CTRL-T")
 
 							*bracketed-paste-mode*
-Bracketed paste mode allows terminal emulators to distinguish between typed
-text and pasted text.
+Bracketed paste mode allows terminal applications to distinguish between typed
+text and pasted text. Thus you can paste text without Nvim trying to format or
+indent the text. See also https://cirw.in/blog/bracketed-paste
 
-For terminal emulators that support it, this mode is enabled by default. Thus
-you can paste text without Nvim giving any special meaning to it, e.g. it will
-not auto-indent the pasted text. See https://cirw.in/blog/bracketed-paste for
-technical details.
+Nvim enables bracketed paste by default. If it does not work in your terminal,
+try the 'paste' option instead.
 
 					*mouse-mode-table* *mouse-overview*
 A short overview of what the mouse buttons do, when 'mousemodel' is "extend":
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 1f94a45c74..7f1e5ce543 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -61,7 +61,7 @@ these differences.
 
 MAJOR COMPONENTS ~
 
-Embedded terminal emulator	|terminal-emulator|
+Embedded terminal emulator	|terminal|
 RPC API				|RPC|
 Shared data			|shada|
 XDG base directories		|xdg|
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 651d617a76..f5d5321a5e 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -523,6 +523,9 @@ CTRL-W >	Increase current window width by N (default 1).
 :vertical res[ize] [N]			*:vertical-resize* *CTRL-W_bar*
 CTRL-W |	Set current window width to N (default: widest possible).
 
+						*:mod* *:mode*
+:mod[e]		Detects the screen size and redraws the screen.
+
 You can also resize a window by dragging a status line up or down with the
 mouse.  Or by dragging a vertical separator line left or right.  This only
 works if the version of Vim that is being used supports the mouse and the
diff --git a/scripts/vim-patch.sh b/scripts/vim-patch.sh
index 37c472ce5b..5ebb6a38b3 100755
--- a/scripts/vim-patch.sh
+++ b/scripts/vim-patch.sh
@@ -135,7 +135,7 @@ preprocess_patch() {
   local na_src='proto\|Make*\|gui_*\|if_lua\|if_mzsch\|if_olepp\|if_ole\|if_perl\|if_py\|if_ruby\|if_tcl\|if_xcmdsrv'
   2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/src/\S*\<\%('${na_src}'\)@norm! d/\v(^diff)|%$
' +w +q "$file"
 
-  # Remove channel.txt, netbeans.txt, os_*.txt, todo.txt, version*.txt, tags
+  # Remove channel.txt, netbeans.txt, os_*.txt, term.txt, todo.txt, version*.txt, tags
   local na_doc='channel\.txt\|netbeans\.txt\|os_\w\+\.txt\|term\.txt\|todo\.txt\|version\d\.txt\|tags'
   2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/runtime/doc/\<\%('${na_doc}'\)\>@norm! d/\v(^diff)|%$
' +w +q "$file"