Adding upstream version 2:8.1.0875.upstream/2%8.1.0875upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 938 insertions, 0 deletions

diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
new file mode 100644
index 0000000..de79ff0
--- /dev/null
+++ b/runtime/doc/terminal.txt
@@ -0,0 +1,938 @@
+*terminal.txt*	For Vim version 8.1.  Last change: 2019 Feb 03
+
+
+		  VIM REFERENCE MANUAL	  by Bram Moolenaar
+
+
+Terminal window support				*terminal* *terminal-window*
+
+
+The terminal feature is optional, use this to check if your Vim has it: >
+	echo has('terminal')
+If the result is "1" you have it.
+
+
+1. Basic use			|terminal-use|
+      Typing				|terminal-typing|
+      Size and color			|terminal-size-color|
+      Syntax				|:terminal|
+      Resizing				|terminal-resizing|
+      Terminal Modes			|Terminal-mode|
+      Cursor style			|terminal-cursor-style|
+      Session				|terminal-session|
+      Special keys			|terminal-special-keys|
+      Unix				|terminal-unix|
+      MS-Windows			|terminal-ms-windows|
+2. Terminal communication	|terminal-communication|
+      Vim to job: term_sendkeys()	|terminal-to-job|
+      Job to Vim: JSON API		|terminal-api|
+      Using the client-server feature	|terminal-client-server|
+3. Remote testing		|terminal-testing|
+4. Diffing screen dumps		|terminal-diff|
+      Writing a screen dump test for Vim  |terminal-dumptest|
+      Creating a screen dump		  |terminal-screendump|
+      Comparing screen dumps		  |terminal-diffscreendump|
+5. Debugging			|terminal-debug|
+      Starting				|termdebug-starting|
+      Example session			|termdebug-example|
+      Stepping through code		|termdebug-stepping|
+      Inspecting variables		|termdebug-variables|
+      Other commands			|termdebug-commands|
+      Prompt mode			|termdebug-prompt|
+      Communication			|termdebug-communication|
+      Customizing			|termdebug-customizing|
+
+{Vi does not have any of these commands}
+{only available when compiled with the |+terminal| feature}
+The terminal feature requires the |+multi_byte|, |+job| and |+channel| features.
+
+==============================================================================
+1. Basic use						*terminal-use*
+
+This feature is for running a terminal emulator in a Vim window.  A job can be
+started connected to the terminal emulator. For example, to run a shell: >
+     :term bash
+
+Or to run build command: >
+     :term make myprogram
+
+The job runs asynchronously from Vim, the window will be updated to show
+output from the job, also while editing in another window.
+
+
+Typing ~
+							*terminal-typing*
+When the keyboard focus is in the terminal window, typed keys will be sent to
+the job.  This uses a pty when possible.  You can click outside of the
+terminal window to move keyboard focus elsewhere.
+
+CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.:
+	CTRL-W CTRL-W	move focus to the next window
+	CTRL-W :	enter an Ex command
+See |CTRL-W| for more commands.
+
+Special in the terminal window:			*CTRL-W_.*  *CTRL-W_N* 
+	CTRL-W .	send a CTRL-W to the job in the terminal
+	CTRL-W CTRL-\	send a CTRL-\ to the job in the terminal
+	CTRL-W N	go to Terminal-Normal mode, see |Terminal-mode|
+	CTRL-\ CTRL-N   go to Terminal-Normal mode, see |Terminal-mode|
+	CTRL-W " {reg}  paste register {reg}		*CTRL-W_quote*
+			Also works with the = register to insert the result of
+			evaluating an expression.
+	CTRL-W CTRL-C	ends the job, see below |t_CTRL-W_CTRL-C|
+
+See option 'termwinkey' for specifying another key instead of CTRL-W that
+will work like CTRL-W.  However, typing 'termwinkey' twice sends 'termwinkey'
+to the job.  For example:
+	'termwinkey' CTRL-W    move focus to the next window
+	'termwinkey' :	       enter an Ex command
+	'termwinkey' 'termwinkey' send 'termwinkey' to the job in the terminal
+	'termwinkey' .	       send 'termwinkey' to the job in the terminal
+	'termwinkey' CTRL-\    send a CTRL-\ to the job in the terminal
+	'termwinkey' N	       go to terminal Normal mode, see below
+	'termwinkey' CTRL-N    same as CTRL-W N
+	'termwinkey' CTRL-C    same as |t_CTRL-W_CTRL-C|
+							*t_CTRL-\_CTRL-N*
+The special key combination CTRL-\ CTRL-N can be used to switch to Normal
+mode, just like this works in any other mode.
+							*t_CTRL-W_CTRL-C*
+CTRL-W CTRL-C can be typed to forcefully end the job.  On MS-Windows a
+CTRL-BREAK will also kill the job.
+
+If you type CTRL-C the effect depends on what the pty has been configured to
+do.  For simple commands this causes a SIGINT to be sent to the job, which
+would end it.  Other commands may ignore the SIGINT or handle the CTRL-C
+themselves (like Vim does).
+
+To change the keys you type use terminal mode mappings, see |:tmap|.
+These are defined like any mapping, but apply only when typing keys that are
+sent to the job running in the terminal.  For example, to make F1 switch
+to Terminal-Normal mode: >
+   tnoremap <F1> <C-W>N
+You can use Esc, but you need to make sure it won't cause other keys to
+break (cursor keys start with an Esc, so they may break): >
+   tnoremap <Esc> <C-W>N
+   set notimeout ttimeout timeoutlen=100
+
+You can also create menus similar to terminal mode mappings, but you have to
+use |:tlmenu| instead of |:tmenu|.
+
+<							*options-in-terminal*
+After opening the terminal window and setting 'buftype' to "terminal" the
+TerminalOpen autocommand event is triggered.  This makes it possible to set
+options specifically for the window and buffer.  Example: >
+   au TerminalOpen * if &buftype == 'terminal' | setlocal bufhidden=hide | endif
+The <abuf> is set to the terminal buffer, but if there is no window (hidden
+terminal) then setting options will happen in the wrong buffer, therefore the
+check for &buftype in the example.
+
+Mouse events (click and drag) are passed to the terminal.  Mouse move events
+are only passed when Vim itself is receiving them.  For a terminal that is
+when 'balloonevalterm' is enabled.
+
+
+Size and color ~
+							*terminal-size-color*
+See option 'termwinsize' for controlling the size of the terminal window.
+(TODO: scrolling when the terminal is larger than the window)
+
+The job running in the terminal can change the colors.  The default foreground
+and background colors are taken from Vim, the Normal highlight group.
+
+For a color terminal the 'background' option is used to decide whether the
+terminal window will start with a white or black background.
+
+To use a different color the Terminal highlight group can be used, for
+example: >
+    hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue
+<
+							*g:terminal_ansi_colors*
+In GUI mode or with 'termguicolors', the 16 ANSI colors used by default in new
+terminal windows may be configured using the variable
+`g:terminal_ansi_colors`, which should be a list of 16 color names or
+hexadecimal color codes, similar to those accepted by |highlight-guifg|.  When
+not using GUI colors, the terminal window always uses the 16 ANSI colors of
+the underlying terminal.
+The |term_setansicolors()| function can be used to change the colors, and
+|term_getansicolors()| to get the currently used colors.
+
+
+Syntax ~
+
+:[range]ter[minal] [options] [command]			*:ter* *:terminal*
+			Open a new terminal window.
+
+			If [command] is provided run it as a job and connect
+			the input and output to the terminal.
+			If [command] is not given the 'shell' option is used.
+			if [command] is NONE no job is started, the pty of the
+			terminal can be used by a command like gdb.
+
+			If [command] is missing the default behavior is to
+			close the terminal when the shell exits.  This can be
+			changed with the ++noclose argument.
+			If [command] is present the default behavior is to
+			keep the terminal open in Terminal-Normal mode.  This
+			can be changed with the ++close argument.
+
+			A new buffer will be created, using [command] or
+			'shell' as the name, prefixed with a "!".  If a buffer
+			by this name already exists a number is added in
+			parentheses.  E.g. if "gdb" exists the second terminal
+			buffer will use "!gdb (1)".
+
+			If [range] is given the specified lines are used as
+			input for the job.  It will not be possible to type
+			keys in the terminal window.  For MS-Windows see the
+			++eof argument below.
+
+						*term++close* *term++open*
+			Supported [options] are:
+			++close		The terminal window will close
+					automatically when the job terminates.
+			++noclose	The terminal window will NOT close
+					automatically when the job terminates.
+			++open		When the job terminates and no window
+					shows it, a window will be opened.
+					Note that this can be interruptive.
+				The last of ++close, ++noclose and ++open
+				matters and rules out earlier arguments.
+
+			++curwin	Open the terminal in the current
+					window, do not split the current
+					window.  Fails if the current buffer
+					cannot be |abandon|ed.
+			++hidden	Open the terminal in a hidden buffer,
+					no window will be used.
+			++norestore	Do not include this terminal window
+					in a session file.
+			++kill={how}	When trying to close the terminal
+					window kill the job with {how}.  See
+					|term_setkill()| for the values.
+			++rows={height} Use {height} for the terminal window
+					height.  If the terminal uses the full
+					Vim height (no window above or below
+					the terminal window) the command line
+					height will be reduced as needed.
+			++cols={width}  Use {width} for the terminal window
+					width. If the terminal uses the full
+					Vim width (no window left or right of
+					the terminal window) this value is
+					ignored.
+			++eof={text}	when using [range]: text to send after
+					the last line was written. Cannot
+					contain white space.  A CR is
+					appended.  For MS-Windows the default
+					is to send CTRL-D.
+					E.g. for a shell use "++eof=exit" and
+					for Python "++eof=exit()".  Special
+					codes can be used like with `:map`,
+					e.g. "<C-Z>" for CTRL-Z.
+			++winpty	Use winpty as the virtual console.
+			++conpty	Use |ConPTY| as the virtual console.
+			If you want to use more options use the |term_start()|
+			function.
+			If you want to split the window vertically, use: >
+				:vertical terminal
+<			Or short: >
+				:vert ter
+
+When the buffer associated with the terminal is forcibly unloaded or wiped out
+the job is killed, similar to calling `job_stop(job, "kill")` .
+Closing the window normally results in |E947|.  When a kill method was set
+with "++kill={how}" or |term_setkill()| then closing the window will use that
+way to kill or interrupt the job.  For example: >
+	:term ++kill=term tail -f /tmp/log
+
+So long as the job is running the window behaves like it contains a modified
+buffer.  Trying to close the window with `CTRL-W :quit` fails.  When using
+`CTRL-W :quit!` the job is ended.  The text in the window is lost.  The buffer
+still exists, but getting it in a window with `:buffer` will show an empty
+buffer.
+
+Trying to close the window with `CTRL-W :close` also fails.   Using
+`CTRL-W :close!` will close the window and make the buffer hidden.
+
+You can use `CTRL-W :hide` to close the terminal window and make the buffer
+hidden, the job keeps running.  The `:buffer` command can be used to turn the
+current window into a terminal window.  If there are unsaved changes this
+fails, use ! to force, as usual.
+
+To have a background job run without a window, and open the window when it's
+done, use options like this: >
+	:term ++hidden ++open make
+Note that the window will open at an unexpected moment, this will interrupt
+what you are doing.
+
+							*E947* *E948*
+So long as the job is running, the buffer is considered modified and Vim
+cannot be quit easily, see |abandon|.
+
+When the job has finished and no changes were made to the buffer: closing the
+window will wipe out the buffer.
+
+Before changes can be made to a terminal buffer, the 'modifiable' option must
+be set.  This is only possible when the job has finished.  At the first change
+the buffer will become a normal buffer and the highlighting is removed.
+You may want to change the buffer name with |:file| to be able to write, since
+the buffer name will still be set to the command.
+
+
+Resizing ~
+							*terminal-resizing*
+The size of the terminal can be in one of three modes:
+
+1. The 'termwinsize' option is empty: The terminal size follows the window
+   size.  The minimal size is 2 screen lines with 10 cells.
+
+2. The 'termwinsize' option is "rows*cols", where "rows" is the minimal number
+   of screen rows and "cols" is the minimal number of cells.
+
+3. The 'termwinsize' option is "rowsXcols" (where the x is upper or lower
+   case).  The terminal size is fixed to the specified number of screen lines
+   and cells.  If the window is bigger there will be unused empty space.
+
+If the window is smaller than the terminal size, only part of the terminal can
+be seen (the lower-left part).
+
+The |term_getsize()| function can be used to get the current size of the
+terminal.  |term_setsize()| can be used only when in the first or second mode,
+not when 'termwinsize' is "rowsXcols".
+
+
+Terminal-Job and Terminal-Normal mode ~
+						*Terminal-mode* *Terminal-Job*
+When the job is running the contents of the terminal is under control of the
+job.  That includes the cursor position.  Typed keys are sent to the job.
+The terminal contents can change at any time.  This is called Terminal-Job
+mode.
+
+Use CTRL-W N (or 'termwinkey' N) to switch to Terminal-Normal mode.  Now the
+contents of the terminal window is under control of Vim, the job output is
+suspended.  CTRL-\ CTRL-N does the same.
+
+Terminal-Job mode is where |:tmap| mappings are applied. Keys sent by
+|term_sendkeys()| are not subject to tmap, but keys from |feedkeys()| are.
+
+It is not possible to enter Insert mode from Terminal-Job mode.
+
+						*Terminal-Normal* *E946*
+In Terminal-Normal mode you can move the cursor around with the usual Vim
+commands, Visually mark text, yank text, etc.  But you cannot change the
+contents of the buffer.  The commands that would start insert mode, such as
+'i' and 'a', return to Terminal-Job mode.  The window will be updated to show
+the contents of the terminal. |:startinsert| is ineffective.
+
+In Terminal-Normal mode the statusline and window title show "(Terminal)".  If
+the job ends while in Terminal-Normal mode this changes to
+"(Terminal-finished)".
+
+When the job outputs lines in the terminal, such that the contents scrolls off
+the top, those lines are remembered and can be seen in Terminal-Normal mode.
+The number of lines is limited by the 'termwinscroll' option. When going over
+this limit, the first 10% of the scrolled lines are deleted and are lost.
+
+
+Cursor style ~
+							*terminal-cursor-style*
+By default the cursor in the terminal window uses a not blinking block.  The
+normal xterm escape sequences can be used to change the blinking state and the
+shape.  Once focus leaves the terminal window Vim will restore the original
+cursor.
+
+An exception is when xterm is started with the "-bc" argument, or another way
+that causes the cursor to blink.  This actually means that the blinking flag
+is inverted.  Since Vim cannot detect this, the terminal window cursor
+blinking will also be inverted.
+
+
+Session ~
+							*terminal-session*
+A terminal window will be restored when using a session file, if possible and
+wanted.
+
+If "terminal" was removed from 'sessionoptions' then no terminal windows will
+be restored.
+
+If the job in the terminal was finished the window will not be restored.
+
+If the terminal can be restored, the command that was used to open it will be
+used again.  To change this use the |term_setrestore()| function.  This can
+also be used to not restore a specific terminal by setting the command to
+"NONE".
+
+
+Special keys ~
+							*terminal-special-keys*
+Since the terminal emulator simulates an xterm, only escape sequences that
+both Vim and xterm recognize will be available in the terminal window.  If you
+want to pass on other escape sequences to the job running in the terminal you
+need to set up forwarding.  Example: >
+	tmap <expr> <Esc>]b SendToTerm("\<Esc>]b")
+	func SendToTerm(what)
+	  call term_sendkeys('', a:what)
+	  return ''
+	endfunc
+
+
+Unix ~
+							*terminal-unix*
+On Unix a pty is used to make it possible to run all kinds of commands.  You
+can even run Vim in the terminal!  That's used for debugging, see below.
+
+Environment variables are used to pass information to the running job:
+    TERM		the name of the terminal, from the 'term' option or
+			$TERM in the GUI; falls back to "xterm" if it does not
+			start with "xterm"
+    ROWS		number of rows in the terminal initially
+    LINES		same as ROWS
+    COLUMNS		number of columns in the terminal initially
+    COLORS		number of colors, 't_Co' (256*256*256 in the GUI)
+    VIM_SERVERNAME	v:servername
+    VIM_TERMINAL	v:version
+
+
+MS-Windows ~
+							*terminal-ms-windows*
+On MS-Windows winpty is used to make it possible to run all kind of commands.
+Obviously, they must be commands that run in a terminal, not open their own
+window.
+
+You need the following two files from winpty:
+
+    winpty.dll
+    winpty-agent.exe
+
+You can download them from the following page:
+
+    https://github.com/rprichard/winpty
+
+Just put the files somewhere in your PATH.  You can set the 'winptydll' option
+to point to the right file, if needed.  If you have both the 32-bit and 64-bit
+version, rename to winpty32.dll and winpty64.dll to match the way Vim was
+build.
+							*ConPTY*
+On more recent versions of MS-Windows 10 (beginning with the "October 2018
+Update"), winpty is no longer required. On those versions, |:terminal| will use
+Windows' built-in support for hosting terminal applications, "ConPTY".  When
+ConPTY is in use, there may be rendering artifacts regarding ambiguous-width
+characters. If you encounter any such issues, set 'termmode' to winpty (which
+you then must have instlled).
+
+Environment variables are used to pass information to the running job:
+    VIM_SERVERNAME	v:servername
+
+==============================================================================
+2. Terminal communication			 *terminal-communication*
+
+There are several ways to communicate with the job running in a terminal:
+- Use |term_sendkeys()| to send text and escape sequences from Vim to the job.
+- Use the JSON API to send encoded commands from the job to Vim.
+- Use the |client-server| mechanism. This works on machines with an X server
+  and on MS-Windows.
+
+
+Vim to job: term_sendkeys() ~
+							*terminal-to-job*
+This allows for remote controlling the job running in the terminal.  It is a
+one-way mechanism.  The job can update the display to signal back to Vim.
+For example, if a shell is running in a terminal, you can do: >
+	call term_sendkeys(buf, "ls *.java\<CR>")
+
+This requires for the job to be in the right state where it will do the right
+thing when receiving the keys.  For the above example, the shell must be
+waiting for a command to be typed.
+
+For a job that was written for the purpose, you can use the JSON API escape
+sequence in the other direction.  E.g.: >
+	call term_sendkeys(buf, "\<Esc>]51;["response"]\x07")
+
+
+Job to Vim: JSON API ~
+							*terminal-api*
+The job can send JSON to Vim, using a special escape sequence.  The JSON
+encodes a command that Vim understands.  Example of such a message: >
+	<Esc>]51;["drop", "README.md"]<07>
+
+The body is always a list, making it easy to find the end: ]<07>.
+The <Esc>]51;msg<07> sequence is reserved by xterm for "Emacs shell", which is
+similar to what we are doing here.
+
+Currently supported commands:
+
+	call {funcname} {argument}
+
+		Call a user defined function with {argument}.
+		The function is called with two arguments: the buffer number
+		of the terminal and {argument}, the decoded JSON argument. 
+		The function name must start with "Tapi_" to avoid
+		accidentally calling a function not meant to be used for the
+		terminal API.
+		The user function should sanity check the argument.
+		The function can use |term_sendkeys()| to send back a reply.
+		Example in JSON: >
+			["call", "Tapi_Impression", ["play", 14]]
+<		Calls a function defined like this: >
+			function Tapi_Impression(bufnum, arglist)
+			  if len(a:arglist) == 2
+			    echomsg "impression " . a:arglist[0]
+			    echomsg "count " . a:arglist[1]
+			  endif
+			endfunc
+<		Output from `:echo` may be erased by a redraw, use `:echomsg`
+		to be able to see it with `:messages`.
+
+	drop {filename} [options]
+
+		Let Vim open a file, like the `:drop` command.  If {filename}
+		is already open in a window, switch to that window.  Otherwise
+		open a new window to edit {filename}.
+		Note that both the job and Vim may change the current
+		directory, thus it's best to use the full path.
+
+		[options] is only used when opening a new window.  If present,
+		it must be a Dict.  Similarly to |++opt|, These entries are recognized:
+		  "ff"		file format: "dos", "mac" or "unix"
+		  "fileformat"	idem
+		  "enc"		overrides 'fileencoding'
+		  "encoding"	idem
+		  "bin"		sets 'binary'
+		  "binary"	idem
+		  "nobin"	resets 'binary'
+		  "nobinary"	idem
+		  "bad"		specifies behavior for bad characters, see
+				|++bad|
+
+		Example in JSON: >
+			["drop", "path/file.txt", {"ff": "dos"}]
+
+A trick to have Vim send this escape sequence: >
+	exe "set t_ts=\<Esc>]51; t_fs=\x07"
+	let &titlestring = '["call","Tapi_TryThis",["hello",123]]'
+	redraw
+	set t_ts& t_fs&
+
+Rationale: Why not allow for any command or expression?  Because that might
+create a security problem.
+
+
+Using the client-server feature ~
+						*terminal-client-server*
+This only works when v:servername is not empty.  If needed you can set it,
+before opening the terminal, with: >
+	call remote_startserver('vim-server')
+
+$VIM_SERVERNAME is set in the terminal to pass on the server name.
+
+In the job you can then do something like: >
+	vim --servername $VIM_SERVERNAME --remote +123 some_file.c
+This will open the file "some_file.c" and put the cursor on line 123.
+
+==============================================================================
+3. Remote testing					*terminal-testing*
+
+Most Vim tests execute a script inside Vim.  For some tests this does not
+work, running the test interferes with the code being tested.  To avoid this
+Vim is executed in a terminal window.  The test sends keystrokes to it and
+inspects the resulting screen state.
+
+Functions ~
+
+|term_sendkeys()|	send keystrokes to a terminal (not subject to tmap)
+|term_wait()|		wait for screen to be updated
+|term_scrape()|		inspect terminal screen
+
+
+==============================================================================
+4. Diffing screen dumps					*terminal-diff*
+
+In some cases it can be bothersome to test that Vim displays the right
+characters on the screen.  E.g. with syntax highlighting.  To make this
+simpler it is possible to take a screen dump of a terminal and compare it to
+an expected screen dump.
+
+Vim uses the window size, text, color and other attributes as displayed.  The
+Vim screen size, font and other properties do not matter.  Therefore this
+mechanism is portable across systems.  A conventional screenshot would reflect
+all differences, including font size and family.
+
+
+Writing a screen dump test for Vim ~
+							*terminal-dumptest*
+For an example see the Test_syntax_c() function in
+src/testdir/test_syntax.vim.  The main parts are:
+- Write a file you want to test with. This is useful for testing syntax
+  highlighting.  You can also start Vim with en empty buffer.
+- Run Vim in a terminal with a specific size.  The default is 20 lines of 75
+  characters.  This makes sure the dump is always this size.  The function
+  RunVimInTerminal() takes care of this.  Pass it the arguments for the Vim
+  command.
+- Send any commands to Vim using |term_sendkeys()|.  For example: >
+	call term_sendkeys(buf, ":echo &lines &columns\<CR>")
+- Check that the screen is now in the expected state, using
+  VerifyScreenDump().  This expects the reference screen dump to be in the
+  src/testdir/dumps/ directory.  Pass the name without ".dump".  It is
+  recommended to use the name of the test function and a sequence number, so
+  that we know what test is using the file.
+- Repeat sending commands and checking the state.
+- Finally stop Vim by calling StopVimInTerminal().
+
+The first time you do this you won't have a screen dump yet.  Create an empty
+file for now, e.g.: >
+	touch src/testdir/dumps/Test_function_name_01.dump
+
+The test will then fail, giving you the command to compare the reference dump
+and the failed dump, e.g.: >
+	call term_dumpdiff("Test_func.dump.failed", "dumps/Test_func.dump")
+
+Use this command in Vim, with the current directory set to src/testdir.
+Once you are satisfied with the test, move the failed dump in place of the
+reference: >
+	:!mv Test_func.dump.failed dumps/Test_func.dump
+
+
+Creating a screen dump ~
+							*terminal-screendump*
+
+To create the screen dump, run Vim (or any other program) in a terminal and
+make it show the desired state.  Then use the |term_dumpwrite()| function to
+create a screen dump file.  For example: >
+	:call term_dumpwrite(77, "mysyntax.dump")
+
+Here "77" is the buffer number of the terminal.  Use `:ls!` to see it.
+
+You can view the screen dump with |term_dumpload()|: >
+	:call term_dumpload("mysyntax.dump")
+
+To verify that Vim still shows exactly the same screen, run Vim again with
+exactly the same way to show the desired state.  Then create a screen dump
+again, using a different file name: >
+	:call term_dumpwrite(88, "test.dump")
+
+To assert that the files are exactly the same use |assert_equalfile()|: >
+	call assert_equalfile("mysyntax.dump", "test.dump")
+
+If there are differences then v:errors will contain the error message.
+
+
+Comparing screen dumps ~
+						*terminal-diffscreendump*
+
+|assert_equalfile()| does not make it easy to see what is different.
+To spot the problem use |term_dumpdiff()|: >
+	call term_dumpdiff("mysyntax.dump", "test.dump")
+
+This will open a window consisting of three parts:
+1.  The contents of the first dump
+2.  The difference between the first and second dump
+3.  The contents of the second dump
+
+You can usually see what differs in the second part.  Use the 'ruler' to
+relate it to the position in the first or second dump.  Letters indicate the
+kind of difference:
+	X	different character
+	>	cursor in first but not in second
+	<	cursor in second but not in first
+	w	character width differs (single vs double width)
+	f	foreground color differs
+	b	background color differs
+	a	attribute differs (bold, underline, reverse, etc.)
+	?	character missing in both
+	+	character missing in first
+	-	character missing in second
+
+Alternatively, press "s" to swap the first and second dump. Do this several
+times so that you can spot the difference in the context of the text.
+
+==============================================================================
+5. Debugging				*terminal-debug* *terminal-debugger*
+
+The Terminal debugging plugin can be used to debug a program with gdb and view
+the source code in a Vim window.  Since this is completely contained inside
+Vim this also works remotely over an ssh connection.
+
+When the |+terminal| feature is missing, the plugin will use the "prompt"
+buffer type, if possible.  The running program will then use a newly opened
+terminal window.  See |termdebug-prompt| below for details.
+
+
+Starting ~
+							*termdebug-starting*
+Load the plugin with this command: >
+	packadd termdebug
+<							*:Termdebug*
+To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
+command name, for example: >
+	:Termdebug vim
+
+This opens two windows:
+
+gdb window	A terminal window in which "gdb vim" is executed.  Here you
+		can directly interact with gdb.  The buffer name is "!gdb".
+
+program window	A terminal window for the executed program.  When "run" is
+		used in gdb the program I/O will happen in this window, so
+		that it does not interfere with controlling gdb.  The buffer
+		name is "gdb program".
+
+The current window is used to show the source code.  When gdb pauses the
+source file location will be displayed, if possible.  A sign is used to
+highlight the current position, using highlight group debugPC.	 
+
+If the buffer in the current window is modified, another window will be opened
+to display the current gdb position.  You can use `:Winbar` to add a window
+toolbar there.
+
+Focus the terminal of the executed program to interact with it.  This works
+the same as any command running in a terminal window.
+
+When the debugger ends, typically by typing "quit" in the gdb window, the two
+opened windows are closed.
+
+Only one debugger can be active at a time.
+							*:TermdebugCommand*
+If you want to give specific commands to the command being debugged, you can
+use the `:TermdebugCommand` command followed by the command name and
+additional parameters. >
+	:TermdebugCommand vim --clean -c ':set nu'
+
+Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
+argument to start the command right away, without pausing at the gdb window
+(and cursor will be in the debugged window).  For example: >
+	:TermdebugCommand! vim --clean
+
+To attach gdb to an already running executable or use a core file, pass extra
+arguments.  E.g.: >
+	:Termdebug vim core
+	:Termdebug vim 98343
+
+If no argument is given, you'll end up in a gdb window, in which you need to
+specify which command to run using e.g. the gdb `file` command.
+
+
+Example session ~
+							*termdebug-example*
+Start in the Vim "src" directory and build Vim: >
+	% make
+Start Vim: >
+	% ./vim
+Load the termdebug plugin and start debugging Vim: >
+	:packadd termdebug
+	:Termdebug vim
+You should now have three windows:
+    source  - where you started, has a window toolbar with buttons
+    gdb	    - you can type gdb commands here
+    program - the executed program will use this window
+
+You can use CTRL-W CTRL-W or the mouse to move focus between windows.
+Put focus on the gdb window and type: >
+	break ex_help
+	run
+Vim will start running in the program window. Put focus there and type: >
+	:help gui
+Gdb will run into the ex_help breakpoint.  The source window now shows the 
+ex_cmds.c file.  A red "1 " marker will appear in the signcolumn where the
+breakpoint was set.  The line where the debugger stopped is highlighted.  You
+can now step through the program.  Let's use the mouse: click on the "Next"
+button in the window toolbar.  You will see the highlighting move as the
+debugger executes a line of source code.
+
+Click "Next" a few times until the for loop is highlighted.  Put the cursor on
+the end of "eap->arg", then click "Eval" in the toolbar.  You will see this
+displayed:
+	"eap->arg": 0x555555e68855 "gui" ~
+This way you can inspect the value of local variables.  You can also focus the
+gdb window and use a "print" command, e.g.: >
+	print *eap
+If mouse pointer movements are working, Vim will also show a balloon when the
+mouse rests on text that can be evaluated by gdb.
+
+Now go back to the source window and put the cursor on the first line after
+the for loop, then type: >
+	:Break
+You will see a ">>" marker appear, this indicates the new breakpoint.  Now
+click "Cont" in the toolbar and the code until the breakpoint will be
+executed.
+
+You can type more advanced commands in the gdb window.  For example, type: >
+	watch curbuf
+Now click "Cont" in the toolbar (or type "cont" in the gdb window). Execution
+will now continue until the value of "curbuf" changes, which is in do_ecmd().
+To remove this watchpoint again type in the gdb window: >
+	delete 3
+
+You can see the stack by typing in the gdb window: >
+	where
+Move through the stack frames, e.g. with: >
+	frame 3
+The source window will show the code, at the point where the call was made to
+a deeper level.
+
+
+Stepping through code ~
+							*termdebug-stepping*
+Put focus on the gdb window to type commands there.  Some common ones are:
+- CTRL-C	interrupt the program
+- next		execute the current line and stop at the next line
+- step		execute the current line and stop at the next statement,
+		entering functions
+- finish	execute until leaving the current function
+- where		show the stack
+- frame N	go to the Nth stack frame
+- continue	continue execution
+
+						*:Run* *:Arguments*
+In the window showing the source code these commands can be used to control
+gdb:
+ `:Run` [args]	    run the program with [args] or the previous arguments
+ `:Arguments` {args}  set arguments for the next `:Run`
+
+ *:Break*	set a breakpoint at the current line; a sign will be displayed
+ *:Clear*	delete the breakpoint at the current line
+
+ *:Step*	execute the gdb "step" command
+ *:Over*	execute the gdb "next" command (`:Next` is a Vim command)
+ *:Finish*	execute the gdb "finish" command
+ *:Continue*	execute the gdb "continue" command
+ *:Stop*	interrupt the program
+
+If 'mouse' is set the plugin adds a window toolbar with these entries:
+  Step		`:Step`
+  Next		`:Over`
+  Finish	`:Finish`
+  Cont		`:Continue`
+  Stop		`:Stop`
+  Eval		`:Evaluate`
+This way you can use the mouse to perform the most common commands.  You need
+to have the 'mouse' option set to enable mouse clicks.
+								*:Winbar*
+You can add the window toolbar in other windows you open with: >
+  :Winbar
+
+If gdb stops at a source line and there is no window currently showing the
+source code, a new window will be created for the source code.  This also
+happens if the buffer in the source code window has been modified and can't be
+abandoned.
+
+Gdb gives each breakpoint a number.  In Vim the number shows up in the sign
+column, with a red background.  You can use these gdb commands:
+- info break	list breakpoints
+- delete N	delete breakpoint N
+You can also use the `:Clear` command if the cursor is in the line with the
+breakpoint, or use the "Clear breakpoint" right-click menu entry.
+
+
+Inspecting variables ~
+					*termdebug-variables* *:Evaluate*
+ `:Evaluate`	    evaluate the expression under the cursor
+ `K`		    same
+ `:Evaluate` {expr}   evaluate {expr}
+ `:'<,'>Evaluate`     evaluate the Visually selected text
+
+This is similar to using "print" in the gdb window.
+You can usually shorten `:Evaluate` to `:Ev`.
+
+
+Other commands ~
+							*termdebug-commands*
+ *:Gdb*	     jump to the gdb window
+ *:Program*    jump to the window with the running program
+ *:Source*     jump to the window with the source code, create it if there
+	     isn't one
+
+
+Prompt mode ~
+						*termdebug-prompt*
+When the |+terminal| feature is not supported and on MS-Windows, gdb will run
+in a buffer with 'buftype' set to "prompt".  This works slightly differently:
+- The gdb window will be in Insert mode while typing commands.  Go to Normal
+  mode with <Esc>, then you can move around in the buffer, copy/paste, etc.
+  Go back to editing the gdb command with any command that starts Insert mode,
+  such as `a` or `i`.
+- The program being debugged will run in a separate window.  On MS-Windows
+  this is a new console window.  On Unix, if the |+terminal| feature is
+  available a Terminal window will be opened to run the debugged program in.
+
+						*termdebug_use_prompt*
+Prompt mode can be used even when the |+terminal| feature is present with: >
+	let g:termdebug_use_prompt = 1
+
+
+Communication ~
+						*termdebug-communication*
+There is another, hidden, buffer, which is used for Vim to communicate with
+gdb.  The buffer name is "gdb communication".  Do not delete this buffer, it
+will break the debugger.
+
+Gdb has some weird behavior, the plugin does its best to work around that.
+For example, after typing "continue" in the gdb window a CTRL-C can be used to
+interrupt the running program.  But after using the MI command
+"-exec-continue"  pressing CTRL-C does not interrupt.  Therefore you will see
+"continue" being used for the `:Continue` command, instead of using the
+communication channel.
+
+
+Customizing ~
+
+GDB command						 *termdebug-customizing*
+
+To change the name of the gdb command, set the "termdebugger" variable before
+invoking `:Termdebug`: >
+	let termdebugger = "mygdb"
+<							*gdb-version*
+Only debuggers fully compatible with gdb will work.  Vim uses the GDB/MI
+interface.  The "new-ui" command  requires gdb version 7.12 or later.  if you
+get this error:
+	Undefined command: "new-ui". Try "help".~
+Then your gdb is too old.
+
+
+Colors						*hl-debugPC* *hl-debugBreakpoint*
+
+The color of the signs can be adjusted with these highlight groups:
+- debugPC		the current position
+- debugBreakpoint	a breakpoint
+
+The defaults are, when 'background' is "light":
+  hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
+  hi debugBreakpoint term=reverse ctermbg=red guibg=red
+
+When 'background' is "dark":
+  hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
+  hi debugBreakpoint term=reverse ctermbg=red guibg=red
+
+
+Shorcuts						*termdebug_shortcuts*
+
+You can define your own shortcuts (mappings) to control gdb, that can work in
+any window, using the TermDebugSendCommand() function.  Example: >
+	map ,w :call TermDebugSendCommand('where')<CR>
+The argument is the gdb command.
+
+
+Popup menu						*termdebug_popup*
+
+By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds
+these entries to the popup menu:
+	Set breakpoint		`:Break`
+	Clear breakpoint	`:Clear`
+	Evaluate		`:Evaluate`
+If you don't want this then disable it with: >
+	let g:termdebug_popup = 0
+
+
+Vim window width						*termdebug_wide*
+
+To change the width of the Vim window when debugging starts, and use a
+vertical split: >
+  let g:termdebug_wide = 163
+This will set &columns to 163 when `:Termdebug` is used.  The value is restored
+when quitting the debugger.
+If g:termdebug_wide is set and &columns is already larger than
+g:termdebug_wide then a vertical split will be used without changing &columns.
+Set it to 1 to get a vertical split without every changing &columns (useful
+for when the terminal can't be resized by Vim).
+
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: