From f82b7841c62ab7e93fa87a1a2d75391204ce87a3 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Tue, 29 May 2018 21:03:50 +0530 Subject: [PATCH] Start work on a kitty website Port the current asciidoc documentation to sphinx --- .gitignore | 1 + README.asciidoc | 512 ------------------ docs/Makefile | 20 + docs/_static/custom.css | 26 + docs/_templates/searchbox.html | 22 + docs/build.rst | 74 +++ docs/conf.py | 196 +++++++ docs/conf.rst | 23 + docs/faq.rst | 114 ++++ docs/graphics-protocol.rst | 396 ++++++++++++++ docs/index.rst | 292 ++++++++++ docs/key-encoding.rst | 129 +++++ docs/kittens/diff.rst | 129 +++++ docs/kittens/hints.rst | 22 + docs/kittens/unicode-input.rst | 18 + docs/performance.rst | 45 ++ docs/protocol-extensions.rst | 165 ++++++ docs/remote-control.rst | 114 ++++ {screenshots => docs/screenshots}/diff.png | Bin .../screenshots}/hints_mode.png | Bin .../screenshots}/screenshot.png | Bin {screenshots => docs/screenshots}/unicode.png | Bin preprocess-readme.py | 57 -- 23 files changed, 1786 insertions(+), 569 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/_static/custom.css create mode 100644 docs/_templates/searchbox.html create mode 100644 docs/build.rst create mode 100644 docs/conf.py create mode 100644 docs/conf.rst create mode 100644 docs/faq.rst create mode 100644 docs/graphics-protocol.rst create mode 100644 docs/index.rst create mode 100644 docs/key-encoding.rst create mode 100644 docs/kittens/diff.rst create mode 100644 docs/kittens/hints.rst create mode 100644 docs/kittens/unicode-input.rst create mode 100644 docs/performance.rst create mode 100644 docs/protocol-extensions.rst create mode 100644 docs/remote-control.rst rename {screenshots => docs/screenshots}/diff.png (100%) rename {screenshots => docs/screenshots}/hints_mode.png (100%) rename {screenshots => docs/screenshots}/screenshot.png (100%) rename {screenshots => docs/screenshots}/unicode.png (100%) delete mode 100755 preprocess-readme.py diff --git a/.gitignore b/.gitignore index db25edd94..676a98024 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ kitty-profile dev __pycache__ glfw/wayland-*-client-protocol.[ch] +docs/_build diff --git a/README.asciidoc b/README.asciidoc index c85f51f5a..fbd55861b 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1,519 +1,7 @@ = kitty - A terminal emulator -:toc: -:toc-placement!: -// START_SHORTCUT_BLOCK -:sc_change_font_size_all_0: pass:quotes[`ctrl+shift+backspace`] -:sc_change_font_size_all_2_0: pass:quotes[`ctrl+shift+minus`] -:sc_change_font_size_all_plus2_0: pass:quotes[`ctrl+shift+equal`] -:sc_close_tab: pass:quotes[`ctrl+shift+q`] -:sc_close_window: pass:quotes[`ctrl+shift+w`] -:sc_copy_to_clipboard: pass:quotes[`ctrl+shift+c`] -:sc_edit_config_file: pass:quotes[`ctrl+shift+f2`] -:sc_eighth_window: pass:quotes[`ctrl+shift+8`] -:sc_fifth_window: pass:quotes[`ctrl+shift+5`] -:sc_first_window: pass:quotes[`ctrl+shift+1`] -:sc_fourth_window: pass:quotes[`ctrl+shift+4`] -:sc_input_unicode_character: pass:quotes[`ctrl+shift+u`] -:sc_kitten_hints: pass:quotes[`ctrl+shift+e`] -:sc_kitten_hints_type_line_program: pass:quotes[`ctrl+shift+p → l`] -:sc_kitten_hints_type_path: pass:quotes[`ctrl+shift+p → shift+f`] -:sc_kitten_hints_type_path_program: pass:quotes[`ctrl+shift+p → f`] -:sc_kitten_hints_type_word_program: pass:quotes[`ctrl+shift+p → w`] -:sc_kitty_shell_window: pass:quotes[`ctrl+shift+escape`] -:sc_move_tab_backward: pass:quotes[`ctrl+shift+,`] -:sc_move_tab_forward: pass:quotes[`ctrl+shift+.`] -:sc_move_window_backward: pass:quotes[`ctrl+shift+b`] -:sc_move_window_forward: pass:quotes[`ctrl+shift+f`] -:sc_move_window_to_top: pass:quotes[`ctrl+shift+``] -:sc_new_os_window: pass:quotes[`ctrl+shift+n`] -:sc_new_tab: pass:quotes[`ctrl+shift+t`] -:sc_new_window: pass:quotes[`ctrl+shift+enter`] -:sc_next_layout: pass:quotes[`ctrl+shift+l`] -:sc_next_tab: pass:quotes[`ctrl+shift+right`] -:sc_next_window: pass:quotes[`ctrl+shift+]`] -:sc_ninth_window: pass:quotes[`ctrl+shift+9`] -:sc_pass_selection_to_program: pass:quotes[`ctrl+shift+o`] -:sc_paste_from_clipboard: pass:quotes[`ctrl+shift+v`] -:sc_paste_from_selection: pass:quotes[`ctrl+shift+s` or `shift+insert`] -:sc_previous_tab: pass:quotes[`ctrl+shift+left`] -:sc_previous_window: pass:quotes[`ctrl+shift+[`] -:sc_scroll_end: pass:quotes[`ctrl+shift+end`] -:sc_scroll_home: pass:quotes[`ctrl+shift+home`] -:sc_scroll_line_down: pass:quotes[`ctrl+shift+down` or `ctrl+shift+j`] -:sc_scroll_line_up: pass:quotes[`ctrl+shift+up` or `ctrl+shift+k`] -:sc_scroll_page_down: pass:quotes[`ctrl+shift+page_down`] -:sc_scroll_page_up: pass:quotes[`ctrl+shift+page_up`] -:sc_second_window: pass:quotes[`ctrl+shift+2`] -:sc_set_background_opacity_0_1: pass:quotes[`ctrl+shift+a → l`] -:sc_set_background_opacity_1: pass:quotes[`ctrl+shift+a → 1`] -:sc_set_background_opacity_default: pass:quotes[`ctrl+shift+a → d`] -:sc_set_background_opacity_plus0_1: pass:quotes[`ctrl+shift+a → m`] -:sc_set_tab_title: pass:quotes[`ctrl+shift+alt+t`] -:sc_seventh_window: pass:quotes[`ctrl+shift+7`] -:sc_show_scrollback: pass:quotes[`ctrl+shift+h`] -:sc_sixth_window: pass:quotes[`ctrl+shift+6`] -:sc_start_resizing_window: pass:quotes[`ctrl+shift+r`] -:sc_tenth_window: pass:quotes[`ctrl+shift+0`] -:sc_third_window: pass:quotes[`ctrl+shift+3`] -:sc_toggle_fullscreen: pass:quotes[`ctrl+shift+f11`] -// END_SHORTCUT_BLOCK -++++ - -++++ image::https://travis-ci.org/kovidgoyal/kitty.svg?branch=master[Build status, link=https://travis-ci.org/kovidgoyal/kitty] -== Major Features - -* Uses OpenGL for rendering, offloads rendering to the GPU for link:#performance[lower system -load] and buttery smooth scrolling. Uses threaded rendering to minimize input -latency. - -* Supports all modern terminal features: link:graphics-protocol.asciidoc[graphics (images)], unicode, -true-color, OpenType ligatures, mouse protocol, focus tracking, bracketed paste and so on. - -* Supports tiling multiple terminal windows side by side in different -link:#layouts[layouts] without needing to use an extra program like tmux - -* Can be link:remote-control.asciidoc[controlled from scripts or the shell prompt], even over SSH. - -* Has a framework for _kittens_, small terminal programs that can be used to extend kitty's functionality. -For example, they are used for link:#unicode-input[Unicode input], link:#hints[Hints] and link:https://github.com/kovidgoyal/kitty/blob/master/kittens/diff/README.asciidoc[Side-by-side diff]. - -* Supports link:#startup-sessions[startup sessions] which allow you to specify the window/tab layout, -working directories and programs to run on startup. - -* Cross-platform support: kitty currently works on Linux and macOS, but because -it uses only OpenGL for rendering, it should be trivial to port to other -platforms. - -* Allows you to open link:#the-scrollback-buffer[the scrollback buffer] in a separate -window using arbitrary programs of your choice. This is useful for browsing -the history comfortably in a pager or editor. - - -image::screenshots/screenshot.png?raw=true[Screenshot, showing three programs in the "Tall" layout] - -toc::[] - - -== Installation - -kitty is designed to run from source, for easy hackability. Make sure -the following dependencies are installed first. - -=== Dependencies - -* python >= 3.5 -* harfbuzz >= 1.5.0 -* zlib -* libpng -* freetype (not needed on macOS) -* fontconfig (not needed on macOS) -* ImageMagick (optional, needed to use the `kitty icat` tool to display images in the terminal) -* pygments (optional, need for syntax highlighting in `kitty +kitten diff`) -* gcc or clang (required only for building) -* pkg-config (required only for building) -* For building on Linux in addition to the above dependencies you might also need to install the `-dev` packages for `xcursor`, `xrandr`, `libxi`, `xinerama`, `libgl1-mesa` and `xkbcommon-x11`, if they are not already installed by your distro. - -=== Install and run from source - -.... -git clone https://github.com/kovidgoyal/kitty && cd kitty -.... - -Now build the native code parts of kitty with the following command: - -.... -make -.... - -You can run kitty, as: - -.... -python3 . -.... - -If that works, you can create a script to launch kitty: - -.... -#!/usr/bin/env python3 - -import runpy -runpy.run_path('/path/to/kitty/dir', run_name='__main__') -.... - -And place it in `~/bin` or `/usr/bin` so that you can run kitty using -just `kitty`. - -=== Linux packages - -* Arch Linux: https://www.archlinux.org/packages/community/x86_64/kitty/ - -* Arch Linux: AUR git package https://aur.archlinux.org/packages/kitty-git/ - -* NixOS / nixpkgs: https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/kitty/default.nix - -* Gentoo: https://packages.gentoo.org/packages/x11-terms/kitty - -* openSUSE: https://build.opensuse.org/package/show/X11:terminals/kitty - -* Debian: https://packages.debian.org/buster/kitty - -=== macOS packages - -kitty is available as a macOS `dmg` file for easy installation from the -link:../../releases[releases page]. You can also run kitty directly from -source using the above install from source instructions, after installing its -dependencies using http://brew.sh/[brew] or a similar package manager. - - -== Design philosophy - -kitty is designed for power keyboard users. To that end all its controls -work with the keyboard (although it fully supports mouse interactions as -well). Its configuration is a simple, human editable, single file for -easy reproducibility (I like to store config files in source control). - -The code in kitty is designed to be simple, modular and hackable. It is -written in a mix of C (for performance sensitive parts) and Python (for -easy hackability of the UI). It does not depend on any large and complex -UI toolkit, using only OpenGL for rendering everything. - -Finally, kitty is designed from the ground up to support all modern -terminal features, such as unicode, true color, bold/italic fonts, text -formatting, etc. It even extends existing text formatting escape codes, -to add support for features not available elsewhere, such as colored and -styled (curly) underlines. One of the design goals of kitty is to be -easily extensible so that new features can be added in the future with -relatively less effort. - -== Tabs and Windows - -kitty is capable of running multiple programs organized into tabs and -windows. The top level of organization is the _Tab_. Each tab consists -of one or more _windows_. The windows can be arranged in multiple -different layouts, like windows are organized in a tiling window -manager. The keyboard controls (which are all customizable) for tabs and -windows are: - -[[scrolling-shortcuts]] -[options="header"] - -=== Scrolling - -|=== -|Action |Shortcut - -|Scroll line up | {sc_scroll_line_up} -|Scroll line down | {sc_scroll_line_down} -|Scroll page up | {sc_scroll_page_up} -|Scroll page down | {sc_scroll_page_down} -|Scroll to top | {sc_scroll_home} -|Scroll to bottom | {sc_scroll_end} - -|=== - -[options="header"] - -=== Tabs - -|=== -|Action |Shortcut - -|New tab | {sc_new_tab} -|Close tab | {sc_close_tab} -|Next tab | {sc_next_tab} -|Previous tab | {sc_previous_tab} -|Next layout | {sc_next_layout} -|Move tab forward | {sc_move_tab_forward} -|Move tab backward | {sc_move_tab_backward} -|Set tab title | {sc_set_tab_title} - -|=== - - -[options="header"] - -=== Windows - -|=== -|Action |Shortcut - -|New window | {sc_new_window} -|New OS window| {sc_new_os_window} -|Close window | {sc_close_window} -|Next window | {sc_next_window} -|Previous window | {sc_previous_window} -|Move window forward | {sc_move_window_forward} -|Move window backward | {sc_move_window_backward} -|Move window to top | {sc_move_window_to_top} -|Focus specific window (windows are counted clockwise from the top left corner) | {sc_first_window}, {sc_second_window} ... {sc_tenth_window} - -|=== - -== Other keyboard shortcuts - -|=== -|Action |Shortcut - -|Copy to clipboard | {sc_copy_to_clipboard} -|Paste from clipboard | {sc_paste_from_clipboard} -|Paste from selection | {sc_paste_from_selection} -|Increase font size | {sc_change_font_size_all_plus2_0} -|Decrease font size | {sc_change_font_size_all_2_0} -|Restore font size | {sc_change_font_size_all_0} -|Toggle fullscreen | {sc_toggle_fullscreen} -|Input unicode character | {sc_input_unicode_character} -|Click URL using the keyboard | {sc_kitten_hints} -|Pass current selection to program | {sc_pass_selection_to_program} -|Edit kitty config file | {sc_edit_config_file} -|Open a kitty shell | {sc_kitty_shell_window} -|Increase background opacity | {sc_set_background_opacity_plus0_1} -|Decrease background opacity | {sc_set_background_opacity_0_1} -|Full background opacity | {sc_set_background_opacity_1} -|Reset background opacity | {sc_set_background_opacity_default} -|=== - - -== Controlling kitty from scripts - -You can control kitty from the command line/scripts by sending it messages. -You can tell kitty to open/close/rename tabs and windows. You can even send -arbitrary input/text to any specified window. Messages can be sent using `kitty -@`. Note that you must set `allow_remote_control yes` in your -link:kitty/kitty.conf[kitty.conf] to use this feature. It even works over SSH -connections. This feature is best illustrated with a -link:remote-control.asciidoc[tutorial]. - - -== The scrollback buffer - -kitty supports scrolling back to view history, just like most terminals. You -can use either the <> or the mouse -scroll wheel to do so. However, kitty has an extra, neat feature. Sometimes -you need to explore the scrollback buffer in more detail, maybe search for some -text or refer to it side-by-side while typing in a follow-up command. kitty -allows you to do this by pressing the {sc_show_scrollback} key-combination, -which will open the scrollback buffer in your favorite pager program (which is -`less` by default). Colors and text formatting are preserved. You can explore -the scrollback pager comfortably within the pager. - - -== Unicode input - -You can input unicode characters by name, hex code, recently used and even an editable favorites list. -Press {sc_input_unicode_character} to start the unicode input widget, shown below. - -image::screenshots/unicode.png?raw=true[Unicode input widget, showing selection of unicode characters by name] - -In Code mode, you enter a unicode character by typing in the hex code for the -character and pressing enter, for example, type in 2716 and press enter to get -✖. You can also choose a character from the list of recently used characters by -typing a leading period and then the two character index and pressing Enter. - -In Name mode you instead type words from the character name and use the arrow -keys/tab to select the character from the displayed matches. You can also type -a leading period and the index for the match if you dont like to use arrow -keys. - -== Hints - -kitty has a _hints mode_ to select and act on arbitrary text snippets currently -visible on the screen. For example, you can press {sc_kitten_hints} -to choose any URL visible on the screen and then open it using your system -browser. - -image::screenshots/hints_mode.png?raw=true[URL hints mode] - -Similarly, you can press {sc_kitten_hints_type_path_program} to -select anything that looks like a path or filename and then insert it into the -terminal, very useful for picking files from the output of a git or ls command and -adding them to the command line for the next command. - -The hints kitten is very powerful to see more detailed help on its various -options and modes of operation, use: `kitty +kitten hints --help`. - -== Miscellaneous features - -* You can also hold down `ctrl+shift` and click on a URL to open it in a browser. -* You can double click to select a word and triple click to select a line. -* You can right click to extend a previous selection - - -== Layouts - -Currently, there are five layouts available, - -* Stack -- Only a single maximized window is shown at a time -* Tall -- One window is shown full height on the left, the rest of the windows are shown one below the other on the right -* Fat -- One window is shown full width on the top, the rest of the windows are shown side-by-side on the bottom -* Grid -- All windows are shown in a grid -* Horizontal -- All windows are shown side-by-side -* Vertical -- All windows are shown one below the other - -You can switch between layouts using the {sc_next_layout} key combination. You can -also create shortcuts to select particular layouts, and choose which layouts -you want to enable/disable, see link:kitty/kitty.conf[kitty.conf] for examples. - -You can resize windows inside layouts. Press {sc_start_resizing_window} to -enter resizing mode and follow the on-screen instructions. In a given window -layout only some operations may be possible for a particular window. For -example, in the Tall layout you can make the first window wider/narrower, but -not taller/shorter. Note that what you are resizing is actually not a window, -but a row/column in the layout, all windows in that row/column will be resized. - -Some layouts take options to control their behavior. For example, the `fat` and `tall` -layouts accept the `bias` option to control how the available space is split up. To specify the -option, in kitty.conf use: - -``` -enabled_layouts tall:bias=70 -``` - -This will make the tall window occupy `70%` of available width. `bias` can be -any number between 10 and 90. - -Writing a new layout only requires about a hundred lines of code, so if there is -some layout you want, take a look at link:kitty/layout.py[layout.py] and submit -a pull request! - - -== Configuration - -kitty is highly customizable, everything from keyboard shortcuts, to painting -frames-per-second. See the heavily commented link:kitty/kitty.conf[default -config file] for an overview of all customization possibilities. - -By default kitty looks for a config file in the OS config directories (usually -`~/.config/kitty/kitty.conf` and additionally -`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a specific -path via the `--config` option or use the `KITTY_CONFIG_DIRECTORY` environment -variable. See the help for the `--config` option in `kitty --help` for full -details. You can also dump the current configuration using the `--debug-config` -option. - - -== Startup Sessions - -You can control the tabs, window layout, working directory, startup -programs, etc. by creating a "session" file and using the `--session` -command line flag. For example: - -.... -# Set the window layout for the current tab -layout tall -# Set the working directory for windows in the current tab -cd ~ -# Create a window and run the specified command in it -launch zsh -# Create a window with some environment variables set and run vim in it -launch env FOO=BAR vim -# Set the title for the next window -title Chat with x -launch irssi --profile x - -# Create a new tab (the part after new_tab is the optional tab name which will -# be displayed in the tab bar, if omitted, the title of the active window will -# be used instead) -new_tab my tab -cd ~/somewhere -# Set the layouts allowed in this tab -enabled_layouts tall, stack -# Set the current layout -layout stack -launch zsh -# Make the current window the active (focused) window -focus -launch emacs -.... - -== Protocol Extensions - -kitty has a few extensions to the xterm protocol, to enable advanced features, -see link:protocol-extensions.asciidoc[Protocol Extensions]. - - -== Font control - -kitty has extremely flexible and powerful font selection features. You can -specify individual families for the regular, bold, italic and bold+italic -fonts. You can even specify specific font families for specific ranges of -unicode characters. This allows precise control over text rendering. It can -come in handy for applications like powerline, without the need to use patched -fonts. See the various font related configuration directives in the -link:kitty/kitty.conf[config file]. - -== Performance - -The main goals for kitty performance are user perceived latency while typing -and "smoothness" while scrolling as well as CPU usage. kitty tries hard to find -an optimum balance for these. To that end it keeps a cache of each rendered -glyph in video RAM so that font rendering is not a bottleneck. Interaction -with child programs takes place in a separate thread from rendering, to improve -smoothness. - -There are two parameters you can tune to adjust the performance. ``repaint_delay`` -and ``input_delay``. These control the artificial delays introduced into the -render loop to reduce CPU usage. See the link:kitty/kitty.conf[config file] for details. -See also the ``sync_to_monitor`` option to further decrease latency at the cost -of some link:https://en.wikipedia.org/wiki/Screen_tearing[tearing] while scrolling. - -You can generate detailed per-function performance data using -link:https://github.com/gperftools/gperftools[gperftools]. Build kitty with -`make profile` which will create an executable called `kitty-profile`. Run -that and perform the task you want to analyse, for example, scrolling a large -file with `less`. After you quit, function call statistics will be printed to -`stdout` and you can use tools like *kcachegrind* for more detailed analysis. - -Here are some CPU usage numbers for the task of scrolling a file continuously in less. -The CPU usage is for the terminal process and X together and is measured using htop. -The measurements are taken at the same font and window size for all terminals on a -`Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz` CPU with a -`Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD 7770/8760 / R7 250X]` GPU. - -|=== -| Terminal | CPU usage (X + terminal) - -| kitty | 6 - 8% -| xterm | 5 - 7% (but scrolling was extremely janky) -| termite | 10 - 13% -| urxvt | 12 - 14% -| gnome-terminal | 15 - 17% -| konsole | 29 - 31% - -|=== - -As you can see, kitty uses much less CPU than all terminals, except xterm, but -its scrolling "smoothness" is much better than that of xterm (at least to my, -admittedly biased, eyes). - -== Note for Linux/macOS packagers - -While kitty does use python, it is not a traditional python package, so please do not install it in site-packages. -Instead run, - -``` -python3 setup.py linux-package -``` - -This will install kitty into the directory `linux-package`. You can run kitty -with `linux-package/bin/kitty`. All the files needed to run kitty will be in -`linux-package/lib/kitty`. The terminfo file will be installed into -`linux-package/share/terminfo`. Simply copy these files into `/usr` to install -kitty. In other words, `linux-package` is the staging area into which kitty is -installed. You can choose a different staging area, by passing the `--prefix` -argument to `setup.py`. - -You should probably split kitty into two packages, `kitty-terminfo` that -installs the terminfo file and `kitty` that installs the main program. -This allows users to install the terminfo file on servers into which they ssh, -without needing to install all of kitty. - -You also need `tic` to compile the terminfo files, it is usually found in the development package of `ncurses` - -This applies to creating packages for kitty for macOS package managers such as -brew or MacPorts as well. == Frequently Asked Questions diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..c01685013 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = kitty +launch /usr/bin/sphinx-build +SPHINXPROJ = kitty +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 000000000..f7e79d2dc --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,26 @@ +/* + * custom.css + * Copyright (C) 2018 Kovid Goyal + * + * Distributed under terms of the MIT license. + */ + +.float-left-img { + float: left; + margin-right: 1em; + margin-bottom: 1em; +} + +a { + text-decoration: none !important; + border-bottom: none !important; +} + +#searchbox h3 { + display: none; +} + +.major-features li { + margin-top: 0.75ex; + margin-bottom: 0.75ex; +} diff --git a/docs/_templates/searchbox.html b/docs/_templates/searchbox.html new file mode 100644 index 000000000..f91b4d100 --- /dev/null +++ b/docs/_templates/searchbox.html @@ -0,0 +1,22 @@ +{# + basic/searchbox.html + ~~~~~~~~~~~~~~~~~~~~ + + Sphinx sidebar template: quick search box. + + :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{%- if pagename != "search" and builder != "singlehtml" %} + + +{%- endif %} diff --git a/docs/build.rst b/docs/build.rst new file mode 100644 index 000000000..bf49f6cee --- /dev/null +++ b/docs/build.rst @@ -0,0 +1,74 @@ +Building kitty from source +============================== + +|kitty| is designed to run from source, for easy hackability. Make sure +the following dependencies are installed first. + +Dependencies +---------------- + +* python >= 3.5 +* harfbuzz >= 1.5.0 +* zlib +* libpng +* freetype (not needed on macOS) +* fontconfig (not needed on macOS) +* ImageMagick (optional, needed to use the ``kitty icat`` tool to display images in the terminal) +* pygments (optional, need for syntax highlighting in ``kitty +kitten diff``) +* gcc or clang (required only for building) +* pkg-config (required only for building) +* For building on Linux in addition to the above dependencies you might also need to install the ``-dev`` packages for ``xcursor``, ``xrandr``, ``libxi``, ``xinerama``, ``libgl1-mesa`` and ``xkbcommon-x11``, if they are not already installed by your distro. + +Install and run from source +------------------------------ + +.. code-block:: sh + + git clone https://github.com/kovidgoyal/kitty && cd kitty + +Now build the native code parts of |kitty| with the following command:: + + make + +You can run |kitty|, as:: + + python3 . + +If that works, you can create a script to launch |kitty|: + +.. code-block:: sh + + #!/usr/bin/env python3 + import runpy + runpy.run_path('/path/to/kitty/dir', run_name='__main__') + +And place it in :file:`~/bin` or :file:`/usr/bin` so that you can run |kitty| using +just ``kitty``. + +Note for Linux/macOS packagers +---------------------------------- + +While kitty does use python, it is not a traditional python package, so please +do not install it in site-packages. +Instead run:: + + python3 setup.py linux-package + +This will install kitty into the directory :file:`linux-package`. You can run kitty +with :file:`linux-package/bin/kitty`. All the files needed to run kitty will be in +:file:`linux-package/lib/kitty`. The terminfo file will be installed into +:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install +kitty. In other words, :file:`linux-package` is the staging area into which kitty is +installed. You can choose a different staging area, by passing the ``--prefix`` +argument to :file:`setup.py`. + +You should probably split kitty into two packages, :file:`kitty-terminfo` that +installs the terminfo file and :file:`kitty` that installs the main program. +This allows users to install the terminfo file on servers into which they ssh, +without needing to install all of kitty. + +You also need :file:`tic` to compile the terminfo files, it is usually found in +the development package of :file:`ncurses`. + +This applies to creating packages for kitty for macOS package managers such as +brew or MacPorts as well. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..db1c07b88 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,196 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +from collections import defaultdict + + +def create_shortcut_defs(): + defns = defaultdict(list) + + for line in open('../kitty/kitty.conf'): + if line.startswith('map '): + _, sc, name = line.split(maxsplit=2) + sc = sc.replace('kitty_mod', 'ctrl+shift') + name = name.rstrip().replace(' ', '_').replace('-', '_').replace('+', 'plus').replace('.', '_').replace('___', '_').replace('__', '_').strip('_') + defns[name].append(':kbd:`' + sc.replace('>', ' → ') + '`') + + defns = [ + '.. |sc_{}| replace:: {}'.format(name, ' or '.join(defns[name])) + for name in sorted(defns) + ] + return '\n'.join(defns) + + +# -- Project information ----------------------------------------------------- + +project = 'kitty' +copyright = '2018, Kovid Goyal' +author = 'Kovid Goyal' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +needs_sphinx = '1.7' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +rst_prolog = ''' +.. |kitty.conf| replace:: :doc:`kitty.conf ` +.. |kitty| replace:: *kitty* + +''' + create_shortcut_defs() + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + 'logo': 'kitty.png', + 'show_powered_by': False, + 'fixed_sidebar': True, + 'sidebar_collapse': True, + 'analytics_id': 'UA-20736318-1', + 'github_button': True, +} + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static', '../logo/kitty.png'] +html_context = { + 'css_files': ['_static/custom.css'] +} + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +html_sidebars = { + '**': [ + 'about.html', + 'searchbox.html', + 'localtoc.html', + 'relations.html', + ] +} +html_show_sourcelink = False + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'kittydoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'kitty.tex', 'kitty Documentation', + 'Kovid Goyal', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'kitty', 'kitty Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'kitty', 'kitty Documentation', + author, 'kitty', 'One line description of project.', + 'Miscellaneous'), +] + + +def setup(app): + pass diff --git a/docs/conf.rst b/docs/conf.rst new file mode 100644 index 000000000..6c3bfc55f --- /dev/null +++ b/docs/conf.rst @@ -0,0 +1,23 @@ +Configuring kitty +=============================== + +|kitty| is highly customizable, everything from keyboard shortcuts, to painting +frames-per-second. See the heavily commented default config file below for an +overview of all customization possibilities. + +You can open the config file within kitty by pressing |sc_edit_config_file|. +You can also display the current configuration by running ``kitty +--debug-config``. + + + +.. literalinclude:: ../kitty/kitty.conf + :language: ini + + +|kitty| looks for a config file in the OS config directories (usually +:file:`~/.config/kitty/kitty.conf` and additionally +:file:`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a +specific path via the ``--config`` option or use the ``KITTY_CONFIG_DIRECTORY`` +environment variable. See the help for the :option:`--config` option in ``kitty +--help`` for full details. diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 000000000..b3f565991 --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,114 @@ +Frequently Asked Questions +============================== + +.. highlight:: sh + +.. contents:: + +Some special symbols are rendered small/truncated in kitty? +----------------------------------------------------------------- + +The number of cells a unicode character takes up are controlled by the unicode +standard. All characters are rendered in a single cell unless the unicode +standard says they should be rendered in two cells. When a symbol does not fit, +it will either be rescaled to be smaller or truncated (depending on how much +extra space it needs). This is often different from other terminals which just +let the character overflow into neighboring cells, which is fine if the +neighboring cell is empty, but looks terrible if it is not. + +Some programs, like powerline, vim with fancy gutter symbols/status-bar, etc. +misuse unicode characters from the private use area to represent symbols. Often +these symbols are square and should be rendered in two cells. However, since +private use area symbols all have their width set to one in the unicode +standard, |kitty| renders them either smaller or truncated. The exception is if +these characters are followed by a space or empty cell in which case kitty +makes use of the extra cell to render them in two cells. + + +How do I build kitty.app on macOS? +---------------------------------------- + +Install `imagemagick`, `optipng` and `librsvg` using `brew` or similar (needed +for the logo generation step). And run:: + + make app + +This :file:`kitty.app` unlike the released one does not include its own copy of +python and the other dependencies. So if you ever un-install/upgrade those dependencies +you might have to rebuild the app. + +Note that the released :file:`kitty.dmg` includes all dependencies, unlike the +:file:`kitty.app` built above and is built automatically by using the :file:`kitty` branch of +`build-calibre `_ however, that +is designed to run on Linux and is not for the faint of heart. + + +Using a color theme with a background color does not work well in vim? +----------------------------------------------------------------------- + +First make sure you have not changed the TERM environment variable, it should +be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file +does not contain the ``bce`` capability. This is a bug in vim. You can work around +it by adding the following to your vimrc:: + + let &t_ut='' + + +See `here `_ for why |kitty| does not support background color erase. + +I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer? +----------------------------------------------------------------------------------------------------------------------- + +This happens because the |kitty| terminfo files are not available on the server. +You can ssh in using the following command which will automatically copy the +terminfo files to the server:: + + kitty +kitten ssh myserver + +If for some reason that does not work (typically because the server is using a +very limited shell), you can use the following one-liner instead (it is slower +as it needs to ssh into the server twice, but will work with most servers):: + + infocmp xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin + +Really, the correct solution for this is to convince the OpenSSH maintainers to +have ssh do this automatically when connecting to a server, so that all +terminals work transparently. + + +How do I change the colors in a running kitty instance? +------------------------------------------------------------ + +You can either use the +`OSC terminal escape codes `_ +to set colors or you can enable :doc:`remote control ` +for |kitty| and use ``kitty @ set-colors --help``. + + +How do I specify command line options for kitty on macOS? +--------------------------------------------------------------- + +Apple does not want you to use command line options with GUI applications. To +workaround that limitation, |kitty| will read command line options from the file +:file:`/macos-launch-services-cmdline` when it is launched +from the GUI, i.e. by clicking the |kitty| application icon or using ``open -a kitty``. +Note that this file is *only read* when running via the GUI. + +You can, of course, also run |kitty| from a terminal with command line options, using: +:file:`/Applications/kitty.app/Contents/MacOS/kitty`. + +And within |kitty| itself, you can always run |kitty| using just `kitty` as it +cleverly adds itself to the ``PATH``. + + +kitty is not able to use my favorite font? +--------------------------------------------- + +|kitty| achieves its stellar performance by caching alpha masks of each rendered +character on the GPU, so that every character needs to be rendered only once. +This means it is a strictly character cell based display. As such it can use +only monospace fonts, since every cell in the grid has to be the same size. If +your font is not listed in ``kitty list-fonts`` it means that it is not +monospace. On Linux you can list all monospace fonts with:: + + fc-list : family spacing | grep spacing=100 diff --git a/docs/graphics-protocol.rst b/docs/graphics-protocol.rst new file mode 100644 index 000000000..f41799912 --- /dev/null +++ b/docs/graphics-protocol.rst @@ -0,0 +1,396 @@ +The terminal graphics protocol +================================== + +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 `#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. + +.. image:: https://user-images.githubusercontent.com/1308621/31647475-1188ab66-b326-11e7-8d26-24b937f1c3e8.png + :alt: Demo of graphics rendering in kitty + :align: center + +Some programs that use the kitty graphics protocol: + + * `termpdf `_ - a terminal PDF/DJVU/CBR viewer + * `ranger `_ - a terminal file manager, with + image previews, see this `PR `_ + * :doc:`kitty-diff ` - a side-by-side terminal diff program with support for images + * `neofetch `_ - A command line system + information tool + + +.. contents:: + + +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: + +.. code-block:: 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: + +.. code-block:: python + + 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 `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. + +======= ==================== ========= ================= +Key Value Default Description +======= ==================== ========= ================= +``a`` Single character. ``t`` The overall action this graphics command is performing. + ``(t, T, q, p, d)`` +**Keys for image transmission** +----------------------------------------------------------- +``f`` Positive integer. ``32`` The format in which the image data is sent. + ``(24, 32, 100)``. +``t`` Single character. ``d`` The transmission medium used. + ``(d, f, t, s)``. +``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. ``null`` The type of data compression. + ``only z`` +``m`` zero or one ``0`` Whether there is more chunked data available. +**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 +**Keys for deleting images** +----------------------------------------------------------- +``d`` Single character. ``a`` What to delete. + ``(a, A, c, C, p, + P, q, Q, x, X, y, + Y, z, Z)``. +======= ==================== ========= ================= + + +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. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..8d1099ed0 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,292 @@ +========================================================== +kitty - the fast, featureful, GPU based, terminal emulator +========================================================== + +.. container:: major-features + + * Offloads rendering to the GPU for :doc:`lower system load ` and + buttery smooth scrolling. Uses threaded rendering to minimize input latency. + + * Supports all modern terminal features: :doc:`graphics (images) + `, unicode, true-color, OpenType ligatures, mouse + protocol, focus tracking, bracketed paste and so on. + + * Supports tiling multiple terminal windows side by side in different + :ref:`layouts ` without needing to use an extra program like tmux + + * Can be :doc:`controlled from scripts or the shell prompt `, + even over SSH. + + * Has a framework for *kittens*, small terminal programs that can be used to + extend |kitty|'s functionality. For example, they are used for + :doc:`Unicode input `, :doc:`Hints ` and + :doc:`Side-by-side diff `. + + * Supports :ref:`startup sessions ` which allow you to specify + the window/tab layout, working directories and programs to run on startup. + + * Cross-platform: |kitty| works on Linux and macOS, but because it uses only + OpenGL for rendering, it should be trivial to port to other platforms. + + * Allows you to open :ref:`the scrollback buffer ` in a + separate window using arbitrary programs of your choice. This is useful for + browsing the history comfortably in a pager or editor. + + +.. figure:: screenshots/screenshot.png + :alt: Screenshot, showing three programs in the 'Tall' layout + :align: center + + Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout + + +Quickstart +-------------- + +If you are on macOS, simply download and install the ``.dmg`` from the `releases +page `_. + +If you are on Linux, install the |kitty| package if your distro provides it, +otherwise follow the :doc:`Build from source instructions `. |kitty| +packages are available for: +`Debian `_, +`openSUSE `_, +`Arch Linux `_, +`NixOS `_, +`Gentoo `_, +`Fedora `_. + + +.. contents:: + + +Design philosophy +------------------- + +|kitty| is designed for power keyboard users. To that end all its controls +work with the keyboard (although it fully supports mouse interactions as +well). Its configuration is a simple, human editable, single file for +easy reproducibility (I like to store configuration in source control). + +The code in |kitty| is designed to be simple, modular and hackable. It is +written in a mix of C (for performance sensitive parts) and Python (for +easy hackability of the UI). It does not depend on any large and complex +UI toolkit, using only OpenGL for rendering everything. + +Finally, |kitty| is designed from the ground up to support all modern +terminal features, such as unicode, true color, bold/italic fonts, text +formatting, etc. It even extends existing text formatting escape codes, +to add support for features not available elsewhere, such as colored and +styled (curly) underlines. One of the design goals of |kitty| is to be +easily extensible so that new features can be added in the future with +relatively less effort. + +Tabs and Windows +------------------- + +|kitty| is capable of running multiple programs organized into tabs and +windows. The top level of organization is the *Tab*. Each tab consists +of one or more *windows*. The windows can be arranged in multiple +different layouts, like windows are organized in a tiling window +manager. The keyboard controls (which are all customizable) for tabs and +windows are: + +Scrolling +~~~~~~~~~~~~~~ + +======================== ======================= +Action Shortcut +======================== ======================= +Scroll line up |sc_scroll_line_up| +Scroll line down |sc_scroll_line_down| +Scroll page up |sc_scroll_page_up| +Scroll page down |sc_scroll_page_down| +Scroll to top |sc_scroll_home| +Scroll to bottom |sc_scroll_end| +======================== ======================= + +Tabs +~~~~~~~~~~~ + +======================== ======================= +Action Shortcut +======================== ======================= +New tab |sc_new_tab| +Close tab |sc_close_tab| +Next tab |sc_next_tab| +Previous tab |sc_previous_tab| +Next layout |sc_next_layout| +Move tab forward |sc_move_tab_forward| +Move tab backward |sc_move_tab_backward| +Set tab title |sc_set_tab_title| +======================== ======================= + + +Windows +~~~~~~~~~~~~~~~~~~ + +======================== ======================= +Action Shortcut +======================== ======================= +New window |sc_new_window| +New OS window |sc_new_os_window| +Close window |sc_close_window| +Next window |sc_next_window| +Previous window |sc_previous_window| +Move window forward |sc_move_window_forward| +Move window backward |sc_move_window_backward| +Move window to top |sc_move_window_to_top| +Focus specific window |sc_first_window|, |sc_second_window| ... |sc_tenth_window| + (clockwise from the top-left) +======================== ======================= + + +Other keyboard shortcuts +---------------------------------- + +================================== ======================= +Action Shortcut +================================== ======================= +Copy to clipboard |sc_copy_to_clipboard| +Paste from clipboard |sc_paste_from_clipboard| +Paste from selection |sc_paste_from_selection| +Increase font size |sc_change_font_size_all_plus2_0| +Decrease font size |sc_change_font_size_all_2_0| +Restore font size |sc_change_font_size_all_0| +Toggle fullscreen |sc_toggle_fullscreen| +Input unicode character |sc_input_unicode_character| +Click URL using the keyboard |sc_kitten_hints| +Pass current selection to program |sc_pass_selection_to_program| +Edit |kitty| config file |sc_edit_config_file| +Open a |kitty| shell |sc_kitty_shell_window| +Increase background opacity |sc_set_background_opacity_plus0_1| +Decrease background opacity |sc_set_background_opacity_0_1| +Full background opacity |sc_set_background_opacity_1| +Reset background opacity |sc_set_background_opacity_default| +================================== ======================= + + +.. _layouts: + +Layouts +---------- + +Currently, there are five layouts available, + +* **Stack** -- Only a single maximized window is shown at a time +* **Tall** -- One window is shown full height on the left, the rest of the windows are shown one below the other on the right +* **Fat** -- One window is shown full width on the top, the rest of the windows are shown side-by-side on the bottom +* **Grid** -- All windows are shown in a grid +* **Horizontal** -- All windows are shown side-by-side +* **Vertical** -- All windows are shown one below the other + +You can switch between layouts using the |sc_next_layout| key combination. You can +also create shortcuts to select particular layouts, and choose which layouts +you want to enable/disable, see |kitty.conf| for examples. + +You can resize windows inside layouts. Press |sc_start_resizing_window| to +enter resizing mode and follow the on-screen instructions. In a given window +layout only some operations may be possible for a particular window. For +example, in the Tall layout you can make the first window wider/narrower, but +not taller/shorter. Note that what you are resizing is actually not a window, +but a row/column in the layout, all windows in that row/column will be resized. + +Some layouts take options to control their behavior. For example, the ``fat`` +and ``tall`` layouts accept the ``bias`` option to control how the available +space is split up. To specify the option, in |kitty.conf| use:: + + enabled_layouts tall:bias=70 + +This will make the tall window occupy ``70%`` of available width. ``bias`` can be +any number between 10 and 90. + +Writing a new layout only requires about a hundred lines of code, so if there +is some layout you want, take a look at `layout.py +`_ and submit +a pull request! + +.. _sessions: + +Startup Sessions +------------------ + +You can control the tabs, window layout, working directory, startup +programs, etc. by creating a "session" file and using the :option:`--session` +command line flag. For example: + +.. code-block:: ini + + # Set the window layout for the current tab + layout tall + # Set the working directory for windows in the current tab + cd ~ + # Create a window and run the specified command in it + launch zsh + # Create a window with some environment variables set and run vim in it + launch env FOO=BAR vim + # Set the title for the next window + title Chat with x + launch irssi --profile x + + # Create a new tab (the part after new_tab is the optional tab name which will + # be displayed in the tab bar, if omitted, the title of the active window will + # be used instead) + new_tab my tab + cd ~/somewhere + # Set the layouts allowed in this tab + enabled_layouts tall, stack + # Set the current layout + layout stack + launch zsh + # Make the current window the active (focused) window + focus + launch emacs + + +Mouse features +------------------- + +* You can also hold down :kbd:`ctrl+shift` and click on a URL to open it in a browser. +* You can double click to select a word and triple click to select a line. +* You can right click to extend a previous selection + + +Font control +----------------- + +|kitty| has extremely flexible and powerful font selection features. You can +specify individual families for the regular, bold, italic and bold+italic +fonts. You can even specify specific font families for specific ranges of +unicode characters. This allows precise control over text rendering. It can +come in handy for applications like powerline, without the need to use patched +fonts. See the various font related configuration directives in |kitty.conf|. + + +.. _scrollback: + +The scrollback buffer +----------------------- + +|kitty| supports scrolling back to view history, just like most terminals. You +can use either keyboard shortcuts or the mouse scroll wheel to do so. However, +|kitty| has an extra, neat feature. Sometimes you need to explore the +scrollback buffer in more detail, maybe search for some text or refer to it +side-by-side while typing in a follow-up command. |kitty| allows you to do this +by pressing the |sc_show_scrollback| key-combination, which will open the +scrollback buffer in your favorite pager program (which is ``less`` by default). +Colors and text formatting are preserved. You can explore the scrollback buffer +comfortably within the pager. + + +Frequently Asked Questions +--------------------------------- + +The list of Frequently Asked Questions (*FAQ*) is :doc:`available here `. + + +.. toctree:: + :hidden: + :glob: + + * + kittens/* diff --git a/docs/key-encoding.rst b/docs/key-encoding.rst new file mode 100644 index 000000000..bc6bfe4de --- /dev/null +++ b/docs/key-encoding.rst @@ -0,0 +1,129 @@ +Key encoding for extended keyboard protocol +=============================================== + +See :ref:`extended-key-protocol` for more information and `this table in JSON +format `_. + +===================== ====================== +Name Encoded representation (base64) +0 ``G`` +1 ``H`` +2 ``I`` +3 ``J`` +4 ``K`` +5 ``L`` +6 ``M`` +7 ``N`` +8 ``O`` +9 ``P`` +A ``S`` +APOSTROPHE ``B`` +B ``T`` +BACKSLASH ``t`` +BACKSPACE ``1`` +C ``U`` +CAPS LOCK ``:`` +COMMA ``C`` +D ``V`` +DELETE ``3`` +DOWN ``6`` +E ``W`` +END ``-`` +ENTER ``z`` +EQUAL ``R`` +ESCAPE ``y`` +F ``X`` +F1 ``/`` +F10 ``]`` +F11 ``{`` +F12 ``}`` +F13 ``@`` +F14 ``%`` +F15 ``$`` +F16 ``#`` +F17 ``BA`` +F18 ``BB`` +F19 ``BC`` +F2 ``*`` +F20 ``BD`` +F21 ``BE`` +F22 ``BF`` +F23 ``BG`` +F24 ``BH`` +F25 ``BI`` +F3 ``?`` +F4 ``&`` +F5 ``<`` +F6 ``>`` +F7 ``(`` +F8 ``)`` +F9 ``[`` +G ``Y`` +GRAVE ACCENT ``v`` +H ``Z`` +HOME ``.`` +I ``a`` +INSERT ``2`` +J ``b`` +K ``c`` +KP 0 ``BJ`` +KP 1 ``BK`` +KP 2 ``BL`` +KP 3 ``BM`` +KP 4 ``BN`` +KP 5 ``BO`` +KP 6 ``BP`` +KP 7 ``BQ`` +KP 8 ``BR`` +KP 9 ``BS`` +KP ADD ``BX`` +KP DECIMAL ``BT`` +KP DIVIDE ``BU`` +KP ENTER ``BY`` +KP EQUAL ``BZ`` +KP MULTIPLY ``BV`` +KP SUBTRACT ``BW`` +L ``d`` +LEFT ``5`` +LEFT ALT ``Bc`` +LEFT BRACKET ``s`` +LEFT CONTROL ``Bb`` +LEFT SHIFT ``Ba`` +LEFT SUPER ``Bd`` +M ``e`` +MINUS ``D`` +N ``f`` +NUM LOCK ``=`` +O ``g`` +P ``h`` +PAGE DOWN ``9`` +PAGE UP ``8`` +PAUSE ``!`` +PERIOD ``E`` +PRINT SCREEN ``^`` +Q ``i`` +R ``j`` +RIGHT ``4`` +RIGHT ALT ``Bg`` +RIGHT BRACKET ``u`` +RIGHT CONTROL ``Bf`` +RIGHT SHIFT ``Be`` +RIGHT SUPER ``Bh`` +S ``k`` +SCROLL LOCK ``+`` +SEMICOLON ``Q`` +SLASH ``F`` +SPACE ``A`` +T ``l`` +TAB ``0`` +U ``m`` +UP ``7`` +V ``n`` +W ``o`` +WORLD 1 ``w`` +WORLD 2 ``x`` +X ``p`` +Y ``q`` +Z ``r`` +===================== ====================== + diff --git a/docs/kittens/diff.rst b/docs/kittens/diff.rst new file mode 100644 index 000000000..db6df7228 --- /dev/null +++ b/docs/kittens/diff.rst @@ -0,0 +1,129 @@ +kitty-diff - A side-by-side diff tool with syntax highlighting and images +============================================================================= + +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 + :alt: Screenshot, showing a sample diff + +.. contents:: + + +Installation +--------------- + +Simply install `kitty `_. You also need +to have either the `git `_ program or the ``diff`` program +installed. Additionally, for syntax highlighting to work, +`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: + +.. code-block:: 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 default context ``=`` +========================= =========================== + + + +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. The default diff.conf is below. + +.. literalinclude:: ../../kittens/diff/diff.conf + :language: ini + + + +Integrating with git +----------------------- + +Add the following to `~/.gitconfig`: + +.. code-block:: ini + + [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 +:doc:`kitty only `, such as the +:doc:`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 :) diff --git a/docs/kittens/hints.rst b/docs/kittens/hints.rst new file mode 100644 index 000000000..0e61be2c1 --- /dev/null +++ b/docs/kittens/hints.rst @@ -0,0 +1,22 @@ +Hints +========== + +|kitty| has a *hints mode* to select and act on arbitrary text snippets currently +visible on the screen. For example, you can press |sc_kitten_hints| +to choose any URL visible on the screen and then open it using your system +browser. + +.. image:: ../screenshots/hints_mode.png + :alt: URL hints mode + +Similarly, you can press |sc_kitten_hints_type_path_program| to +select anything that looks like a path or filename and then insert it into the +terminal, very useful for picking files from the output of a ``git`` or ``ls`` command and +adding them to the command line for the next command. + +The hints kitten is very powerful to see more detailed help on its various +options and modes of operation, use:: + + kitty +kitten hints --help + + diff --git a/docs/kittens/unicode-input.rst b/docs/kittens/unicode-input.rst new file mode 100644 index 000000000..0976e37f1 --- /dev/null +++ b/docs/kittens/unicode-input.rst @@ -0,0 +1,18 @@ +Unicode input +================ + +You can input unicode characters by name, hex code, recently used and even an editable favorites list. +Press |sc_input_unicode_character| to start the unicode input widget, shown below. + +.. image:: ../screenshots/unicode.png + :alt: A screenshot of the unicode input widget + +In *Code* mode, you enter a unicode character by typing in the hex code for the +character and pressing enter, for example, type in ``2716`` and press enter to get +✖. You can also choose a character from the list of recently used characters by +typing a leading period and then the two character index and pressing Enter. + +In *Name* mode you instead type words from the character name and use the arrow +keys/tab to select the character from the displayed matches. You can also type +a leading period and the index for the match if you dont like to use arrow +keys. diff --git a/docs/performance.rst b/docs/performance.rst new file mode 100644 index 000000000..030e421a7 --- /dev/null +++ b/docs/performance.rst @@ -0,0 +1,45 @@ +|kitty| Performance +=================== + +The main goals for |kitty| performance are user perceived latency while typing +and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to find +an optimum balance for these. To that end it keeps a cache of each rendered +glyph in video RAM so that font rendering is not a bottleneck. Interaction +with child programs takes place in a separate thread from rendering, to improve +smoothness. + +There are two parameters you can tune to adjust the performance. ``repaint_delay`` +and ``input_delay``. These control the artificial delays introduced into the +render loop to reduce CPU usage. See |kitty.conf| for details. +See also the ``sync_to_monitor`` option to further decrease latency at the cost +of some `tearing `_ while scrolling. + +You can generate detailed per-function performance data using +`gperftools `_. Build |kitty| with +`make profile` which will create an executable called `kitty-profile`. Run +that and perform the task you want to analyse, for example, scrolling a large +file with `less`. After you quit, function call statistics will be printed to +`stdout` and you can use tools like *kcachegrind* for more detailed analysis. + +Here are some CPU usage numbers for the task of scrolling a file continuously +in less. The CPU usage is for the terminal process and X together and is +measured using htop. The measurements are taken at the same font and window +size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU +with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD +7770/8760 / R7 250X]`` GPU. + +============== ========================= +Terminal CPU usage (X + terminal) +============== ========================= +|kitty| 6 - 8% +xterm 5 - 7% (but scrolling was extremely janky) +termite 10 - 13% +urxvt 12 - 14% +gnome-terminal 15 - 17% +konsole 29 - 31% +============== ========================= + + +As you can see, |kitty| uses much less CPU than all terminals, except xterm, but +its scrolling "smoothness" is much better than that of xterm (at least to my, +admittedly biased, eyes). diff --git a/docs/protocol-extensions.rst b/docs/protocol-extensions.rst new file mode 100644 index 000000000..ce4792ab6 --- /dev/null +++ b/docs/protocol-extensions.rst @@ -0,0 +1,165 @@ +Extensions to the xterm protocol +=================================== + +|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. + +.. contents:: + +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 (`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 :doc:`/graphics-protocol` for a description +of this protocol to enable drawing of arbitrary raster images in the terminal. + + +.. _extended-key-protocol: + +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: + `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 `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 + +Schematically:: + + _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 :doc:`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, `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 +`this discussion `_ +and `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 diff --git a/docs/remote-control.rst b/docs/remote-control.rst new file mode 100644 index 000000000..0d128f21d --- /dev/null +++ b/docs/remote-control.rst @@ -0,0 +1,114 @@ +Controlling kitty from scripts or the shell +============================================== + +.. highlight:: sh + +|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 :option:`--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 :option:`--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 :option:`--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 :option:`--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 :option:`--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 (|sc_kitty_shell_window| by default). This has the added +advantage that you dont need to use ``allow_remote_control`` to make it work. diff --git a/screenshots/diff.png b/docs/screenshots/diff.png similarity index 100% rename from screenshots/diff.png rename to docs/screenshots/diff.png diff --git a/screenshots/hints_mode.png b/docs/screenshots/hints_mode.png similarity index 100% rename from screenshots/hints_mode.png rename to docs/screenshots/hints_mode.png diff --git a/screenshots/screenshot.png b/docs/screenshots/screenshot.png similarity index 100% rename from screenshots/screenshot.png rename to docs/screenshots/screenshot.png diff --git a/screenshots/unicode.png b/docs/screenshots/unicode.png similarity index 100% rename from screenshots/unicode.png rename to docs/screenshots/unicode.png diff --git a/preprocess-readme.py b/preprocess-readme.py deleted file mode 100755 index ae5705fd0..000000000 --- a/preprocess-readme.py +++ /dev/null @@ -1,57 +0,0 @@ -#!/usr/bin/env python3 -# vim:fileencoding=utf-8 -# License: GPL v3 Copyright: 2016, Kovid Goyal - -import json -import os -import re -import subprocess -from collections import defaultdict - -base = os.path.dirname(os.path.abspath(__file__)) -os.chdir(base) - -defns = defaultdict(list) - -for line in open('kitty/kitty.conf'): - if line.startswith('map '): - _, sc, name = line.split(maxsplit=2) - sc = sc.replace('kitty_mod', 'ctrl+shift') - name = name.rstrip().replace(' ', '_').replace('-', '_').replace('+', 'plus').replace('.', '_').replace('___', '_').replace('__', '_').strip('_') - defns[name].append('`' + sc.replace('>', ' → ') + '`') - -defns = [ - ':sc_{}: pass:quotes[{}]'.format(name, ' or '.join(defns[name])) - for name in sorted(defns) -] -defns = '\n'.join(defns) - -raw = open('README.asciidoc').read() -pat = re.compile( - r'^// START_SHORTCUT_BLOCK$.+?^// END_SHORTCUT_BLOCK$', re.M | re.DOTALL -) -nraw = pat.sub( - '// START_SHORTCUT_BLOCK\n' + defns + '\n// END_SHORTCUT_BLOCK', raw -) -if raw != nraw: - print('Updating shortcuts block') - open('README.asciidoc', 'w').write(nraw) - -raw = subprocess.check_output([ - 'kitty', '+runpy', - 'from kitty.key_encoding import *; import json; print(json.dumps(ENCODING))' -]).decode('utf-8') -key_map = json.loads(raw) -lines = [ - 'See link:protocol-extensions.asciidoc#keyboard-handling[Keyboard Handling protocol extension]', - ' for more information and link:key_encoding.json[for this table in JSON format].', - '', '|===', '| Name | Encoded representation (base64)', '' -] -for k in sorted(key_map): - lines.append('| {:15s} | `{}`'.format(k.replace('_', ' '), key_map[k].replace('`', '\\`'))) -lines += ['', '|==='] -with open('key_encoding.asciidoc', 'w') as f: - print('= Key encoding for extended keyboard protocol\n', file=f) - print('\n'.join(lines), file=f) -with open('key_encoding.json', 'w') as f: - f.write(json.dumps(key_map, indent=2))