vim: runtime/doc/terminal.txt annotate

annotate runtime/doc/terminal.txt @ 11659:49c12c93abf3

Updated runtime files and translations. commit https://github.com/vim/vim/commit/74675a666b51edd61e0210132658d81a86c5102c Author: Bram Moolenaar <Bram@vim.org> Date: Sat Jul 15 13:53:23 2017 +0200 Updated runtime files and translations.

author	Christian Brabandt <cb@256bit.org>
date	Sat, 15 Jul 2017 14:00:04 +0200
parents	b8299e742f41
children	21f3930dfe6e

rev	line source
11659 49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	1 terminal.txt For Vim version 8.0. Last change: 2017 Jul 15
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	2
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	3
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	5
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	6
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	7 Terminal window support terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	8
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	9
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	10 WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	11
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	12
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	13 1. Basic use \|terminal-use\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	14 2. Remote testing \|terminal-testing\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	15 3. Debugging \|terminal-debug\|
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	16
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	17 {Vi does not have any of these commands}
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	18
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	19 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	20 1. Basic use terminal-use
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	21
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	22 This feature is for running a terminal emulator in a Vim window. A job can be
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	23 started connected to the terminal emulator. For example, to run a shell: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	24 :term bash
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	25
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	26 Or to run a debugger: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	27 :term gdb vim
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	28
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	29 The job runs asynchronously from Vim, the window will be updated to show
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	30 output from the job, also while editing in any other window.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	31
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	32 When the keyboard focus is in the terminal window, typed keys will be send to
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	33 the job. This uses a pty when possible.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	34
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	35 Navigate between windows with CTRL-W commands (and mouse).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	36 E.g. CTRL-W CTRL-W moves focus to the next window.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	37
11659 49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	38 See option 'termkey' for specifying the key that precedes a Vim command.
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	39 Default is CTRL-W.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	40
11659 49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	41 See option 'termsize' for controlling the size of the terminal window.
49c12c93abf3 Updated runtime files and translations. Christian Brabandt <cb@256bit.org> parents: 11621 diff changeset	42 (TODO: scrolling when the terminal is larger than the window)
11621 b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	43
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	44 Syntax ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	45 :ter :terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	46 :terminal[!] [command] Open a new terminal window.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	47
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	48 If [command] is provided run it as a job and connect
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	49 the input and output to the terminal.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	50 If [command] is not given the 'shell' option is used.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	51
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	52 A new buffer will be created, using [command] or
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	53 'shell' as the name. If a buffer by this name already
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	54 exists a number is added in parenthesis.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	55 E.g. if "gdb" exists the second terminal buffer will
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	56 use "gdb (1)".
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	57
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	58 The window can be closed, in which case the buffer
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	59 becomes hidden. The command will not be stopped. The
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	60 `:buffer` command can be used to turn the current
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	61 window into a terminal window, using the existing
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	62 buffer. If there are unsaved changes this fails, use
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	63 ! to force, as usual.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	64
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	65 Resizing ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	66
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	67 The size of the terminal can be in one of three modes:
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	68
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	69 1. The 'termsize' option is empty: The terminal size follows the window size.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	70 The minimal size is 2 screen lines with 10 cells.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	71
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	72 2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	73 screen rows and "cols" is the minial number of cells.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	74
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	75 3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	76 The terminal size is fixed to the specified number of screen lines and
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	77 cells. If the window is bigger there will be unused empty space.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	78
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	79 If the window is smaller than the terminal size, only part of the terminal can
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	80 be seen (the lower-left part).
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	81
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	82 The \|term_getsize()\| function can be used to get the current size of the
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	83 terminal. \|term_setsize()\| can be used only when in the first or second mode,
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	84 not when 'termsize' is "rowsXcols".
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	85
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	86 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	87 2. Remote testing terminal-testing
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	88
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	89 Most Vim tests execute a script inside Vim. For some tests this does not
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	90 work, running the test interferes with the code being tested. To avoid this
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	91 Vim is executed in a terminal window. The test sends keystrokes to it and
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	92 inspects the resulting screen state.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	93
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	94 Functions ~
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	95
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	96 term_sendkeys() send keystrokes to a terminal
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	97 term_wait() wait for screen to be updated
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	98 term_scrape() inspect terminal screen
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	99
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	100
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	101 ==============================================================================
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	102 3. Debugging terminal-debug
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	103
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	104 The Terminal debugging plugin can be used to debug a program with gdb and view
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	105 the source code in a Vim window. For example: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	106
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	107 :TermDebug vim
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	108
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	109 This opens three windows:
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	110 - A terminal window in which "gdb vim" is executed. Here you can directly
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	111 interact with gdb.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	112 - A terminal window for the executed program. When "run" is used in gdb the
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	113 program I/O will happen in this window, so that it does not interfere with
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	114 controlling gdb.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	115 - A normal Vim window used to show the source code. When gdb jumps to a
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	116 source file location this window will display the code, if possible. Values
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	117 of variables can be inspected, breakpoints set and cleared, etc.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	118
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	119 This uses two terminal windows. To open the gdb window: >
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	120 :term gdb [arguments]
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	121 To open the terminal to run the tested program \|term_open()\| is used.
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	122
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	123 TODO
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	124
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	125
b8299e742f41 patch 8.0.0693: no terminal emulator support Christian Brabandt <cb@256bit.org> parents: diff changeset	126 vim:tw=78:ts=8:ft=help:norl:

Mercurial > vim

annotate runtime/doc/terminal.txt @ 11659:49c12c93abf3