doc: Begin terminal emulator documentation

With some spacing/indentation fixes.

Helped by: @Pyrohh, @kopischke

7 files changed, 154 insertions, 7 deletions

diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile
index 2f9063231d..4bced03d7e 100644
--- a/runtime/doc/Makefile
+++ b/runtime/doc/Makefile
@@ -55,6 +55,7 @@ DOCS = \
 	nvim_intro.txt \
 	nvim_provider.txt \
 	nvim_python.txt \
+	nvim_terminal_emulator.txt \
 	options.txt \
 	os_dos.txt \
 	os_mac.txt \
@@ -176,6 +177,7 @@ HTMLS = \
 	nvim_intro.html \
 	nvim_provider.html \
 	nvim_python.html \
+	nvim_terminal_emulator.html \
 	options.html \
 	os_dos.html \
 	os_mac.html \
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index eea59754c8..1393131ab7 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -253,6 +253,7 @@ Name			triggered by ~
 |BufNew|		just after creating a new buffer
 
 |SwapExists|		detected an existing swap file
+|TermOpen|		when a terminal buffer is starting
 
 	Options
 |FileType|		when the 'filetype' option has been set
@@ -871,6 +872,11 @@ TermChanged			After the value of 'term' has changed.  Useful
 				for re-loading the syntax file to update the
 				colors, fonts and other terminal-dependent
 				settings.  Executed for all loaded buffers.
+						 {Nvim} *TermOpen*
+TermOpen			When a terminal buffer is starting.  This can
+				be used to configure the terminal emulator by
+				setting buffer variables.
+				See |nvim-terminal-emulator| for details.
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 1b1d93a065..5f572e9caa 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -6318,6 +6318,17 @@ tempname()					*tempname()* *temp-file-name*
 		For MS-Windows forward slashes are used when the 'shellslash'
 		option is set or when 'shellcmdflag' starts with '-'.
 
+termopen({command}[, {opts}])			{Nvim} *termopen()*
+		Spawns {command} using the shell in a new pseudo-terminal
+		session connected to the current buffer.  This function fails
+		if the current buffer is modified (all buffer contents are
+		destroyed).  The {opts} dict is similar to the one passed to
+		|jobstart()|, but the `pty`, `width`, `height`, and `TERM` fields are
+		ignored: `height`/`width` are taken from the current window and
+		$TERM is set to "xterm-256color".  Returns the same values as
+		|jobstart()|.
+
+		See |nvim-terminal-emulator| for more information.
 
 tan({expr})						*tan()*
 		Return the tangent of {expr}, measured in radians, as a |Float|
diff --git a/runtime/doc/nvim_intro.txt b/runtime/doc/nvim_intro.txt
index d44648c575..40f65620af 100644
--- a/runtime/doc/nvim_intro.txt
+++ b/runtime/doc/nvim_intro.txt
@@ -13,13 +13,14 @@ see |help.txt|.
 For now, it is just an index with the most relevant topics/features that
 differentiate Nvim from Vim:
 
-1. Differences from Vim		|vim-differences|
-2. Msgpack-RPC			|msgpack-rpc|
-3. Job control			|job-control|
-4. Python plugins		|nvim-python|
-5. Clipboard integration	|nvim-clipboard|
-6. Remote plugins		|remote-plugin|
-7. Provider infrastructure	|nvim-provider|
+1. Differences from Vim		 |vim-differences|
+2. Msgpack-RPC			 |msgpack-rpc|
+3. Job control			 |job-control|
+4. Python plugins		 |nvim-python|
+5. Clipboard integration	 |nvim-clipboard|
+6. Remote plugins		 |remote-plugin|
+7. Provider infrastructure	 |nvim-provider|
+8. Integrated terminal emulator  |nvim-terminal-emulator|
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
new file mode 100644
index 0000000000..160242a7fa
--- /dev/null
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -0,0 +1,114 @@
+*nvim_terminal_emulator.txt*    For Nvim.				{Nvim}
+
+
+		 NVIM REFERENCE MANUAL    by Thiago de Arruda
+
+
+Nvim integrated terminal emulator		     *nvim-terminal-emulator*
+
+1. Introduction			|nvim-terminal-emulator-introduction|
+2. Spawning			|nvim-terminal-emulator-spawning|
+3. Input			|nvim-terminal-emulator-input|
+4. Configuration		|nvim-terminal-emulator-configuration|
+
+==============================================================================
+1. Introduction			      *nvim-terminal-emulator-introduction*
+
+One feature that distinguishes Nvim from Vim is that it implements a mostly
+complete VT220/xterm-like terminal emulator. The terminal is presented to the
+user as a special buffer type, one that is 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[1], a powerful abstract terminal
+emulation library.
+
+[1]: http://www.leonerd.org.uk/code/libvterm/
+
+==============================================================================
+2. Spawning			      *nvim-terminal-emulator-spawning*
+
+There are 3 ways to create a terminal buffer:
+
+- By invoking the |:terminal| ex command.
+- By calling the |termopen()| function.
+- By editing a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`.
+  For example:
+>
+    :e term://bash
+    :vsp term://top
+<
+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.
+
+==============================================================================
+3. Input			      *nvim-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:
+>
+    :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. Here are some mappings to improve
+the navigation experience:
+>
+    :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
+    :tnoremap <A-l> <C-\><C-n><C-w>l
+    :nnoremap <A-h> <C-w>h
+    :nnoremap <A-j> <C-w>j
+    :nnoremap <A-k> <C-w>k
+    :nnoremap <A-l> <C-w>l
+<
+This 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.
+
+Mouse input is also fully supported, and has the following behavior:
+
+- If the program has enabled mouse events, the corresponding events will be
+  forwarded to the program.
+- If mouse events are disabled (the default), terminal focus will be lost and
+  the event will be processed as in a normal buffer.
+- If another window is clicked, terminal focus will be lost and nvim will jump
+  to the clicked window
+- If the mouse wheel is used while the mouse is positioned in another window,
+  the terminal wont lose focus and the hovered window will be scrolled.
+
+==============================================================================
+4. Configuration		     *nvim-terminal-emulator-configuration*
+
+Terminal buffers can be customized through the following global/buffer-local
+variables (set via the |TermOpen| autocmd):
+
+- `{g,b}:terminal_scrollback_buffer_size`: Scrollback buffer size, between 1
+  and 100000 inclusive. The default is 1000.
+- `{g,b}:terminal_color_$NUM`: The terminal color palette, where `$NUM` is the
+  color index, between 0 and 255 inclusive. This only affects UIs with RGB
+  capabilities; for normal terminals the color index is simply forwarded.
+- `{g,b}:terminal_focused_cursor_highlight`: Highlight group applied to the
+  cursor in a focused terminal. The default equivalent to having a group with
+  `cterm=reverse` `gui=reverse``.
+- `{g,b}:terminal_unfocused_cursor_highlight`: Highlight group applied to the
+  cursor in an unfocused terminal. The default equivalent to having a group with
+  `ctermbg=11` `guibg=#fce94f``.
+
+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.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 0322fae991..0c964ae519 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1277,6 +1277,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 			or list of locations |:lwindow|
 	  help		help buffer (you are not supposed to set this
 			manually)
+	  terminal	terminal buffer, this is set automatically when a 
+			terminal is created. See |nvim-terminal-emulator| for
+			more information.
 
 	This option is used together with 'bufhidden' and 'swapfile' to
 	specify special kinds of buffers.   See |special-buffers|.
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 7797b02ba8..d138fcf456 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -224,6 +224,16 @@ g8			Print the hex values of the bytes used in the
 						  *:sh* *:shell* *E371* *E360*
 :sh[ell]		Removed. |vim-differences| {Nvim}
 
+						  *:term* *:terminal*
+:term[inal][!] {cmd}	Spawns {command} using the current value of 'shell'
+			in a new terminal buffer.  This is equivalent to: >
+
+			      :enew | call termopen('{cmd}') | startinsert
+<
+			Like |:enew|, it will fail if the current buffer is
+			modified, but can be forced with "!".  See |termopen()|
+			and |nvim-terminal-emulator| for more information.
+
 							*:!cmd* *:!* *E34*
 :!{cmd}			Execute {cmd} with the shell. See also 'shell'.