From f6d0cadcc54b05bf7800f2df8945777fcb7f66ee Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 30 May 2018 12:52:59 +0530 Subject: [PATCH] Redirect old asciidoc pages to new website --- README.asciidoc | 9 - graphics-protocol.asciidoc | 391 +---------------------------------- kittens/diff/README.asciidoc | 130 +----------- protocol-extensions.asciidoc | 171 +-------------- remote-control.asciidoc | 111 +--------- 5 files changed, 4 insertions(+), 808 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 7a4c3f535..2cd0f8ccf 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -3,12 +3,3 @@ See https://sw.kovidgoyal.net/kitty image::https://travis-ci.org/kovidgoyal/kitty.svg?branch=master[Build status, link=https://travis-ci.org/kovidgoyal/kitty] - - -== Resources on terminal behavior - -http://invisible-island.net/xterm/ctlseqs/ctlseqs.html - -https://en.wikipedia.org/wiki/C0_and_C1_control_codes - -https://vt100.net/ diff --git a/graphics-protocol.asciidoc b/graphics-protocol.asciidoc index 51c787aab..570d0df61 100644 --- a/graphics-protocol.asciidoc +++ b/graphics-protocol.asciidoc @@ -1,390 +1 @@ -= The terminal graphics protocol -:toc: -:toc-placement!: - -The goal of this specification is to create a flexible and performant protocol -that allows the program running in the terminal, hereafter called the _client_, -to render arbitrary pixel (raster) graphics to the screen of the terminal -emulator. The major design goals are - - * Should not require terminal emulators to understand image formats. - * Should allow specifying graphics to be drawn at individual pixel positions. - * The graphics should integrate with the text, in particular it should be possible to draw graphics - below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically. - * Should use optimizations when the client is running on the same computer as the terminal emulator. - -For some discussion regarding the design choices, see link:../../issues/33[#33]. - -To see a quick demo, inside a kitty terminal run: - -``` -kitty icat path/to/some/image.png -``` - -You can also see a screenshot with more sophisticated features such as alpha-blending and text over graphics -link:https://github.com/kovidgoyal/kitty/issues/33#issuecomment-334436100[here]. - -Some programs that use the kitty graphics protocol: - - * link:https://github.com/dsanson/termpdf[termdpf] - a terminal PDF/DJVU/CBR viewer - * link:https://github.com/ranger/ranger[ranger] - a terminal file manager, with image previews, see this link:https://github.com/ranger/ranger/pull/1077[PR] - * link:https://github.com/kovidgoyal/kitty/tree/master/kittens/diff[kitty-diff] - a side-by-side terminal diff program with support for images - -toc::[] - -== Getting the window size - -In order to know what size of images to display and how to position them, the client must be able to get the -window size in pixels and the number of cells per row and column. This can be done by using the `TIOCGWINSZ` ioctl. -Some code to demonstrate its use - -In C: -```C -struct ttysize ts; -ioctl(0, TIOCGWINSZ, &ts); -printf("number of columns: %i, number of rows: %i, screen width: %i, screen height: %i\n", sz.ws_col, sz.ws_row, sz.ws_xpixel, sz.ws_ypixel); -``` - -In Python: -```py -import array, fcntl, termios -buf = array.array('H', [0, 0, 0, 0]) -fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf) -print('number of columns: {}, number of rows: {}, screen width: {}, screen height: {}'.format(*buf)) -``` - -Note that some terminals return `0` for the width and height values. Such terminals should be modified to return the correct values. -Examples of terminals that return correct values: `kitty, xterm` - -You can also use the *CSI t* escape code to get the screen size. Send `[14t` to *stdout* and kitty will reply on *stdin* with -`[4;;t` where *height* and *width* are the window size in pixels. This escape code is supported in many terminals, -not just kitty. - -== The graphics escape code - -All graphics escape codes are of the form: - -``` -_G;\ -``` - -This is a so-called _Application Programming Command (APC)_. Most terminal -emulators ignore APC codes, making it safe to use. - -The control data is a comma-separated list of `key=value` pairs. The payload -is arbitrary binary data, base64-encoded to prevent interoperation problems -with legacy terminals that get confused by control codes within an APC code. -The meaning of the payload is interpreted based on the control data. - -The first step is to transmit the actual image data. - -== Transferring pixel data - -The first consideration when transferring data between the client and the -terminal emulator is the format in which to do so. Since there is a vast and -growing number of image formats in existence, it does not make sense to have -every terminal emulator implement support for them. Instead, the client should -send simple pixel data to the terminal emulator. The obvious downside to this -is performance, especially when the client is running on a remote machine. -Techniques for remedying this limitation are discussed later. The terminal -emulator must understand pixel data in three formats, 24-bit RGB, 32-bit RGBA and -PNG. This is specified using the `f` key in the control data. `f=32` (which is the -default) indicates 32-bit RGBA data and `f=24` indicates 24-bit RGB data and `f=100` -indicates PNG data. The PNG format is supported for convenience and a compact way -of transmitting paletted images. - -=== RGB and RGBA data - -In these formats the pixel data is stored directly as 3 or 4 bytes per pixel, respectively. -When specifying images in this format, the image dimensions **must** be sent in the control data. -For example: - -``` -_Gf=24,s=10,v=20;\ -``` - -Here the width and height are specified using the `s` and `v` keys respectively. Since -`f=24` there are three bytes per pixel and therefore the pixel data must be `3 * 10 * 20 = 600` -bytes. - -=== PNG data - -In this format any PNG image can be transmitted directly. For example: - -``` -_Gf=100;\ - -``` - -The PNG format is specified using the `f=100` key. The width and height of -the image will be read from the PNG data itself. Note that if you use both PNG and -compression, then you must provide the `S` key with the size of the PNG data. - - -=== Compression - -The client can send compressed image data to the terminal emulator, by specifying the -`o` key. Currently, only zlib based deflate compression is supported, which is specified using -`o=z`. For example, - -``` -_Gf=24,s=10,v=20,o=z;\ -``` - -This is the same as the example from the RGB data section, except that the -payload is now compressed using deflate. The terminal emulator will decompress -it before rendering. You can specify compression for any format. The terminal -emulator will decompress before interpreting the pixel data. - - -=== The transmission medium - -The transmission medium is specified using the `t` key. The `t` key defaults to `d` -and can take the values: - -|=== -| Value of `t` | Meaning - -| d | Direct (the data is transmitted within the escape code itself) -| f | A simple file -| t | A temporary file, the terminal emulator will delete the file after reading the pixel data -| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data -|=== - -==== Local client - -First let us consider the local client techniques (files and shared memory). Some examples: - -``` -_Gf=100,t=f;\ -``` - -Here we tell the terminal emulator to read PNG data from the specified file of -the specified size. - -``` -_Gs=10,v=2,t=s,o=z;\ -``` - -Here we tell the terminal emulator to read compressed image data from -the specified shared memory object. - -The client can also specify a size and offset to tell the terminal emulator -to only read a part of the specified file. The is done using the `S` and `O` -keys respectively. For example: - -``` -_Gs=10,v=2,t=s,S=80,O=10;\ -``` - -This tells the terminal emulator to read `80` bytes starting from the offset `10` -inside the specified shared memory buffer. - - -==== Remote client - -Remote clients, those that are unable to use the filesystem/shared memory to -transmit data, must send the pixel data directly using escape codes. Since -escape codes are of limited maximum length, the data will need to be chunked up -for transfer. This is done using the `m` key. The pixel data must first be -base64 encoded then chunked up into chunks no larger than `4096` bytes. The client -then sends the graphics escape code as usual, with the addition of an `m` key that -must have the value `1` for all but the last chunk, where it must be `0`. For example, -if the data is split into three chunks, the client would send the following -sequence of escape codes to the terminal emulator: - -``` -_Gs=100,v=30,m=1;\ -_Gm=1;\ -_Gm=0;\ -``` - -Note that only the first escape code needs to have the full set of control -codes such as width, height, format etc. Subsequent chunks must have -only the `m` key. The client **must** finish sending all chunks for a single image -before sending any other graphics related escape codes. - - -=== Detecting available transmission mediums - -Since a client has no a-priori knowledge of whether it shares a filesystem/shared memory -with the terminal emulator, it can send an id with the control data, using the `i` key -(which can be an arbitrary positive integer up to 4294967295, it must not be zero). -If it does so, the terminal emulator will reply after trying to load the image, saying -whether loading was successful or not. For example: - -``` -_Gi=31,s=10,v=2,t=s;\ -``` - -to which the terminal emulator will reply (after trying to load the data): - -``` -_Gi=31;error message or OK\ -``` - -Here the `i` value will be the same as was sent by the client in the original -request. The message data will be a ASCII encoded string containing only -printable characters and spaces. The string will be `OK` if reading the pixel -data succeeded or an error message. - -Sometimes, using an id is not appropriate, for example, if you do not want to -replace a previously sent image with the same id, or if you are sending a dummy -image and do not want it stored by the terminal emulator. In that case, you can -use the *query action*, set `a=q`. Then the terminal emulator will try to load -the image and respond with either OK or an error, as above, but it will not -replace an existing image with the same id, nor will it store the image. - - -== Display images on screen - -Every transmitted image can be displayed an arbitrary number of times on the -screen, in different locations, using different parts of the source image, as -needed. You can either simultaneously transmit and display an image using the -action `a=T`, or first transmit the image with a id, such as `i=10` and then display -it with `a=p,i=10` which will display the previously transmitted image at the current -cursor position. When specifying an image id, the terminal emulator will reply with an -acknowledgement code, which will be either: - -``` -_Gi=;OK\ -``` - -when the image referred to by id was found, or - -``` -_Gi=;ENOENT:\ -``` - -when the image with the specified id was not found. This is similar to the -scheme described above for querying available transmission media, except that -here we are querying if the image with the specified id is available or needs to -be re-transmitted. - -=== Controlling displayed image layout - -The image is rendered at the current cursor position, from the upper left corner of -the current cell. You can also specify extra `X=3` and `Y=4` pixel offsets to display from -a different origin within the cell. Note that the offsets must be smaller that the size of the cell. - -By default, the entire image will be displayed (images wider than the available -width will be truncated on the right edge). You can choose a source rectangle (in pixels) -as the part of the image to display. This is done with the keys: `x, y, w, h` which specify -the top-left corner, width and height of the source rectangle. - -You can also ask the terminal emulator to display the image in a specified rectangle -(num of columns / num of lines), using the control codes `c,r`. `c` is the number of columns -and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit -the specified area. Note that if you specify a start cell offset via the `X,Y` keys, it is not -added to the number of rows/columns. - -Finally, you can specify the image *z-index*, i.e. the vertical stacking order. Images -placed in the same location with different z-index values will be blended if -they are semi-transparent. You can specify z-index values using the `z` key. -Negative z-index values mean that the images will be drawn under the text. This -allows rendering of text on top of images. - -== Deleting images - -Images can be deleted by using the delete action `a=d`. If specified without any -other keys, it will delete all images visible on screen. To delete specific images, -use the `d` key as described in the table below. Note that each value of d has -both a lowercase and an uppercase variant. The lowercase variant only deletes the -images without necessarily freeing up the stored image data, so that the images can be -re-displayed without needing to resend the data. The uppercase variants will delete -the image data as well, provided that the image is not referenced elsewhere, such as in the -scrollback buffer. The values of the `x` and `y` keys are the same as cursor positions (i.e. -x=1, y=1 is the top left cell). - -|=== -| Value of `d` | Meaning - -| `a` or `A` | Delete all images visible on screen -| `i` or `I` | Delete all images with the specified id, specified using the `i` key. -| `c` or `C` | Delete all images that intersect with the current cursor position. -| `p` or `P` | Delete all images that intersect a specific cell, the cell is specified using the `x` and `y` keys -| `q` or `Q` | Delete all images that intersect a specific cell having a specific z-index. The cell and z-index is specified using the `x`, `y` and `z` keys. -| `x` or `X` | Delete all images that intersect the specified column, specified using the `x` key. -| `y` or `Y` | Delete all images that intersect the specified row, specified using the `y` key. -| `z` or `Z` | Delete all images that have the specified z-index, specified using the `z` key. - -|=== - - -Some examples: - -``` -_Ga=d\ # delete all visible images -_Ga=d,i=10\ # delete the image with id=10 -_Ga=Z,z=-1\ # delete the images with z-index -1, also freeing up image data -_Ga=P,x=3,y=4\ # delete all images that intersect the cell at (3, 4) -``` - -=== Image persistence and storage quotas - -In order to avoid *Denial-of-Service* attacks, terminal emulators should have a -maximum storage quota for image data. It should allow at least a few full -screen images. For example the quota in kitty is 320MB per buffer. When adding -a new image, if the total size exceeds the quota, the terminal emulator should -delete older images to make space for the new one. - - -== Control data reference - -The table below shows all the control data keys as well as what values they can -take, and the default value they take when missing. All integers are 32-bit. - -[cols="^1,<3,^1,<6"] -|=== -|Key | Value | Default | Description - -| `a` | Single character. `(t, T, q, p, d)` | `t` | The overall action this graphics command is performing. - -4+^.^h| Keys for image transmission - -| `f` | Positive integer. `(24, 32, 100)`. | `32` | The format in which the image data is sent. -| `t` | Single character. `(d, f, t, s)`. | `d` | The transmission medium used. -| `s` | Positive integer. | `0` | The width of the image being sent. -| `v` | Positive integer. | `0` | The height of the image being sent. -| `S` | Positive integer. | `0` | The size of data to read from a file. -| `O` | Positive integer. | `0` | The offset from which to read data from a file. -| `i` | Positive integer. `(0 - 4294967295)` | `0` | The image id -| `o` | Single character. `only z` | `null` | The type of data compression. -| `m` | zero or one | `0` | Whether there is more chunked data available. - -4+^.^h| Keys for image display - -| `x` | Positive integer | `0` | The left edge (in pixels) of the image area to display -| `y` | Positive integer | `0` | The top edge (in pixels) of the image area to display -| `w` | Positive integer | `0` | The width (in pixels) of the image area to display. By default, the entire width is used. -| `h` | Positive integer | `0` | The height (in pixels) of the image area to display. By default, the entire height is used -| `X` | Positive integer | `0` | The x-offset within the first cell at which to start displaying the image -| `Y` | Positive integer | `0` | The y-offset within the first cell at which to start displaying the image -| `c` | Positive integer | `0` | The number of columns to display the image over -| `r` | Positive integer | `0` | The number of rows to display the image over -| `z` | Integer | `0` | The *z-index* vertical stacking order of the image - -4+^.^h| Keys for deleting images - -| `d` | Single character. `(a, A, c, C, p, P, q, Q, x, X, y, Y, z, Z)`. | `a` | What to delete. - -|=== - - -== Interaction with other terminal actions - -When resetting the terminal, all images that are visible on the screen must be -cleared. When switching from the main screen to the alternate screen buffer -(1049 private mode) all images in the alternate screen must be cleared, just as -all text is cleared. The clear screen escape code (usually `[2J`) should also -clear all images. This is so that the clear command works. - -The other commands to erase text must have no effect on graphics. -The dedicated delete graphics commands must be used for those. - -When scrolling the screen (such as when using index cursor movement commands, -or scrolling through the history buffer), images must be scrolled along with -text. When page margins are defined and the index commands are used, only -images that are entirely within the page area (between the margins) must be -scrolled. When scrolling them would cause them to extend outside the page area, -they must be clipped. +See https://sw.kovidgoyal.net/kitty/graphics-protocol.html diff --git a/kittens/diff/README.asciidoc b/kittens/diff/README.asciidoc index 654c59ca6..e7d4cab3c 100644 --- a/kittens/diff/README.asciidoc +++ b/kittens/diff/README.asciidoc @@ -1,129 +1 @@ -= kitty-diff - A side-by-side diff tool with syntax highlighting and images -:toc: -:toc-placement!: - - -== Major Features - -* Displays diffs side-by-side in the kitty terminal. - -* Does syntax highlighting of displayed diffs - -* Displays images as well as text diffs, even over SSH - -* Does recursive directory diffing - - -image::../../screenshots/diff.png?raw=true[Screenshot, showing a sample diff] - -toc::[] - - -== Installation - -Simply install link:https://github.com/kovidgoyal/kitty[kitty]. You also need -to have either the link:https://git-scm.com/[git] program or the `diff` program -installed. Additionally, for syntax highlighting to work, -link:http://pygments.org/[pygments] must be installed (note that pygments is -included in the macOS kitty app). - - -== Usage - -In the kitty terminal, run: - -.... -kitty +kitten diff file1 file2 -.... - -to see the diff between file1 and file2. - -Create an alias in your shell's startup file to shorten the command, for example: - -```sh -alias d="kitty +kitten diff" -``` - -Now all you need to do to diff two files is: - -``` -d file1 file2 -``` - -You can also pass directories instead of files to see the recursive diff of the -directory contents. - - -== Keyboard controls - -|=== -|Action |Shortcut - -|Quit | `q, Ctrl+c` -|Scroll line up | `k, up` -|Scroll line down | `j, down` -|Scroll page up | `PgUp` -|Scroll page down | `PgDn` -|Scroll to top | `Home` -|Scroll to bottom | `End` -|Scroll to next page | `Space, PgDn` -|Scroll to previous page | `PgUp` -|Scroll to next change | `n` -|Scroll to previous change | `p` - -|Increase lines of context | `+` -|Decrease lines of context | `-` -|All lines of context | `a` -|Restore context to default| `=` - -|=== - -[options="header"] - - -== Configuring kitty-diff - -You can configure the colors used, keyboard shortcut, the diff implementation, -the default lines of context, etc. by creating a diff.conf in your kitty -config folder. See the link:diff.conf[default diff.conf] for details. - - -== Integrating with git - -Add the following to `~/.gitconfig`: - -```gitconfig -[diff] - tool = kitty - guitool = kitty.gui -[difftool] - prompt = false - trustExitCode = true -[difftool "kitty"] - cmd = kitty +kitten diff $LOCAL $REMOTE -[difftool "kitty.gui"] - cmd = kitty kitty +kitten diff $LOCAL $REMOTE -``` - -Now to use kitty-diff to view git diffs, you can simply do: - -``` -git difftool --no-symlinks --dir-diff -``` - -Once again, creating an alias for this command is useful. - - -== Why does this work only in kitty? - -The diff kitten makes use of various features that are -link:https://github.com/kovidgoyal/kitty/blob/master/protocol-extensions.asciidoc[kitty -only], such as the -link:https://github.com/kovidgoyal/kitty/blob/master/graphics-protocol.asciidoc[kitty -graphics protocol], the extended keyboard protocol, etc. It also leverages -terminal program infrastructure I created for all of kitty's other kittens to -reduce the amount of code needed (the entire implementation is under 2000 lines -of code). - -And fundamentally, it's kitty only because I wrote it for myself, and I am -highly unlikely to use any other terminals :) +See https://sw.kovidgoyal.net/kitty/kittens/diff.html diff --git a/protocol-extensions.asciidoc b/protocol-extensions.asciidoc index 209686cc5..2fb491ebd 100644 --- a/protocol-extensions.asciidoc +++ b/protocol-extensions.asciidoc @@ -1,170 +1 @@ -= Extensions to the xterm protocol -:toc: -:toc-placement!: - -kitty has a few extensions to the xterm protocol, to enable advanced features. -These are typically in the form of new or re-purposed escape codes. While these -extensions are currently kitty specific, it would be nice to get some of them -adopted more broadly, to push the state of terminal emulators forward. - -The goal of these extensions is to be as small an unobtrusive as possible, -while filling in some gaps in the existing xterm protocol. In particular, one -of the goals of this specification is explicitly not to "re-imagine" the tty. -The tty should remain what it is -- a device for efficiently processing text -received as a simple byte stream. Another objective is to only move the minimum -possible amount of extra functionality into the terminal program itself. This -is to make it as easy to implement these protocol extensions as possible, -thereby hopefully encouraging their widespread adoption. - -If you wish to discuss these extensions, propose additions/changes to them -please do so by opening issues in the github bug tracker. - -toc::[] - -== Colored and styled underlines - -kitty supports colored and styled (wavy) underlines. This is of particular use -in terminal editors such as vim and emacs to display red, wavy underlines under -mis-spelled words and/or syntax errors. This is done by re-purposing some SGR escape codes -that are not used in modern terminals (https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes) - -To set the underline style: - -``` -[4:0m # this is no underline -[4:1m # this is a straight underline -[4:2m # this is a double underline -[4:3m # this is a curly underline -[4:4m # this is a dotted underline (not implemented in kitty) -[4:5m # this is a dashed underline (not implemented in kitty) -[4m # this is a straight underline (for backwards compat) -[24m # this is no underline (for backwards compat) -``` - -To set the underline color (this is reserved and as far as I can tell not actually used for anything): - -``` -[58...m -``` - -This works exactly like the codes `38, 48` that are used to set foreground and -background color respectively. - -To reset the underline color (also previously reserved and unused): - -``` -[59m -``` - -To detect support for this feature in a terminal emulator, query the terminfo database -for the `Su` boolean capability. - -== Graphics rendering - -See link:graphics-protocol.asciidoc[Graphics Protocol] for a description -of this protocol to enable drawing of arbitrary raster images in the terminal. - - -== Keyboard handling - -There are various problems with the current state of keyboard handling. They -include: - - * No way to use modifiers other than `Ctrl` and `Alt` - * No way to use multiple modifier keys, other than, `Shift+Alt`. - * No way to handle different types of keyboard events, such as press, release or repeat - * No reliable way to distinguish single `Esc` keypresses from the - start of a escape sequence. Currently, client programs use - fragile timing related hacks for this, leading to bugs, for example: - link:https://github.com/neovim/neovim/issues/2035[neovim #2035] - -There are already two distinct keyboard handling modes, _normal mode_ and -_application mode_. These modes generate different escape sequences for the -various special keys (arrow keys, function keys, home/end etc.) Most terminals -start out in normal mode, however, most shell programs like `bash` switch them to -application mode. We propose adding a third mode, named _full mode_ that addresses -the shortcomings listed above. - -Switching to the new _full mode_ is accomplished using the standard private -mode DECSET escape sequence - -``` -[?2017h -``` - -and to leave _full mode_, use DECRST - -``` -[?2017l -``` - -The number `2017` above is not used for any existing modes, as far as I know. -Client programs can query if the terminal emulator is in _full mode_ by using -the standard link:http://vt100.net/docs/vt510-rm/DECRQM[DECRQM] escape sequence. - -The new mode works as follows: - - * All printable key presses without modifier keys are sent just as in the - _normal mode_. This means all printable ASCII characters and in addition, - `Enter`, `Space` and `Backspace`. Also any unicode characters generated by - platform specific extended input modes, such as using the `AltGr` key. This - is done so that client programs that are not aware of this mode can still - handle basic text entry, so if a _full mode_ using program crashes and does - not reset, the user can still issue a `reset` command in the shell to restore - normal key handling. Note that this includes pressing the `Shift` modifier - and printable keys. Note that this means there are no repeat and release - events for these keys and also for the left and right shift keys. - - * For non printable keys and key combinations including one or more modifiers, - an escape sequence encoding the key event is sent. For details on the - escape sequence, see below. - -The escape sequence encodes the following properties: - - * Type of event: `press,repeat,release` - * Modifiers pressed at the time of the event - * The actual key being pressed - -``` -_K\ -``` - -Where `` is one of `p` -- press, `r` -- release and `t` -- repeat. -Modifiers is a bitmask represented as a single base64 digit. Shift -- `0x1`, -Alt -- `0x2`, Control -- `0x4` and Super -- `0x8`. `` is a number -(encoded in base85) corresponding to the key pressed. The key name to number -mapping is defined in link:key_encoding.asciidoc[this table]. - -For example: - -``` -_KpGp\ is ++x (press) -_KrP8\ is ++++PageUp (release) -``` - -This encoding means each key event is represented by 8 or 9 printable ascii -only bytes, for maximum robustness. - - -== Setting text styles/colors in arbitrary regions of the screen - -There already exists an escape code to set *some* text attributes in arbitrary -regions of the screen, -link:https://vt100.net/docs/vt510-rm/DECCARA.html[DECCARA]. However, it is -limited to only a few attributes. kitty extends this to work with *all* SGR -attributes. So, for example, this can be used to set the background color in -an arbitrary region of the screen. - -The motivation for this extension is the various problems with the existing -solution for erasing to background color, namely the *background color erase -(bce)* capability. See -link:https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545[this discussion] -and link:http://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches[this FAQ] -for a summary of problems with *bce*. - -For example, to set the background color to blue in a -rectangular region of the screen from (3, 4) to (10, 11), you use: - -``` -[2*x[4;3;11;10;44$r[*x -``` +See https://sw.kovidgoyal.net/kitty/protocol-extensions.html diff --git a/remote-control.asciidoc b/remote-control.asciidoc index 8bd1e17f5..9004eff1c 100644 --- a/remote-control.asciidoc +++ b/remote-control.asciidoc @@ -1,110 +1 @@ -= Controlling kitty from scripts or the shell - -kitty can be controlled from scripts or the shell prompt. You can open new -windows, send arbitrary text input to any window, name windows and tabs, etc. -Let's walk through a few examples of controlling kitty. - -Start by running kitty as: - - kitty -o allow_remote_control=yes --window-layout tall - -In order for control to work, `allow_remote_control` must be enabled in -kitty.conf. Here we turn it on explicitly at the command line. - -Now, in the new kitty window, enter the command: - - kitty @ new-window --title Output --keep-focus cat - -This will open a new window, running the ``cat`` program that will appear next -to the current window. - -Let's send some text to this new window: - - kitty @ send-text --match cmdline:cat Hello, World - -This will make `Hello, World` show up in the window running the `cat` program. -The `--match` option is very powerful, it allows selecting windows by their -titles, the command line of the program running in the window, the working -directory of the program running in the window, etc. See `kitty @ send-text ---help` for details. - -More usefully, you can pipe the output of a command running in one window to -another window, for example: - - ls | kitty @ send-text --match title:Output --stdin - -This will show the output of ls in the output window instead of the current -window. You can use this technique to, for example, show the output of running -`make` in your editor in a different window. The possibilities are endless. - -You can even have things you type show up in a different window. Run: - - kitty @ send-text --match title:Output --stdin - -And type some text, it will show up in the output window, instead of the current -window. Type `Ctrl+D` when you are ready to stop. - -Now, let's open a new tab. - - kitty @ new-window --new-tab --tab-title "My Tab" --keep-focus bash - -This will open a new tab running the bash shell with the title "My Tab". -We can change the title of the tab with: - - kitty @ set-tab-title --match title:My New Title - -Let's change the title of the current tab: - - kitty @ set-tab-title Master Tab - -Now lets switch to the newly opened tab: - - kitty @ focus-tab --match title:New - -Similarly, to focus the previously opened output window (which will also switch -back to the old tab, automatically): - - kitty @ focus-window --match title:Output - -You can get a listing of available tabs and windows, by running: - - kitty @ ls - -This outputs a tree of data in JSON format. The top level of the tree is all -operating system kitty windows. Each OS window has an id and a list of tabs. -Each tab has its own id, a title and a list of windows. Each window has an id, -title, current working directory, process id (PID) and command-line of the -process running in the window. You can use this information with `--match` -to control individual windows. - -As you can see, it is very easy to control kitty using the -`kitty @` messaging system. This tutorial touches only the -surface of what is possible. See `kitty @ --help` for more details. - -Note that in the example's above, `kitty @` messaging works only when run inside a kitty window, -not anywhere. But, within a kitty window it even works over SSH. If you want to control -kitty from programs/scripts not running inside a kitty window, you have to implement a couple of -extra steps. First start kitty as: - - kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty - -The `--listen-on` option tells kitty to listen for control messages at the -specified path. See `kitty --help` for details. Now you can control this -instance of kitty using the `--to` command line argument to `kitty @`. For example: - - kitty @ --to unix:/tmp/mykitty ls - - -Note that is all you want to do is run a single kitty "daemon" and have subsequent -kitty invocations appear as new top-level windows, you can use the simpler `--single-instance` -option, see `kitty --help` for that. - -== The builtin kitty shell - -You can explore the kitty command language more easily using the builtin kitty -shell. Run `kitty @` with no arguments and you will be dropped into the kitty -shell with completion for kitty command names and options. - -You can even open the kitty shell inside a running kitty using a simple -keyboard shortcut (`ctrl+shift+escape` by default). This has the added -advantage that you dont need to use `allow_remote_control` to make it work. +See https://sw.kovidgoyal.net/kitty/remote-control.html