Merge #7105 from justinmk/doc-tui

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|.
+<				Use |v:dying| to detect an abnormal exit.
-				When v:dying is 2 or more this event is not
+				Use |v:exiting| to get the exit code.
-				triggered.
+				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|.
+<				Use |v:dying| to detect an abnormal exit.
-				When v:dying is 2 or more this event is not
+				Use |v:exiting| to get the exit code.
-				triggered.
+				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

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*
 

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

runtime/doc/help.txt

@@ -96,7 +96,7 @@ General subjects ~
 |howto.txt|	how to do the most common editing tasks
 |tips.txt|	various tips on using Vim
 |message.txt|	(error) messages and explanations
-|develop.txt|	development of Vim
+|develop.txt|	development of Nvim
 |debug.txt|	debugging Vim itself
 |uganda.txt|	Vim distribution conditions and what to do with your money
 
@@ -134,7 +134,6 @@ Advanced editing ~
 Special issues ~
 |print.txt|	printing
 |remote.txt|	using Vim as a server or client
-|term.txt|	using different terminals and mice
 |digraph.txt|	list of available digraphs
 |mbyte.txt|	multi-byte text support
 |mlang.txt|	non-English language support

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:
+Terminal buffers behave like normal buffers, except:
-- Plugins can set 'modifiable' to modify text, but lines cannot be deleted.
+- With 'modifiable', lines can be edited but not deleted.
-- 'scrollback' controls how many off-screen lines are kept.
+- 'scrollback' controls how many lines are kept.
-- Terminal output is followed if the cursor is on the last line.
+- 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
+When the terminal starts, the buffer contents are updated and the buffer is
-terminal display and change its name to `term://{cwd}//{pid}:{cmd}`.
+named in the form of `term://{cwd}//{pid}:{cmd}`. This naming scheme is used
-The "term://..." scheme enables |:mksession| to "restore" a terminal buffer by
+by |:mksession| to restore a terminal buffer (by restarting the {cmd}).
-restarting the {cmd} when the session is loaded.
 
 ==============================================================================
-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
+The `{g,b}:terminal_color_$NUM` variables control the terminal color palette,
-  color index, between 0 and 255 inclusive. This setting only affects UIs with
+where `$NUM` is the color index between 0 and 255 inclusive. This setting only
-  RGB capabilities; for normal terminals the color index is simply forwarded.
+affects UIs with RGB capabilities; for normal terminals the color index is
-
+just forwarded. The variables are read only during |TermOpen|.
-The `{g,b}:terminal_color_$NUM` variables are processed only when the terminal
-starts (after |TermOpen|).
 
 ==============================================================================
-Status Variables				    *terminal-emulator-status*
+Status Variables				*terminal-status*
 
 Terminal buffers maintain some information about the terminal in buffer-local
 variables:

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.
 

runtime/doc/os_win32.txt

@@ -1,179 +0,0 @@
-*os_win32.txt*  Nvim
-
-
-                            NVIM REFERENCE MANUAL
-
-
-						*win32* *Win32* *MS-Windows*
-This file documents the Win32 version of Nvim.
-
-==============================================================================
-1. Known problems					*win32-problems*
-
-When doing file name completion, Vim also finds matches for the short file
-name.  But Vim will still find and use the corresponding long file name.  For
-example, if you have the long file name "this_is_a_test" with the short file
-name "this_i~1", the command ":e *1" will start editing "this_is_a_test".
-
-==============================================================================
-2. Startup						*win32-startup*
-
-Current directory					*win32-curdir*
-
-If Vim is started with a single file name argument, and it has a full path
-(starts with "x:\"), Vim assumes it was started from the file explorer and
-will set the current directory to where that file is.  To avoid this when
-typing a command to start Vim, use a forward slash instead of a backslash.
-Example: >
-
-	vim c:\text\files\foo.txt
-
-Will change to the "C:\text\files" directory. >
-
-	vim c:/text\files\foo.txt
-
-Will use the current directory.
-
-
-Term option						*win32-term*
-
-The only kind of terminal type that the Win32 version of Vim understands is
-"win32", which is built-in.  If you set 'term' to anything else, you will
-probably get very strange behavior from Vim.  Therefore Vim does not obtain
-the default value of 'term' from the environment variable "TERM".
-
-$PATH							*win32-PATH*
-
-The directory of the Vim executable is appended to $PATH.  This is mostly to
-make "!xxd" work, as it is in the Tools menu.  And it also means that when
-executable() returns 1 the executable can actually be executed.
-
-Quotes in file names					*win32-quotes*
-
-Quotes inside a file name (or any other command line argument) can be escaped
-with a backslash.  E.g. >
-	vim -c "echo 'foo\"bar'"
-
-Alternatively use three quotes to get one: >
-	vim -c "echo 'foo"""bar'"
-
-The quotation rules are:
-
-1. A `"` starts quotation.
-2. Another `"` or `""` ends quotation. If the quotation ends with `""`, a `"`
-   is produced at the end of the quoted string.
-
-Examples, with [] around an argument:
-        "foo"           -> [foo]
-        "foo""          -> [foo"]
-        "foo"bar        -> [foobar]
-        "foo" bar       -> [foo], [bar]
-        "foo""bar       -> [foo"bar]
-        "foo"" bar      -> [foo"], [bar]
-        "foo"""bar"     -> [foo"bar]
-
-
-==============================================================================
-3. Using the mouse					*win32-mouse*
-
-The Win32 version of Vim supports using the mouse.  If you have a two-button
-mouse, the middle button can be emulated by pressing both left and right
-buttons simultaneously - but note that in the Win32 GUI, if you have the right
-mouse button pop-up menu enabled (see 'mouse'), you should err on the side of
-pressing the left button first.				|mouse-using|
-
-When the mouse doesn't work, try disabling the "Quick Edit Mode" feature of
-the console.
-
-==============================================================================
-4. Win32 mini FAQ					*win32-faq*
-
-Q. How do I change the font?
-A. In the GUI version, you can use the 'guifont' option.  Example: >
-	:set guifont=Lucida_Console:h15:cDEFAULT
-<  In the console version, you need to set the font of the console itself.
-   You cannot do this from within Vim.
-
-Q. I'm using Vim to edit a symbolically linked file on a Unix NFS file server.
-   When I write the file, Vim does not "write through" the symlink.  Instead,
-   it deletes the symbolic link and creates a new file in its place.  Why?
-A. On Unix, Vim is prepared for links (symbolic or hard).  A backup copy of
-   the original file is made and then the original file is overwritten.  This
-   assures that all properties of the file remain the same.  On non-Unix
-   systems, the original file is renamed and a new file is written.  Only the
-   protection bits are set like the original file.  However, this doesn't work
-   properly when working on an NFS-mounted file system where links and other
-   things exist.  The only way to fix this in the current version is not
-   making a backup file, by ":set nobackup nowritebackup"     |'writebackup'|
-
-Q. I'm using Vim to edit a file on a Unix file server through Samba.  When I
-   write the file, the owner of the file is changed.  Why?
-A. When writing a file Vim renames the original file, this is a backup (in
-   case writing the file fails halfway).  Then the file is written as a new
-   file.  Samba then gives it the default owner for the file system, which may
-   differ from the original owner.
-   To avoid this set the 'backupcopy' option to "yes".  Vim will then make a
-   copy of the file for the backup, and overwrite the original file.  The
-   owner isn't changed then.
-
-Q. How do I get to see the output of ":make" while it's running?
-A. Basically what you need is to put a tee program that will copy its input
-   (the output from make) to both stdout and to the errorfile.  You can find a
-   copy of tee (and a number of other GNU tools) at
-   http://gnuwin32.sourceforge.net or http://unxutils.sourceforge.net
-   Alternatively, try the more recent Cygnus version of the GNU tools at
-   http://www.cygwin.com  Other Unix-style tools for Win32 are listed at
-   http://directory.google.com/Top/Computers/Software/Operating_Systems/Unix/Win32/
-   When you do get a copy of tee, you'll need to add >
-	:set shellpipe=\|\ tee
-<  to your _vimrc.
-
-							*:!start*
-Q. How can I run an external command or program asynchronously?
-A. When using :! to run an external command, you can run it with "start": >
-	:!start winfile.exe<CR>
-<  Using "start" stops Vim switching to another screen, opening a new console,
-   or waiting for the program to complete; it indicates that you are running a
-   program that does not affect the files you are editing.  Programs begun
-   with :!start do not get passed Vim's open file handles, which means they do
-   not have to be closed before Vim.
-   To avoid this special treatment, use ":! start".
-   There are two optional arguments (see the next Q):
-       /min  the window will be minimized
-       /b    no console window will be opened
-   You can use only one of these flags at a time.  A second one will be
-   treated as the start of the command.
-
-Q. How do I avoid getting a window for programs that I run asynchronously?
-A. You have two possible solutions depending on what you want:
-   1) You may use the /min flag in order to run program in a minimized state
-      with no other changes. It will work equally for console and GUI
-      applications.
-   2) You can use the /b flag to run console applications without creating a
-      console window for them (GUI applications are not affected). But you
-      should use this flag only if the application you run doesn't require any
-      input.  Otherwise it will get an EOF error because its input stream
-      (stdin) would be redirected to \\.\NUL (stdout and stderr too).
-
-   Example for a console application, run Exuberant ctags: >
-        :!start /min ctags -R .
-<  When it has finished you should see file named "tags" in your current
-   directory.  You should notice the window title blinking on your taskbar.
-   This is more noticeable for commands that take longer.
-   Now delete the "tags" file and run this command: >
-        :!start /b ctags -R .
-<  You should have the same "tags" file, but this time there will be no
-   blinking on the taskbar.
-   Example for a GUI application: >
-        :!start /min notepad
-        :!start /b notepad
-<  The first command runs notepad minimized and the second one runs it
-   normally.
-
-						*windows-icon*
-Q. I don't like the Vim icon, can I change it?
-A. Yes, place your favorite icon in bitmaps/vim.ico in a directory of
-   'runtimepath'.  For example ~/vimfiles/bitmaps/vim.ico.
-
-
- vim:tw=78:fo=tcq2:ts=8:ft=help:norl:

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.
+correct values. See |:mode|.
-
-One command can be used to set the screen size:
-
-						*:mod* *:mode*
-:mod[e]
-
-Detects the screen size and redraws the screen.
 
 ==============================================================================
 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
+Bracketed paste mode allows terminal applications to distinguish between typed
-text and pasted text.
+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
+Nvim enables bracketed paste by default. If it does not work in your terminal,
-you can paste text without Nvim giving any special meaning to it, e.g. it will
+try the 'paste' option instead.
-not auto-indent the pasted text. See https://cirw.in/blog/bracketed-paste for
-technical details.
 
 					*mouse-mode-table* *mouse-overview*
 A short overview of what the mouse buttons do, when 'mousemodel' is "extend":

runtime/doc/various.txt

@@ -276,6 +276,21 @@ g8			Print the hex values of the bytes used in the
 <			The screen is not redrawn then, thus you have to use
 			CTRL-L or ":redraw!" if the command did display
 			something.
+							*:!start*
+:!start	{cmd}		(Windows only). Special-case of |:!| which works
+			asynchronously, for running a program that does not
+			affect the files you are editing.
+			Optional arguments (can only use one at a time):
+				/min  window will be minimized
+				/b    no console window will be opened
+			Note: If the process requires input, /b will get an
+			EOF error because its input stream (stdin) would be
+			redirected to \\.\NUL (stdout and stderr too).
+
+			Programs begun with :!start do not get passed Vim's
+			open file handles, which means they do not have to be
+			closed before Vim. To avoid this special treatment,
+			use ":! start".
 
 							*:!!*
 :!!			Repeat last ":!{cmd}".

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|

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

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"