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

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

1 files changed, 1196 insertions, 0 deletions

diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
new file mode 100644
index 0000000..546b0bf
--- /dev/null
+++ b/runtime/doc/term.txt
@@ -0,0 +1,1196 @@
+*term.txt*      For Vim version 9.1.  Last change: 2023 Dec 09
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Terminal information					*terminal-info*
+
+Vim uses information about the terminal you are using to fill the screen and
+recognize what keys you hit.  If this information is not correct, the screen
+may be messed up or keys may not be recognized.  The actions which have to be
+performed on the screen are accomplished by outputting a string of
+characters.  Special keys produce a string of characters.  These strings are
+stored in the terminal options, see |terminal-options|.
+
+NOTE: Most of this is not used when running the |GUI|.
+
+1. Startup			|startup-terminal|
+2. Terminal options		|terminal-options|
+3. Window size			|window-size|
+4. Slow and fast terminals	|slow-fast-terminal|
+5. Using the mouse		|mouse-using|
+
+==============================================================================
+1. Startup						*startup-terminal*
+
+When Vim is started a default terminal type is assumed.  For the Amiga this is
+a standard CLI window, for MS-Windows the pc terminal, for Unix an ansi
+terminal.  A few other terminal types are always available, see below
+|builtin-terms|.
+
+You can give the terminal name with the '-T' Vim argument.  If it is not given
+Vim will try to get the name from the TERM environment variable.
+
+				*termcap* *terminfo* *E557* *E558* *E559*
+On Unix the terminfo database or termcap file is used.  This is referred to as
+"termcap" in all the documentation.  At compile time, when running configure,
+the choice whether to use terminfo or termcap is done automatically.  When
+running Vim the output of ":version" will show |+terminfo| if terminfo is
+used.  Also see |xterm-screens|.
+
+On non-Unix systems a termcap is only available if Vim was compiled with
+TERMCAP defined.
+
+					*builtin-terms* *builtin_terms*
+A number of builtin terminals are available.  Since patch 9.0.0280 there is no
+difference between Vim versions.  You can see a list of available builtin
+terminals in the error message you get for `:set term=xxx` (when not running
+the GUI).  Also see |++builtin_terms|.
+
+If the termcap code is included Vim will try to get the strings for the
+terminal you are using from the termcap file and the builtin termcaps.  Both
+are always used, if an entry for the terminal you are using is present.  Which
+one is used first depends on the 'ttybuiltin' option:
+
+'ttybuiltin' on		1: builtin termcap	2: external termcap
+'ttybuiltin' off	1: external termcap	2: builtin termcap
+
+If an option is missing in one of them, it will be obtained from the other
+one.  If an option is present in both, the one first encountered is used.
+
+Which external termcap file is used varies from system to system and may
+depend on the environment variables "TERMCAP" and "TERMPATH".  See "man
+tgetent".
+
+Settings depending on terminal			*term-dependent-settings*
+
+If you want to set options or mappings, depending on the terminal name, you
+can do this best in your .vimrc.  Example: >
+
+   if &term == "xterm"
+     ... xterm maps and settings ...
+   elseif &term =~ "vt10."
+     ... vt100, vt102 maps and settings ...
+   endif
+<
+						*raw-terminal-mode*
+For normal editing the terminal will be put into "raw" mode.  The strings
+defined with 't_ti', 't_TI' and 't_ks' will be sent to the terminal.  Normally
+this puts the terminal in a state where the termcap codes are valid and
+activates the cursor and function keys.
+When Vim exits the terminal will be put back into the mode it was before Vim
+started.  The strings defined with 't_te', 't_TE' and 't_ke' will be sent to
+the terminal.  On the Amiga, with commands that execute an external command
+(e.g., "!!"), the terminal will be put into Normal mode for a moment.  This
+means that you can stop the output to the screen by hitting a printing key.
+Output resumes when you hit <BS>.
+
+Note: When 't_ti' is not empty, Vim assumes that it causes switching to the
+alternate screen.  This may slightly change what happens when executing a
+shell command or exiting Vim.  To avoid this use 't_TI' and 't_TE' (but make
+sure to add to them, not overwrite).
+
+Vim will try to detect what keyboard protocol the terminal is using with the
+'t_RK' termcap entry.  This is sent after 't_TI', but only when there is no
+work to do (no typeahead and no pending commands).  That is to avoid the
+response to end up in a shell command or arrive after Vim exits.
+
+						*xterm-bracketed-paste*
+When the 't_BE' option is set then 't_BE' will be sent to the
+terminal when entering "raw" mode and 't_BD' when leaving "raw" mode.  The
+terminal is then expected to put 't_PS' before pasted text and 't_PE' after
+pasted text.  This way Vim can separate text that is pasted from characters
+that are typed.  The pasted text is handled like when the middle mouse button
+is used, it is inserted literally and not interpreted as commands.
+
+Please note: while bracketed paste is trying to prevent nasty side-effects
+from pasting (like the CTRL-C or <ESC> key), it's not a guaranteed security
+measure because different terminals may implement this mode slightly
+differently.  You should still be careful with what you paste into Vim.
+
+When the cursor is in the first column, the pasted text will be inserted
+before it.  Otherwise the pasted text is appended after the cursor position.
+This means one cannot paste after the first column.  Unfortunately Vim does
+not have a way to tell where the mouse pointer was.
+
+Note that in some situations Vim will not recognize the bracketed paste and
+you will get the raw text.  In other situations Vim will only get the first
+pasted character and drop the rest, e.g. when using the "r" command.  If you
+have a problem with this, disable bracketed paste by putting this in your
+.vimrc: >
+	set t_BE=
+If this is done while Vim is running the 't_BD' will be sent to the terminal
+to disable bracketed paste.
+
+If |t_PS| or |t_PE| is not set, then |t_BE| will not be used.  This is to make
+sure that bracketed paste is not enabled when the escape codes surrounding
+pasted text cannot be recognized.
+
+Note: bracketed paste mode will be disabled, when the 'esckeys' option is not
+set (also when the 'compatible' option is set).
+
+If your terminal supports bracketed paste, but the options are not set
+automatically, you can try using something like this: >
+
+	if &term =~ "screen"
+	  let &t_BE = "\e[?2004h"
+	  let &t_BD = "\e[?2004l"
+	  exec "set t_PS=\e[200~"
+	  exec "set t_PE=\e[201~"
+	endif
+
+The terminfo entries "BE", "BD", "PS" and "PE" were added in ncurses version
+6.4, early 2023, for some terminals.  If you have this version then you may
+not have to manually configure your terminal.
+
+							*tmux-integration*
+If you experience issues when running Vim inside tmux, here are a few hints.
+You can comment-out parts if something doesn't work (it may depend on the
+terminal that tmux is running in): >
+
+    if !has('gui_running') && &term =~ '^\%(screen\|tmux\)'
+        " Better mouse support, see  :help 'ttymouse'
+        set ttymouse=sgr
+
+        " Enable true colors, see  :help xterm-true-color
+        let &termguicolors = v:true
+        let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
+        let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
+
+        " Enable bracketed paste mode, see  :help xterm-bracketed-paste
+        let &t_BE = "\<Esc>[?2004h"
+        let &t_BD = "\<Esc>[?2004l"
+        let &t_PS = "\<Esc>[200~"
+        let &t_PE = "\<Esc>[201~"
+
+        " Enable focus event tracking, see  :help xterm-focus-event
+        let &t_fe = "\<Esc>[?1004h"
+        let &t_fd = "\<Esc>[?1004l"
+	execute "set <FocusGained>=\<Esc>[I"
+        execute "set <FocusLost>=\<Esc>[O"
+
+        " Enable modified arrow keys, see  :help arrow_modifiers
+        execute "silent! set <xUp>=\<Esc>[@;*A"
+        execute "silent! set <xDown>=\<Esc>[@;*B"
+        execute "silent! set <xRight>=\<Esc>[@;*C"
+        execute "silent! set <xLeft>=\<Esc>[@;*D"
+    endif
+<
+							*cs7-problem*
+Note: If the terminal settings are changed after running Vim, you might have
+an illegal combination of settings.  This has been reported on Solaris 2.5
+with "stty cs8 parenb", which is restored as "stty cs7 parenb".  Use
+"stty cs8 -parenb -istrip" instead, this is restored correctly.
+
+Some termcap entries are wrong in the sense that after sending 't_ks' the
+cursor keys send codes different from the codes defined in the termcap.  To
+avoid this you can set 't_ks' (and 't_ke') to empty strings.  This must be
+done during initialization (see |initialization|), otherwise it's too late.
+
+Some termcap entries assume that the highest bit is always reset.  For
+example: The cursor-up entry for the Amiga could be ":ku=\E[A:".  But the
+Amiga really sends "\233A".  This works fine if the highest bit is reset,
+e.g., when using an Amiga over a serial line.  If the cursor keys don't work,
+try the entry ":ku=\233A:".
+
+Some termcap entries have the entry ":ku=\E[A:".  But the Amiga really sends
+"\233A".  On output "\E[" and "\233" are often equivalent, on input they
+aren't.  You will have to change the termcap entry, or change the key code with
+the :set command to fix this.
+
+Many cursor key codes start with an <Esc>.  Vim must find out if this is a
+single hit of the <Esc> key or the start of a cursor key sequence.  It waits
+for a next character to arrive.  If it does not arrive within one second a
+single <Esc> is assumed.  On very slow systems this may fail, causing cursor
+keys not to work sometimes.  If you discover this problem reset the 'timeout'
+option.  Vim will wait for the next character to arrive after an <Esc>.  If
+you want to enter a single <Esc> you must type it twice.  Resetting the
+'esckeys' option avoids this problem in Insert mode, but you lose the
+possibility to use cursor and function keys in Insert mode.
+
+On the Amiga the recognition of window resizing is activated only when the
+terminal name is "amiga" or "builtin_amiga".
+
+Some terminals have confusing codes for the cursor keys.  The televideo 925 is
+such a terminal.  It sends a CTRL-H for cursor-left.  This would make it
+impossible to distinguish a backspace and cursor-left.  To avoid this problem
+CTRL-H is never recognized as cursor-left.
+
+					*vt100-cursor-keys* *xterm-cursor-keys*
+Other terminals (e.g., vt100 and xterm) have cursor keys that send <Esc>OA,
+<Esc>OB, etc.  Unfortunately these are valid commands in insert mode: Stop
+insert, Open a new line above the new one, start inserting 'A', 'B', etc.
+Instead of performing these commands Vim will erroneously recognize this typed
+key sequence as a cursor key movement.  To avoid this and make Vim do what you
+want in either case you could use these settings: >
+	:set notimeout		" don't timeout on mappings
+	:set ttimeout		" do timeout on terminal key codes
+	:set timeoutlen=100	" timeout after 100 msec
+This requires the key-codes to be sent within 100 msec in order to recognize
+them as a cursor key.  When you type you normally are not that fast, so they
+are recognized as individual typed commands, even though Vim receives the same
+sequence of bytes.
+
+				*vt100-function-keys* *xterm-function-keys*
+An xterm can send function keys F1 to F4 in two modes: vt100 compatible or
+not.  Because Vim may not know what the xterm is sending, both types of keys
+are recognized.  The same happens for the <Home> and <End> keys.
+			normal			vt100 ~
+	<F1>	t_k1	<Esc>[11~	<xF1>	<Esc>OP	    *<xF1>-xterm*
+	<F2>	t_k2	<Esc>[12~	<xF2>	<Esc>OQ	    *<xF2>-xterm*
+	<F3>	t_k3	<Esc>[13~	<xF3>	<Esc>OR	    *<xF3>-xterm*
+	<F4>	t_k4	<Esc>[14~	<xF4>	<Esc>OS	    *<xF4>-xterm*
+	<Home>	t_kh	<Esc>[7~	<xHome>	<Esc>OH	    *<xHome>-xterm*
+	<End>	t_@7	<Esc>[4~	<xEnd>	<Esc>OF	    *<xEnd>-xterm*
+
+When Vim starts, <xF1> is mapped to <F1>, <xF2> to <F2> etc.  This means that
+by default both codes do the same thing.  If you make a mapping for <xF2>,
+because your terminal does have two keys, the default mapping is overwritten,
+thus you can use the <F2> and <xF2> keys for something different.
+
+							*xterm-shifted-keys*
+Newer versions of xterm support shifted function keys and special keys.  Vim
+recognizes most of them.  Use ":set termcap" to check which are supported and
+what the codes are.  Mostly these are not in a termcap, they are only
+supported by the builtin_xterm termcap.
+
+							*xterm-modifier-keys*
+Newer versions of xterm support Alt and Ctrl for most function keys.  To avoid
+having to add all combinations of Alt, Ctrl and Shift for every key a special
+sequence is recognized at the end of a termcap entry: ";*X".  The "X" can be
+any character, often '~' is used.  The ";*" stands for an optional modifier
+argument.  ";2" is Shift, ";3" is Alt, ";5" is Ctrl and ";9" is Meta (when
+it's different from Alt).  They can be combined.  Examples: >
+	:set <F8>=^[[19;*~
+	:set <Home>=^[[1;*H
+Another speciality about these codes is that they are not overwritten by
+another code.  That is to avoid that the codes obtained from xterm directly
+|t_RV| overwrite them.
+
+Another special value is a termcap entry ending in "@;*X".  This is for cursor
+keys, which either use "CSI X" or "CSI 1 ; modifier X".  Thus the "@"
+stands for either "1" if a modifier follows, or nothing.
+							*arrow_modifiers*
+Several terminal emulators (alacritty, gnome, konsole, etc.) send special
+codes for keys with modifiers, but these do not have an entry in the
+termcap/terminfo database.  You can make them work by adding a few lines in
+your vimrc.  For example, to make the Control modifier work with arrow keys
+for the gnome terminal: >
+	if &term =~ 'gnome'
+	   execute "set <xUp>=\<Esc>[@;*A"
+	   execute "set <xDown>=\<Esc>[@;*B"
+	   execute "set <xRight>=\<Esc>[@;*C"
+	   execute "set <xLeft>=\<Esc>[@;*D"
+	endif
+<							*xterm-scroll-region*
+The default termcap entry for xterm on Sun and other platforms does not
+contain the entry for scroll regions.  Add ":cs=\E[%i%d;%dr:" to the xterm
+entry in /etc/termcap and everything should work.
+
+							*xterm-end-home-keys*
+On some systems (at least on FreeBSD with XFree86 3.1.2) the codes that the
+<End> and <Home> keys send contain a <Nul> character.  To make these keys send
+the proper key code, add these lines to your ~/.Xdefaults file:
+
+*VT100.Translations:		#override \n\
+		<Key>Home: string("0x1b") string("[7~") \n\
+		<Key>End: string("0x1b") string("[8~")
+
+						*xterm-8bit* *xterm-8-bit*
+Xterm can be run in a mode where it uses 8-bit escape sequences.  The CSI code
+is used instead of <Esc>[.  The advantage is that an <Esc> can quickly be
+recognized in Insert mode, because it can't be confused with the start of a
+special key.
+For the builtin termcap entries, Vim checks if the 'term' option contains
+"8bit" anywhere.  It then uses 8-bit characters for the termcap entries, the
+mouse and a few other things.  You would normally set $TERM in your shell to
+"xterm-8bit" and Vim picks this up and adjusts to the 8-bit setting
+automatically.
+When Vim receives a response to the |t_RV| (request version) sequence and it
+starts with CSI, it assumes that the terminal is in 8-bit mode and will
+convert all key sequences to their 8-bit variants.
+
+						*xterm-terminfo-entries*
+For some time the terminfo entries were insufficient to describe all the
+features that Vim can use.  The builtin xterm termcap entries did have these,
+with the result that several terminals that were similar enough to xterm took
+advantage of these by prefixing "xterm-" to the terminal name in $TERM.
+
+This leads to problems, because quite often these terminals are not 100%
+compatible with xterm.  At the start of 2023 several entries have been added
+to the terminfo database to make it possible to use these features without
+using the "xterm" workaround.  These are the relevant entries (so far):
+
+	name	xterm value	description ~
+	RV	"\033[>c"	Request version |t_RV|
+
+	BE	"\033[?2004h"	enable bracketed paste mode |t_BE|
+	BD	"\033[?2004l"	disable bracketed paste mode |t_BD|
+	PS	"\033[200~"	pasted text start |t_PS|
+	PE	"\033[201~"	pasted text end |t_PE|
+
+	XM	"\033[?1006;1004;1000%?%p1%{1}%=%th%el%;"
+				mouse enable / disable |t_XM|
+	FE	"\033[?1004h"	enable focus event tracking |t_fe|
+	FD	"\033[?1004l"	disable focus event tracking |t_fd|
+
+The "XM" entry includes "1006" to enable SGR style mouse reporting.  This
+supports columns above 223.  It also includes "1004" which enables focus
+reporting.
+Note: As of 2023, the "1004" is currently not used by Vim itself, instead
+it is recommended to set focus reporting independently of mouse tracking by
+the |t_fe| and |t_fd| entries, as ncurses also starts to use with the latest
+versions (and will then also end up in terminfo/termcap).
+
+						*xterm-kitty* *kitty-terminal*
+The Kitty terminal is a special case.  Mainly because it works differently
+from most other terminals, but also because, instead of trying the fit in and
+make it behave like other terminals by default, it dictates how applications
+need to work when using Kitty.  This makes it very difficult for Vim to work
+in a Kitty terminal.  Some exceptions have been hard coded, but it is not at
+all nice to have to make exceptions for one specific terminal.
+
+One of the problems is that the value for $TERM is set to "xterm-kitty".  For
+Vim this is an indication that the terminal is xterm-compatible and the
+builtin xterm termcap entries should be used.  Many other terminals depend on
+this.  However, Kitty is not fully xterm compatible.  The author suggested to
+ignore the "xterm-" prefix and use the terminfo entry anyway, so that is what
+happens now, the builtin xterm termcap entries are not used.  However, the
+t_RV is set, otherwise other things would not work, such as automatically
+setting 'ttymouse' to "sgr" (at least until |t_XM| is being used for this).
+
+It is not clear why kitty sets $TERM to "xterm-kitty", the terminal isn't
+really xterm compatible.  "kitty" would be more appropriate, but a terminfo
+entry with that name is not widespread.
+
+Note that using the kitty keyboard protocol is a separate feature, see
+|kitty-keyboard-protocol|.
+
+
+==============================================================================
+2. Terminal options		*terminal-options* *termcap-options* *E436*
+
+The terminal options can be set just like normal options.  But they are not
+shown with the ":set all" command.  Instead use ":set termcap".
+
+It is always possible to change individual strings by setting the
+appropriate option.  For example: >
+	:set t_ce=^V^[[K	(CTRL-V, <Esc>, [, K)
+
+The options are listed below.  The associated termcap code is always equal to
+the last two characters of the option name.  Only one termcap code is
+required: Cursor motion, 't_cm'.
+
+The options 't_da', 't_db', 't_ms', 't_xs', 't_xn' represent flags in the
+termcap.  When the termcap flag is present, the option will be set to "y".
+But any non-empty string means that the flag is set.  An empty string means
+that the flag is not set.  't_CS' works like this too, but it isn't a termcap
+flag.
+
+OUTPUT CODES						*terminal-output-codes*
+	option	meaning	~
+
+	t_AB	set background color (ANSI)			*t_AB* *'t_AB'*
+	t_AF	set foreground color (ANSI)			*t_AF* *'t_AF'*
+	t_AL	add number of blank lines			*t_AL* *'t_AL'*
+	t_al	add new blank line				*t_al* *'t_al'*
+	t_bc	backspace character				*t_bc* *'t_bc'*
+	t_cd	clear to end of screen				*t_cd* *'t_cd'*
+	t_ce	clear to end of line				*t_ce* *'t_ce'*
+	t_cl	clear screen					*t_cl* *'t_cl'*
+	t_cm	cursor motion (required!)		  *E437* *t_cm* *'t_cm'*
+	t_Co	number of colors				*t_Co* *'t_Co'*
+	t_CS	if non-empty, cursor relative to scroll region	*t_CS* *'t_CS'*
+	t_cs	define scrolling region				*t_cs* *'t_cs'*
+	t_CV	define vertical scrolling region		*t_CV* *'t_CV'*
+	t_da	if non-empty, lines from above scroll down	*t_da* *'t_da'*
+	t_db	if non-empty, lines from below scroll up	*t_db* *'t_db'*
+	t_DL	delete number of lines				*t_DL* *'t_DL'*
+	t_dl	delete line					*t_dl* *'t_dl'*
+	t_fs	set window title end (from status line)		*t_fs* *'t_fs'*
+	t_ke	exit "keypad transmit" mode			*t_ke* *'t_ke'*
+	t_ks	start "keypad transmit" mode			*t_ks* *'t_ks'*
+	t_le	move cursor one char left			*t_le* *'t_le'*
+	t_mb	blinking mode					*t_mb* *'t_mb'*
+	t_md	bold mode					*t_md* *'t_md'*
+	t_me	Normal mode (undoes t_mr, t_mb, t_md and color)	*t_me* *'t_me'*
+	t_mr	reverse (invert) mode				*t_mr* *'t_mr'*
+								*t_ms* *'t_ms'*
+	t_ms	if non-empty, cursor can be moved in standout/inverse mode
+	t_nd	non destructive space character			*t_nd* *'t_nd'*
+	t_op	reset to original color pair			*t_op* *'t_op'*
+	t_RI	cursor number of chars right			*t_RI* *'t_RI'*
+	t_Sb	set background color				*t_Sb* *'t_Sb'*
+	t_Sf	set foreground color				*t_Sf* *'t_Sf'*
+	t_se	standout end					*t_se* *'t_se'*
+	t_so	standout mode					*t_so* *'t_so'*
+	t_sr	scroll reverse (backward)			*t_sr* *'t_sr'*
+	t_te	end of "termcap" mode				*t_te* *'t_te'*
+	t_ti	put terminal into "termcap" mode		*t_ti* *'t_ti'*
+	t_ts	set window title start (to status line)		*t_ts* *'t_ts'*
+	t_ue	underline end					*t_ue* *'t_ue'*
+	t_us	underline mode					*t_us* *'t_us'*
+	t_ut	clearing uses the current background color	*t_ut* *'t_ut'*
+	t_vb	visual bell					*t_vb* *'t_vb'*
+	t_ve	cursor visible					*t_ve* *'t_ve'*
+	t_vi	cursor invisible				*t_vi* *'t_vi'*
+	t_vs	cursor very visible (blink)			*t_vs* *'t_vs'*
+								*t_xs* *'t_xs'*
+	t_xs	if non-empty, standout not erased by overwriting (hpterm)
+								*t_xn* *'t_xn'*
+	t_xn	if non-empty, writing a character at the last screen cell
+		does not cause scrolling
+	t_ZH	italics mode					*t_ZH* *'t_ZH'*
+	t_ZR	italics end					*t_ZR* *'t_ZR'*
+
+Added by Vim (there are no standard codes for these):
+	t_AU	set underline color (ANSI)			*t_AU* *'t_AU'*
+	t_Ce	undercurl and underline end			*t_Ce* *'t_Ce'*
+	t_Cs	undercurl (curly underline) mode		*t_Cs* *'t_Cs'*
+	t_Us	double underline mode				*t_Us* *'t_Us'*
+	t_ds	dotted underline mode				*t_ds* *'t_ds'*
+	t_Ds	dashed underline mode				*t_Ds* *'t_Ds'*
+	t_Te	strikethrough end				*t_Te* *'t_Te'*
+	t_Ts	strikethrough mode				*t_Ts* *'t_Ts'*
+	t_IS	set icon text start				*t_IS* *'t_IS'*
+	t_IE	set icon text end				*t_IE* *'t_IE'*
+	t_WP	set window position (Y, X) in pixels		*t_WP* *'t_WP'*
+	t_GP	get window position (Y, X) in pixels		*t_GP* *'t_GP'*
+	t_WS	set window size (height, width in cells)	*t_WS* *'t_WS'*
+	t_VS	cursor normally visible (no blink)		*t_VS* *'t_VS'*
+	t_SI	start insert mode (bar cursor shape)		*t_SI* *'t_SI'*
+	t_SR	start replace mode (underline cursor shape)	*t_SR* *'t_SR'*
+	t_EI	end insert or replace mode (block cursor shape)	*t_EI* *'t_EI'*
+		|termcap-cursor-shape|
+	t_RV	request terminal version string (works for	*t_RV* *'t_RV'*
+		xterm and other terminal emulators)  The
+		response is stored in |v:termresponse| |xterm-8bit|
+		|'ttymouse'| |xterm-codes|
+	t_XM	enable/disable mouse reporting,			*t_XM* *'t_XM'*
+		see |mouse-reporting| below
+	t_RK	request terminal keyboard protocol state;	*t_RK* *'t_RK'*
+		sent after |t_TI|
+	t_u7	request cursor position (for xterm)		*t_u7* *'t_u7'*
+		see |'ambiwidth'|
+		The response is stored in |v:termu7resp|
+	t_RF	request terminal foreground color		*t_RF* *'t_RF'*
+		The response is stored in |v:termrfgresp|
+	t_RB	request terminal background color		*t_RB* *'t_RB'*
+		The response is stored in |v:termrbgresp|
+	t_8f	set foreground color (R, G, B)			*t_8f* *'t_8f'*
+		|xterm-true-color|
+	t_8b	set background color (R, G, B)			*t_8b* *'t_8b'*
+		|xterm-true-color|
+	t_8u	set underline color (R, G, B)			*t_8u* *'t_8u'*
+	t_BE	enable bracketed paste mode			*t_BE* *'t_BE'*
+		|xterm-bracketed-paste|
+	t_BD	disable bracketed paste mode			*t_BD* *'t_BD'*
+		|xterm-bracketed-paste|
+	t_SC	set cursor color start				*t_SC* *'t_SC'*
+	t_EC	set cursor color end				*t_EC* *'t_EC'*
+	t_SH	set cursor shape				*t_SH* *'t_SH'*
+	t_RC	request terminal cursor blinking		*t_RC* *'t_RC'*
+		The response is stored in |v:termblinkresp|
+	t_RS	request terminal cursor style			*t_RS* *'t_RS'*
+		The response is stored in |v:termstyleresp|
+	t_ST	save window title to stack			*t_ST* *'t_ST'*
+	t_RT	restore window title from stack			*t_RT* *'t_RT'*
+	t_Si	save icon text to stack				*t_Si* *'t_Si'*
+	t_Ri	restore icon text from stack			*t_Ri* *'t_Ri'*
+	t_TE	end of "raw" mode				*t_TE* *'t_TE'*
+	t_TI	put terminal into "raw" mode			*t_TI* *'t_TI'*
+	t_fe	enable focus-event tracking			*t_fe* *'t_fe'*
+		|xterm-focus-event|
+	t_fd	disable focus-event tracking			*t_fd* *'t_fd'*
+		|xterm-focus-event|
+
+Some codes have a start, middle and end part.  The start and end are defined
+by the termcap option, the middle part is text.
+	set title text:     t_ts {title text} t_fs
+	set icon text:      t_IS {icon text} t_IE
+	set cursor color:   t_SC  {color name}  t_EC
+
+t_SH must take one argument:
+	0, 1 or none	blinking block cursor
+	2		block cursor
+	3		blinking underline cursor
+	4		underline cursor
+	5		blinking vertical bar cursor
+	6		vertical bar cursor
+
+t_RS is sent only if the response to t_RV has been received.  It is not used
+on Mac OS when Terminal.app could be recognized from the termresponse.
+
+							*mouse-reporting*
+Many terminals can report mouse clicks and some can report mouse movement and
+dragging.  Vim needs to know what codes are being used for this.
+
+The "XM" terminfo/termcap entry is used for this.  Vim also has the 'ttymouse'
+option to specify the mouse protocol being used.  See the option for the
+possible values.
+
+If Vim can read the "XM" terminfo/termcap entry then it will be used for
+enabling and disabling the mouse reporting.  If it is missing, then the value
+from 'ttymouse' is used to decide how to do this.
+
+If the "XM" entry exists and the first number is "1006" then 'ttymouse' will
+be set to "sgr", unless it was already set earlier.
+
+
+KEY CODES						*terminal-key-codes*
+Note: Use the <> form if possible
+
+	option	name		meaning	~
+
+	t_ku	<Up>		arrow up			*t_ku* *'t_ku'*
+	t_kd	<Down>		arrow down			*t_kd* *'t_kd'*
+	t_kr	<Right>		arrow right			*t_kr* *'t_kr'*
+	t_kl	<Left>		arrow left			*t_kl* *'t_kl'*
+		<xUp>		alternate arrow up		*<xUp>*
+		<xDown>		alternate arrow down		*<xDown>*
+		<xRight>	alternate arrow right		*<xRight>*
+		<xLeft>		alternate arrow left		*<xLeft>*
+		<S-Up>		shift arrow up
+		<S-Down>	shift arrow down
+	t_%i	<S-Right>	shift arrow right		*t_%i* *'t_%i'*
+	t_#4	<S-Left>	shift arrow left		*t_#4* *'t_#4'*
+	t_k1	<F1>		function key 1			*t_k1* *'t_k1'*
+		<xF1>		alternate F1			*<xF1>*
+	t_k2	<F2>		function key 2		*<F2>*	*t_k2* *'t_k2'*
+		<xF2>		alternate F2			*<xF2>*
+	t_k3	<F3>		function key 3		*<F3>*	*t_k3* *'t_k3'*
+		<xF3>		alternate F3			*<xF3>*
+	t_k4	<F4>		function key 4		*<F4>*	*t_k4* *'t_k4'*
+		<xF4>		alternate F4			*<xF4>*
+	t_k5	<F5>		function key 5		*<F5>*	*t_k5* *'t_k5'*
+	t_k6	<F6>		function key 6		*<F6>*	*t_k6* *'t_k6'*
+	t_k7	<F7>		function key 7		*<F7>*	*t_k7* *'t_k7'*
+	t_k8	<F8>		function key 8		*<F8>*	*t_k8* *'t_k8'*
+	t_k9	<F9>		function key 9		*<F9>*	*t_k9* *'t_k9'*
+	t_k;	<F10>		function key 10		*<F10>*	*t_k;* *'t_k;'*
+	t_F1	<F11>		function key 11		*<F11>*	*t_F1* *'t_F1'*
+	t_F2	<F12>		function key 12		*<F12>*	*t_F2* *'t_F2'*
+	t_F3	<F13>		function key 13		*<F13>*	*t_F3* *'t_F3'*
+	t_F4	<F14>		function key 14		*<F14>*	*t_F4* *'t_F4'*
+	t_F5	<F15>		function key 15		*<F15>*	*t_F5* *'t_F5'*
+	t_F6	<F16>		function key 16		*<F16>*	*t_F6* *'t_F6'*
+	t_F7	<F17>		function key 17		*<F17>*	*t_F7* *'t_F7'*
+	t_F8	<F18>		function key 18		*<F18>*	*t_F8* *'t_F8'*
+	t_F9	<F19>		function key 19		*<F19>*	*t_F9* *'t_F9'*
+		<S-F1>		shifted function key 1
+		<S-xF1>		alternate <S-F1>		*<S-xF1>*
+		<S-F2>		shifted function key 2		*<S-F2>*
+		<S-xF2>		alternate <S-F2>		*<S-xF2>*
+		<S-F3>		shifted function key 3		*<S-F3>*
+		<S-xF3>		alternate <S-F3>		*<S-xF3>*
+		<S-F4>		shifted function key 4		*<S-F4>*
+		<S-xF4>		alternate <S-F4>		*<S-xF4>*
+		<S-F5>		shifted function key 5		*<S-F5>*
+		<S-F6>		shifted function key 6		*<S-F6>*
+		<S-F7>		shifted function key 7		*<S-F7>*
+		<S-F8>		shifted function key 8		*<S-F8>*
+		<S-F9>		shifted function key 9		*<S-F9>*
+		<S-F10>		shifted function key 10		*<S-F10>*
+		<S-F11>		shifted function key 11		*<S-F11>*
+		<S-F12>		shifted function key 12		*<S-F12>*
+	t_%1	<Help>		help key			*t_%1* *'t_%1'*
+	t_&8	<Undo>		undo key			*t_&8* *'t_&8'*
+	t_kI	<Insert>	insert key			*t_kI* *'t_kI'*
+		<kInsert>	keypad insert key
+	t_kD	<Del>		delete key			*t_kD* *'t_kD'*
+	t_kb	<BS>		backspace key			*t_kb* *'t_kb'*
+	t_kB	<S-Tab>		back-tab (shift-tab)  *<S-Tab>*	*t_kB* *'t_kB'*
+	t_kh	<Home>		home key			*t_kh* *'t_kh'*
+	t_#2	<S-Home>	shifted home key     *<S-Home>*	*t_#2* *'t_#2'*
+		<xHome>		alternate home key		*<xHome>*
+	t_@7	<End>		end key				*t_@7* *'t_@7'*
+	t_*7	<S-End>		shifted end key	*<S-End>* *t_star7* *'t_star7'*
+		<xEnd>		alternate end key		*<xEnd>*
+	t_kP	<PageUp>	page-up key			*t_kP* *'t_kP'*
+	t_kN	<PageDown>	page-down key			*t_kN* *'t_kN'*
+	t_K1	<kHome>		keypad home key			*t_K1* *'t_K1'*
+	t_K4	<kEnd>		keypad end key			*t_K4* *'t_K4'*
+	t_K3	<kPageUp>	keypad page-up key		*t_K3* *'t_K3'*
+	t_K5	<kPageDown>	keypad page-down key		*t_K5* *'t_K5'*
+	t_K6	<kPlus>		keypad plus key	      *<kPlus>*	*t_K6* *'t_K6'*
+	t_K7	<kMinus>	keypad minus key     *<kMinus>*	*t_K7* *'t_K7'*
+	t_K8	<kDivide>	keypad divide	    *<kDivide>*	*t_K8* *'t_K8'*
+	t_K9	<kMultiply>	keypad multiply   *<kMultiply>*	*t_K9* *'t_K9'*
+	t_KA	<kEnter>	keypad enter key     *<kEnter>*	*t_KA* *'t_KA'*
+	t_KB	<kPoint>	keypad decimal point *<kPoint>*	*t_KB* *'t_KB'*
+	t_KC	<k0>		keypad 0		 *<k0>*	*t_KC* *'t_KC'*
+	t_KD	<k1>		keypad 1		 *<k1>*	*t_KD* *'t_KD'*
+	t_KE	<k2>		keypad 2		 *<k2>*	*t_KE* *'t_KE'*
+	t_KF	<k3>		keypad 3		 *<k3>*	*t_KF* *'t_KF'*
+	t_KG	<k4>		keypad 4		 *<k4>*	*t_KG* *'t_KG'*
+	t_KH	<k5>		keypad 5		 *<k5>*	*t_KH* *'t_KH'*
+	t_KI	<k6>		keypad 6		 *<k6>*	*t_KI* *'t_KI'*
+	t_KJ	<k7>		keypad 7		 *<k7>*	*t_KJ* *'t_KJ'*
+	t_KK	<k8>		keypad 8		 *<k8>*	*t_KK* *'t_KK'*
+	t_KL	<k9>		keypad 9		 *<k9>*	*t_KL* *'t_KL'*
+		<Mouse>		leader of mouse code		*<Mouse>*
+
+	t_PS	<PasteStart>	start of bracketed paste	*t_PS* *'t_PS'*
+				|xterm-bracketed-paste|
+	t_PE	<PasteEnd>	end of bracketed paste		*t_PE* *'t_PE'*
+				|xterm-bracketed-paste|
+		<FocusGained>	Vim window got focus (internal only)
+		<FocusLost>	Vim window lost focus (internal only)
+
+Note about t_so and t_mr: When the termcap entry "so" is not present the
+entry for "mr" is used.  And vice versa.  The same is done for "se" and "me".
+If your terminal supports both inversion and standout mode, you can see two
+different modes.  If your terminal supports only one of the modes, both will
+look the same.
+
+							*keypad-comma*
+The keypad keys, when they are not mapped, behave like the equivalent normal
+key.  There is one exception: if you have a comma on the keypad instead of a
+decimal point, Vim will use a dot anyway.  Use these mappings to fix that: >
+	:noremap <kPoint> ,
+	:noremap! <kPoint> ,
+<							*xterm-codes*
+There is a special trick to obtain the key codes which currently only works
+for xterm.  When |t_RV| is defined and a response is received which indicates
+an xterm with patchlevel 141 or higher, Vim uses special escape sequences to
+request the key codes directly from the xterm.  The responses are used to
+adjust the various t_ codes.  This avoids the problem that the xterm can
+produce different codes, depending on the mode it is in (8-bit, VT102,
+VT220, etc.).  The result is that codes like <xF1> are no longer needed.
+
+One of the codes that can change is 't_Co', the number of colors.  This will
+trigger a redraw.  If this is a problem, reset the 'xtermcodes' option as
+early as possible: >
+	set noxtermcodes
+
+Note: Requesting the key codes is only done on startup.  If the xterm options
+are changed after Vim has started, the escape sequences may not be recognized
+anymore.
+
+							*xterm-true-color*
+Vim supports using true colors in the terminal (taken from |highlight-guifg|
+and |highlight-guibg|), given that the terminal supports this. To make this
+work the 'termguicolors' option needs to be set.
+See https://github.com/termstandard/colors for a list of terminals that
+support true colors.
+
+For telling the terminal what RGB color to use the |t_8f| and |t_8b| termcap
+entries are used.  These are set by default to values that work for most
+terminals.  If that does not work for your terminal you can set them manually.
+The default values are set like this: >
+	 let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
+	 let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
+
+Some terminals accept the same sequences, but with all semicolons replaced by
+colons (this is actually more compatible, but less widely supported): >
+	 let &t_8f = "\<Esc>[38:2:%lu:%lu:%lum"
+	 let &t_8b = "\<Esc>[48:2:%lu:%lu:%lum"
+
+These options contain printf strings, with |printf()| (actually, its C
+equivalent hence `l` modifier) invoked with the t_ option value and three
+unsigned long integers that may have any value between 0 and 255 (inclusive)
+representing red, green and blue colors respectively.
+
+							*xterm-resize*
+Window resizing with xterm only works if the allowWindowOps resource is
+enabled.  On some systems and versions of xterm it's disabled by default
+because someone thought it would be a security issue.  It's not clear if this
+is actually the case.
+
+To overrule the default, put this line in your ~/.Xdefaults or
+~/.Xresources:
+>
+	XTerm*allowWindowOps:		true
+
+And run "xrdb -merge .Xresources" to make it effective.  You can check the
+value with the context menu (right mouse button while CTRL key is pressed),
+there should be a tick at allow-window-ops.
+
+							*xterm-focus-event*
+Some terminals including xterm support the focus event tracking feature.
+If this feature is enabled by the 't_fe' sequence, special key sequences are
+sent from the terminal to Vim every time the terminal gains or loses focus.
+Vim fires focus events (|FocusGained|/|FocusLost|) by handling them accordingly.
+Focus event tracking is disabled by a 't_fd' sequence when exiting "raw" mode.
+If you would like to disable this feature, add the following to your .vimrc:
+	`set t_fd=`
+	`set t_fe=`
+If your terminal does support this but Vim does not recognize the terminal,
+you may have to set the options yourself: >
+	let &t_fe = "\<Esc>[?1004h"
+	let &t_fd = "\<Esc>[?1004l"
+	execute "set <FocusGained>=\<Esc>[I"
+        execute "set <FocusLost>=\<Esc>[O"
+If this causes garbage to show when Vim starts up then it doesn't work.
+
+							*termcap-colors*
+Note about colors: The 't_Co' option tells Vim the number of colors available.
+When it is non-zero, the 't_AB' and 't_AF' options are used to set the color.
+If one of these is not available, 't_Sb' and 't_Sf' are used.  't_me' is used
+to reset to the default colors.  Also see 'termguicolors'.
+When the GUI is running 't_Co' is set to 16777216.
+
+				*termcap-cursor-shape* *termcap-cursor-color*
+When Vim enters Insert mode the 't_SI' escape sequence is sent.  When Vim
+enters Replace mode the 't_SR' escape sequence is sent if it is set, otherwise
+'t_SI' is sent.  When leaving Insert mode or Replace mode 't_EI' is used.
+Note: When 't_EI' is not set then 't_SI' and 't_SR' will not be sent.  And
+when 't_SI' or 't_SR' is not set then 't_EI' is sent only once.
+
+This can be used to change the shape or color of the cursor in Insert or
+Replace mode. These are not standard termcap/terminfo entries, you need to set
+them yourself.
+Example for an xterm, this changes the color of the cursor: >
+    if &term =~ "xterm"
+	let &t_SI = "\<Esc>]12;purple\x7"
+	let &t_SR = "\<Esc>]12;red\x7"
+	let &t_EI = "\<Esc>]12;blue\x7"
+    endif
+NOTE: When Vim exits the shape for Normal mode will remain.  The shape from
+before Vim started will not be restored.
+
+For Windows Terminal you can use something like this: >
+    " Note: This should be set after `set termguicolors` or `set t_Co=256`.
+    if &term =~ 'xterm' || &term == 'win32'
+	" Use DECSCUSR escape sequences
+	let &t_SI = "\e[5 q"    " blink bar
+	let &t_SR = "\e[3 q"    " blink underline
+	let &t_EI = "\e[1 q"    " blink block
+	let &t_ti ..= "\e[1 q"  " blink block
+	let &t_te ..= "\e[0 q"  " default (depends on terminal, normally blink
+				" block)
+    endif
+
+{not available when compiled without the |+cursorshape| feature}
+
+							*termcap-title*
+The 't_ts' and 't_fs' options are used to set the window title if the terminal
+allows title setting via sending strings.  They are sent before and after the
+title string, respectively.  Similar 't_IS' and 't_IE'  are used to set the
+icon text.  These are Vim-internal extensions of the Unix termcap, so they
+cannot be obtained from an external termcap.  However, the builtin termcap
+contains suitable entries for xterm and iris-ansi, so you don't need to set
+them here.
+							*hpterm*
+If inversion or other highlighting does not work correctly, try setting the
+'t_xs' option to a non-empty string.  This makes the 't_ce' code be used to
+remove highlighting from a line.  This is required for "hpterm".  Setting the
+'weirdinvert' option has the same effect as making 't_xs' non-empty, and vice
+versa.
+
+							*scroll-region*
+Some termcaps do not include an entry for "cs" (scroll region), although the
+terminal does support it.  For example: xterm on a Sun.  You can use the
+builtin_xterm or define t_cs yourself.  For example: >
+	:set t_cs=^V^[[%i%d;%dr
+Where ^V is CTRL-V and ^[ is <Esc>.
+
+The vertical scroll region t_CV is not a standard termcap code.  Vim uses it
+internally in the GUI.  But it can also be defined for a terminal, if you can
+find one that supports it.  The two arguments are the left and right column of
+the region which to restrict the scrolling to.  Just like t_cs defines the top
+and bottom lines.  Defining t_CV will make scrolling in vertically split
+windows a lot faster.  Don't set t_CV when t_da or t_db is set (text isn't
+cleared when scrolling).
+
+Unfortunately it is not possible to deduce from the termcap how cursor
+positioning should be done when using a scrolling region: Relative to the
+beginning of the screen or relative to the beginning of the scrolling region.
+Most terminals use the first method.  The 't_CS' option should be set to any
+string when cursor positioning is relative to the start of the scrolling
+region.  It should be set to an empty string otherwise.
+
+Note for xterm users: The shifted cursor keys normally don't work.  You can
+	make them work with the xmodmap command and some mappings in Vim.
+
+	Give these commands in the xterm:
+		xmodmap -e "keysym Up = Up F13"
+		xmodmap -e "keysym Down = Down F16"
+		xmodmap -e "keysym Left = Left F18"
+		xmodmap -e "keysym Right = Right F19"
+
+	And use these mappings in Vim:
+		:map <t_F3> <S-Up>
+		:map! <t_F3> <S-Up>
+		:map <t_F6> <S-Down>
+		:map! <t_F6> <S-Down>
+		:map <t_F8> <S-Left>
+		:map! <t_F8> <S-Left>
+		:map <t_F9> <S-Right>
+		:map! <t_F9> <S-Right>
+
+Instead of, say, <S-Up> you can use any other command that you want to use the
+shift-cursor-up key for.  (Note: To help people that have a Sun keyboard with
+left side keys F14 is not used because it is confused with the undo key; F15
+is not used, because it does a window-to-front; F17 is not used, because it
+closes the window.  On other systems you can probably use them.)
+
+==============================================================================
+3. Window size						*window-size*
+
+[This is about the size of the whole window Vim is using, not a window that is
+created with the ":split" command.]
+
+If you are running Vim on an Amiga and the terminal name is "amiga" or
+"builtin_amiga", the amiga-specific window resizing will be enabled.  On Unix
+systems three methods are tried to get the window size:
+
+- an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system)
+- the environment variables "LINES" and "COLUMNS"
+- from the termcap entries "li" and "co"
+
+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* *E359*
+:mod[e] [mode]
+
+Without argument this only detects the screen size and redraws the screen.
+[mode] was used on MS-DOS, but it doesn't work anymore.  In |Vim9| this
+command is not supported.
+
+==============================================================================
+4. Slow and fast terminals			*slow-fast-terminal*
+						*slow-terminal*
+
+If you have a fast terminal you may like to set the 'ruler' option.  The
+cursor position is shown in the status line.  If you are using horizontal
+scrolling ('wrap' option off) consider setting 'sidescroll' to a small
+number.
+
+If you have a slow terminal you may want to reset the 'showcmd' option.
+The command characters will not be shown in the status line.  If the terminal
+scrolls very slowly, set the 'scrolljump' to 5 or so.  If the cursor is moved
+off the screen (e.g., with "j") Vim will scroll 5 lines at a time.  Another
+possibility is to reduce the number of lines that Vim uses with the command
+"z{height}<CR>".
+
+If the characters from the terminal are arriving with more than 1 second
+between them you might want to set the 'timeout' and/or 'ttimeout' option.
+See the "Options" chapter |options|.
+
+If your terminal does not support a scrolling region, but it does support
+insert/delete line commands, scrolling with multiple windows may make the
+lines jump up and down.  This would happen if the 'ttyfast' option has been
+reset.  Check that with: >
+	verbose set ttyfast?
+
+If your terminal scrolls very slowly, but redrawing is not slow, set the
+'ttyscroll' option to a small number, e.g., 3.  This will make Vim redraw the
+screen instead of scrolling, when there are more than 3 lines to be scrolled.
+
+If you are using a color terminal that is slow, use this command: >
+	hi NonText cterm=NONE ctermfg=NONE
+This avoids that spaces are sent when they have different attributes.  On most
+terminals you can't see this anyway.
+
+If you are using Vim over a slow serial line, you might want to try running
+Vim inside the "screen" program.  Screen will optimize the terminal I/O quite
+a bit.
+
+If you are testing termcap options, but you cannot see what is happening, you
+might want to set the 'writedelay' option.  When non-zero, one character is
+sent to the terminal at a time.  This makes the screen updating a lot slower,
+making it possible to see what is happening.
+
+==============================================================================
+5. Using the mouse					*mouse-using*
+
+This section is about using the mouse on a terminal or a terminal window.  How
+to use the mouse in a GUI window is explained in |gui-mouse|.  For scrolling
+with a mouse wheel see |scroll-mouse-wheel|.
+
+Don't forget to enable the mouse with this command: >
+	:set mouse=a
+Otherwise Vim won't recognize the mouse in all modes (See 'mouse').
+
+Currently the mouse is supported for Unix in an xterm window, in a *BSD
+console with |sysmouse|, in a Linux console (with GPM |gpm-mouse|), and
+in a Windows console.
+Mouse clicks can be used to position the cursor, select an area and paste.
+
+These characters in the 'mouse' option tell in which situations the mouse will
+be used by Vim:
+		n	Normal mode
+		v	Visual mode
+		i	Insert mode
+		c	Command-line mode
+		h	all previous modes when in a help file
+		a	all previous modes
+		r	for |hit-enter| prompt
+
+The default for 'mouse' is empty, the mouse is not used.  Normally you would
+do: >
+	:set mouse=a
+to start using the mouse (this is equivalent to setting 'mouse' to "nvich").
+If you only want to use the mouse in a few modes or also want to use it for
+the two questions you will have to concatenate the letters for those modes.
+For example: >
+	:set mouse=nv
+Will make the mouse work in Normal mode and Visual mode. >
+	:set mouse=h
+Will make the mouse work in help files only (so you can use "g<LeftMouse>" to
+jump to tags).
+
+Whether the selection that is started with the mouse is in Visual mode or
+Select mode depends on whether "mouse" is included in the 'selectmode'
+option.
+							*terminal-mouse*
+In an xterm, with the currently active mode included in the 'mouse' option,
+normal mouse clicks are used by Vim, mouse clicks with the shift or ctrl key
+pressed go to the xterm.  With the currently active mode not included in
+'mouse' all mouse clicks go to the xterm.
+
+For terminals where it is not possible to have the mouse events be used by the
+terminal itself by using a modifier, a workaround is to not use mouse events
+for Vim in command-line mode: >
+	:set mouse=nvi
+Then to select text with the terminal, use ":" to go to command-line mode,
+select and copy the text to the system, then press Esc.
+
+Another way is to temporarily use ":sh" to run a shell, copy the text, then
+exit the shell.  'mouse' can remain set to "a" then.
+							*xterm-clipboard*
+In the Motif GUI version, when running in a terminal and there is
+access to the X-server (DISPLAY is set), the copy and paste will behave like
+in the GUI.  If not, the middle mouse button will insert the unnamed register.
+In that case, here is how you copy and paste a piece of text:
+
+Copy/paste with the mouse and Visual mode ('mouse' option must be set, see
+above):
+1. Press left mouse button on first letter of text, move mouse pointer to last
+   letter of the text and release the button.  This will start Visual mode and
+   highlight the selected area.
+2. Press "y" to yank the Visual text in the unnamed register.
+3. Click the left mouse button at the insert position.
+4. Click the middle mouse button.
+
+Shortcut: If the insert position is on the screen at the same time as the
+Visual text, you can do 2, 3 and 4 all in one: Click the middle mouse button
+at the insert position.
+
+Note: When the |-X| command line argument is used, Vim will not connect to the
+X server and copy/paste to the X clipboard (selection) will not work.  Use the
+shift key with the mouse buttons to let the xterm do the selection.
+
+							*xterm-command-server*
+When the X-server clipboard is available, the command server described in
+|x11-clientserver| can be enabled with the --servername command line argument.
+
+							*xterm-copy-paste*
+NOTE: In some (older) xterms, it's not possible to move the cursor past column
+95 or 223.  This is an xterm problem, not Vim's.  Get a newer xterm
+|color-xterm|.  Also see |'ttymouse'|.
+
+Copy/paste in xterm with (current mode NOT included in 'mouse'):
+1. Press left mouse button on first letter of text, move mouse pointer to last
+   letter of the text and release the button.
+2. Use normal Vim commands to put the cursor at the insert position.
+3. Press "a" to start Insert mode.
+4. Click the middle mouse button.
+5. Press ESC to end Insert mode.
+(The same can be done with anything in 'mouse' if you keep the shift key
+pressed while using the mouse.)
+
+Note: if you lose the 8th bit when pasting (special characters are translated
+into other characters), you may have to do "stty cs8 -istrip -parenb" in your
+shell before starting Vim.
+
+Thus in an xterm the shift and ctrl keys cannot be used with the mouse.  Mouse
+commands requiring the CTRL modifier can be simulated by typing the "g" key
+before using the mouse:
+	"g<LeftMouse>"	is "<C-LeftMouse>	(jump to tag under mouse click)
+	"g<RightMouse>" is "<C-RightMouse>	("CTRL-T")
+
+					*mouse-mode-table* *mouse-overview*
+A short overview of what the mouse buttons do, when 'mousemodel' is "extend":
+
+Normal Mode:
+event	      position	   selection	  change  action	~
+	       cursor			  window		~
+<LeftMouse>     yes	     end	    yes
+<C-LeftMouse>   yes	     end	    yes	   "CTRL-]" (2)
+<S-LeftMouse>   yes	  no change	    yes	   "*" (2)    *<S-LeftMouse>*
+<LeftDrag>      yes	start or extend (1) no		      *<LeftDrag>*
+<LeftRelease>   yes	start or extend (1) no
+<MiddleMouse>   yes	  if not active     no	   put
+<MiddleMouse>   yes	  if active	    no	   yank and put
+<RightMouse>    yes	start or extend     yes
+<A-RightMouse>  yes start or extend blockw. yes		      *<A-RightMouse>*
+<S-RightMouse>  yes	   no change	    yes	   "#" (2)    *<S-RightMouse>*
+<C-RightMouse>  no	   no change	    no	   "CTRL-T"
+<RightDrag>     yes	    extend	    no		      *<RightDrag>*
+<RightRelease>  yes	    extend	    no		      *<RightRelease>*
+
+Insert or Replace Mode:
+event	      position	   selection	  change  action	~
+	       cursor			  window		~
+<LeftMouse>     yes     (cannot be active)  yes
+<C-LeftMouse>   yes     (cannot be active)  yes	   "CTRL-O^]" (2)
+<S-LeftMouse>   yes     (cannot be active)  yes	   "CTRL-O*" (2)
+<LeftDrag>      yes     start or extend (1) no	   like CTRL-O (1)
+<LeftRelease>   yes     start or extend (1) no	   like CTRL-O (1)
+<MiddleMouse>   no      (cannot be active)  no	   put register
+<RightMouse>    yes     start or extend	    yes	   like CTRL-O
+<A-RightMouse>  yes start or extend blockw. yes
+<S-RightMouse>  yes     (cannot be active)  yes	   "CTRL-O#" (2)
+<C-RightMouse>  no	(cannot be active)  no	   "CTRL-O CTRL-T"
+
+In a help window:
+event	      position	   selection	  change  action	~
+	       cursor			  window		~
+<2-LeftMouse>   yes     (cannot be active)  no	   "^]" (jump to help tag)
+
+When 'mousemodel' is "popup", these are different:
+
+Normal Mode:
+event	      position	   selection	  change  action	~
+	       cursor			  window		~
+<S-LeftMouse>	yes	start or extend (1) no
+<A-LeftMouse>   yes start or extend blockw. no		      *<A-LeftMouse>*
+<RightMouse>	no	popup menu	    no
+
+Insert or Replace Mode:
+event	      position	   selection	  change  action	~
+	       cursor			  window		~
+<S-LeftMouse>   yes     start or extend (1) no	   like CTRL-O (1)
+<A-LeftMouse>   yes start or extend blockw. no
+<RightMouse>    no	popup menu	    no
+
+(1) only if mouse pointer moved since press
+(2) only if click is in same buffer
+
+Clicking the left mouse button causes the cursor to be positioned.  If the
+click is in another window that window is made the active window.  When
+editing the command-line the cursor can only be positioned on the
+command-line.  When in Insert mode Vim remains in Insert mode.  If 'scrolloff'
+is set, and the cursor is positioned within 'scrolloff' lines from the window
+border, the text is scrolled.
+
+A selection can be started by pressing the left mouse button on the first
+character, moving the mouse to the last character, then releasing the mouse
+button.  You will not always see the selection until you release the button,
+only in some versions (GUI, Win32) will the dragging be shown immediately.
+Note that you can make the text scroll by moving the mouse at least one
+character in the first/last line in the window when 'scrolloff' is non-zero.
+
+In Normal, Visual and Select mode clicking the right mouse button causes the
+Visual area to be extended.  When 'mousemodel' is "popup", the left button has
+to be used while keeping the shift key pressed.  When clicking in a window
+which is editing another buffer, the Visual or Select mode is stopped.
+
+In Normal, Visual and Select mode clicking the right mouse button with the alt
+key pressed causes the Visual area to become blockwise.  When 'mousemodel' is
+"popup" the left button has to be used with the alt key.  Note that this won't
+work on systems where the window manager consumes the mouse events when the
+alt key is pressed (it may move the window).
+
+							*double-click*
+Double, triple and quadruple clicks are supported when the GUI is active, for
+Win32, and for an xterm (if the gettimeofday() function is available).  For
+selecting text, extra clicks extend the selection:
+	click		select ~
+	double		word or % match		*<2-LeftMouse>*
+	triple		line			*<3-LeftMouse>*
+	quadruple	rectangular block	*<4-LeftMouse>*
+Exception: In a Help window a double click jumps to help for the word that is
+clicked on.
+A double click on a word selects that word.  'iskeyword' is used to specify
+which characters are included in a word.  A double click on a character
+that has a match selects until that match (like using "v%").  If the match is
+an #if/#else/#endif block, the selection becomes linewise.
+For MS-Windows and xterm the time for double clicking can be set with the
+'mousetime' option.  For the other systems this time is defined outside of Vim.
+An example, for using a double click to jump to the tag under the cursor: >
+	:map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR>
+
+Dragging the mouse with a double click (button-down, button-up, button-down
+and then drag) will result in whole words to be selected.  This continues
+until the button is released, at which point the selection is per character
+again.
+
+For scrolling with the mouse see |scroll-mouse-wheel|.
+
+							*gpm-mouse*
+The GPM mouse is only supported when the |+mouse_gpm| feature was enabled at
+compile time.  The GPM mouse driver (Linux console) does not support quadruple
+clicks.
+
+In Insert mode, when a selection is started, Vim goes into Normal mode
+temporarily.  When Visual or Select mode ends, it returns to Insert mode.
+This is like using CTRL-O in Insert mode.  Select mode is used when the
+'selectmode' option contains "mouse".
+							*sysmouse*
+The sysmouse is only supported when the |+mouse_sysmouse| feature was enabled
+at compile time.  The sysmouse driver (*BSD console) does not support keyboard
+modifiers.
+
+							*drag-status-line*
+When working with several windows, the size of the windows can be changed by
+dragging the status line with the mouse.  Point the mouse at a status line,
+press the left button, move the mouse to the new position of the status line,
+release the button.  Just clicking the mouse in a status line makes that window
+the current window, without moving the cursor.  If by selecting a window it
+will change position or size, the dragging of the status line will look
+confusing, but it will work (just try it).
+
+					*<MiddleRelease>* *<MiddleDrag>*
+Mouse clicks can be mapped.  The codes for mouse clicks are:
+     code	    mouse button	      normal action	~
+ <LeftMouse>	 left pressed		    set cursor position
+ <LeftDrag>	 left moved while pressed   extend selection
+ <LeftRelease>	 left released		    set selection end
+ <MiddleMouse>	 middle pressed		    paste text at cursor position
+ <MiddleDrag>	 middle moved while pressed -
+ <MiddleRelease> middle released	    -
+ <RightMouse>	 right pressed		    extend selection
+ <RightDrag>	 right moved while pressed  extend selection
+ <RightRelease>  right released		    set selection end
+ <X1Mouse>	 X1 button pressed	    -			*X1Mouse*
+ <X1Drag>	 X1 moved while pressed	    -			*X1Drag*
+ <X1Release>	 X1 button release	    -			*X1Release*
+ <X2Mouse>	 X2 button pressed	    -			*X2Mouse*
+ <X2Drag>	 X2 moved while pressed     -			*X2Drag*
+ <X2Release>	 X2 button release	    -			*X2Release*
+
+The X1 and X2 buttons refer to the extra buttons found on some mice.  The
+'Microsoft Explorer' mouse has these buttons available to the right thumb.
+Currently X1 and X2 only work on Win32 and X11 environments.
+
+Examples: >
+	:noremap <MiddleMouse> <LeftMouse><MiddleMouse>
+Paste at the position of the middle mouse button click (otherwise the paste
+would be done at the cursor position). >
+
+	:noremap <LeftRelease> <LeftRelease>y
+Immediately yank the selection, when using Visual mode.
+
+Note the use of ":noremap" instead of "map" to avoid a recursive mapping.
+>
+	:map <X1Mouse> <C-O>
+	:map <X2Mouse> <C-I>
+Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
+|CTRL-O| and |CTRL-I|.
+
+						*mouse-swap-buttons*
+To swap the meaning of the left and right mouse buttons: >
+	:noremap	<LeftMouse>	<RightMouse>
+	:noremap	<LeftDrag>	<RightDrag>
+	:noremap	<LeftRelease>	<RightRelease>
+	:noremap	<RightMouse>	<LeftMouse>
+	:noremap	<RightDrag>	<LeftDrag>
+	:noremap	<RightRelease>	<LeftRelease>
+	:noremap	g<LeftMouse>	<C-RightMouse>
+	:noremap	g<RightMouse>	<C-LeftMouse>
+	:noremap!	<LeftMouse>	<RightMouse>
+	:noremap!	<LeftDrag>	<RightDrag>
+	:noremap!	<LeftRelease>	<RightRelease>
+	:noremap!	<RightMouse>	<LeftMouse>
+	:noremap!	<RightDrag>	<LeftDrag>
+	:noremap!	<RightRelease>	<LeftRelease>
+<
+ vim:tw=78:ts=8:noet:ft=help:norl: