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))