version 0.11.3

Fixes #711

.gitignore

@@ -13,3 +13,6 @@ kitty-profile
 dev
 __pycache__
 glfw/wayland-*-client-protocol.[ch]
+docs/_build
+docs/generated
+.DS_Store

.travis.yml

@@ -1,6 +1,23 @@
+git:
+    depth: false
 matrix:
     fast_finish: true
     include:
+        - os: linux
+          dist: trusty
+          group: beta
+          language: python
+          sudo: false
+          env: USE_BUNDLE=1 SW=$HOME/sw PKG_CONFIG_PATH=$SW/lib/pkgconfig LD_LIBRARY_PATH=$SW/lib PYTHON=$SW/bin/python3
+          addons:
+            apt:
+              packages:
+                - libxi-dev
+                - libxrandr-dev
+                - libxinerama-dev
+                - libxcursor-dev
+                - libxcb-xkb-dev
+
         - os: linux
           dist: trusty
           group: beta
@@ -18,7 +35,6 @@ matrix:
                 - libxrandr-dev
                 - libxinerama-dev
                 - libxcursor-dev
-                - libunistring-dev
                 - libxcb-xkb-dev
                 - libpng-dev
                 - python3-pil
@@ -40,7 +56,6 @@ matrix:
                 - libxrandr-dev
                 - libxinerama-dev
                 - libxcursor-dev
-                - libunistring-dev
                 - libxcb-xkb-dev
                 - libpng-dev
                 - python3-pil
@@ -50,7 +65,7 @@ matrix:
           group: beta
           sudo: false
           env:
-            - RUN_FLAKE=1 BUILD_PKG=1
+            - RUN_FLAKE=1 BUILD_PKG=linux-package
           language: python
           python: "3.6"
           addons:
@@ -62,7 +77,6 @@ matrix:
                 - libxrandr-dev
                 - libxinerama-dev
                 - libxcursor-dev
-                - libunistring-dev
                 - libxcb-xkb-dev
                 - libpng-dev
                 - python3-pil
@@ -73,7 +87,7 @@ matrix:
 
         - os: osx
           language: generic
-          env: USE_BREW=1 BUILD_PKG=1
+          env: USE_BREW=1 BUILD_PKG=osx-bundle
 
 env:
     global:
@@ -89,27 +103,41 @@ install: |
         if [[ "$USE_BREW" == "1" ]]; then
             brew update;
             brew upgrade python;
-            brew install harfbuzz --without-glib --without-gobject-introspection --without-graphite2 --without-icu4c --without-freetype;
+            brew install harfbuzz --without-graphite2 --without-icu4c --without-freetype;
+            brew install imagemagick
+            brew install optipng
+            brew install librsvg
+            logo/make.py
         else
             mkdir -p $SW;
             curl https://download.calibre-ebook.com/travis/kitty/osx.tar.xz | tar xJ -C $SW;
         fi
     else
-        pushd /tmp
-        wget --no-check-certificate http://xkbcommon.org/download/libxkbcommon-0.6.1.tar.xz
-        tar xf libxkbcommon-0.6.1.tar.xz
-        cd libxkbcommon-0.6.1
-        ./configure --prefix=$HOME/harfbuzz --disable-dependency-tracking --disable-static
-        make -j2
-        make install
-        wget https://github.com/behdad/harfbuzz/releases/download/1.6.3/harfbuzz-1.6.3.tar.bz2
-        tar xf harfbuzz-1.6.3.tar.bz2
-        cd harfbuzz-1.6.3
-        ./configure --prefix=$HOME/harfbuzz --disable-dependency-tracking --disable-static --with-glib=no --with-gobject=no --with-cairo=no --with-fontconfig=no --with-icu=no --with-directwrite=no --with-freetype=yes
-        make -j2
-        make install
-        cd ..
-        popd
+        if [[ "$USE_BUNDLE" == "1" ]]; then
+            mkdir -p $SW;
+            curl https://download.calibre-ebook.com/travis/kitty/linux-64.tar.xz | tar xJ -C $SW;
+            find $SW -type f -name '*.pc' -exec sed -i "s,/sw/sw,$SW,g" {} \;;
+            find $SW -type f -name '_sysconfig*.py' -exec sed -i "s,/sw/sw,$SW,g" {} \;;
+        else
+            pushd /tmp
+            wget --no-check-certificate http://xkbcommon.org/download/libxkbcommon-0.6.1.tar.xz
+            tar xf libxkbcommon-0.6.1.tar.xz
+            cd libxkbcommon-0.6.1
+            ./configure --prefix=$HOME/harfbuzz --disable-dependency-tracking --disable-static
+            make -j2
+            make install
+            wget https://github.com/behdad/harfbuzz/releases/download/1.6.3/harfbuzz-1.6.3.tar.bz2
+            tar xf harfbuzz-1.6.3.tar.bz2
+            cd harfbuzz-1.6.3
+            ./configure --prefix=$HOME/harfbuzz --disable-dependency-tracking --disable-static --with-glib=no --with-gobject=no --with-cairo=no --with-fontconfig=no --with-icu=no --with-directwrite=no --with-freetype=yes
+            make -j2
+            make install
+            cd ..
+            popd
+        fi
+        if [[ "$BUILD_PKG" == "linux-package" ]]; then
+            pip install sphinx
+        fi
     fi
     pkg-config --cflags harfbuzz
     if [[ "$TRAVIS_OS_NAME" != 'osx' ]]; then
@@ -119,11 +147,20 @@ install: |
     set +e
 
 before_script:
-    - echo $LD_LIBRARY_PATH
+    - echo LD_LIBRARY_PATH=$LD_LIBRARY_PATH PKG_CONFIG_PATH=$PKG_CONFIG_PATH
     - $PYTHON setup.py build --debug --verbose $SANITIZE_ARG;
 
-script:
-    - if grep -Inr '\s$' kitty kitty_tests *.py *.asciidoc .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
-    - if [[ -z $SANITIZE_ARG ]]; then $PYTHON test.py; else ./asan-launcher test.py; fi
-    - if [[ "$RUN_FLAKE" == "1" ]]; then flake8 --count .; fi
-    - if [[ "$BUILD_PKG" == "1" ]]; then $PYTHON setup.py linux-package; fi
+script: |
+    set -e
+
+    if grep -Inr '\s$' kitty kitty_tests kittens docs *.py *.asciidoc *.rst .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
+
+    if [[ -z "$SANITIZE_ARG" ]]; then $PYTHON test.py; else ./asan-launcher test.py; fi
+
+    if [[ "$RUN_FLAKE" == "1" ]]; then flake8 --count .; fi
+
+    if [[ "$BUILD_PKG" == "linux-package" ]]; then make FAIL_WARN=-W man && make FAIL_WARN=-W html; fi
+
+    if [[ ! -z "$BUILD_PKG" ]]; then $PYTHON setup.py $BUILD_PKG; fi
+
+    set +e

=template.py

@@ -1,5 +0,0 @@
-#!/usr/bin/env python
-# vim:fileencoding=utf-8
-# License: GPL v3 Copyright: %YEAR%, %USER% <%MAIL%>
-
-%HERE%

CHANGELOG.rst

@@ -1,540 +1 @@
-Changelog
-==============
-
-kitty is a feature full, cross-platform, *fast*, GPU based terminal emulator.
-
-version 0.10.0 [2018-05-21]
-------------------------------
-
-- A diff kitten to show side-by-side diffs with syntax highlighting and support
-  for images. See `diff README
-  <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`_.
-
-- Make windows in the various kitty layouts manually resizable. See the
-  `Layouts section of the README
-  <https://github.com/kovidgoyal/kitty#layouts>`_ for details.
-
-- Implement support for the SGR *faint* escape code to make text blend
-  into the background (`#446 <https://github.com/kovidgoyal/kitty/issues/446>`_).
-
-- Make the hints kitten a little `smarter
-  <https://github.com/kovidgoyal/kitty/commit/ad1109b6fe0a6802ca4f77182a7a0b36086b3e9f>`_,
-  so that URLs that stretch over multiple lines are detected. Also improve
-  detection of surrounding brackets/quotes.
-
-- Make the kitty window id available as the environment variable
-  `KITTY_WINDOW_ID` (`#532 <https://github.com/kovidgoyal/kitty/issues/532>`_).
-
-- Add a "fat" layout that is similar to the "tall" layout but vertically
-  oriented.
-
-- Expand environment variables in config file include directives
-
-- Allow programs running in kitty to `read/write from the clipboard
-  <https://github.com/kovidgoyal/kitty/commit/889ca7791244253cb08fbc3eca8883a87fb943a7>`_.
-  By default only writing is allowed.
-
-- Fix moving cursor outside a defined page area incorrectly causing the cursor
-  to be placed inside the page area. Caused incorrect rendering in neovim, in
-  some situations.
-
-- Render a couple more powerline symbols directly, bypassing the font
-  (`#550 <https://github.com/kovidgoyal/kitty/issues/550>`_).
-
-- Fix ctrl+alt+<special> not working in normal and application keyboard (`#548
-  <https://github.com/kovidgoyal/kitty/issues/548>`_).
-
-- Partial fix for rendering Right-to-left languages like Arabic. Rendering of
-  Arabic is never going to be perfect, but now it is at least readable.
-
-- Fix Ctrl+backspace acting as plain backspace in normal and application
-  keyboard modes (`#538 <https://github.com/kovidgoyal/kitty/issues/538>`_). 
-
-- Have the paste_from_selection action paste from the clipboard on platforms
-  that do not have a primary selection such as Wayland and macOS 
-  (`#529 <https://github.com/kovidgoyal/kitty/issues/529>`_)
-
-- Fix cursor_stop_blinking_after=0 not working (`#530 <https://github.com/kovidgoyal/kitty/issues/530>`_)
-
-
-version 0.9.1 [2018-05-05]
-------------------------------
-
-- Show a bell symbol on the tab if a bell occurs in one of the windows in the tab and
-  the window is not the currently focused window
-
-- Change the window border color if a bell occurs in an unfocused window. Can
-  be disabled by setting the bell_border_color to be the same as the
-  inactive_border_color.
-
-- macOS: Add support for dead keys
-
-- Unicode input: When searching by name search for prefix matches as well as
-  whole word matches
-
-- Dynamically allocate the memory used for the scrollback history buffer.
-  Reduces startup memory consumption when using very large scrollback
-  buffer sizes.
-
-- Add an option to not request window attention on bell.
-
-- Remote control: Allow matching windows by number (visible position).
-
-- macOS: Fix changing tab title and kitty shell not working
-
-- When triple-clicking select all wrapped lines belonging to a single logical line.
-
-- hints kitten: Detect bracketed URLs and dont include the closing bracket in the URL.
-
-- When calling pass_selection_to_program use the current directory of the child
-  process as the cwd of the program.
-
-- Add macos_hide_from_tasks option to hide kitty from the macOS task switcher
-
-- macOS: When the macos_titlebar_color is set to background change the titlebar
-  colors to match the current background color of the active kitty window
-
-- Add a setting to clear all shortcuts defined up to that point in the config
-  file(s)
-
-- Add a setting (kitty_mod) to change the modifier used by all the default
-  kitty shortcuts, globally
-
-- Fix Shift+function key not working
-
-- Support the F13 to F25 function keys
-  
-- Don't fail to start if the user deletes the hintstyle key from their
-  fontconfig configuration.
-
-- When rendering a private use unicode codepoint and a space as a two cell
-  ligature, set the foreground colors of the space cell to match the colors of
-  the first cell. Works around applications like powerline that use different
-  colors for the two cells.
-
-- Fix passing @text to other programs such as when viewing the scrollback
-  buffer not working correctly if kitty is itself scrolled up.
-
-- Fix window focus gained/lost events not being reported to child programs when
-  switching windows/tabs using the various keyboard shortcuts.
-
-- Fix tab title not changing to reflect the window title when switching between different windows in a tab
-
-- Ignore -e if it is specified on the command line. This is for compatibility
-  with broken software that assumes terminals should run with an -e option to
-  execute commands instead of just passing the commands as arguments. 
-
-
-version 0.9.0 [2018-04-15]
-------------------------------
-
-- A new kitty command shell to allow controlling kitty via commands. Press
-  `ctrl+shift+escape` to run the shell.
-
-- The hints kitten has become much more powerful. Now in addition to URLs you
-  can use it to select word, paths, filenames, lines, etc. from the screen.
-  These can be inserted into the terminal, copied to clipboard or sent to
-  external programs.
-
-- Linux: Switch to libxkbcommon for keyboard handling. It allows kitty to
-  support XCompose and dead keys and also react to keyboard remapping/layout
-  change without needing a restart.
-
-- Add support for multiple-key-sequence shortcuts
-
-- A new remote control command `set-colors` to change the current and/or
-  configured colors.
-
-- When double-clicking to select a word, select words that continue onto the
-  next/prev line as well.
-
-- Add an `include` directive for the config files to read multiple config files
-
-- Improve mouse selection for windows with padding. Moving the mouse into the
-  padding area now acts as if the mouse is over the nearest cell.
-
-- Allow setting all 256 terminal colors in the config file
-
-- Fix using `kitty --single-instance` to open a new window in a running kitty
-  instance, not respecting the `--directory` flag
-
-- URL hints: Exclude trailing punctuation from URLs
-
-- URL hints: Launch the browser from the kitty parent process rather than the
-  hints kitten. Fixes launching on some systems where xdg-open doesn't like
-  being run from a kitten.
-
-- Allow using rectangle select mode by pressing shift in addition to the
-  rectangle select modifiers even when the terminal program has grabbed the
-  mouse.
-
-
-version 0.8.4 [2018-03-31]
------------------------------
-
-- Fix presence of XDG_CONFIG_DIRS and absence of XDG_CONFIG_HOME preventing
-  kitty from starting
-
-- Revert change in last release to cell width calculation. Instead just clip
-  the right edges of characters that overflow the cell by at most two pixels
-
-
-version 0.8.3 [2018-03-29]
------------------------------
-
-- Fix a regression that broke the visual bell and invert screen colors escape
-  code
-
-- Allow double-click and triple-click + drag to extend selections word at a
-  time or line at a time
-
-- Add a keyboard shortcut to set the tab title
-
-- Fix setting window title to empty via OSC escape code not working correctly
-
-- Linux: Fix cell width calculation incorrect for some fonts (cell widths are
-  now calculated by actually rendering bitmaps, which is slower but more
-  accurate)
-
-- Allow specifying a system wide kitty config file, for all users
-
-- Add a --debug-config command line flag to output data about the system and
-  kitty configuration.
-
-- Wayland: Fix auto-repeat of keys not working
-
-
-version 0.8.2 [2018-03-17]
------------------------------
-
-- Allow extending existing selections by right clicking
-
-- Add a configurable keyboard shortcut and remote command to set the font size to a specific value
-
-- Add an option to have kitty close the window when the main processes running in it exits, even if there are still background processes writing to that terminal
-
-- Add configurable keyboard shortcuts to switch to a specific layout
-
-- Add a keyboard shortcut to edit the kitty config file easily 
-
-- macOS: Fix restoring of window size not correct on Retina screens
-
-- macOS: Add a facility to specify command line arguments when running kitty from the GUI 
-
-- Add a focus-tab remote command
-
-- Fix screen not being refreshed immediately after moving a window.
-
-- Fix a crash when getting the contents of the scrollback buffer as text
-
-version 0.8.1 [2018-03-09]
------------------------------
-
-- Extend kitty's remote control feature to work over both UNIX and TCP sockets,
-  so now you can control kitty from across the internet, if you want to.
-
-- Render private use unicode characters that are followed by a space as a two
-  character ligature. This fixes rendering for applications that misuse
-  private-use characters to display square symbols.
-
-- Fix Unicode emoji presentation variant selector causing new a fallback font
-  instance to be created
-
-- Fix a rare error that prevented the Unicode input kitten from working
-  sometimes
-
-- Allow using Ctrl+Alt+letter in legacy keyboard modes by outputting them as Ctrl+letter and Alt+letter.
-  This matches other terminals' behavior.
-
-- Fix cursor position off-by-one on horizontal axis when resizing the terminal
-
-- Wayland: Fix auto-repeat of keys not working
-
-- Wayland: Add support for window decorations provided by the Wayland shell
-
-- macOS: Fix URL hints not working 
-
-- macOS: Fix shell not starting in login mode on some computers
-
-- macOS: Output errors into console.app when running as a bundle
-
-
-version 0.8.0 [2018-02-24]
------------------------------
-
-- A framework for kittens, that is, small terminal programs designed to run
-  inside kitty and extend its capabilities. Examples include unicode input and
-  selecting URLs with the keyboard.
-
-- Input arbitrary unicode characters by pressing Ctrl+Shift+u. You can choose
-  characters by name, by hex code, by recently used, etc. There is even and
-  editable Favorites list.
-
-- Open URLs using only the keyboard. kitty has a new "hints mode". Press
-  Ctrl+Shift+e and all detected URLs on the screen are highlighted with a key
-  to press to open them. The facility is customizable so you can change
-  what is detected as a URL and which program is used to open it.
-
-- Add an option to change the titlebar color of kitty windows on macOS
-
-- Only consider Emoji characters with default Emoji presentation to be two
-  cells wide. This matches the standard. Also add support for the Unicode Emoji
-  variation presentation selector.
-
-- Prevent video tearing during high speed scrolling by syncing draws
-  to the monitor's refresh rate. There is a new configuration option to
-  control this ``sync_to_monitor``.
-
-- When displaying only a single window, use the default background color of the
-  window (which can be changed via escape codes) as the color for the margin
-  and padding of the window.
-
-- Add some non standard terminfo capabilities used by neovim and tmux.
-
-- Fix large drop in performance when using multiple top-level windows on macOS
-
-- Fix save/restore of window sizes not working correctly.
-
-- Remove option to use system wcwidth(). Now always use a wcwidth() based on
-  the Unicode standard. Only sane way.
-
-- Fix a regression that caused a few ligature glyphs to not render correctly in
-  rare circumstances.
-
-- Browsing the scrollback buffer now happens in an overlay window instead of a
-  new window/tab.
-
-version 0.7.1 [2018-01-31]
----------------------------
-
-- Add an option to adjust the width of character cells
-
-- Fix selecting text with the mouse in the scrollback buffer selecting text
-  from the line above the actually selected line
-
-- Fix some italic fonts having the right edge of characters cut-off,
-  unnecessarily
-
-
-version 0.7.0 [2018-01-24]
----------------------------
-
-- Allow controlling kitty from the shell prompt/scripts. You can
-  open/close/rename windows and tabs and even send input to specific windows.
-  See the README for details.
-
-- Add option to put tab bar at the top instead of the bottom
-
-- Add option to override the default shell
-
-- Add "Horizontal" and "Vertical" window layouts
-
-- Sessions: Allow setting titles and working directories for individual windows 
-
-- Option to copy to clipboard on mouse select
-
-- Fix incorrect reporting of mouse move events when using the SGR protocol
-
-- Make alt+backspace delete the previous word
-
-- Take the mouse wheel multiplier option in to account when generating fake key
-  scroll events
-
-- macOS: Fix closing top-level window does not transfer focus to other
-  top-level windows.
-
-- macOS: Fix alt+arrow keys not working when disabling the macos_option_as_alt
-  config option.
-
-- kitty icat: Workaround for bug in ImageMagick that would cause some images
-  to fail to display at certain sizes.
-
-- Fix rendering of text with ligature fonts that do not use dummy glyphs
-
-- Fix a regression that caused copying of the selection to clipboard to only
-  copy the visible part of the selection
-
-- Fix incorrect handling of some unicode combining marks that are not re-ordered
-
-- Fix handling on non-BMP combining characters
-
-- Drop the dependency on libunistring
-
-
-version 0.6.1 [2017-12-28]
----------------------------
-
-- Add an option to fade the text in inactive windows
-
-- Add new actions to open windows/tabs/etc. with the working directory set to 
-  the working directory of the current window.
-
-- Automatically adjust cell size when DPI changes, for example when kitty is
-  moved from one monitor to another with a different DPI
-
-- Ensure underlines are rendered even for fonts with very poor metrics
-
-- Fix some emoji glyphs not colored on Linux
-
-- Internal wcwidth() implementation is now auto-generated from the unicode
-  standard database
-
-- Allow configuring the modifiers to use for rectangular selection with the
-  mouse.
-
-- Fix incorrect minimum wayland version in the build script
-
-- Fix a crash when detecting a URL that ends at the end of the line
-
-- Fix regression that broke drawing of hollow cursor when window loses focus
-
-
-version 0.6.0 [2017-12-18]
----------------------------
-
-- Support background transparency via the background_opacity option. Provided
-  that your OS/window manager supports transparency, you can now have kitty
-  render pixels that have only the default background color as
-  semi-transparent.
-
-- Support multiple top level (OS) windows. These windows all share the sprite
-  texture cache on the GPU, further reducing overall resource usage. Use
-  the shortcut `ctrl+shift+n` to open a new top-level window.
-
-- Add support for a *daemon* mode using the `--single-instance` command line
-  option. With this option you can have only a single kitty instance running.
-  All future invocations simply open new top-level windows in the existing
-  instance.
-
-- Support colored emoji
-
-- Use CoreText instead of FreeType to render text on macOS
-
-- Support running on the "low power" GPU on dual GPU macOS machines
-
-- Add a new "grid" window layout
-
-- Drop the dependency on glfw (kitty now uses a modified, bundled copy of glfw)
-
-- Add an option to control the audio bell volume on X11 systems
-
-- Add a command line switch to set the name part of the WM_CLASS window
-  property independently.
-
-- Add a command line switch to set the window title.
-
-- Add more options to customize the tab-bar's appearance (font styles and
-  separator)
-
-- Allow drag and drop of files into kitty. On drop kitty will paste the
-  file path to the running program.
-
-- Add an option to control the underline style for URL highlighting on hover
-
-- X11: Set the WINDOWID environment variable 
-
-- Fix middle and right buttons swapped when sending mouse events to child
-  processes
-
-- Allow selecting in a rectangle by holding down Ctrl+Alt while dragging with
-  the mouse.
-
-
-version 0.5.1 [2017-12-01]
----------------------------
-
-- Add an option to control the thickness of lines in box drawing characters
-
-- Increase max. allowed ligature length to nine characters
-
-- Fix text not vertically centered when adjusting line height
-
-- Fix unicode block characters not being rendered properly
-
-- Fix shift+up/down not generating correct escape codes
-
-- Image display: Fix displaying images taller than two screen heights not
-  scrolling properly
-
-
-version 0.5.0 [2017-11-19]
----------------------------
-
-- Add support for ligature fonts such as Fira Code, Hasklig, etc. kitty now
-  uses harfbuzz for text shaping which allow it to support advanced OpenType
-  features such as contextual alternates/ligatures/combining glyphs/etc.
-
-- Make it easy to select fonts by allowing listing of monospace fonts using:
-  kitty list-fonts
-
-- Add an option to have window focus follow mouse
-
-- Add a keyboard shortcut (ctrl+shift+f11) to toggle fullscreen mode
-
-- macOS: Fix handling of option key. It now behaves just like the alt key on
-  Linux. There is an option to make it type unicode characters instead.
-
-- Linux: Add support for startup notification on X11 desktops. kitty will
-  now inform the window manager when its startup is complete.
-
-- Fix shell prompt being duplicated when window is resized
-
-- Fix crash when displaying more than 64 images in the same session
-
-- Add support for colons in SGR color codes. These are generated by some
-  applications such as neovim when they mistakenly identify kitty as a libvte
-  based terminal.
-
-- Fix mouse interaction not working in apps using obsolete mouse interaction
-  protocols
-
-- Linux: no longer require glew as a dependency
-
-
-version 0.4.2 [2017-10-23]
----------------------------
-
-- Fix a regression in 0.4.0 that broke custom key mappings
-
-- Fix a regression in 0.4.0 that broke support for non-QWERTY keyboard layouts 
-
-- Avoid using threads to reap zombie child processes. Also prevent kitty from
-  hanging if the open program hangs when clicking on a URL.
-
-
-version 0.4.0 [2017-10-22]
----------------------------
-
-- Support for drawing arbitrary raster graphics (images) in the terminal via a
-  new graphics protocol. kitty can draw images with full 32-bit color using both
-  ssh connections and files/shared memory (when available) for better
-  performance. The drawing primitives support alpha blending and z-index.
-  Images can be drawn both above and below text. See
-  https://github.com/kovidgoyal/kitty/blob/master/graphics-protocol.asciidoc
-  for details. 
-
-- Refactor kitty's internals to make it even faster and more efficient. The CPU
-  usage of kitty + X server while doing intensive tasks such as scrolling a
-  file continuously in less has been reduced by 50%. There are now two
-  configuration options ``repaint_delay`` and ``input_delay`` you can use to
-  fine tune kitty's performance vs CPU usage profile. The CPU usage of kitty +
-  X when scrolling in less is now significantly better than most (all?) other
-  terminals. See https://github.com/kovidgoyal/kitty#performance
-
-- Hovering over URLs with the mouse now underlines them to indicate they
-  can be clicked. Hold down Ctrl+Shift while clicking to open the URL.
-
-- Selection using the mouse is now more intelligent. It does not add
-  blank cells (i.e. cells that have no content) after the end of text in a
-  line to the selection.
-
-- The block cursor in now fully opaque but renders the character under it in
-  the background color, for enhanced visibility.
-
-- Allow combining multiple independent actions into a single shortcut
-
-- Add a new shortcut to pass the current selection to an external program
-
-- Allow creating shortcuts to open new windows running arbitrary commands. You
-  can also pass the current selection to the command as an arguments and the
-  contents of the screen + scrollback buffer as stdin to the command.
+See https://sw.kovidgoyal.net/kitty/changelog.html

INSTALL.md

@@ -0,0 +1,7 @@
+To build from source:
+
+    https://sw.kovidgoyal.net/kitty/build.html
+
+Pre-built binaries:
+
+    https://sw.kovidgoyal.net/kitty/binary.html

Makefile

@@ -32,3 +32,14 @@ rendered_logo: logo/kitty.iconset/icon_256x256.png
 
 app: rendered_logo
 	python3 setup.py kitty.app $(VVAL)
+
+man:
+	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs man
+
+html:
+	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs html
+
+linkcheck:
+	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs linkcheck
+
+docs: man html

README.asciidoc

@@ -1,628 +1,5 @@
-= kitty - A terminal emulator
-:toc:
-:toc-placement!:
-// START_SHORTCUT_BLOCK
-: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_decrease_font_size: pass:quotes[`ctrl+shift+minus`]
-: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_increase_font_size: pass:quotes[`ctrl+shift+equal`]
-:sc_input_unicode_character: pass:quotes[`ctrl+shift+u`]
-: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_restore_font_size: pass:quotes[`ctrl+shift+backspace`]
-:sc_run_kitten_text_hints: pass:quotes[`ctrl+shift+e`]
-:sc_run_kitten_text_hints_type_line_program: pass:quotes[`ctrl+shift+p → l`]
-:sc_run_kitten_text_hints_type_path: pass:quotes[`ctrl+shift+p → shift+f`]
-:sc_run_kitten_text_hints_type_path_program: pass:quotes[`ctrl+shift+p → f`]
-:sc_run_kitten_text_hints_type_word_program: pass:quotes[`ctrl+shift+p → w`]
-: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_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
+= kitty - the fast, featureful, GPU based, terminal emulator
+
+See https://sw.kovidgoyal.net/kitty
 
-++++
-<img align="left" role="left" src="logo/kitty.png?raw=true"/>
-++++
 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] and link:#hints[Hints].
-
-* 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.qa.debian.org/k/kitty/news/20180419T070013Z.html
-
-=== 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}
-
-|===
-
-=== Miscellaneous
-
-|===
-|Action |Shortcut
-
-|Increase font size   | {sc_increase_font_size}
-|Decrease font size   | {sc_decrease_font_size}
-|Restore font size    | {sc_restore_font_size}
-|Toggle fullscreen    | {sc_toggle_fullscreen}
-|Input unicode character | {sc_input_unicode_character}
-|Click URL using the keyboard | {sc_run_simple_kitten_text_url_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}
-|===
-
-
-== 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 <<scrolling-shortcuts,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 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_run_kitten_text_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_run_kitten_text_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
-launch 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
-
-=== 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 `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 kitty.dmg includes all dependencies, unlike the
-`kitty.app` built above and is built automatically by using the `kitty` branch of
-link:https://github.com/kovidgoyal/build-calibre[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 link:https://github.com/kovidgoyal/kitty/blob/master/protocol-extensions.asciidoc#setting-text-styles-colors-in-arbitrary-regions-of-the-screen[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.
-Either install kitty on the server, or simply copy over the terminfo files,
-using:
-
-....
-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.
-
-In the meantime, you can automate it by using a simple script called, for example,
-`~/bin/myssh`
-
-....
-#!/bin/sh
-infocmp xterm-kitty | ssh $1 tic -x -o \~/.terminfo /dev/stdin && ssh $1
-....
-
-Then you can use `myssh server` to log in to `server` with the terminfo file
-being automatically available.
-
-
-=== How do I change the colors in a running kitty instance?
-
-You can either use the
-link:http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands[OSC
-terminal escape codes] to set colors or you can enable link:remote-control.asciidoc[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
-`<kitty config dir>/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:
-`/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
-```
-
-== Resources on terminal behavior
-
-http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
-
-https://en.wikipedia.org/wiki/C0_and_C1_control_codes
-
-https://vt100.net/

__main__.py

@@ -3,6 +3,7 @@
 # License: GPL v3 Copyright: 2015, Kovid Goyal <kovid at kovidgoyal.net>
 
 import sys
+import os
 
 
 def icat(args):
@@ -25,6 +26,13 @@ def runpy(args):
     exec(args[1])
 
 
+def hold(args):
+    import subprocess
+    ret = subprocess.Popen(args[1:]).wait()
+    sys.stdin.read()
+    raise SystemExit(ret)
+
+
 def launch(args):
     import runpy
     sys.argv = args[1:]
@@ -32,7 +40,12 @@ def launch(args):
 
 
 def run_kitten(args):
-    kitten = args[1]
+    try:
+        kitten = args[1]
+    except IndexError:
+        from kittens.runner import list_kittens
+        list_kittens()
+        raise SystemExit(1)
     sys.argv = args[1:]
     from kittens.runner import run_kitten
     run_kitten(kitten)
@@ -55,9 +68,24 @@ entry_points = {
     '+': namespaced,
 }
 namespaced_entry_points = {k: v for k, v in entry_points.items() if k[0] not in '+@'}
+namespaced_entry_points['hold'] = hold
+
+
+def setup_openssl_environment():
+    # Workaround for Linux distros that have still failed to get their heads
+    # out of their asses and implement a common location for SSL certificates.
+    # It's not that hard people, there exists a wonderful tool called the symlink
+    # See http://www.mobileread.com/forums/showthread.php?t=256095
+    if 'SSL_CERT_FILE' not in os.environ and 'SSL_CERT_DIR' not in os.environ:
+        if os.access('/etc/pki/tls/certs/ca-bundle.crt', os.R_OK):
+            os.environ['SSL_CERT_FILE'] = '/etc/pki/tls/certs/ca-bundle.crt'
+        elif os.path.isdir('/etc/ssl/certs'):
+            os.environ['SSL_CERT_DIR'] = '/etc/ssl/certs'
 
 
 def main():
+    if getattr(sys, 'frozen', False) and 'darwin' not in sys.platform.lower():
+        setup_openssl_environment()
     first_arg = '' if len(sys.argv) < 2 else sys.argv[1]
     func = entry_points.get(first_arg)
     if func is None:

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -T $(FAIL_WARN)
+SPHINXBUILD   = python3 .. +launch $(shell which 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)

docs/_static/custom.css

@@ -0,0 +1,120 @@
+/*
+ * 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;
+}
+
+.float-right-img { float: right; margin-left: 1em; margin-bottom: 1em }
+
+.half-with-img { max-width: 50% }
+
+.fit-img { max-width: 95% }
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+    text-align: justify;
+}
+
+pre {
+    white-space: pre-wrap;
+}
+
+pre.pre {
+    white-space: pre;
+}
+
+a[href], input[type="submit"] { cursor: pointer; }
+
+img[style] {
+    /* Used for :scale: images to have them render properly but still popup when clicked */
+    width: auto !important;
+    height: auto !important;
+}
+
+a {
+    text-decoration: none !important;
+    border-bottom: none !important;
+}
+
+body div.document {
+    margin-top: 1ex;
+}
+
+.major-features li {
+    margin-top: 0.75ex;
+    margin-bottom: 0.75ex;
+}
+
+.support-form input[type=submit] {
+    border-radius: 6px;
+    box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
+    background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100);
+    border: 1px solid rgb(255, 170, 34);
+    display: inline-block;
+    color: rgb(51, 51, 51);
+    font-family: Arial;
+    font-size: 15px;
+    font-weight: bold;
+    padding: 6px 24px;
+    text-decoration: none;
+    text-shadow: rgb(255, 238, 102) 0px 1px 0px;
+}
+
+.support-form input[type=submit]:hover {
+    background: linear-gradient(rgb(255, 171, 35) 5%, rgb(255, 236, 100) 100%) rgb(255, 171, 35);
+}
+
+.support-form input[type=submit]:focus {
+    outline: 0;
+}
+
+
+div.sphinxsidebar {
+    font-size: inherit;
+    line-height: inherit;
+}
+
+#sidebartoc li {
+    margin-top: 0.75ex;
+    margin-bottom: 0.75ex;
+}
+
+#sidebartoc ul {
+    list-style: none !important;
+}
+
+#sidebartoc a[href]:hover {
+    color: red;
+}
+
+
+.green {
+    color: green;
+}
+
+.cyan {
+    color: blue;
+}
+
+.env {
+    font-style: italic;
+}
+
+.italic {
+    font-style: italic;
+}
+
+.bold {
+    font-weight: bold;
+}
+
+.title {
+    font-size: larger;
+    font-weight: bold
+}

docs/_templates/layout.html

@@ -0,0 +1,13 @@
+{% extends "!layout.html" %}
+
+{%- block extrahead %}
+<!-- Google Analytics -->
+<script>
+window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
+ga('create', 'UA-20736318-2', 'auto');
+ga('send', 'pageview');
+</script>
+<script async="async" src='https://www.google-analytics.com/analytics.js'></script>
+<!-- End Google Analytics -->
+  {{ super() }}
+{% endblock %}

docs/_templates/localtoc.html

@@ -0,0 +1,6 @@
+{%- if display_toc %}
+<div>&nbsp;</div>
+<div id="sidebartoc">
+  {{ toc }}
+</div>
+{%- endif %}

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" %}
+<div id="searchbox" style="display: none" role="search">
+    <div class="searchformwrapper">
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" placeholder="{{ _('Search') }}" />
+      <input type="submit" value="{{ _('Go') }}" style="cursor: pointer" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+{%- endif %}

docs/_templates/support.html

@@ -0,0 +1,7 @@
+{% if pagename != "support" %}
+<div id="support" style="text-align: center">
+    <form class="support-form" action="{{ pathto('support') }}" title="{{ _('Donate to support kitty development') }}">
+        <input type="submit" value="{{ _('Support kitty') }}">
+    </form>
+</div>
+{% endif %}

docs/binary.rst

@@ -0,0 +1,65 @@
+kitty - Binary install
+========================
+
+.. |ins| replace:: curl -L :literal:`https://sw.kovidgoyal.net/kitty/installer.sh` | sh /dev/stdin
+
+.. highlight:: sh
+
+You can install pre-built binaries of |kitty| if you are on macOS or Linux using
+the following simple command:
+
+.. parsed-literal::
+    :class: pre
+
+    |ins|
+
+
+The binaries will be installed in the standard location for your OS,
+:file:`/Applications/kitty.app` on macOS and :file:`~/.local/kitty.app` on
+Linux. The installer only touches files in that directory.
+
+
+Manually installing
+---------------------
+
+If something goes wrong or you simply do not want to run the installer, you can
+manually download and install |kitty| from the `GitHub releases page
+<https://github.com/kovidgoyal/kitty/releases>`_. If you are on macOS, download
+the :file:`.dmg` and install as normal. If you are on Linux, download the tarball
+and extract it into a directory. The |kitty| executable will be in the
+:file:`bin` sub-directory.
+
+
+Customizing the installation
+--------------------------------
+
+* You can specify a different install location, with ``dest``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         dest=/some/other/location
+
+* You can tell the installer not to launch |kitty| after installing it with
+  ``launch=n``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         launch=n
+
+* You can use a previously downloaded dmg/tarball, with ``installer``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         installer=/path/to/dmg or tarball
+
+
+Building from source
+------------------------
+
+|kitty| is easy to build from source, follow the :doc:`instructions <build>`.

docs/build.rst

@@ -0,0 +1,94 @@
+Building kitty from source
+==============================
+
+.. image:: https://travis-ci.org/kovidgoyal/kitty.svg?branch=master
+  :alt: Build status
+  :target: https://travis-ci.org/kovidgoyal/kitty
+
+
+|kitty| is designed to run from source, for easy hackability. Make sure
+the following dependencies are installed first.
+
+Dependencies
+----------------
+
+Run-time 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``)
+
+Build-time dependencies:
+
+    * gcc or clang
+    * pkg-config
+    * For building on Linux in addition to the above dependencies you might also need to install the ``-dev`` packages for:
+      ``libxcursor-dev``, ``libxrandr-dev``, ``libxi-dev``, ``libxinerama-dev``, ``libgl1-mesa-dev`` and ``libxkbcommon-x11-dev``,
+      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
+----------------------------------
+
+The released |kitty| source code is available as a `tarball`_ from
+`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`_.
+
+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|.
+
+.. note::
+        You need a couple of extra dependencies to build linux-package.
+        :file:`tic` to compile terminfo files, usually found in the
+        development package of :file:`ncurses`. Also, if you are building form
+        a git checkout instead of the released source code tarball, you will
+        need :file:`sphinx-build` from the `Sphinx documentation generator
+        <http://www.sphinx-doc.org/>`_.
+
+This applies to creating packages for |kitty| for macOS package managers such as
+brew or MacPorts as well.

docs/changelog.rst

@@ -0,0 +1,750 @@
+Changelog
+==============
+
+|kitty| is a feature full, cross-platform, *fast*, GPU based terminal emulator.
+
+0.11.3 [2018-07-10]
+------------------------------
+
+- Draw only the minimum borders needed for inactive windows. That is only the borders
+  that separate the inactive window from a neighbor. Note that setting
+  a non-zero window margin overrides this and causes all borders to be drawn.
+  The old behavior of drawing all borders can be restored via the
+  :opt:`draw_minimal_borders` setting in kitty.conf.
+
+- macOS: Add an option :opt:`macos_window_resizable` to control if kitty
+  top-level windows are resizable using the mouse or not (:iss:`698`)
+
+- macOS: Use a custom mouse cursor that shows up well on both light and dark backgrounds
+  (:iss:`359`)
+
+- macOS: Workaround for switching from fullscreen to windowed mode with the
+  titlebar hidden causing window resizing to not work. (:iss:`711`)
+
+- Fix triple-click to select line not working when the entire line is filled
+  (:iss:`703`)
+
+- When dragging to select with the mouse "grab" the mouse so that if it strays
+  into neighboring windows, the selection is still updated (:pull:`624`)
+
+- When clicking in the margin/border area of a window, map the click to the
+  nearest cell in the window. Avoids selection with the mouse failing when
+  starting the selection just outside the window.
+
+- When drag-scrolling stop the scroll when the mouse button is released.
+
+- Fix a regression in the previous release that caused pasting large amounts
+  of text to be duplicated (:iss:`709`)
+
+
+0.11.2 [2018-07-01]
+------------------------------
+
+- Linux: Allow using XKB key names to bind shortcuts to keys not supported by GLFW (:pull:`665`)
+
+- kitty shell: Ignore failure to read readline history file. Happens if the
+  user migrates their kitty cache directory between systems with incompatible
+  readline implementations.
+
+- macOS: Fix an error in remote control when using --listen-on (:iss:`679`)
+
+- hints kitten: Add a :option:`kitty +kitten hints --multiple` option to select
+  multiple items (:iss:`687`)
+
+- Fix pasting large amounts of text very slow (:iss:`682`)
+
+- Add an option :opt:`single_window_margin_width` to allow different margins
+  when only a single window is visible in the layout (:iss:`688`)
+
+- Add a :option:`kitty --hold` command line option to stay open after the child process exits (:iss:`667`)
+
+- diff kitten: When triggering a search scroll to the first match automatically
+
+- :option:`kitty --debug-font-fallback` also prints out what basic fonts were matched
+
+- When closing a kitty window reset the mouse cursor to its default shape and ensure it is visible (:iss:`655`).
+
+- Remote control: Speed-up reading of command responses
+
+- Linux installer: Fix installer failing on systems with python < 3.5
+
+- Support "-T" as an alias for "--title" (:pull:`659`)
+
+- Fix a regression in the previous release that broke using :option:`kitty
+  --debug-config` with custom key mappings (:iss:`695`)
+
+
+0.11.1 [2018-06-17]
+------------------------------
+
+- diff kitten: Implement searching for text in the diff (:iss:`574`)
+
+- Add an option :opt:`startup_session` to :file:`kitty.conf` to specify a
+  default startup session (:iss:`641`)
+
+- Add a command line option :option:`kitty --wait-for-single-instance-window-close`
+  to make :option:`kitty --single-instance` wait for the closing of the newly opened
+  window before quitting (:iss:`630`)
+
+- diff kitten: Allow theming the selection background/foreground as well
+
+- diff kitten: Display CRLF line endings using the unicode return symbol
+  instead of <d> as it is less intrusive (:iss:`638`)
+
+- diff kitten: Fix default foreground/background colors not being restored when
+  kitten quits (:iss:`637`)
+
+- Fix :option:`kitty @ set-colors --all` not working when more than one window
+  present (:iss:`632`)
+
+- Fix a regression that broke the legacy increase/decrease_font_size actions
+
+- Clear scrollback on reset (:iss:`631`)
+
+
+0.11.0 [2018-06-12]
+------------------------------
+
+- A new tab bar style "fade" in which each tab's edges fade into the background.
+  See :opt:`tab_bar_style` and :opt:`tab_fade` for details. The old look can be
+  restored by setting :opt:`tab_bar_style` to :code:`separator`.
+
+- :doc:`Pre-compiled binaries <binary>` with all bundled dependencies for Linux
+  (:iss:`595`)
+
+- A :doc:`new kitten <kittens/panel>` to create dock panels on X11 desktops
+  showing the output from arbitrary terminal programs.
+
+- Reduce data sent to the GPU per render by 30% (:commit:`8dea5b3`)
+
+- Implement changing the font size for individual top level (OS) windows
+  (:iss:`408`)
+
+- When viewing the scrollback in less using :sc:`show_scrollback` and kitty
+  is currently scrolled, position the scrollback in less to match kitty's
+  scroll position. (:iss:`148`)
+
+- ssh kitten: Support all SSH options. It can now be aliased directly to ssh
+  for convenience. (:pull:`591`)
+
+- icat kitten: Add :option:`kitty +kitten icat --print-window-size` to easily
+  detect the window size in pixels from scripting languages (:iss:`581`)
+
+- hints kitten: Allow selecting hashes from the terminal with
+  :sc:`insert_selected_hash` useful for git commits. (:pull:`604`)
+
+- Allow specifying initial window size in number of cells in addition to pixels
+  (:iss:`436`)
+
+- Add a setting to control the margins to the left and right of the tab-bar
+  (:iss:`584`)
+
+- When closing a tab switch to the last active tab instead of the right-most
+  tab (:iss:`585`)
+
+- Wayland: Fix kitty not starting when using wl_roots based compositors
+  (:iss:`157`)
+
+- Wayland: Fix mouse wheel/touchpad scrolling in opposite direction to other apps (:iss:`594`)
+
+- macOS: Fix the new OS window keyboard shortcut (:sc:`new_os_window`) not
+  working if no kitty window currently has focus. (:iss:`524`)
+
+- macOS: Keep kitty running even when the last window is closed. This is in
+  line with how applications are supposed to behave on macOS (:iss:`543`).
+  There is a new option (:opt:`macos_quit_when_last_window_closed`) to control
+  this.
+
+- macOS: Add macOS standard shortcuts for copy, paste and new OS window
+  (⌘+C, ⌘+V, ⌘+N)
+
+- Add a config option (:opt:`editor`) to set the EDITOR kitty uses (:iss:`580`)
+
+- Add a config option (:opt:`x11_hide_window_decorations`) to hide window
+  decorations under X11/Wayland (:iss:`607`)
+
+- Add an option to @set-window-title to make the title change non-permanent
+  (:iss:`592`)
+
+- Add support for the CSI t escape code to query window and cell sizes
+  (:iss:`581`)
+
+- Linux: When using layouts that map the keys to non-ascii characters,
+  map shortcuts using the ascii equivalents, from the default layout.
+  (:iss:`606`)
+
+- Linux: Fix fonts not being correctly read from TrueType Collection
+  (.ttc) files (:iss:`577`)
+
+- Fix :opt:`inactive_text_alpha` also applying to the tab bar (:iss:`612`)
+
+- :doc:`hints kitten <kittens/hints>`: Fix a regression that caused some blank lines to be not
+  be displayed.
+
+- Linux: Include a man page and the HTML docs when building the linux-package
+
+- Remote control: Fix kitty @ sometimes failing to read the response from
+  kitty. (:iss:`614`)
+
+- Fix `kitty @ set-colors` not working with the window border colors.
+  (:iss:`623`)
+
+- Fix a regression in 0.10 that caused incorrect rendering of the status bar in
+  irssi when used inside screen. (:iss:`621`)
+
+
+0.10.1 [2018-05-24]
+------------------------------
+
+- Add a kitten to easily ssh into servers that automatically copies the
+  terminfo files over. ``kitty +kitten ssh myserver``.
+
+- diff kitten: Make the keyboard shortcuts configurable (:iss:`563`)
+
+- Allow controlling *background_opacity* via either keyboard shortcuts or
+  remote control. Note that you must set *dynamic_background_opacity yes* in
+  kitty.conf first. (:iss:`569`)
+
+- diff kitten: Add keybindings to scroll by page
+
+- diff kitten: Fix incorrect syntax highlighting for a few file formats such as
+  yaml
+
+- macOS: Fix regression that caused the *macos_option_as_alt* setting to always
+  be disabled for all OS windows in a kitty instance after the first window
+  (:iss:`571`)
+
+- Fix Ctrl+Alt+Space not working in normal and application keyboard modes
+  (:iss:`562`)
+
+
+0.10.0 [2018-05-21]
+------------------------------
+
+- A diff kitten to show side-by-side diffs with syntax highlighting and support
+  for images. See :doc:`diff kitten <kittens/diff>`.
+
+- Make windows in the various kitty layouts manually resizable. See
+  :ref:`layouts` for details.
+
+- Implement support for the SGR *faint* escape code to make text blend
+  into the background (:iss:`446`).
+
+- Make the hints kitten a little smarter (:commit:`ad1109b`)
+  so that URLs that stretch over multiple lines are detected. Also improve
+  detection of surrounding brackets/quotes.
+
+- Make the kitty window id available as the environment variable
+  ``KITTY_WINDOW_ID`` (:iss:`532`).
+
+- Add a "fat" layout that is similar to the "tall" layout but vertically
+  oriented.
+
+- Expand environment variables in config file include directives
+
+- Allow programs running in kitty to read/write from the clipboard (:commit:`889ca77`).
+  By default only writing is allowed. This feature is supported in many
+  terminals, search for `OSC 52 clipboard` to find out more about using it.
+
+- Fix moving cursor outside a defined page area incorrectly causing the cursor
+  to be placed inside the page area. Caused incorrect rendering in neovim, in
+  some situations (:iss:`542`).
+
+- Render a couple more powerline symbols directly, bypassing the font
+  (:iss:`550`).
+
+- Fix ctrl+alt+<special> not working in normal and application keyboard (:iss:`548`).
+
+- Partial fix for rendering Right-to-left languages like Arabic. Rendering of
+  Arabic is never going to be perfect, but now it is at least readable.
+
+- Fix Ctrl+backspace acting as plain backspace in normal and application
+  keyboard modes (:iss:`538`).
+
+- Have the paste_from_selection action paste from the clipboard on platforms
+  that do not have a primary selection such as Wayland and macOS
+  (:iss:`529`)
+
+- Fix cursor_stop_blinking_after=0 not working (:iss:`530`)
+
+
+0.9.1 [2018-05-05]
+------------------------------
+
+- Show a bell symbol on the tab if a bell occurs in one of the windows in the tab and
+  the window is not the currently focused window
+
+- Change the window border color if a bell occurs in an unfocused window. Can
+  be disabled by setting the bell_border_color to be the same as the
+  inactive_border_color.
+
+- macOS: Add support for dead keys
+
+- Unicode input: When searching by name search for prefix matches as well as
+  whole word matches
+
+- Dynamically allocate the memory used for the scrollback history buffer.
+  Reduces startup memory consumption when using very large scrollback
+  buffer sizes.
+
+- Add an option to not request window attention on bell.
+
+- Remote control: Allow matching windows by number (visible position).
+
+- macOS: Fix changing tab title and kitty shell not working
+
+- When triple-clicking select all wrapped lines belonging to a single logical line.
+
+- hints kitten: Detect bracketed URLs and dont include the closing bracket in the URL.
+
+- When calling pass_selection_to_program use the current directory of the child
+  process as the cwd of the program.
+
+- Add macos_hide_from_tasks option to hide kitty from the macOS task switcher
+
+- macOS: When the macos_titlebar_color is set to background change the titlebar
+  colors to match the current background color of the active kitty window
+
+- Add a setting to clear all shortcuts defined up to that point in the config
+  file(s)
+
+- Add a setting (kitty_mod) to change the modifier used by all the default
+  kitty shortcuts, globally
+
+- Fix Shift+function key not working
+
+- Support the F13 to F25 function keys
+
+- Don't fail to start if the user deletes the hintstyle key from their
+  fontconfig configuration.
+
+- When rendering a private use unicode codepoint and a space as a two cell
+  ligature, set the foreground colors of the space cell to match the colors of
+  the first cell. Works around applications like powerline that use different
+  colors for the two cells.
+
+- Fix passing @text to other programs such as when viewing the scrollback
+  buffer not working correctly if kitty is itself scrolled up.
+
+- Fix window focus gained/lost events not being reported to child programs when
+  switching windows/tabs using the various keyboard shortcuts.
+
+- Fix tab title not changing to reflect the window title when switching between different windows in a tab
+
+- Ignore -e if it is specified on the command line. This is for compatibility
+  with broken software that assumes terminals should run with an -e option to
+  execute commands instead of just passing the commands as arguments.
+
+
+0.9.0 [2018-04-15]
+------------------------------
+
+- A new kitty command shell to allow controlling kitty via commands. Press
+  `ctrl+shift+escape` to run the shell.
+
+- The hints kitten has become much more powerful. Now in addition to URLs you
+  can use it to select word, paths, filenames, lines, etc. from the screen.
+  These can be inserted into the terminal, copied to clipboard or sent to
+  external programs.
+
+- Linux: Switch to libxkbcommon for keyboard handling. It allows kitty to
+  support XCompose and dead keys and also react to keyboard remapping/layout
+  change without needing a restart.
+
+- Add support for multiple-key-sequence shortcuts
+
+- A new remote control command `set-colors` to change the current and/or
+  configured colors.
+
+- When double-clicking to select a word, select words that continue onto the
+  next/prev line as well.
+
+- Add an `include` directive for the config files to read multiple config files
+
+- Improve mouse selection for windows with padding. Moving the mouse into the
+  padding area now acts as if the mouse is over the nearest cell.
+
+- Allow setting all 256 terminal colors in the config file
+
+- Fix using `kitty --single-instance` to open a new window in a running kitty
+  instance, not respecting the `--directory` flag
+
+- URL hints: Exclude trailing punctuation from URLs
+
+- URL hints: Launch the browser from the kitty parent process rather than the
+  hints kitten. Fixes launching on some systems where xdg-open doesn't like
+  being run from a kitten.
+
+- Allow using rectangle select mode by pressing shift in addition to the
+  rectangle select modifiers even when the terminal program has grabbed the
+  mouse.
+
+
+0.8.4 [2018-03-31]
+-----------------------------
+
+- Fix presence of XDG_CONFIG_DIRS and absence of XDG_CONFIG_HOME preventing
+  kitty from starting
+
+- Revert change in last release to cell width calculation. Instead just clip
+  the right edges of characters that overflow the cell by at most two pixels
+
+
+0.8.3 [2018-03-29]
+-----------------------------
+
+- Fix a regression that broke the visual bell and invert screen colors escape
+  code
+
+- Allow double-click and triple-click + drag to extend selections word at a
+  time or line at a time
+
+- Add a keyboard shortcut to set the tab title
+
+- Fix setting window title to empty via OSC escape code not working correctly
+
+- Linux: Fix cell width calculation incorrect for some fonts (cell widths are
+  now calculated by actually rendering bitmaps, which is slower but more
+  accurate)
+
+- Allow specifying a system wide kitty config file, for all users
+
+- Add a --debug-config command line flag to output data about the system and
+  kitty configuration.
+
+- Wayland: Fix auto-repeat of keys not working
+
+
+0.8.2 [2018-03-17]
+-----------------------------
+
+- Allow extending existing selections by right clicking
+
+- Add a configurable keyboard shortcut and remote command to set the font size to a specific value
+
+- Add an option to have kitty close the window when the main processes running in it exits, even if there are still background processes writing to that terminal
+
+- Add configurable keyboard shortcuts to switch to a specific layout
+
+- Add a keyboard shortcut to edit the kitty config file easily
+
+- macOS: Fix restoring of window size not correct on Retina screens
+
+- macOS: Add a facility to specify command line arguments when running kitty from the GUI
+
+- Add a focus-tab remote command
+
+- Fix screen not being refreshed immediately after moving a window.
+
+- Fix a crash when getting the contents of the scrollback buffer as text
+
+0.8.1 [2018-03-09]
+-----------------------------
+
+- Extend kitty's remote control feature to work over both UNIX and TCP sockets,
+  so now you can control kitty from across the internet, if you want to.
+
+- Render private use unicode characters that are followed by a space as a two
+  character ligature. This fixes rendering for applications that misuse
+  private-use characters to display square symbols.
+
+- Fix Unicode emoji presentation variant selector causing new a fallback font
+  instance to be created
+
+- Fix a rare error that prevented the Unicode input kitten from working
+  sometimes
+
+- Allow using Ctrl+Alt+letter in legacy keyboard modes by outputting them as Ctrl+letter and Alt+letter.
+  This matches other terminals' behavior.
+
+- Fix cursor position off-by-one on horizontal axis when resizing the terminal
+
+- Wayland: Fix auto-repeat of keys not working
+
+- Wayland: Add support for window decorations provided by the Wayland shell
+
+- macOS: Fix URL hints not working
+
+- macOS: Fix shell not starting in login mode on some computers
+
+- macOS: Output errors into console.app when running as a bundle
+
+
+0.8.0 [2018-02-24]
+-----------------------------
+
+- A framework for kittens, that is, small terminal programs designed to run
+  inside kitty and extend its capabilities. Examples include unicode input and
+  selecting URLs with the keyboard.
+
+- Input arbitrary unicode characters by pressing Ctrl+Shift+u. You can choose
+  characters by name, by hex code, by recently used, etc. There is even and
+  editable Favorites list.
+
+- Open URLs using only the keyboard. kitty has a new "hints mode". Press
+  Ctrl+Shift+e and all detected URLs on the screen are highlighted with a key
+  to press to open them. The facility is customizable so you can change
+  what is detected as a URL and which program is used to open it.
+
+- Add an option to change the titlebar color of kitty windows on macOS
+
+- Only consider Emoji characters with default Emoji presentation to be two
+  cells wide. This matches the standard. Also add support for the Unicode Emoji
+  variation presentation selector.
+
+- Prevent video tearing during high speed scrolling by syncing draws
+  to the monitor's refresh rate. There is a new configuration option to
+  control this ``sync_to_monitor``.
+
+- When displaying only a single window, use the default background color of the
+  window (which can be changed via escape codes) as the color for the margin
+  and padding of the window.
+
+- Add some non standard terminfo capabilities used by neovim and tmux.
+
+- Fix large drop in performance when using multiple top-level windows on macOS
+
+- Fix save/restore of window sizes not working correctly.
+
+- Remove option to use system wcwidth(). Now always use a wcwidth() based on
+  the Unicode standard. Only sane way.
+
+- Fix a regression that caused a few ligature glyphs to not render correctly in
+  rare circumstances.
+
+- Browsing the scrollback buffer now happens in an overlay window instead of a
+  new window/tab.
+
+0.7.1 [2018-01-31]
+---------------------------
+
+- Add an option to adjust the width of character cells
+
+- Fix selecting text with the mouse in the scrollback buffer selecting text
+  from the line above the actually selected line
+
+- Fix some italic fonts having the right edge of characters cut-off,
+  unnecessarily
+
+
+0.7.0 [2018-01-24]
+---------------------------
+
+- Allow controlling kitty from the shell prompt/scripts. You can
+  open/close/rename windows and tabs and even send input to specific windows.
+  See the README for details.
+
+- Add option to put tab bar at the top instead of the bottom
+
+- Add option to override the default shell
+
+- Add "Horizontal" and "Vertical" window layouts
+
+- Sessions: Allow setting titles and working directories for individual windows
+
+- Option to copy to clipboard on mouse select
+
+- Fix incorrect reporting of mouse move events when using the SGR protocol
+
+- Make alt+backspace delete the previous word
+
+- Take the mouse wheel multiplier option in to account when generating fake key
+  scroll events
+
+- macOS: Fix closing top-level window does not transfer focus to other
+  top-level windows.
+
+- macOS: Fix alt+arrow keys not working when disabling the macos_option_as_alt
+  config option.
+
+- kitty icat: Workaround for bug in ImageMagick that would cause some images
+  to fail to display at certain sizes.
+
+- Fix rendering of text with ligature fonts that do not use dummy glyphs
+
+- Fix a regression that caused copying of the selection to clipboard to only
+  copy the visible part of the selection
+
+- Fix incorrect handling of some unicode combining marks that are not re-ordered
+
+- Fix handling on non-BMP combining characters
+
+- Drop the dependency on libunistring
+
+
+0.6.1 [2017-12-28]
+---------------------------
+
+- Add an option to fade the text in inactive windows
+
+- Add new actions to open windows/tabs/etc. with the working directory set to
+  the working directory of the current window.
+
+- Automatically adjust cell size when DPI changes, for example when kitty is
+  moved from one monitor to another with a different DPI
+
+- Ensure underlines are rendered even for fonts with very poor metrics
+
+- Fix some emoji glyphs not colored on Linux
+
+- Internal wcwidth() implementation is now auto-generated from the unicode
+  standard database
+
+- Allow configuring the modifiers to use for rectangular selection with the
+  mouse.
+
+- Fix incorrect minimum wayland version in the build script
+
+- Fix a crash when detecting a URL that ends at the end of the line
+
+- Fix regression that broke drawing of hollow cursor when window loses focus
+
+
+0.6.0 [2017-12-18]
+---------------------------
+
+- Support background transparency via the background_opacity option. Provided
+  that your OS/window manager supports transparency, you can now have kitty
+  render pixels that have only the default background color as
+  semi-transparent.
+
+- Support multiple top level (OS) windows. These windows all share the sprite
+  texture cache on the GPU, further reducing overall resource usage. Use
+  the shortcut `ctrl+shift+n` to open a new top-level window.
+
+- Add support for a *daemon* mode using the `--single-instance` command line
+  option. With this option you can have only a single kitty instance running.
+  All future invocations simply open new top-level windows in the existing
+  instance.
+
+- Support colored emoji
+
+- Use CoreText instead of FreeType to render text on macOS
+
+- Support running on the "low power" GPU on dual GPU macOS machines
+
+- Add a new "grid" window layout
+
+- Drop the dependency on glfw (kitty now uses a modified, bundled copy of glfw)
+
+- Add an option to control the audio bell volume on X11 systems
+
+- Add a command line switch to set the name part of the WM_CLASS window
+  property independently.
+
+- Add a command line switch to set the window title.
+
+- Add more options to customize the tab-bar's appearance (font styles and
+  separator)
+
+- Allow drag and drop of files into kitty. On drop kitty will paste the
+  file path to the running program.
+
+- Add an option to control the underline style for URL highlighting on hover
+
+- X11: Set the WINDOWID environment variable
+
+- Fix middle and right buttons swapped when sending mouse events to child
+  processes
+
+- Allow selecting in a rectangle by holding down Ctrl+Alt while dragging with
+  the mouse.
+
+
+0.5.1 [2017-12-01]
+---------------------------
+
+- Add an option to control the thickness of lines in box drawing characters
+
+- Increase max. allowed ligature length to nine characters
+
+- Fix text not vertically centered when adjusting line height
+
+- Fix unicode block characters not being rendered properly
+
+- Fix shift+up/down not generating correct escape codes
+
+- Image display: Fix displaying images taller than two screen heights not
+  scrolling properly
+
+
+0.5.0 [2017-11-19]
+---------------------------
+
+- Add support for ligature fonts such as Fira Code, Hasklig, etc. kitty now
+  uses harfbuzz for text shaping which allow it to support advanced OpenType
+  features such as contextual alternates/ligatures/combining glyphs/etc.
+
+- Make it easy to select fonts by allowing listing of monospace fonts using:
+  kitty list-fonts
+
+- Add an option to have window focus follow mouse
+
+- Add a keyboard shortcut (ctrl+shift+f11) to toggle fullscreen mode
+
+- macOS: Fix handling of option key. It now behaves just like the alt key on
+  Linux. There is an option to make it type unicode characters instead.
+
+- Linux: Add support for startup notification on X11 desktops. kitty will
+  now inform the window manager when its startup is complete.
+
+- Fix shell prompt being duplicated when window is resized
+
+- Fix crash when displaying more than 64 images in the same session
+
+- Add support for colons in SGR color codes. These are generated by some
+  applications such as neovim when they mistakenly identify kitty as a libvte
+  based terminal.
+
+- Fix mouse interaction not working in apps using obsolete mouse interaction
+  protocols
+
+- Linux: no longer require glew as a dependency
+
+
+0.4.2 [2017-10-23]
+---------------------------
+
+- Fix a regression in 0.4.0 that broke custom key mappings
+
+- Fix a regression in 0.4.0 that broke support for non-QWERTY keyboard layouts
+
+- Avoid using threads to reap zombie child processes. Also prevent kitty from
+  hanging if the open program hangs when clicking on a URL.
+
+
+0.4.0 [2017-10-22]
+---------------------------
+
+- Support for drawing arbitrary raster graphics (images) in the terminal via a
+  new graphics protocol. kitty can draw images with full 32-bit color using both
+  ssh connections and files/shared memory (when available) for better
+  performance. The drawing primitives support alpha blending and z-index.
+  Images can be drawn both above and below text. See :doc:`graphics-protocol`.
+  for details.
+
+- Refactor kitty's internals to make it even faster and more efficient. The CPU
+  usage of kitty + X server while doing intensive tasks such as scrolling a
+  file continuously in less has been reduced by 50%. There are now two
+  configuration options ``repaint_delay`` and ``input_delay`` you can use to
+  fine tune kitty's performance vs CPU usage profile. The CPU usage of kitty +
+  X when scrolling in less is now significantly better than most (all?) other
+  terminals. See :doc:`performance`.
+
+- Hovering over URLs with the mouse now underlines them to indicate they
+  can be clicked. Hold down Ctrl+Shift while clicking to open the URL.
+
+- Selection using the mouse is now more intelligent. It does not add
+  blank cells (i.e. cells that have no content) after the end of text in a
+  line to the selection.
+
+- The block cursor in now fully opaque but renders the character under it in
+  the background color, for enhanced visibility.
+
+- Allow combining multiple independent actions into a single shortcut
+
+- Add a new shortcut to pass the current selection to an external program
+
+- Allow creating shortcuts to open new windows running arbitrary commands. You
+  can also pass the current selection to the command as an arguments and the
+  contents of the screen + scrollback buffer as stdin to the command.

docs/conf.py

@@ -0,0 +1,538 @@
+# -*- 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
+
+import os
+import re
+import subprocess
+import sys
+from functools import partial
+
+from docutils import nodes
+from docutils.parsers.rst.roles import set_classes
+from pygments.lexer import RegexLexer, bygroups
+from pygments.token import (
+    Comment, Keyword, Literal, Name, Number, String, Whitespace
+)
+from sphinx import addnodes
+from sphinx.util.logging import getLogger
+
+from kitty.constants import str_version
+
+# config {{{
+# -- Project information -----------------------------------------------------
+
+project = 'kitty'
+copyright = '2018, Kovid Goyal'
+author = 'Kovid Goyal'
+building_man_pages = 'man' in sys.argv
+
+# The short X.Y version
+version = str_version
+# The full version, including alpha/beta/rc tags
+release = str_version
+logger = getLogger(__name__)
+
+
+# -- 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',
+    'generated/cli-*.rst', 'generated/conf-*.rst'
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+rst_prolog = '''
+.. |kitty| replace:: *kitty*
+.. |version| replace:: VERSION
+.. _tarball: https://github.com/kovidgoyal/kitty/releases/download/vVERSION/kitty-VERSION.tar.xz
+.. role:: green
+.. role:: italic
+.. role:: bold
+.. role:: cyan
+.. role:: title
+.. role:: env
+
+'''.replace('VERSION', str_version)
+
+
+# -- 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,
+    'github_button': False,
+    'github_banner': True,
+    'github_user': 'kovidgoyal',
+    'github_repo': 'kitty',
+    # increase contrast of link color with text color
+    'link': '#00587d',
+    'link_hover': 'green',
+}
+
+
+# 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']
+}
+html_favicon = '../logo/kitty.png'
+
+# 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',
+        'support.html',
+        'searchbox.html',
+        'localtoc.html',
+        'relations.html',
+    ]
+}
+html_show_sourcelink = False
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('invocation', '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', 'A cross-platform, fast, feature full, GPU based terminal emulator',
+     'Miscellaneous'),
+]
+# }}}
+
+
+# GitHub linking inlne roles {{{
+
+def num_role(which, name, rawtext, text, lineno, inliner, options={}, content=[]):
+    ' Link to a github issue '
+    try:
+        issue_num = int(text)
+        if issue_num <= 0:
+            raise ValueError
+    except ValueError:
+        msg = inliner.reporter.error(
+            'GitHub issue number must be a number greater than or equal to 1; '
+            '"%s" is invalid.' % text, line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    url = f'https://github.com/kovidgoyal/kitty/{which}/{issue_num}'
+    set_classes(options)
+    node = nodes.reference(rawtext, f'#{issue_num}', refuri=url, **options)
+    return [node], []
+
+
+def commit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    ' Link to a github commit '
+    try:
+        commit_id = subprocess.check_output(f'git rev-list --max-count=1 --skip=# {text}'.split()).decode('utf-8').strip()
+    except Exception:
+        msg = inliner.reporter.error(
+            f'GitHub commit id "{text}" not recognized.', line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    url = f'https://github.com/kovidgoyal/kitty/commit/{commit_id}'
+    set_classes(options)
+    short_id = subprocess.check_output(f'git rev-list --max-count=1 --abbrev-commit --skip=# {commit_id}'.split()).decode('utf-8').strip()
+    node = nodes.reference(rawtext, f'commit: {short_id}', refuri=url, **options)
+    return [node], []
+# }}}
+
+
+# Sidebar ToC {{{
+def create_toc(app, pagename):
+    toctree = app.env.get_toc_for(pagename, app.builder)
+    if toctree is not None:
+        subtree = toctree[toctree.first_child_matching_class(nodes.list_item)]
+        bl = subtree.first_child_matching_class(nodes.bullet_list)
+        if bl is None:
+            return  # Empty ToC
+        subtree = subtree[bl]
+        # for li in subtree.traverse(nodes.list_item):
+        #     modify_li(li)
+        # subtree['ids'] = [ID]
+        return app.builder.render_partial(subtree)['fragment']
+
+
+def add_html_context(app, pagename, templatename, context, *args):
+    if 'toc' in context:
+        context['toc'] = create_toc(app, pagename) or context['toc']
+# }}}
+
+
+# CLI docs {{{
+def write_cli_docs(all_kitten_names):
+    from kitty.cli import option_spec_as_rst
+    with open('generated/cli-kitty.rst', 'w') as f:
+        f.write(option_spec_as_rst(appname='kitty').replace(
+            'kitty --to', 'kitty @ --to'))
+    as_rst = partial(option_spec_as_rst, heading_char='_')
+    from kitty.remote_control import global_options_spec, cli_msg, cmap, all_commands
+    with open('generated/cli-kitty-at.rst', 'w') as f:
+        p = partial(print, file=f)
+        p('kitty @\n' + '-' * 80)
+        p('.. program::', 'kitty @')
+        p('\n\n' + as_rst(
+            global_options_spec, message=cli_msg, usage='command ...', appname='kitty @'))
+        from kitty.cmds import cli_params_for
+        for cmd_name in all_commands:
+            func = cmap[cmd_name]
+            p(f'.. _at_{func.name}:\n')
+            p('kitty @', func.name + '\n' + '-' * 120)
+            p('.. program::', 'kitty @', func.name)
+            p('\n\n' + as_rst(*cli_params_for(func)))
+    from kittens.runner import get_kitten_cli_docs
+    for kitten in all_kitten_names:
+        data = get_kitten_cli_docs(kitten)
+        if data:
+            with open(f'generated/cli-kitten-{kitten}.rst', 'w') as f:
+                p = partial(print, file=f)
+                p('.. program::', f'kitty +kitten {kitten}')
+                p('\n\n' + option_spec_as_rst(
+                    data['options'], message=data['help_text'], usage=data['usage'], appname=f'kitty +kitten {kitten}',
+                    heading_char='^'))
+
+# }}}
+
+
+# config file docs {{{
+
+class ConfLexer(RegexLexer):
+    name = 'Conf'
+    aliases = ['conf']
+    filenames = ['*.conf']
+
+    tokens = {
+        'root': [
+            (r'#.*?$', Comment.Single),
+            (r'\s+$', Whitespace),
+            (r'\s+', Whitespace),
+            (r'(include)(\s+)(.+?)$', bygroups(Comment.Preproc, Whitespace, Name.Namespace)),
+            (r'(map)(\s+)(\S+)(\s+)', bygroups(
+                Keyword.Declaration, Whitespace, String, Whitespace), 'action'),
+            (r'(symbol_map)(\s+)(\S+)(\s+)(.+?)$', bygroups(
+                Keyword.Declaration, Whitespace, String, Whitespace, Literal)),
+            (r'([a-zA-Z_0-9]+)(\s+)', bygroups(
+                Name.Variable, Whitespace), 'args'),
+        ],
+        'action': [
+            (r'[a-z_0-9]+$', Name.Function, 'root'),
+            (r'[a-z_0-9]+', Name.Function, 'args'),
+        ],
+        'args': [
+            (r'\s+', Whitespace, 'args'),
+            (r'\b(yes|no)\b$', Number.Bin, 'root'),
+            (r'\b(yes|no)\b', Number.Bin, 'args'),
+            (r'[+-]?[0-9]+\s*$', Number.Integer, 'root'),
+            (r'[+-]?[0-9.]+\s*$', Number.Float, 'root'),
+            (r'[+-]?[0-9]+', Number.Integer, 'args'),
+            (r'[+-]?[0-9.]+', Number.Float, 'args'),
+            (r'#[a-fA-F0-9]{3,6}\s*$', String, 'root'),
+            (r'#[a-fA-F0-9]{3,6}\s*', String, 'args'),
+            (r'.+', String, 'root'),
+        ],
+    }
+
+
+class SessionLexer(RegexLexer):
+    name = 'Session'
+    aliases = ['session']
+    filenames = ['*.session']
+
+    tokens = {
+        'root': [
+            (r'#.*?$', Comment.Single),
+            (r'[a-z][a-z0-9_]+', Name.Function, 'args'),
+        ],
+        'args': [
+            (r'.*?$', Literal, 'root'),
+        ]
+    }
+
+
+def link_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    m = re.match(r'(.+)\s+<(.+?)>', text)
+    if m is None:
+        msg = inliner.reporter.error(f'link "{text}" not recognized', line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    text, url = m.group(1, 2)
+    set_classes(options)
+    node = nodes.reference(rawtext, text, refuri=url, **options)
+    return [node], []
+
+
+def expand_opt_references(conf_name, text):
+    conf_name += '.'
+
+    def expand(m):
+        ref = m.group(1)
+        if '<' not in ref and '.' not in ref:
+            full_ref = conf_name + ref
+            return ':opt:`{} <{}>`'.format(ref, full_ref)
+        return m.group()
+
+    return re.sub(r':opt:`(.+?)`', expand, text)
+
+
+opt_aliases = {}
+shortcut_slugs = {}
+
+
+def parse_opt_node(env, sig, signode):
+    """Transform an option description into RST nodes."""
+    count = 0
+    firstname = ''
+    for potential_option in sig.split(', '):
+        optname = potential_option.strip()
+        if count:
+            signode += addnodes.desc_addname(', ', ', ')
+        text = optname.split('.', 1)[-1]
+        signode += addnodes.desc_name(text, text)
+        if not count:
+            firstname = optname
+            signode['allnames'] = [optname]
+        else:
+            signode['allnames'].append(optname)
+            opt_aliases[optname] = firstname
+        count += 1
+    if not firstname:
+        raise ValueError('{} is not a valid opt'.format(sig))
+    return firstname
+
+
+def parse_shortcut_node(env, sig, signode):
+    """Transform a shortcut description into RST nodes."""
+    conf_name, text = sig.split('.', 1)
+    signode += addnodes.desc_name(text, text)
+    return sig
+
+
+def render_conf(conf_name, all_options):
+    from kitty.conf.definition import merged_opts, Option
+    ans = ['.. default-domain:: conf', '']
+    a = ans.append
+    current_group = None
+    all_options = list(all_options)
+    kitty_mod = 'kitty_mod'
+
+    def render_group(group):
+        a('')
+        a(f'.. _conf-{conf_name}-{group.name}:')
+        a('')
+        a(group.short_text)
+        heading_level = '+' if '.' in group.name else '^'
+        a(heading_level * (len(group.short_text) + 20))
+        a('')
+        if group.start_text:
+            a(group.start_text)
+            a('')
+
+    def handle_group_end(group):
+        if group.end_text:
+            a(''), a(current_group.end_text)
+
+    def handle_group(new_group, new_group_is_shortcut=False):
+        nonlocal current_group
+        if new_group is not current_group:
+            if current_group:
+                handle_group_end(current_group)
+            current_group = new_group
+            render_group(current_group)
+
+    def handle_option(i, opt):
+        nonlocal kitty_mod
+        if not opt.long_text or not opt.add_to_docs:
+            return
+        handle_group(opt.group)
+        if opt.name == 'kitty_mod':
+            kitty_mod = opt.defval_as_string
+        mopts = list(merged_opts(all_options, opt, i))
+        a('.. opt:: ' + ', '.join(conf_name + '.' + mo.name for mo in mopts))
+        a('.. code-block:: conf')
+        a('')
+        sz = max(len(x.name) for x in mopts)
+        for mo in mopts:
+            a(('    {:%ds} {}' % sz).format(mo.name, mo.defval_as_string))
+        a('')
+        if opt.long_text:
+            a(expand_opt_references(conf_name, opt.long_text))
+            a('')
+
+    def handle_shortcuts(shortcuts):
+        sc = shortcuts[0]
+        handle_group(sc.group, True)
+        sc_text = f'{conf_name}.{sc.short_text}'
+        a('.. shortcut:: ' + sc_text)
+        shortcuts = [s for s in shortcuts if s.add_to_default]
+        shortcut_slugs[f'{conf_name}.{sc.name}'] = (sc_text, sc.key.replace('kitty_mod', kitty_mod))
+        if shortcuts:
+            a('.. code-block:: conf')
+            a('')
+            for x in shortcuts:
+                if x.add_to_default:
+                    a('    map {} {}'.format(x.key.replace('kitty_mod', kitty_mod), x.action_def))
+        a('')
+        if sc.long_text:
+            a(expand_opt_references(conf_name, sc.long_text))
+            a('')
+
+    for i, opt in enumerate(all_options):
+        if isinstance(opt, Option):
+            handle_option(i, opt)
+        else:
+            handle_shortcuts(opt)
+
+    if current_group:
+        handle_group_end(current_group)
+    return '\n'.join(ans)
+
+
+def process_opt_link(env, refnode, has_explicit_title, title, target):
+    conf_name, opt = target.partition('.')[::2]
+    if not opt:
+        conf_name, opt = 'kitty', conf_name
+    full_name = conf_name + '.' + opt
+    return title, opt_aliases.get(full_name, full_name)
+
+
+def process_shortcut_link(env, refnode, has_explicit_title, title, target):
+    conf_name, slug = target.partition('.')[::2]
+    if not slug:
+        conf_name, slug = 'kitty', conf_name
+    full_name = conf_name + '.' + slug
+    try:
+        target, title = shortcut_slugs[full_name]
+    except KeyError:
+        logger.warning('Unknown shortcut: {}'.format(target), location=refnode)
+    return title, target
+
+
+def write_conf_docs(app, all_kitten_names):
+    app.add_lexer('conf', ConfLexer())
+    app.add_object_type(
+        'opt', 'opt',
+        indextemplate="pair: %s; Config Setting",
+        parse_node=parse_opt_node,
+    )
+    # Warn about opt references that could not be resolved
+    opt_role = app.registry.domain_roles['std']['opt']
+    opt_role.warn_dangling = True
+    opt_role.process_link = process_opt_link
+
+    app.add_object_type(
+        'shortcut', 'sc',
+        indextemplate="pair: %s; Keyboard Shortcut",
+        parse_node=parse_shortcut_node,
+    )
+    sc_role = app.registry.domain_roles['std']['sc']
+    sc_role.warn_dangling = True
+    sc_role.process_link = process_shortcut_link
+
+    def generate_default_config(all_options, name):
+        from kitty.conf.definition import as_conf_file
+        with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f:
+            print('.. highlight:: conf\n', file=f)
+            f.write(render_conf(name, all_options.values()))
+
+        conf_name = re.sub(r'^kitten-', '', name) + '.conf'
+        with open(f'generated/conf/{conf_name}', 'w', encoding='utf-8') as f:
+            text = '\n'.join(as_conf_file(all_options.values()))
+            print(text, file=f)
+
+    from kitty.config_data import all_options
+    generate_default_config(all_options, 'kitty')
+
+    from kittens.runner import get_kitten_conf_docs
+    for kitten in all_kitten_names:
+        all_options = get_kitten_conf_docs(kitten)
+        if all_options:
+            generate_default_config(all_options, f'kitten-{kitten}')
+# }}}
+
+
+def setup(app):
+    os.makedirs('generated/conf', exist_ok=True)
+    from kittens.runner import all_kitten_names
+    all_kitten_names = all_kitten_names()
+    write_cli_docs(all_kitten_names)
+    write_conf_docs(app, all_kitten_names)
+    app.add_lexer('session', SessionLexer())
+    app.add_role('link', link_role)
+    app.add_role('iss', partial(num_role, 'issues'))
+    app.add_role('pull', partial(num_role, 'pull'))
+    app.add_role('commit', commit_role)
+    app.connect('html-page-context', add_html_context)

docs/conf.rst

@@ -0,0 +1,40 @@
+:tocdepth: 2
+
+Configuring kitty
+===============================
+
+.. highlight:: conf
+
+|kitty| is highly customizable, everything from keyboard shortcuts, to painting
+frames-per-second. See 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``.
+
+.. _confloc:
+
+|kitty| looks for a config file in the OS config directories (usually
+:file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the
+:option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY``
+environment variable. See the :option:`kitty --config` option for full details.
+
+You can include secondary config files via the :code:`include` directive.  If
+you use a relative path for include, it is resolved with respect to the
+location of the current config file. Note that environment variables are
+expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if
+:code:`USER=name`.  For example::
+
+     include other.conf
+
+
+.. include:: /generated/conf-kitty.rst
+
+
+Sample kitty.conf
+^^^^^^^^^^^^^^^^^^^^^
+
+You can download a sample :file:`kitty.conf` file with all default settings and
+comments describing each setting by clicking: :download:`sample kitty.conf
+</generated/conf/kitty.conf>`.

docs/faq.rst

@@ -0,0 +1,115 @@
+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 <https://github.com/kovidgoyal/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 :ref:`here <ext_styles>` 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
+a non POSIX compliant 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 <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands>`_
+to set colors or you can enable :doc:`remote control <remote-control>`
+for |kitty| and use :ref:`at_set-colors`.
+
+
+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:`<kitty config dir>/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

docs/graphics-protocol.rst

@@ -0,0 +1,398 @@
+:tocdepth: 3
+
+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
+<https://github.com/kovidgoyal/kitty/issues/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 <https://github.com/dsanson/termpdf>`_ - a terminal PDF/DJVU/CBR viewer
+ * `ranger <https://github.com/ranger/ranger>`_ - a terminal file manager, with
+   image previews, see this `PR <https://github.com/ranger/ranger/pull/1077>`_
+ * :doc:`kitty-diff <kittens/diff>` - a side-by-side terminal diff program with support for images
+ * `neofetch <https://github.com/dylanaraps/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
+``<ESC>[14t`` to *stdout* and kitty will reply on *stdin* with
+``<ESC>[4;<height>;<width>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::
+
+    <ESC>_G<control data>;<payload><ESC>\
+
+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::
+
+    <ESC>_Gf=24,s=10,v=20;<payload><ESC>\
+
+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::
+
+    <ESC>_Gf=100;<payload><ESC>\
+
+
+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::
+
+    <ESC>_Gf=24,s=10,v=20,o=z;<payload><ESC>\
+
+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 <http://man7.org/linux/man-pages/man7/shm_overview.7.html>`_.
+                      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::
+
+    <ESC>_Gf=100,t=f;<encoded /path/to/file.png><ESC>\
+
+Here we tell the terminal emulator to read PNG data from the specified file of
+the specified size::
+
+    <ESC>_Gs=10,v=2,t=s,o=z;<encoded /some-shared-memory-name><ESC>\
+
+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::
+
+    <ESC>_Gs=10,v=2,t=s,S=80,O=10;<encoded /some-shared-memory-name><ESC>\
+
+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::
+
+    <ESC>_Gs=100,v=30,m=1;<encoded pixel data first chunk><ESC>\
+    <ESC>_Gm=1;<encoded pixel data second chunk><ESC>\
+    <ESC>_Gm=0;<encoded pixel data last chunk><ESC>\
+
+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::
+
+    <ESC>_Gi=31,s=10,v=2,t=s;<encoded /some-shared-memory-name><ESC>\
+
+to which the terminal emulator will reply (after trying to load the data)::
+
+    <ESC>_Gi=31;error message or OK<ESC>\
+
+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::
+
+    <ESC>_Gi=<id>;OK<ESC>\
+
+when the image referred to by id was found, or::
+
+    <ESC>_Gi=<id>;ENOENT:<some detailed error msg><ESC>\
+
+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::
+
+    <ESC>_Ga=d<ESC>\         # delete all visible images
+    <ESC>_Ga=d,i=10<ESC>\    # delete the image with id=10
+    <ESC>_Ga=Z,z=-1<ESC>\    # delete the images with z-index -1, also freeing up image data
+    <ESC>_Ga=P,x=3,y=4<ESC>\ # 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 ``<ESC>[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.

docs/index.rst

@@ -0,0 +1,352 @@
+:tocdepth: 2
+
+==========================================================
+kitty - the fast, featureful, GPU based terminal emulator
+==========================================================
+
+.. container:: major-features
+
+    * Offloads rendering to the GPU for :doc:`lower system load <performance>` and
+      buttery smooth scrolling.  Uses threaded rendering to minimize input latency.
+
+    * Supports all modern terminal features: :doc:`graphics (images)
+      <graphics-protocol>`, unicode, true-color, OpenType ligatures, mouse
+      protocol, focus tracking, `bracketed paste
+      <https://cirw.in/blog/bracketed-paste>`_ and several :doc:`new terminal
+      protocol extensions <protocol-extensions>`.
+
+    * Supports tiling multiple terminal windows side by side in different
+      :ref:`layouts <layouts>` without needing to use an extra program like tmux
+
+    * Can be :doc:`controlled from scripts or the shell prompt <remote-control>`,
+      even over SSH.
+
+    * Has a framework for :ref:`kittens`, small terminal programs that can be used to
+      extend |kitty|'s functionality.  For example, they are used for
+      :doc:`Unicode input <kittens/unicode-input>`, :doc:`Hints <kittens/hints>` and
+      :doc:`Side-by-side diff <kittens/diff>`.
+
+    * Supports :ref:`startup sessions <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 Unix-like platforms.
+
+    * Allows you to open :ref:`the scrollback buffer <scrollback>` 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
+    :scale: 100%
+
+    Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
+
+
+.. _quickstart:
+
+Quickstart
+--------------
+
+Pre-built binaries of |kitty| are available for both macOS and Linux.
+See the :doc:`binary install instructions </binary>`.
+
+If you are on Linux, you can also use your distribution's |kitty| package.
+|kitty| packages are available for:
+`Debian <https://packages.debian.org/buster/kitty>`_,
+`openSUSE <https://build.opensuse.org/package/show/X11:terminals/kitty>`_,
+`Arch Linux <https://www.archlinux.org/packages/community/x86_64/kitty/>`_,
+`NixOS <https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/kitty/default.nix>`_,
+`Gentoo <https://packages.gentoo.org/packages/x11-terms/kitty>`_,
+`Fedora <https://copr.fedorainfracloud.org/coprs/oleastre/kitty-terminal/>`_.
+
+See :doc:`Configuring kitty <conf>` for help on configuring |kitty| and
+:doc:`Invocation <invocation>` for the command line arguments |kitty| supports.
+
+
+.. 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` (also :kbd:`⌘+n` on macOS)
+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` (also :kbd:`⌘+c` on macOS)
+Paste from clipboard                :sc:`paste_from_clipboard` (also :kbd:`⌘+v` on macOS)
+Paste from selection                :sc:`paste_from_selection`
+Increase font size                  :sc:`increase_font_size`
+Decrease font size                  :sc:`decrease_font_size`
+Restore font size                   :sc:`reset_font_size`
+Toggle fullscreen                   :sc:`toggle_fullscreen`
+Input unicode character             :sc:`input_unicode_character`
+Click URL using the keyboard        :sc:`open_url`
+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`
+Increase background opacity         :sc:`increase_background_opacity`
+Decrease background opacity         :sc:`decrease_background_opacity`
+Full background opacity             :sc:`full_background_opacity`
+Reset background opacity            :sc:`reset_background_opacity`
+==================================  =======================
+
+
+.. _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 :ref:`conf-kitty-shortcuts.layout` 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 :opt:`kitty.conf <enabled_layouts>` 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
+<https://github.com/kovidgoyal/kitty/blob/master/kitty/layout.py>`_  and submit
+a pull request!
+
+.. _kittens:
+
+Kittens
+------------------
+
+|kitty| has a framework for easily creating terminal programs that make use of
+its advanced features. These programs are called kittens. They are used both
+to add features to |kitty| itself and to create useful standalone programs.
+Some prominent kittens:
+
+:doc:`icat <kittens/icat>`
+    Display images in the terminal
+
+
+:doc:`diff <kittens/diff>`
+    A fast, side-by-side diff for the terminal with syntax highlighting and
+    images
+
+
+:doc:`Unicode Input <kittens/unicode-input>`
+    Easily input arbitrary unicode characters in |kitty| by name or hex code.
+
+
+:doc:`Hints <kittens/hints>`
+    Select and open/paste/insert arbitrary text snippets such as URLs,
+    filenames, words, lines, etc from the terminal screen.
+
+
+:doc:`Panel <kittens/panel>`
+    Draw a GPU accelerated dock panel on your desktop showing the output
+    from an arbitrary terminal program.
+
+:doc:`Clipboard <kittens/clipboard>`
+    Copy/paste to the clipboard from shell scripts, even over SSH.
+
+
+Configuring kitty
+-------------------
+
+|kitty| is highly configurable, everything from keyboard shortcuts to
+painting frames-per-second. For details and a sample :file:`kitty.conf`,
+see the :doc:`configuration docs <conf>`.
+
+.. _sessions:
+
+Startup Sessions
+------------------
+
+You can control the tabs, window layout, working directory, startup programs,
+etc. by creating a "session" file and using the :option:`kitty --session`
+command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
+For example:
+
+.. code-block:: session
+
+    # 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
+:ref:`conf-kitty-fonts`.
+
+
+.. _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 <faq>`.
+
+
+Changelog
+------------------
+
+See :doc:`changelog`.
+
+.. toctree::
+    :hidden:
+    :glob:
+
+    *
+    kittens/*

docs/installer.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+import atexit
+import json
+import os
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+
+py3 = sys.version_info[0] > 2
+is64bit = platform.architecture()[0] == '64bit'
+is_macos = 'darwin' in sys.platform.lower()
+
+try:
+    __file__
+    from_file = True
+except NameError:
+    from_file = False
+
+if py3:
+    unicode = str
+    raw_input = input
+    import urllib.request as urllib
+
+    def encode_for_subprocess(x):
+        return x
+else:
+    from future_builtins import map
+    import urllib2 as urllib
+
+    def encode_for_subprocess(x):
+        if isinstance(x, unicode):
+            x = x.encode('utf-8')
+        return x
+
+
+def run(*args):
+    if len(args) == 1:
+        args = shlex.split(args[0])
+    args = list(map(encode_for_subprocess, args))
+    ret = subprocess.Popen(args).wait()
+    if ret != 0:
+        raise SystemExit(ret)
+
+
+class Reporter:  # {{{
+
+    def __init__(self, fname):
+        self.fname = fname
+        self.last_percent = 0
+
+    def __call__(self, blocks, block_size, total_size):
+        percent = (blocks*block_size)/float(total_size)
+        report = '\rDownloaded {:.1%}         '.format(percent)
+        if percent - self.last_percent > 0.05:
+            self.last_percent = percent
+            print(report, end='')
+            sys.stdout.flush()
+# }}}
+
+
+def get_latest_release_data():
+    print('Checking for latest release on GitHub...')
+    req = urllib.Request('https://api.github.com/repos/kovidgoyal/kitty/releases/latest', headers={'Accept': 'application/vnd.github.v3+json'})
+    res = urllib.urlopen(req).read().decode('utf-8')
+    data = json.loads(res)
+    html_url = data['html_url'].replace('/tag/', '/download/').rstrip('/')
+    for asset in data.get('assets', ()):
+        name = asset['name']
+        if is_macos:
+            if name.endswith('.dmg'):
+                return html_url + '/' + name, asset['size']
+        else:
+            if name.endswith('.txz'):
+                if is64bit:
+                    if name.endswith('-x86_64.txz'):
+                        return html_url + '/' + name, asset['size']
+                else:
+                    if name.endswith('-i686.txz'):
+                        return html_url + '/' + name, asset['size']
+    raise SystemExit('Failed to find the installer package on github')
+
+
+def do_download(url, size, dest):
+    print('Will download and install', os.path.basename(dest))
+    reporter = Reporter(os.path.basename(dest))
+
+    # Get content length and check if range is supported
+    rq = urllib.urlopen(url)
+    headers = rq.info()
+    sent_size = int(headers['content-length'])
+    if sent_size != size:
+        raise SystemExit('Failed to download from {} Content-Length ({}) != {}'.format(url, sent_size, size))
+    with open(dest, 'wb') as f:
+        while f.tell() < size:
+            raw = rq.read(8192)
+            if not raw:
+                break
+            f.write(raw)
+            reporter(f.tell(), 1, size)
+    rq.close()
+    if os.path.getsize(dest) < size:
+        raise SystemExit('Download failed, try again later')
+    print('\rDownloaded {} bytes'.format(os.path.getsize(dest)))
+
+
+def clean_cache(cache, fname):
+    for x in os.listdir(cache):
+        if fname not in x:
+            os.remove(os.path.join(cache, x))
+
+
+def download_installer(url, size):
+    fname = url.rpartition('/')[-1]
+    tdir = tempfile.gettempdir()
+    cache = os.path.join(tdir, 'kitty-installer-cache')
+    if not os.path.exists(cache):
+        os.makedirs(cache)
+    clean_cache(cache, fname)
+    dest = os.path.join(cache, fname)
+    if os.path.exists(dest) and os.path.getsize(dest) == size:
+        print('Using previously downloaded', fname)
+        return dest
+    if os.path.exists(dest):
+        os.remove(dest)
+    do_download(url, size, dest)
+    return dest
+
+
+def macos_install(dmg, dest='/Applications', launch=True):
+    mp = tempfile.mkdtemp()
+    atexit.register(shutil.rmtree, mp)
+    run('hdiutil', 'attach', dmg, '-mountpoint', mp)
+    try:
+        os.chdir(mp)
+        app = 'kitty.app'
+        d = os.path.join(dest, app)
+        if os.path.exists(d):
+            shutil.rmtree(d)
+        dest = os.path.join(dest, app)
+        run('ditto', '-v', app, dest)
+        print('Successfully installed kitty into', dest)
+        if launch:
+            run('open', dest)
+    finally:
+        os.chdir('/')
+        run('hdiutil', 'detach', mp)
+
+
+def linux_install(installer, dest=os.path.expanduser('~/.local'), launch=True):
+    dest = os.path.join(dest, 'kitty.app')
+    if os.path.exists(dest):
+        shutil.rmtree(dest)
+    os.makedirs(dest)
+    print('Extracting tarball...')
+    run('tar', '-C', dest, '-xJof', installer)
+    print('kitty successfully installed to', dest)
+    kitty = os.path.join(dest, 'bin', 'kitty')
+    print('Use', kitty, 'to run kitty')
+    if launch:
+        run(kitty, '--detach')
+
+
+def main(dest=None, launch=True, installer=None):
+    if not dest:
+        if is_macos:
+            dest = '/Applications'
+        else:
+            dest = os.path.expanduser('~/.local')
+    machine = os.uname()[4]
+    if machine and machine.lower().startswith('arm'):
+        raise SystemExit(
+            'You are running on an ARM system. The kitty binaries are only'
+            ' available for x86 systems. You will have to build from'
+            ' source.')
+    if not installer:
+        url, size = get_latest_release_data()
+        installer = download_installer(url, size)
+    else:
+        installer = os.path.abspath(installer)
+        if not os.access(installer, os.R_OK):
+            raise SystemExit('Could not read from: {}'.format(installer))
+    if is_macos:
+        macos_install(installer, dest=dest, launch=launch)
+    else:
+        linux_install(installer, dest=dest, launch=launch)
+
+
+def script_launch():
+    # To test: python3 -c "import runpy; runpy.run_path('installer.py', run_name='script_launch')"
+    def path(x):
+        return os.path.expandvars(os.path.expanduser(x))
+
+    def to_bool(x):
+        return x.lower() in {'y', 'yes', '1', 'true'}
+
+    type_map = {x: path for x in 'dest installer'.split()}
+    type_map['launch'] = to_bool
+    kwargs = {}
+
+    for arg in sys.argv[1:]:
+        if arg:
+            m = re.match('([a-z_]+)=(.+)', arg)
+            if m is None:
+                raise SystemExit('Unrecognized command line argument: ' + arg)
+            k = m.group(1)
+            if k not in type_map:
+                raise SystemExit('Unrecognized command line argument: ' + arg)
+            kwargs[k] = type_map[k](m.group(2))
+    main(**kwargs)
+
+
+def update_intaller_wrapper():
+    # To run: python3 -c "import runpy; runpy.run_path('installer.py', run_name='update_wrapper')" installer.sh
+    src = open(__file__, 'rb').read().decode('utf-8')
+    wrapper = sys.argv[-1]
+    with open(wrapper, 'r+b') as f:
+        raw = f.read().decode('utf-8')
+        nraw = re.sub(r'^# HEREDOC_START.+^# HEREDOC_END', lambda m: '# HEREDOC_START\n{}\n# HEREDOC_END'.format(src), raw, flags=re.MULTILINE | re.DOTALL)
+        if 'update_intaller_wrapper()' not in nraw:
+            raise SystemExit('regex substitute of HEREDOC failed')
+        f.seek(0), f.truncate()
+        f.write(nraw.encode('utf-8'))
+
+
+if __name__ == '__main__' and from_file:
+    main()
+elif __name__ == 'update_wrapper':
+    update_intaller_wrapper()
+elif __name__ == 'script_launch':
+    script_launch()

docs/installer.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+#
+# installer.sh
+# Copyright (C) 2018 Kovid Goyal <kovid at kovidgoyal.net>
+#
+# Distributed under terms of the GPLv3 license.
+#
+
+python=$(command -v python3)
+if [ -z "$python" ]; then
+    python=$(command -v python2)
+fi
+if [ -z "$python" ]; then
+    python=$(command -v python2.7)
+fi
+if [ -z "$python" ]; then
+    python=$(command -v python)
+fi
+if [ -z "$python" ]; then
+    python=python
+fi
+
+echo Using python executable: $python
+
+$python -c "import sys; script_launch=lambda:sys.exit('Download of installer failed!'); exec(sys.stdin.read()); script_launch()" "$@" <<'INSTALLER_HEREDOC'
+# {{{
+# HEREDOC_START
+# HEREDOC_END
+# }}}
+INSTALLER_HEREDOC

docs/invocation.rst

@@ -0,0 +1,6 @@
+The kitty command line interface
+====================================
+
+.. program:: kitty
+
+.. include:: generated/cli-kitty.rst

docs/key-encoding.rst

@@ -0,0 +1,128 @@
+Key encoding for extended keyboard protocol
+===============================================
+
+See :ref:`extended-key-protocol` for more information and `this table in JSON
+format <https://github.com/kovidgoyal/kitty/blob/master/key_encoding.json>`_.
+
+=====================   ======================
+Name                    Encoded representation
+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``
+=====================   ======================

docs/kittens/clipboard.rst

@@ -0,0 +1,27 @@
+clipboard - copy/paste to the system clipboard
+==================================================
+
+.. highlight:: sh
+
+
+The ``clipboard`` kitten can be used to read or write to the system clipboard
+from the shell. It even works over SSH. Using it is as simple as::
+
+    echo hooray | kitty +kitten clipboard
+
+All text received on :file:`stdin` is copied to the clipboard.
+
+To get text from the clipboard you have to enable reading of the clipboard
+in :opt:`clipboard_control` in :file:`kitty.conf`. Once you do that, you can
+use::
+
+    kitty +kitten clipboard --get-clipboard
+
+
+.. program:: kitty +kitten clipboard
+
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-clipboard.rst

docs/kittens/diff.rst

@@ -0,0 +1,157 @@
+kitty-diff - A fast side-by-side diff tool with syntax highlighting and images
+================================================================================
+
+.. highlight:: sh
+
+Major Features
+-----------------
+
+.. container:: major-features
+
+    * Displays diffs side-by-side in the kitty terminal
+
+    * Does syntax highlighting of the displayed diffs, asynchronously, for maximum
+      speed
+
+    * Displays images as well as text diffs, even over SSH
+
+    * Does recursive directory diffing
+
+
+.. figure:: ../screenshots/diff.png
+   :alt: Screenshot, showing a sample diff
+   :align: center
+   :scale: 100%
+
+   Screenshot, showing a sample diff
+
+.. contents::
+
+
+Installation
+---------------
+
+Simply :ref:`install kitty <quickstart>`.  You also need
+to have either the `git <https://git-scm.com/>`_ program or the ``diff`` program
+installed. Additionally, for syntax highlighting to work,
+`pygments <http://pygments.org/>`_ 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                        :kbd:`q, Ctrl+c, Esc`
+Scroll line up              :kbd:`k, up`
+Scroll line down            :kbd:`j, down`
+Scroll page up              :kbd:`PgUp`
+Scroll page down            :kbd:`PgDn`
+Scroll to top               :kbd:`Home`
+Scroll to bottom            :kbd:`End`
+Scroll to next page         :kbd:`Space, PgDn`
+Scroll to previous page     :kbd:`PgUp`
+Scroll to next change       :kbd:`n`
+Scroll to previous change   :kbd:`p`
+Increase lines of context   :kbd:`+`
+Decrease lines of context   :kbd:`-`
+All lines of context        :kbd:`a`
+Restore default context     :kbd:`=`
+Search forwards             :kbd:`/`
+Search backwards            :kbd:`?`
+Clear search                :kbd:`Esc`
+Scroll to next match        :kbd:`>, .`
+Scroll to previous match    :kbd:`<, ,`
+=========================   ===========================
+
+
+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
+</protocol-extensions>`,  such as the :doc:`kitty graphics protocol
+</graphics-protocol>`, the :ref:`extended keyboard protocol
+<extended-key-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 :)
+
+
+
+Configuration
+------------------------
+
+You can configure the colors used, keyboard shortcuts, the diff implementation,
+the default lines of context, etc.  by creating a :file:`diff.conf` file in
+your :ref:`kitty config folder <confloc>`. See below for the supported
+configuration directives.
+
+
+.. include:: /generated/conf-kitten-diff.rst
+
+
+Command Line Interface
+-------------------------
+
+.. include:: /generated/cli-kitten-diff.rst
+
+
+
+Sample diff.conf
+-----------------
+
+You can download a sample :file:`diff.conf` file with all default settings and
+comments describing each setting by clicking: :download:`sample diff.conf
+</generated/conf/diff.conf>`.

docs/kittens/hints.rst

@@ -0,0 +1,27 @@
+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:`open_url`
+to choose any URL visible on the screen and then open it using your system
+browser.
+
+.. figure:: ../screenshots/hints_mode.png
+    :alt: URL hints mode
+    :align: center
+    :scale: 100%
+
+    URL hints mode
+
+Similarly, you can press :sc:`insert_selected_path` 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, see below.
+
+Command Line Interface
+-------------------------
+
+.. include:: ../generated/cli-kitten-hints.rst

docs/kittens/icat.rst

@@ -0,0 +1,29 @@
+icat - Display images in the terminal
+========================================
+
+The ``icat`` kitten can be used to display arbitrary images in the |kitty|
+terminal. Using it is as simple as::
+
+    kitty +kitten icat image.jpeg
+
+It supports all image types supported by `ImageMagick
+<https://www.imagemagick.org>`_. It even works over SSH. For details, see
+the :doc:`kitty graphics protocol </graphics-protocol>`.
+
+.. note::
+
+    `ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
+    work.
+
+
+.. program:: kitty +kitten icat
+
+
+The ``icat`` kitten has various command line arguments to allow it to be used
+from inside other programs to display images. In particular, :option:`--place`,
+:option:`--detect-support` and :option:`--print-window-size`.
+
+Command Line Interface
+--------------------------
+
+.. include:: /generated/cli-kitten-icat.rst

docs/kittens/panel.rst

@@ -0,0 +1,43 @@
+Draw a GPU accelerated dock panel on your desktop
+====================================================================================================
+
+.. highlight:: sh
+
+
+You can use this kitten to draw a GPU accelerated panel on the edge
+of your screen, that shows the output from an arbitrary terminal program.
+
+It is useful for showing status information or notifications on your desktop
+using terminal programs instead of GUI toolkits.
+
+
+.. figure:: ../screenshots/panel.png
+   :alt: Screenshot, showing a sample panel
+   :align: center
+   :scale: 100%
+
+   Screenshot, showing a sample panel
+
+
+The screenshot above shows a sample panel that displays the current desktop and
+window title as well as miscellaneous system information such as network
+activity, CPU load, date/time, etc.
+
+.. note::
+
+    This kitten currently only works on X11 desktops
+
+Using this kitten is simple, for example::
+
+    kitty +kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s'
+
+This will show ``Hello, world.`` at the top edge of your screen for five
+seconds. Here the terminal program we are running is ``sh`` with a script to
+print out ``Hello, world!``. You can make the terminal program as complex as
+you like, as demonstrated in the screenshot above.
+
+
+Command Line Interface
+-------------------------
+
+.. include:: ../generated/cli-kitten-panel.rst

docs/kittens/unicode-input.rst

@@ -0,0 +1,22 @@
+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.
+
+.. figure:: ../screenshots/unicode.png
+    :alt: A screenshot of the unicode input widget
+    :align: center
+    :scale: 100%
+
+    A screenshot of the unicode input widget
+
+In :guilabel:`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 :guilabel:`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.

docs/performance.rst

@@ -0,0 +1,59 @@
+|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 :ref:`conf-kitty-performance` for details.
+See also the ``sync_to_monitor`` option to further decrease latency at the cost
+of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
+
+You can generate detailed per-function performance data using
+`gperftools <https://github.com/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).
+
+
+.. _perf-cat:
+
+.. note::
+
+    Some people have asked why kitty does not perform better than terminal XXX in
+    the test of sinking large amounts of data, such as catting a large text
+    file. The answer is because this is not a goal for kitty. kitty
+    deliberately throttles input parsing and output rendering to minimize
+    resource usage while still being able to sink output faster than any real
+    world program can produce it. Reducing CPU usage, and hence battery drain
+    while achieving instant response times and smooth scrolling to a human eye
+    is a far more important goal.

docs/protocol-extensions.rst

@@ -0,0 +1,186 @@
+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
+<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences>`_)
+
+To set the underline style::
+
+    <ESC>[4:0m  # this is no underline
+    <ESC>[4:1m  # this is a straight underline
+    <ESC>[4:2m  # this is a double underline
+    <ESC>[4:3m  # this is a curly underline
+    <ESC>[4:4m  # this is a dotted underline (not implemented in kitty)
+    <ESC>[4:5m  # this is a dashed underline (not implemented in kitty)
+    <ESC>[4m    # this is a straight underline (for backwards compat)
+    <ESC>[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)::
+
+    <ESC>[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)::
+
+    <ESC>[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 reliably 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 <https://github.com/neovim/neovim/issues/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::
+
+    <ESC>[?2017h
+
+and to leave *full mode*, use DECRST::
+
+    <ESC>[?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 <https://vt100.net/docs/vt510-rm/DECRQM.html>`_ 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::
+
+    <ESC>_K<type><modifiers><key><ESC>\
+
+Where ``<type>`` 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``.  ``<key>`` is a number
+(encoded in base85) corresponding to the key pressed. The key name to number
+mapping is defined in :doc:`this table <key-encoding>`.
+
+For example::
+
+    <ESC>_KpGp<ESC>\  is  <Ctrl>+<Alt>+x (press)
+    <ESC>_KrP8<ESC>\  is  <Ctrl>+<Alt>+<Shift>+<Super>+PageUp (release)
+
+This encoding means each key event is represented by 8 or 9 printable ascii
+only bytes, for maximum robustness.
+
+
+.. _ext_styles:
+
+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
+<https://vt100.net/docs/vt510-rm/DECCARA.html>`_.  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 <https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545>`_
+and `this FAQ <http://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`_
+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::
+
+    <ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x
+
+
+Saving and restoring the default foreground/background/selection/cursor colors
+---------------------------------------------------------------------------------
+
+It is often useful for a full screen application with its own color themes
+to set the default foreground, background, selection and cursor colors. This
+allows for various performance optimizations when drawing the screen. The
+problem is that if the user previously used the escape codes to change these
+colors herself, then running the full screen application will lose her
+changes even after it exits. To avoid this, kitty introduces a new pair of
+*OSC* escape codes to push and pop the current color values from a stack::
+
+    <ESC>]30001<ESC>\  # push onto stack
+    <ESC>]30101<ESC>\  # pop from stack
+
+These escape codes save/restore the so called *dynamic colors*, default
+background, default foreground, selection background, selection foreground and
+cursor color.

docs/remote-control.rst

@@ -0,0 +1,122 @@
+:tocdepth: 2
+
+Controlling kitty from scripts or the shell
+==============================================
+
+.. highlight:: sh
+
+Tutorial
+----------
+
+|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, :opt:`allow_remote_control` must be enabled in
+:file:`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:`kitty @ send-text --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:`kitty @ focus-window --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:`kitty --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:`kitty @ --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:`kitty --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` by default). This has the added
+advantage that you dont need to use ``allow_remote_control`` to make it work.
+
+
+.. include:: generated/cli-kitty-at.rst

docs/support.html

@@ -0,0 +1,69 @@
+<style>
+.support-button {
+    border-radius: 6px;
+    box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
+    display: inline-block;
+    cursor: pointer;
+    color: rgb(51, 51, 51);
+    font-size: inherit;
+    font-family: Arial;
+    font-weight: bold;
+    padding: 8px 24px;
+    text-decoration: none;
+}
+
+.support-button:hover {
+    transform: scale(1.5);
+}
+
+.support-button {
+    outline: 0;
+}
+.support-button:visited {
+    color: rgb(51, 51, 51);
+    outline: 0;
+}
+
+#support-buttons > div {
+    margin-top: 3ex;
+    text-align: center;
+}
+
+#paypal input[type=submit] {
+    background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100);
+    border: 1px solid rgb(255, 171, 35);
+}
+
+#liberapay a {
+    background: linear-gradient(rgb(92, 184, 92) 5%, rgb(62, 142, 62) 100%) rgb(92, 184, 92);
+    border: 1px solid rgb(62, 142, 62);
+    color: rgb(51, 51, 51);
+}
+
+#patreon a {
+    background: linear-gradient(rgb(11, 100, 163) 5%, rgb(5, 45, 73) 100%) rgb(11, 100, 163);
+    border: 1px solid rgb(5, 45, 73);
+    color: #eee;
+}
+</style>
+
+<div id="support-buttons">
+<div id="patreon">
+    <a class="support-button" href="https://www.patreon.com/bePatron?u=917933">Patronage via Patreon</a>
+</div>
+
+<div>
+    <form id="paypal" action="https://www.paypal.com/cgi-bin/webscr" method="post" title="Contribute to support calibre development">
+        <input type="hidden" name="cmd" value="_s-xclick" />
+        <input type="hidden" name="hosted_button_id" value="FEELASHWEL5HS" />
+        <input class="support-button" type="submit" name="submit" value="One time support via PayPal" />
+        <img alt="" border="0" src="https://www.paypalobjects.com/en_GB/i/scr/pixel.gif" width="1" height="1" />
+    </form>
+</div>
+
+<div id="liberapay">
+    <a class="support-button" href="https://liberapay.com/kovidgoyal/donate">Patronage via Liberapay</a>
+</div>
+
+</div>
+

docs/support.rst

@@ -0,0 +1,23 @@
+Support kitty development
+===========================
+
+My goal with |kitty| is to move the stagnant terminal ecosystem forward.  To that
+end kitty has many foundational features, such as: :doc:`image support
+<graphics-protocol>`, :doc:`superlative performance <performance>`,
+:doc:`various enhancements to the terminal protocol <protocol-extensions>`,
+etc. These features allow the development of rich terminal applications, such
+as :doc:`Side-by-side diff <kittens/diff>` and :doc:`Unicode input
+<kittens/unicode-input>`.
+
+If you wish to support this mission and see the terminal ecosystem evolve,
+consider donating so that I can devote more time to |kitty| development.
+I have personally written `almost all kitty code
+<https://github.com/kovidgoyal/kitty/graphs/contributors>`_.
+
+You can choose to make either a one-time payment via PayPal or become a
+*patron* of kitty development via the Patreon or Liberapay services
+below:
+
+
+.. raw:: html
+    :file: support.html

gen-wcwidth.py

@@ -15,6 +15,12 @@ from urllib.request import urlopen
 
 os.chdir(os.path.dirname(os.path.abspath(__file__)))
 
+non_characters = frozenset(range(0xfffe, 0x10ffff, 0x10000))
+non_characters |= frozenset(range(0xffff, 0x10ffff + 1, 0x10000))
+non_characters |= frozenset(range(0xfdd0, 0xfdf0))
+if len(non_characters) != 66:
+    raise SystemExit('non_characters table incorrect')
+
 
 def get_data(fname, folder='UCD'):
     url = f'https://www.unicode.org/Public/{folder}/latest/{fname}'
@@ -189,11 +195,12 @@ def gen_emoji():
         p('\treturn false;\n}')
 
 
-def category_test(name, p, classes, comment, static=False):
+def category_test(name, p, classes, comment, static=False, extra_chars=frozenset()):
     static = 'static inline ' if static else ''
     chars = set()
     for c in classes:
         chars |= class_maps[c]
+    chars |= extra_chars
     p(f'{static}bool\n{name}(char_type code) {{')
     p(f'\t// {comment} ({len(chars)} codepoints)' + ' {{' '{')
     p('\tswitch(code) {')
@@ -245,7 +252,7 @@ def gen_ucd():
     with create_header('kitty/unicode-data.c') as p:
         p('#include "unicode-data.h"')
         category_test('is_combining_char', p, {c for c in class_maps if c.startswith('M')}, 'M category (marks)')
-        category_test('is_ignored_char', p, 'Cc Cf Cs'.split(), 'Control characters (Cc Cf Cs)')
+        category_test('is_ignored_char', p, 'Cc Cf Cs'.split(), 'Control characters and non-characters', extra_chars=non_characters)
         category_test('is_word_char', p, {c for c in class_maps if c[0] in 'LN'}, 'L and N categories')
         category_test('is_CZ_category', p, cz, 'C and Z categories')
         category_test('is_P_category', p, {c for c in class_maps if c[0] == 'P'}, 'P category (punctuation)')
@@ -258,7 +265,7 @@ def gen_ucd():
         p('combining_type mark_for_codepoint(char_type c) {')
         rmap = codepoint_to_mark_map(p, mark_map)
         p('}\n')
-        if rmap[0xfe0e] != 1275:
+        if rmap[0xfe0e] != 1280:
             raise ValueError('The mark for 0xfe0e has changed, you have to update VS15 to {} and VS16 to {} in unicode-data.h'.format(
                 rmap[0xfe0e], rmap[0xfe0f]
             ))
@@ -393,7 +400,7 @@ def gen_wcwidth():
         add(p, 'East Asian double width', doublewidth, 2)
         add(p, 'Emoji Presentation', emoji_categories['Emoji_Presentation'], 2)
 
-        add(p, 'Not assigned in the unicode character database', not_assigned, -1)
+        add(p, 'Not assigned in the unicode character database', not_assigned, -4)
 
         p('\t\tdefault: return 1;')
         p('\t}')

glad/generate.py

@@ -43,6 +43,8 @@ def export():
     switch = ['glad_debug_{0} = glad_{0}'.format(f) for f in functions]
     c = c.replace('<glad/glad.h>', '"gl-wrapper.h"', 1)
     c = '#pragma GCC diagnostic ignored "-Wpedantic"\n' + c
+    # See https://github.com/kovidgoyal/kitty/issues/654
+    c = c.replace('strncpy(local_str, gl_str_tmp, len+1)', 'memcpy(local_str, gl_str_tmp, len+1)', 1)
     c += '''
 int
 init_glad(GLADloadproc load, int debug) {

glfw/backend_utils.h

@@ -0,0 +1,66 @@
+//========================================================================
+// GLFW 3.3 Wayland - www.glfw.org
+//------------------------------------------------------------------------
+// Copyright (c) 2014 Jonas Ådahl <jadahl@gmail.com>
+//
+// This software is provided 'as-is', without any express or implied
+// warranty. In no event will the authors be held liable for any damages
+// arising from the use of this software.
+//
+// Permission is granted to anyone to use this software for any purpose,
+// including commercial applications, and to alter it and redistribute it
+// freely, subject to the following restrictions:
+//
+// 1. The origin of this software must not be misrepresented; you must not
+//    claim that you wrote the original software. If you use this software
+//    in a product, an acknowledgment in the product documentation would
+//    be appreciated but is not required.
+//
+// 2. Altered source versions must be plainly marked as such, and must not
+//    be misrepresented as being the original software.
+//
+// 3. This notice may not be removed or altered from any source
+//    distribution.
+//
+//========================================================================
+
+#pragma once
+#include <unistd.h>
+#include <poll.h>
+#include <errno.h>
+
+#ifdef __NetBSD__
+#define ppoll pollts
+#endif
+
+static inline void
+drainFd(int fd) {
+    static char drain_buf[64];
+    while(read(fd, drain_buf, sizeof(drain_buf)) < 0 && errno == EINTR);
+}
+
+
+static inline int
+pollWithTimeout(struct pollfd *fds, nfds_t nfds, double timeout) {
+    const long seconds = (long) timeout;
+    const long nanoseconds = (long) ((timeout - seconds) * 1e9);
+    struct timespec tv = { seconds, nanoseconds };
+    return ppoll(fds, nfds, &tv, NULL);
+}
+
+static inline void
+initPollData(struct pollfd *fds, int wakeup_fd, int display_fd) {
+    fds[0].fd = wakeup_fd; fds[1].fd = display_fd;
+    fds[0].events = POLLIN; fds[1].events = POLLIN;
+}
+
+static inline void
+closeFds(int *fds, size_t count) {
+    while(count--) {
+        if (*fds > 0) {
+            close(*fds);
+            *fds = -1;
+        }
+        fds++;
+    }
+}

glfw/cocoa_init.m

@@ -69,7 +69,6 @@ static void changeToResourcesDirectory(void)
 static void createKeyTables(void)
 {
     int scancode;
-    _glfw.ns.debug_keyboard = getenv("GLFW_DEBUG_KEYBOARD") != NULL;
 
     memset(_glfw.ns.keycodes, -1, sizeof(_glfw.ns.keycodes));
     memset(_glfw.ns.scancodes, -1, sizeof(_glfw.ns.scancodes));

glfw/cocoa_platform.h

@@ -38,6 +38,7 @@ typedef void* id;
 
 typedef VkFlags VkMacOSSurfaceCreateFlagsMVK;
 typedef int (* GLFWcocoatextinputfilterfun)(int,int,int);
+typedef int (* GLFWapplicationshouldhandlereopenfun)(int);
 
 typedef struct VkMacOSSurfaceCreateInfoMVK
 {
@@ -120,7 +121,6 @@ typedef struct _GLFWlibraryNS
 
     char                keyName[64];
     char                text[256];
-    GLFWbool            debug_keyboard;
     short int           keycodes[256];
     short int           scancodes[GLFW_KEY_LAST + 1];
     char*               clipboardString;

glfw/cocoa_window.m

@@ -209,7 +209,7 @@ static int translateFlags(NSUInteger flags)
     return mods;
 }
 
-#define debug_key(...) if (_glfw.ns.debug_keyboard) NSLog(__VA_ARGS__)
+#define debug_key(...) if (_glfw.hints.init.debugKeyboard) NSLog(__VA_ARGS__)
 
 static inline const char*
 format_mods(int mods) {
@@ -482,6 +482,15 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     return NSTerminateCancel;
 }
 
+static GLFWapplicationshouldhandlereopenfun handle_reopen_callback = NULL;
+
+- (BOOL)applicationShouldHandleReopen:(NSApplication *)sender hasVisibleWindows:(BOOL)flag
+{
+    if (!handle_reopen_callback) return YES;
+    if (handle_reopen_callback(flag)) return YES;
+    return NO;
+}
+
 - (void)applicationDidChangeScreenParameters:(NSNotification *) notification
 {
     _GLFWwindow* window;
@@ -1877,44 +1886,44 @@ int _glfwPlatformGetKeyScancode(int key)
 
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
-                              int xhot, int yhot)
+                              int xhot, int yhot, int count)
 {
     NSImage* native;
     NSBitmapImageRep* rep;
 
     if (!initializeAppKit())
         return GLFW_FALSE;
-
-    rep = [[NSBitmapImageRep alloc]
-        initWithBitmapDataPlanes:NULL
-                      pixelsWide:image->width
-                      pixelsHigh:image->height
-                   bitsPerSample:8
-                 samplesPerPixel:4
-                        hasAlpha:YES
-                        isPlanar:NO
-                  colorSpaceName:NSCalibratedRGBColorSpace
-                    bitmapFormat:NSAlphaNonpremultipliedBitmapFormat
-                     bytesPerRow:image->width * 4
-                    bitsPerPixel:32];
-
-    if (rep == nil)
+    native = [[NSImage alloc] initWithSize:NSMakeSize(image->width, image->height)];
+    if (native == nil)
         return GLFW_FALSE;
 
-    memcpy([rep bitmapData], image->pixels, image->width * image->height * 4);
+    for (int i = 0; i < count; i++) {
+        const GLFWimage *src = image + i;
+        rep = [[NSBitmapImageRep alloc]
+            initWithBitmapDataPlanes:NULL
+                        pixelsWide:src->width
+                        pixelsHigh:src->height
+                    bitsPerSample:8
+                    samplesPerPixel:4
+                            hasAlpha:YES
+                            isPlanar:NO
+                    colorSpaceName:NSCalibratedRGBColorSpace
+                        bitmapFormat:NSAlphaNonpremultipliedBitmapFormat
+                        bytesPerRow:src->width * 4
+                        bitsPerPixel:32];
+        if (rep == nil)
+            return GLFW_FALSE;
 
-    native = [[NSImage alloc] initWithSize:NSMakeSize(image->width, image->height)];
-    [native addRepresentation:rep];
+        memcpy([rep bitmapData], src->pixels, src->width * src->height * 4);
+        [native addRepresentation:rep];
+        [rep release];
+    }
 
     cursor->ns.object = [[NSCursor alloc] initWithImage:native
                                                 hotSpot:NSMakePoint(xhot, yhot)];
-
     [native release];
-    [rep release];
-
     if (cursor->ns.object == nil)
         return GLFW_FALSE;
-
     return GLFW_TRUE;
 }
 
@@ -2088,3 +2097,102 @@ GLFWAPI GLFWcocoatextinputfilterfun glfwSetCocoaTextInputFilter(GLFWwindow *hand
     window->ns.textInputFilterCallback = callback;
     return previous;
 }
+
+GLFWAPI GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback) {
+    GLFWapplicationshouldhandlereopenfun previous = handle_reopen_callback;
+    handle_reopen_callback = callback;
+    return previous;
+}
+
+GLFWAPI void glfwGetCocoaKeyEquivalent(int glfw_key, int glfw_mods, unsigned short *cocoa_key, int *cocoa_mods) {
+    *cocoa_key = 0;
+    *cocoa_mods = 0;
+
+    if (glfw_mods & GLFW_MOD_SHIFT)
+        *cocoa_mods |= NSEventModifierFlagShift;
+    if (glfw_mods & GLFW_MOD_CONTROL)
+        *cocoa_mods |= NSEventModifierFlagControl;
+    if (glfw_mods & GLFW_MOD_ALT)
+        *cocoa_mods |= NSEventModifierFlagOption;
+    if (glfw_mods & GLFW_MOD_SUPER)
+        *cocoa_mods |= NSEventModifierFlagCommand;
+    if (glfw_mods & GLFW_MOD_CAPS_LOCK)
+        *cocoa_mods |= NSEventModifierFlagCapsLock;
+
+    switch(glfw_key) {
+#define K(ch, name) case GLFW_KEY_##name: *cocoa_key = ch; break;
+        K('a', A);
+        K('b', B);
+        K('c', C);
+        K('d', D);
+        K('e', E);
+        K('f', F);
+        K('g', G);
+        K('h', H);
+        K('i', I);
+        K('j', J);
+        K('k', K);
+        K('l', L);
+        K('m', M);
+        K('n', N);
+        K('o', O);
+        K('p', P);
+        K('q', Q);
+        K('r', R);
+        K('s', S);
+        K('t', T);
+        K('u', U);
+        K('v', V);
+        K('w', W);
+        K('x', X);
+        K('y', Y);
+        K('z', Z);
+        K('0', 0);
+        K('1', 1);
+        K('2', 2);
+        K('3', 3);
+        K('5', 5);
+        K('6', 6);
+        K('7', 7);
+        K('8', 8);
+        K('9', 9);
+        K('\'', APOSTROPHE);
+        K(',', COMMA);
+        K('.', PERIOD);
+        K('/', SLASH);
+        K('-', MINUS);
+        K('=', EQUAL);
+        K(';', SEMICOLON);
+        K('[', LEFT_BRACKET);
+        K(']', RIGHT_BRACKET);
+        K('`', GRAVE_ACCENT);
+        K('\\', BACKSLASH);
+
+        K(0x35, ESCAPE);
+        K('\r', ENTER);
+        K('\t', TAB);
+        K(NSBackspaceCharacter, BACKSPACE);
+        K(NSInsertFunctionKey, INSERT);
+        K(NSDeleteCharacter, DELETE);
+        K(NSLeftArrowFunctionKey, LEFT);
+        K(NSRightArrowFunctionKey, RIGHT);
+        K(NSUpArrowFunctionKey, UP);
+        K(NSDownArrowFunctionKey, DOWN);
+        K(NSPageUpFunctionKey, PAGE_UP);
+        K(NSPageDownFunctionKey, PAGE_DOWN);
+        K(NSHomeFunctionKey, HOME);
+        K(NSEndFunctionKey, END);
+        K(NSPrintFunctionKey, PRINT_SCREEN);
+        case GLFW_KEY_F1 ... GLFW_KEY_F24:
+            *cocoa_key = NSF1FunctionKey + (glfw_key - GLFW_KEY_F1); break;
+        case GLFW_KEY_KP_0 ... GLFW_KEY_KP_9:
+            *cocoa_key = NSEventModifierFlagNumericPad | (0x52 + (glfw_key - GLFW_KEY_KP_0)); break;
+        K((unichar)(0x41|NSEventModifierFlagNumericPad), KP_DECIMAL);
+        K((unichar)(0x43|NSEventModifierFlagNumericPad), KP_MULTIPLY);
+        K((unichar)(0x45|NSEventModifierFlagNumericPad), KP_ADD);
+        K((unichar)(0x4B|NSEventModifierFlagNumericPad), KP_DIVIDE);
+        K((unichar)(0x4E|NSEventModifierFlagNumericPad), KP_SUBTRACT);
+        K((unichar)(0x51|NSEventModifierFlagNumericPad), KP_EQUAL);
+#undef K
+    }
+}

glfw/glfw.py

@@ -43,7 +43,12 @@ def init_env(env, pkg_config, at_least_version, module='x11'):
     else:
         ans.ldpaths.extend('-lrt -lm -ldl'.split())
     sinfo = json.load(open(os.path.join(base, 'source-info.json')))
-    ans.sources = sinfo['common']['sources'] + sinfo[module]['sources']
+    module_sources = list(sinfo[module]['sources'])
+    if module in ('x11', 'wayland'):
+        remove = 'linux_joystick.c' if is_bsd else 'null_joystick.c'
+        module_sources.remove(remove)
+
+    ans.sources = sinfo['common']['sources'] + module_sources
     ans.all_headers = [x for x in os.listdir(base) if x.endswith('.h')]
 
     if module in ('x11', 'wayland'):
@@ -62,6 +67,8 @@ def init_env(env, pkg_config, at_least_version, module='x11'):
         at_least_version('wayland-protocols', *sinfo['wayland_protocols'])
         ans.wayland_packagedir = os.path.abspath(pkg_config('wayland-protocols', '--variable=pkgdatadir')[0])
         ans.wayland_scanner = os.path.abspath(pkg_config('wayland-scanner', '--variable=wayland_scanner')[0])
+        scanner_version = tuple(map(int, pkg_config('wayland-scanner', '--modversion')[0].strip().split('.')))
+        ans.wayland_scanner_code = 'private-code' if scanner_version >= (1, 14, 91) else 'code'
         ans.wayland_protocols = tuple(sinfo[module]['protocols'])
         for p in ans.wayland_protocols:
             ans.sources.append(wayland_protocol_file_name(p))
@@ -82,7 +89,7 @@ def build_wayland_protocols(env, run_tool, emphasis, newer, dest_dir):
             dest = wayland_protocol_file_name(src, ext)
             dest = os.path.join(dest_dir, dest)
             if newer(dest, src):
-                q = 'client-header' if ext == 'h' else 'code'
+                q = 'client-header' if ext == 'h' else env.wayland_scanner_code
                 run_tool([env.wayland_scanner, q, src, dest],
                          desc='Generating {} ...'.format(emphasis(os.path.basename(dest))))
 
@@ -93,13 +100,13 @@ def collect_source_information():
 
     def extract_sources(group, start_pos=0):
         for which in 'HEADERS SOURCES'.split():
-            yield which.lower(), filter(
+            yield which.lower(), list(filter(
                 lambda x: x[0] not in '"$',
                 re.search(
                     r'{0}_{1}\s+([^)]+?)[)]'.format(group, which),
                     raw[start_pos:]
                 ).group(1).strip().split()
-            )
+            ))
 
     wayland_protocols = re.search(r'WaylandProtocols\s+(\S+)\s+', mraw).group(1)
     wayland_protocols = list(map(int, wayland_protocols.split('.')))
@@ -107,13 +114,13 @@ def collect_source_information():
         'common': dict(extract_sources('common')),
         'wayland_protocols': wayland_protocols,
     }
-    joystick = 'null' if is_bsd else 'linux'
     for group in 'cocoa win32 x11 wayland osmesa'.split():
         m = re.search('_GLFW_' + group.upper(), raw)
         ans[group] = dict(extract_sources('glfw', m.start()))
         if group in ('x11', 'wayland'):
-            ans[group]['headers'].append('{}_joystick.h'.format(joystick))
-            ans[group]['sources'].append('{}_joystick.c'.format(joystick))
+            for joystick in ('linux', 'null'):
+                ans[group]['headers'].append('{}_joystick.h'.format(joystick))
+                ans[group]['sources'].append('{}_joystick.c'.format(joystick))
         if group == 'wayland':
             ans[group]['protocols'] = p = []
             for m in re.finditer(r'WAYLAND_PROTOCOLS_PKGDATADIR\}/(.+?)"?$', raw, flags=re.M):
@@ -197,10 +204,13 @@ def generate_wrappers(glfw_header, glfw_native_header):
     void* glfwGetCocoaWindow(GLFWwindow* window)
     uint32_t glfwGetCocoaMonitor(GLFWmonitor* monitor)
     GLFWcocoatextinputfilterfun glfwSetCocoaTextInputFilter(GLFWwindow* window, GLFWcocoatextinputfilterfun callback)
+    GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback)
+    void glfwGetCocoaKeyEquivalent(int glfw_key, int glfw_mods, void* cocoa_key, void* cocoa_mods)
     void* glfwGetX11Display(void)
     int32_t glfwGetX11Window(GLFWwindow* window)
     void glfwSetX11SelectionString(const char* string)
     const char* glfwGetX11SelectionString(void)
+    int glfwGetXKBScancode(const char* key_name, int case_sensitive)
 '''.splitlines():
         if line:
             functions.append(Function(line.strip(), check_fail=False))
@@ -214,6 +224,8 @@ def generate_wrappers(glfw_header, glfw_native_header):
 #include <stddef.h>
 #include <stdint.h>
 typedef int (* GLFWcocoatextinputfilterfun)(int,int,unsigned int);
+typedef int (* GLFWapplicationshouldhandlereopenfun)(int);
+
 {}
 
 {}
@@ -224,9 +236,9 @@ const char* load_glfw(const char* path);
         f.write(header)
 
     code = '''
-#include <dlfcn.h>
 #include "data-types.h"
 #include "glfw-wrapper.h"
+#include <dlfcn.h>
 
 static void* handle = NULL;
 

glfw/glfw3.h

@@ -819,6 +819,12 @@ extern "C" {
  *  Mouse cursor hover [window attribute](@ref GLFW_HOVERED_attrib).
  */
 #define GLFW_HOVERED                0x0002000B
+/*! @brief Input focus on calling show window hint and attribute
+ *
+ *  Input focus [window hint](@ref GLFW_FOCUS_ON_SHOW_hint) or
+ *  [window attribute](@ref GLFW_FOCUS_ON_SHOW_attrib).
+ */
+#define GLFW_FOCUS_ON_SHOW          0x0002000C
 
 /*! @brief Framebuffer bit depth hint.
  *
@@ -1051,6 +1057,7 @@ extern "C" {
 /*! @addtogroup init
  *  @{ */
 #define GLFW_JOYSTICK_HAT_BUTTONS   0x00050001
+#define GLFW_DEBUG_KEYBOARD         0x00050002
 
 #define GLFW_COCOA_CHDIR_RESOURCES  0x00051001
 #define GLFW_COCOA_MENUBAR          0x00051002
@@ -3057,6 +3064,11 @@ GLFWAPI void glfwMaximizeWindow(GLFWwindow* window);
  *  hidden.  If the window is already visible or is in full screen mode, this
  *  function does nothing.
  *
+ *  By default, windowed mode windows are focused when shown
+ *  Set the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint
+ *  to change this behavior for all newly created windows, or change the
+ *  behavior for an existing window with @ref glfwSetWindowAttrib.
+ *
  *  @param[in] window The window to make visible.
  *
  *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
@@ -3104,6 +3116,10 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window);
  *  initially created.  Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
  *  disable this behavior.
  *
+ *  Also by default, windowed mode windows are focused when shown
+ *  with @ref glfwShowWindow. Set the
+ *  [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) to disable this behavior.
+ *
  *  __Do not use this function__ to steal focus from other applications unless
  *  you are certain that is what the user wants.  Focus stealing can be
  *  extremely disruptive.
@@ -3301,8 +3317,9 @@ GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib);
  *
  *  The supported attributes are [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
  *  [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib),
- *  [GLFW_FLOATING](@ref GLFW_FLOATING_attrib) and
- *  [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib).
+ *  [GLFW_FLOATING](@ref GLFW_FLOATING_attrib),
+ *  [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) and
+ *  [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib).
  *
  *  Some of these attributes are ignored for full screen windows.  The new
  *  value will take effect if the window is later made windowed.
@@ -4106,6 +4123,7 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
  *  @param[in] image The desired cursor image.
  *  @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot.
  *  @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot.
+ *  @param[in] count The number of images. Used on Cocoa for retina cursors. The first image should be the 1:1 scale image.
  *  @return The handle of the created cursor, or `NULL` if an
  *  [error](@ref error_handling) occurred.
  *
@@ -4121,11 +4139,11 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
  *  @sa @ref glfwDestroyCursor
  *  @sa @ref glfwCreateStandardCursor
  *
- *  @since Added in version 3.1.
+ *  @since Added in version 3.1. Changed in 4.0 to add the count parameter.
  *
  *  @ingroup input
  */
-GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot);
+GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot, int count);
 
 /*! @brief Creates a cursor with a standard shape.
  *

glfw/init.c

@@ -51,6 +51,7 @@ static GLFWerrorfun _glfwErrorCallback;
 static _GLFWinitconfig _glfwInitHints =
 {
     GLFW_TRUE,      // hat buttons
+    GLFW_FALSE,     // debug keyboard
     {
         GLFW_TRUE,  // macOS menu bar
         GLFW_TRUE   // macOS bundle chdir
@@ -255,6 +256,9 @@ GLFWAPI void glfwInitHint(int hint, int value)
         case GLFW_JOYSTICK_HAT_BUTTONS:
             _glfwInitHints.hatButtons = value;
             return;
+        case GLFW_DEBUG_KEYBOARD:
+            _glfwInitHints.debugKeyboard = value;
+            return;
         case GLFW_COCOA_CHDIR_RESOURCES:
             _glfwInitHints.ns.chdir = value;
             return;
@@ -311,4 +315,3 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun)
     _GLFW_SWAP_POINTERS(_glfwErrorCallback, cbfun);
     return cbfun;
 }
-

glfw/input.c

@@ -799,11 +799,12 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* handle, double xpos, double ypos)
     }
 }
 
-GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
+GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot, int count)
 {
     _GLFWcursor* cursor;
 
     assert(image != NULL);
+    assert(count > 0);
 
     _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
 
@@ -811,7 +812,7 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
     cursor->next = _glfw.cursorListHead;
     _glfw.cursorListHead = cursor;
 
-    if (!_glfwPlatformCreateCursor(cursor, image, xhot, yhot))
+    if (!_glfwPlatformCreateCursor(cursor, image, xhot, yhot, count))
     {
         glfwDestroyCursor((GLFWcursor*) cursor);
         return NULL;

glfw/internal.h

@@ -242,6 +242,7 @@ struct _GLFWerror
 struct _GLFWinitconfig
 {
     GLFWbool      hatButtons;
+    GLFWbool      debugKeyboard;
     struct {
         GLFWbool  menubar;
         GLFWbool  chdir;
@@ -267,6 +268,7 @@ struct _GLFWwndconfig
     GLFWbool      floating;
     GLFWbool      maximized;
     GLFWbool      centerCursor;
+    GLFWbool      focusOnShow;
     struct {
         GLFWbool  retina;
         char      frameName[256];
@@ -372,6 +374,7 @@ struct _GLFWwindow
     GLFWbool            decorated;
     GLFWbool            autoIconify;
     GLFWbool            floating;
+    GLFWbool            focusOnShow;
     GLFWbool            shouldClose;
     void*               userPointer;
     GLFWvidmode         videoMode;
@@ -597,7 +600,7 @@ void _glfwPlatformGetCursorPos(_GLFWwindow* window, double* xpos, double* ypos);
 void _glfwPlatformSetCursorPos(_GLFWwindow* window, double xpos, double ypos);
 void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode);
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
-                              const GLFWimage* image, int xhot, int yhot);
+                              const GLFWimage* image, int xhot, int yhot, int count);
 int _glfwPlatformCreateStandardCursor(_GLFWcursor* cursor, int shape);
 void _glfwPlatformDestroyCursor(_GLFWcursor* cursor);
 void _glfwPlatformSetCursor(_GLFWwindow* window, _GLFWcursor* cursor);

glfw/null_window.c

@@ -267,7 +267,7 @@ void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode)
 
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
-                              int xhot, int yhot)
+                              int xhot, int yhot, int count)
 {
     return GLFW_TRUE;
 }

glfw/source-info.json

@@ -1,132 +1,138 @@
 {
   "cocoa": {
     "headers": [
-      "cocoa_platform.h", 
-      "cocoa_joystick.h", 
-      "posix_thread.h", 
-      "nsgl_context.h", 
-      "egl_context.h", 
+      "cocoa_platform.h",
+      "cocoa_joystick.h",
+      "posix_thread.h",
+      "nsgl_context.h",
+      "egl_context.h",
       "osmesa_context.h"
-    ], 
+    ],
     "sources": [
-      "cocoa_init.m", 
-      "cocoa_joystick.m", 
-      "cocoa_monitor.m", 
-      "cocoa_window.m", 
-      "cocoa_time.c", 
-      "posix_thread.c", 
-      "nsgl_context.m", 
-      "egl_context.c", 
+      "cocoa_init.m",
+      "cocoa_joystick.m",
+      "cocoa_monitor.m",
+      "cocoa_window.m",
+      "cocoa_time.c",
+      "posix_thread.c",
+      "nsgl_context.m",
+      "egl_context.c",
       "osmesa_context.c"
     ]
-  }, 
+  },
   "common": {
     "headers": [
-      "internal.h", 
+      "internal.h",
       "mappings.h"
-    ], 
+    ],
     "sources": [
-      "context.c", 
-      "init.c", 
-      "input.c", 
-      "monitor.c", 
-      "vulkan.c", 
+      "context.c",
+      "init.c",
+      "input.c",
+      "monitor.c",
+      "vulkan.c",
       "window.c"
     ]
-  }, 
+  },
   "osmesa": {
     "headers": [
-      "null_platform.h", 
-      "null_joystick.h", 
-      "posix_time.h", 
-      "posix_thread.h", 
+      "null_platform.h",
+      "null_joystick.h",
+      "posix_time.h",
+      "posix_thread.h",
       "osmesa_context.h"
-    ], 
+    ],
     "sources": [
-      "null_init.c", 
-      "null_monitor.c", 
-      "null_window.c", 
-      "null_joystick.c", 
-      "posix_time.c", 
-      "posix_thread.c", 
+      "null_init.c",
+      "null_monitor.c",
+      "null_window.c",
+      "null_joystick.c",
+      "posix_time.c",
+      "posix_thread.c",
       "osmesa_context.c"
     ]
-  }, 
+  },
   "wayland": {
     "headers": [
-      "wl_platform.h", 
-      "posix_time.h", 
-      "posix_thread.h", 
-      "xkb_glfw.h", 
-      "egl_context.h", 
-      "osmesa_context.h", 
-      "linux_joystick.h"
-    ], 
+      "wl_platform.h",
+      "posix_time.h",
+      "posix_thread.h",
+      "xkb_glfw.h",
+      "backend_utils.h",
+      "egl_context.h",
+      "osmesa_context.h",
+      "linux_joystick.h",
+      "null_joystick.h"
+    ],
     "protocols": [
-      "stable/xdg-shell/xdg-shell.xml", 
-      "stable/viewporter/viewporter.xml", 
-      "unstable/relative-pointer/relative-pointer-unstable-v1.xml", 
-      "unstable/pointer-constraints/pointer-constraints-unstable-v1.xml", 
+      "stable/xdg-shell/xdg-shell.xml",
+      "stable/viewporter/viewporter.xml",
+      "unstable/relative-pointer/relative-pointer-unstable-v1.xml",
+      "unstable/pointer-constraints/pointer-constraints-unstable-v1.xml",
       "unstable/idle-inhibit/idle-inhibit-unstable-v1.xml"
-    ], 
+    ],
     "sources": [
-      "wl_init.c", 
-      "wl_monitor.c", 
-      "wl_window.c", 
-      "posix_time.c", 
-      "posix_thread.c", 
-      "xkb_glfw.c", 
-      "egl_context.c", 
-      "osmesa_context.c", 
-      "linux_joystick.c"
+      "wl_init.c",
+      "wl_monitor.c",
+      "wl_window.c",
+      "posix_time.c",
+      "posix_thread.c",
+      "xkb_glfw.c",
+      "egl_context.c",
+      "osmesa_context.c",
+      "linux_joystick.c",
+      "null_joystick.c"
     ]
-  }, 
+  },
   "wayland_protocols": [
-    1, 
+    1,
     12
-  ], 
+  ],
   "win32": {
     "headers": [
-      "win32_platform.h", 
-      "win32_joystick.h", 
-      "wgl_context.h", 
-      "egl_context.h", 
+      "win32_platform.h",
+      "win32_joystick.h",
+      "wgl_context.h",
+      "egl_context.h",
       "osmesa_context.h"
-    ], 
+    ],
     "sources": [
-      "win32_init.c", 
-      "win32_joystick.c", 
-      "win32_monitor.c", 
-      "win32_time.c", 
-      "win32_thread.c", 
-      "win32_window.c", 
-      "wgl_context.c", 
-      "egl_context.c", 
+      "win32_init.c",
+      "win32_joystick.c",
+      "win32_monitor.c",
+      "win32_time.c",
+      "win32_thread.c",
+      "win32_window.c",
+      "wgl_context.c",
+      "egl_context.c",
       "osmesa_context.c"
     ]
-  }, 
+  },
   "x11": {
     "headers": [
-      "x11_platform.h", 
-      "xkb_glfw.h", 
-      "posix_time.h", 
-      "posix_thread.h", 
-      "glx_context.h", 
-      "egl_context.h", 
-      "osmesa_context.h", 
-      "linux_joystick.h"
-    ], 
+      "x11_platform.h",
+      "xkb_glfw.h",
+      "backend_utils.h",
+      "posix_time.h",
+      "posix_thread.h",
+      "glx_context.h",
+      "egl_context.h",
+      "osmesa_context.h",
+      "linux_joystick.h",
+      "null_joystick.h"
+    ],
     "sources": [
-      "x11_init.c", 
-      "x11_monitor.c", 
-      "x11_window.c", 
-      "xkb_glfw.c", 
-      "posix_time.c", 
-      "posix_thread.c", 
-      "glx_context.c", 
-      "egl_context.c", 
-      "osmesa_context.c", 
-      "linux_joystick.c"
+      "x11_init.c",
+      "x11_monitor.c",
+      "x11_window.c",
+      "xkb_glfw.c",
+      "posix_time.c",
+      "posix_thread.c",
+      "glx_context.c",
+      "egl_context.c",
+      "osmesa_context.c",
+      "linux_joystick.c",
+      "null_joystick.c"
     ]
   }
 }

glfw/win32_window.c

@@ -1839,7 +1839,7 @@ int _glfwPlatformGetKeyScancode(int key)
 
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
-                              int xhot, int yhot)
+                              int xhot, int yhot, int count)
 {
     cursor->win32.handle = (HCURSOR) createIcon(image, xhot, yhot, GLFW_FALSE);
     if (!cursor->win32.handle)

glfw/window.c

@@ -201,6 +201,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height,
     window->decorated   = wndconfig.decorated;
     window->autoIconify = wndconfig.autoIconify;
     window->floating    = wndconfig.floating;
+    window->focusOnShow = wndconfig.focusOnShow;
     window->cursorMode  = GLFW_CURSOR_NORMAL;
 
     window->minwidth    = GLFW_DONT_CARE;
@@ -267,6 +268,7 @@ void glfwDefaultWindowHints(void)
     _glfw.hints.window.focused      = GLFW_TRUE;
     _glfw.hints.window.autoIconify  = GLFW_TRUE;
     _glfw.hints.window.centerCursor = GLFW_TRUE;
+    _glfw.hints.window.focusOnShow  = GLFW_TRUE;
 
     // The default is 24 bits of color, 24 bits of depth and 8 bits of stencil,
     // double buffered
@@ -370,6 +372,9 @@ GLFWAPI void glfwWindowHint(int hint, int value)
         case GLFW_CENTER_CURSOR:
             _glfw.hints.window.centerCursor = value ? GLFW_TRUE : GLFW_FALSE;
             return;
+        case GLFW_FOCUS_ON_SHOW:
+            _glfw.hints.window.focusOnShow = value ? GLFW_TRUE : GLFW_FALSE;
+            return;
         case GLFW_CLIENT_API:
             _glfw.hints.context.client = value;
             return;
@@ -755,7 +760,9 @@ GLFWAPI void glfwShowWindow(GLFWwindow* handle)
         return;
 
     _glfwPlatformShowWindow(window);
-    _glfwPlatformFocusWindow(window);
+
+    if (window->focusOnShow)
+        _glfwPlatformFocusWindow(window);
 }
 
 GLFWAPI void glfwRequestWindowAttention(GLFWwindow* handle)
@@ -820,6 +827,8 @@ GLFWAPI int glfwGetWindowAttrib(GLFWwindow* handle, int attrib)
             return _glfwPlatformWindowMaximized(window);
         case GLFW_HOVERED:
             return _glfwPlatformWindowHovered(window);
+        case GLFW_FOCUS_ON_SHOW:
+            return window->focusOnShow;
         case GLFW_TRANSPARENT_FRAMEBUFFER:
             return _glfwPlatformFramebufferTransparent(window);
         case GLFW_RESIZABLE:
@@ -896,6 +905,8 @@ GLFWAPI void glfwSetWindowAttrib(GLFWwindow* handle, int attrib, int value)
         if (!window->monitor)
             _glfwPlatformSetWindowFloating(window, value);
     }
+    else if (attrib == GLFW_FOCUS_ON_SHOW)
+        window->focusOnShow = value;
     else
         _glfwInputError(GLFW_INVALID_ENUM, "Invalid window attribute 0x%08X", attrib);
 }

glfw/wl_init.c

@@ -24,7 +24,9 @@
 //
 //========================================================================
 
+#define _GNU_SOURCE
 #include "internal.h"
+#include "backend_utils.h"
 
 #include <assert.h>
 #include <linux/input.h>
@@ -33,6 +35,7 @@
 #include <string.h>
 #include <sys/mman.h>
 #include <unistd.h>
+#include <fcntl.h>
 #include <wayland-client.h>
 
 
@@ -161,7 +164,7 @@ static void pointerHandleMotion(void* data,
                                 wl_fixed_t sy)
 {
     _GLFWwindow* window = _glfw.wl.pointerFocus;
-    const char* cursorName;
+    const char* cursorName = NULL;
 
     if (!window)
         return;
@@ -615,6 +618,13 @@ static const struct wl_registry_listener registryListener = {
 
 int _glfwPlatformInit(void)
 {
+    if (pipe2(_glfw.wl.eventLoopData.wakeupFds, O_CLOEXEC | O_NONBLOCK) != 0)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                "Wayland: failed to create self pipe");
+        return GLFW_FALSE;
+    }
+
     _glfw.wl.cursor.handle = _glfw_dlopen("libwayland-cursor.so.0");
     if (!_glfw.wl.cursor.handle)
     {
@@ -654,6 +664,7 @@ int _glfwPlatformInit(void)
                         "Wayland: Failed to connect to display");
         return GLFW_FALSE;
     }
+    initPollData(_glfw.wl.eventLoopData.fds, _glfw.wl.eventLoopData.wakeupFds[0], wl_display_get_fd(_glfw.wl.display));
 
     _glfw.wl.registry = wl_display_get_registry(_glfw.wl.display);
     wl_registry_add_listener(_glfw.wl.registry, &registryListener, NULL);
@@ -744,6 +755,7 @@ void _glfwPlatformTerminate(void)
         wl_display_flush(_glfw.wl.display);
         wl_display_disconnect(_glfw.wl.display);
     }
+    closeFds(_glfw.wl.eventLoopData.wakeupFds, sizeof(_glfw.wl.eventLoopData.wakeupFds)/sizeof(_glfw.wl.eventLoopData.wakeupFds[0]));
 }
 
 const char* _glfwPlatformGetVersionString(void)

glfw/wl_platform.h

@@ -26,6 +26,7 @@
 
 #include <wayland-client.h>
 #include <dlfcn.h>
+#include <poll.h>
 
 typedef VkFlags VkWaylandSurfaceCreateFlagsKHR;
 
@@ -228,6 +229,11 @@ typedef struct _GLFWlibraryWayland
         PFN_wl_egl_window_resize window_resize;
     } egl;
 
+    struct {
+        struct pollfd fds[2];
+        int wakeupFds[2];
+    } eventLoopData;
+
 } _GLFWlibraryWayland;
 
 // Wayland-specific per-monitor data

glfw/wl_window.c

@@ -27,15 +27,14 @@
 #define _GNU_SOURCE
 
 #include "internal.h"
+#include "backend_utils.h"
 
 #include <stdio.h>
 #include <stdlib.h>
 #include <errno.h>
-#include <unistd.h>
 #include <string.h>
 #include <fcntl.h>
 #include <sys/mman.h>
-#include <poll.h>
 
 
 static void handlePing(void* data,
@@ -700,21 +699,20 @@ dispatchPendingKeyRepeats() {
     }
 }
 
-static int
-adjustTimeoutForKeyRepeat(int timeout) {
+static double
+adjustTimeoutForKeyRepeat(double timeout) {
     if (_glfw.wl.keyRepeatInfo.nextRepeatAt <= 0 || _glfw.wl.keyRepeatInfo.keyboardFocus != _glfw.wl.keyboardFocus || _glfw.wl.keyboardRepeatRate == 0) return timeout;
     double now = glfwGetTime();
-    if (timeout < 0 || now + timeout / 1000. > _glfw.wl.keyRepeatInfo.nextRepeatAt) {
-        timeout = _glfw.wl.keyRepeatInfo.nextRepeatAt <= now ? 0 : ( (_glfw.wl.keyRepeatInfo.nextRepeatAt - now) * 1000 + 1 );
+    if (timeout < 0 || now + timeout > _glfw.wl.keyRepeatInfo.nextRepeatAt) {
+        timeout = _glfw.wl.keyRepeatInfo.nextRepeatAt <= now ? 0 : ( (_glfw.wl.keyRepeatInfo.nextRepeatAt - now) + 0.001 );
     }
     return timeout;
 }
 
 static void
-handleEvents(int timeout)
+handleEvents(double timeout)
 {
     struct wl_display* display = _glfw.wl.display;
-    struct pollfd pfd = { wl_display_get_fd(display), POLLIN };
 
     while (wl_display_prepare_read(display) != 0)
         wl_display_dispatch_pending(display);
@@ -736,19 +734,25 @@ handleEvents(int timeout)
 
     dispatchPendingKeyRepeats();
     timeout = adjustTimeoutForKeyRepeat(timeout);
+    GLFWbool read_ok = GLFW_FALSE;
+    for (nfds_t i = 0; i < 2; i++) _glfw.wl.eventLoopData.fds[i].revents = 0;
 
-    if (poll(&pfd, 1, timeout) > 0)
-    {
-        if (pfd.revents & POLLIN)
+    if (timeout >= 0) {
+        const int result = pollWithTimeout(_glfw.wl.eventLoopData.fds, 2, timeout);
+        if (result > 0)
         {
-            wl_display_read_events(display);
-            wl_display_dispatch_pending(display);
+            if (_glfw.wl.eventLoopData.fds[0].revents & POLLIN) drainFd(_glfw.wl.eventLoopData.fds[0].fd);
+            read_ok = _glfw.wl.eventLoopData.fds[1].revents & POLLIN;
         }
-        else
-        {
-            wl_display_cancel_read(display);
+    } else {
+        if (poll(_glfw.wl.eventLoopData.fds, 2, -1) > 0) {
+            if (_glfw.wl.eventLoopData.fds[0].revents & POLLIN) drainFd(_glfw.wl.eventLoopData.fds[0].fd);
+            read_ok = _glfw.wl.eventLoopData.fds[1].revents & POLLIN;
         }
-
+    }
+    if (read_ok) {
+        wl_display_read_events(display);
+        wl_display_dispatch_pending(display);
     }
     else
     {
@@ -1206,12 +1210,13 @@ void _glfwPlatformWaitEvents(void)
 
 void _glfwPlatformWaitEventsTimeout(double timeout)
 {
-    handleEvents((int) (timeout * 1e3));
+    handleEvents(timeout);
 }
 
 void _glfwPlatformPostEmptyEvent(void)
 {
     wl_display_sync(_glfw.wl.display);
+    while (write(_glfw.wl.eventLoopData.wakeupFds[1], "w", 1) < 0 && errno == EINTR);
 }
 
 void _glfwPlatformGetCursorPos(_GLFWwindow* window, double* xpos, double* ypos)
@@ -1252,7 +1257,7 @@ int _glfwPlatformGetKeyScancode(int key)
 
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
-                              int xhot, int yhot)
+                              int xhot, int yhot, int count)
 {
     cursor->wl.buffer = createShmBuffer(image);
     cursor->wl.width = image->width;
@@ -1558,3 +1563,7 @@ GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* handle)
     _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
     return window->wl.surface;
 }
+
+GLFWAPI int glfwGetXKBScancode(const char* keyName, GLFWbool caseSensitive) {
+    return glfw_xkb_keysym_from_name(keyName, caseSensitive);
+}

glfw/x11_init.c

@@ -25,7 +25,9 @@
 //
 //========================================================================
 
+#define _GNU_SOURCE
 #include "internal.h"
+#include "backend_utils.h"
 
 #include <X11/Xresource.h>
 
@@ -34,6 +36,7 @@
 #include <limits.h>
 #include <stdio.h>
 #include <locale.h>
+#include <fcntl.h>
 
 
 // Check whether the specified atom is supported
@@ -454,7 +457,7 @@ static GLFWbool initExtensions(void)
 
 // Retrieve system content scale via folklore heuristics
 //
-static void getSystemContentScale(float* xscale, float* yscale)
+void _glfwGetSystemContentScaleX11(float* xscale, float* yscale, GLFWbool bypass_cache)
 {
     // NOTE: Default to the display-wide DPI as we don't currently have a policy
     //       for which monitor a window is considered to be on
@@ -466,7 +469,20 @@ static void getSystemContentScale(float* xscale, float* yscale)
     // NOTE: Basing the scale on Xft.dpi where available should provide the most
     //       consistent user experience (matches Qt, Gtk, etc), although not
     //       always the most accurate one
-    char* rms = XResourceManagerString(_glfw.x11.display);
+    char* rms = NULL;
+    char* owned_rms = NULL;
+
+    if (bypass_cache)
+    {
+        _glfwGetWindowPropertyX11(_glfw.x11.root,
+                                  _glfw.x11.RESOURCE_MANAGER,
+                                  XA_STRING,
+                                  (unsigned char**) &owned_rms);
+        rms = owned_rms;
+    } else {
+        rms = XResourceManagerString(_glfw.x11.display);
+    }
+
     if (rms)
     {
         XrmDatabase db = XrmGetStringDatabase(rms);
@@ -483,6 +499,7 @@ static void getSystemContentScale(float* xscale, float* yscale)
 
             XrmDestroyDatabase(db);
         }
+        XFree(owned_rms);
     }
 
     *xscale = xdpi / 96.f;
@@ -589,7 +606,6 @@ Cursor _glfwCreateCursorX11(const GLFWimage* image, int xhot, int yhot)
     return cursor;
 }
 
-
 //////////////////////////////////////////////////////////////////////////
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
@@ -599,6 +615,13 @@ int _glfwPlatformInit(void)
     XInitThreads();
     XrmInitialize();
 
+    if (pipe2(_glfw.x11.eventLoopData.wakeupFds, O_CLOEXEC | O_NONBLOCK) != 0)
+    {
+        _glfwInputError(GLFW_PLATFORM_ERROR,
+                "X11: failed to create self pipe");
+        return GLFW_FALSE;
+    }
+
     _glfw.x11.display = XOpenDisplay(NULL);
     if (!_glfw.x11.display)
     {
@@ -617,11 +640,16 @@ int _glfwPlatformInit(void)
         return GLFW_FALSE;
     }
 
+    initPollData(_glfw.x11.eventLoopData.fds, _glfw.x11.eventLoopData.wakeupFds[0], ConnectionNumber(_glfw.x11.display));
+    _glfw.x11.eventLoopData.fds[2].events = POLLIN;
+
     _glfw.x11.screen = DefaultScreen(_glfw.x11.display);
     _glfw.x11.root = RootWindow(_glfw.x11.display, _glfw.x11.screen);
     _glfw.x11.context = XUniqueContext();
+    _glfw.x11.RESOURCE_MANAGER = XInternAtom(_glfw.x11.display, "RESOURCE_MANAGER", True);
+    XSelectInput(_glfw.x11.display, _glfw.x11.root, PropertyChangeMask);
 
-    getSystemContentScale(&_glfw.x11.contentScaleX, &_glfw.x11.contentScaleY);
+    _glfwGetSystemContentScaleX11(&_glfw.x11.contentScaleX, &_glfw.x11.contentScaleY, GLFW_FALSE);
 
     if (!initExtensions())
         return GLFW_FALSE;
@@ -668,6 +696,7 @@ void _glfwPlatformTerminate(void)
     {
         XCloseDisplay(_glfw.x11.display);
         _glfw.x11.display = NULL;
+        _glfw.x11.eventLoopData.fds[0].fd = -1;
     }
 
     if (_glfw.x11.xcursor.handle)
@@ -714,6 +743,7 @@ void _glfwPlatformTerminate(void)
 #if defined(__linux__)
     _glfwTerminateJoysticksLinux();
 #endif
+    closeFds(_glfw.x11.eventLoopData.wakeupFds, sizeof(_glfw.x11.eventLoopData.wakeupFds)/sizeof(_glfw.x11.eventLoopData.wakeupFds[0]));
 }
 
 const char* _glfwPlatformGetVersionString(void)

glfw/x11_platform.h

@@ -29,6 +29,7 @@
 #include <signal.h>
 #include <stdint.h>
 #include <dlfcn.h>
+#include <poll.h>
 
 #include <X11/Xlib.h>
 #include <X11/keysym.h>
@@ -282,6 +283,9 @@ typedef struct _GLFWlibraryX11
     Atom            ATOM_PAIR;
     Atom            GLFW_SELECTION;
 
+    // XRM database atom
+    Atom            RESOURCE_MANAGER;
+
     struct {
         GLFWbool    available;
         void*       handle;
@@ -378,6 +382,11 @@ typedef struct _GLFWlibraryX11
         PFN_XRenderFindVisualFormat FindVisualFormat;
     } xrender;
 
+    struct {
+        struct pollfd fds[3];
+        int wakeupFds[2];
+    } eventLoopData;
+
 } _GLFWlibraryX11;
 
 // X11-specific per-monitor data
@@ -402,7 +411,6 @@ typedef struct _GLFWcursorX11
 
 } _GLFWcursorX11;
 
-
 void _glfwPollMonitorsX11(void);
 void _glfwSetVideoModeX11(_GLFWmonitor* monitor, const GLFWvidmode* desired);
 void _glfwRestoreVideoModeX11(_GLFWmonitor* monitor);
@@ -419,4 +427,5 @@ void _glfwGrabErrorHandlerX11(void);
 void _glfwReleaseErrorHandlerX11(void);
 void _glfwInputErrorX11(int error, const char* message);
 
+void _glfwGetSystemContentScaleX11(float* xscale, float* yscale, GLFWbool bypass_cache);
 void _glfwPushSelectionToManagerX11(void);

glfw/x11_window.c

@@ -25,13 +25,13 @@
 //
 //========================================================================
 
+#define _GNU_SOURCE
 #include "internal.h"
+#include "backend_utils.h"
 
 #include <X11/cursorfont.h>
 #include <X11/Xmd.h>
 
-#include <sys/select.h>
-
 #include <string.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -50,50 +50,52 @@
 
 #define _GLFW_XDND_VERSION 5
 
-
-// Wait for data to arrive using select
+// Wait for data to arrive using poll
 // This avoids blocking other threads via the per-display Xlib lock that also
 // covers GLX functions
 //
 static GLFWbool waitForEvent(double* timeout)
 {
-    fd_set fds;
-    const int fd = ConnectionNumber(_glfw.x11.display);
-    int count = fd + 1;
+    nfds_t count = 2;
 
 #if defined(__linux__)
-    if (_glfw.linjs.inotify > fd)
-        count = _glfw.linjs.inotify + 1;
+    if (_glfw.linjs.inotify > 0)
+    {
+        count = 3;
+        _glfw.x11.eventLoopData.fds[2].fd = _glfw.linjs.inotify;
+    }
 #endif
     for (;;)
     {
-        FD_ZERO(&fds);
-        FD_SET(fd, &fds);
-#if defined(__linux__)
-        if (_glfw.linjs.inotify > 0)
-            FD_SET(_glfw.linjs.inotify, &fds);
-#endif
-
+        for (nfds_t i = 0; i < count; i++) _glfw.x11.eventLoopData.fds[i].revents = 0;
         if (timeout)
         {
-            const long seconds = (long) *timeout;
-            const long microseconds = (long) ((*timeout - seconds) * 1e6);
-            struct timeval tv = { seconds, microseconds };
             const uint64_t base = _glfwPlatformGetTimerValue();
-
-            const int result = select(count, &fds, NULL, NULL, &tv);
-            const int error = errno;
-
+            const int result = pollWithTimeout(_glfw.x11.eventLoopData.fds, count, *timeout);
             *timeout -= (_glfwPlatformGetTimerValue() - base) /
                 (double) _glfwPlatformGetTimerFrequency();
 
             if (result > 0)
+            {
+                if (_glfw.x11.eventLoopData.fds[0].revents & POLLIN) drainFd(_glfw.x11.eventLoopData.fds[0].fd);
                 return GLFW_TRUE;
-            if ((result == -1 && error == EINTR) || *timeout <= 0.0)
+            }
+            if (result == 0)
                 return GLFW_FALSE;
+            if (*timeout > 0 && (errno == EINTR || errno == EAGAIN)) continue;
+            return GLFW_FALSE;
+        }
+        else {
+            const int result = poll(_glfw.x11.eventLoopData.fds, count, -1);
+            if (result > 0)
+            {
+                if (_glfw.x11.eventLoopData.fds[0].revents & POLLIN) drainFd(_glfw.x11.eventLoopData.fds[0].fd);
+                return GLFW_TRUE;
+            }
+            if (result == 0)
+                return GLFW_FALSE;
+            if (errno != EINTR && errno != EAGAIN) return GLFW_FALSE;
         }
-        else if (select(count, &fds, NULL, NULL, NULL) != -1 || errno != EINTR)
-            return GLFW_TRUE;
     }
 }
 
@@ -1142,6 +1144,24 @@ static void releaseMonitor(_GLFWwindow* window)
     }
 }
 
+static void onConfigChange()
+{
+    float xscale, yscale;
+    _glfwGetSystemContentScaleX11(&xscale, &yscale, GLFW_TRUE);
+
+    if (xscale != _glfw.x11.contentScaleX || yscale != _glfw.x11.contentScaleY)
+    {
+        _GLFWwindow* window = _glfw.windowListHead;
+        _glfw.x11.contentScaleX = xscale;
+        _glfw.x11.contentScaleY = yscale;
+        while (window)
+        {
+            _glfwInputWindowContentScale(window, xscale, yscale);
+            window = window->next;
+        }
+    }
+}
+
 // Process the specified X event
 //
 static void processEvent(XEvent *event)
@@ -1159,6 +1179,14 @@ static void processEvent(XEvent *event)
         }
     }
 
+    if (event->type == PropertyNotify &&
+        event->xproperty.window == _glfw.x11.root &&
+        event->xproperty.atom == _glfw.x11.RESOURCE_MANAGER)
+    {
+        onConfigChange();
+        return;
+    }
+
     if (event->type == GenericEvent)
     {
         if (_glfw.x11.xi.available)
@@ -2597,6 +2625,7 @@ void _glfwPlatformPostEmptyEvent(void)
 
     XSendEvent(_glfw.x11.display, _glfw.x11.helperWindowHandle, False, 0, &event);
     XFlush(_glfw.x11.display);
+    while (write(_glfw.x11.eventLoopData.wakeupFds[1], "w", 1) < 0 && errno == EINTR);
 }
 
 void _glfwPlatformGetCursorPos(_GLFWwindow* window, double* xpos, double* ypos)
@@ -2655,7 +2684,7 @@ int _glfwPlatformGetKeyScancode(int key)
 
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,
                               const GLFWimage* image,
-                              int xhot, int yhot)
+                              int xhot, int yhot, int count)
 {
     cursor->x11.handle = _glfwCreateCursorX11(image, xhot, yhot);
     if (!cursor->x11.handle)
@@ -2908,3 +2937,7 @@ GLFWAPI const char* glfwGetX11SelectionString(void)
     _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
     return getSelectionString(_glfw.x11.PRIMARY);
 }
+
+GLFWAPI int glfwGetXKBScancode(const char* keyName, GLFWbool caseSensitive) {
+    return glfw_xkb_keysym_from_name(keyName, caseSensitive);
+}

glfw/xkb_glfw.c

@@ -30,8 +30,7 @@
 #include "internal.h"
 #include "xkb_glfw.h"
 
-static GLFWbool debug_keyboard = GLFW_FALSE;
-#define debug(...) if (debug_keyboard) printf(__VA_ARGS__);
+#define debug(...) if (_glfw.hints.init.debugKeyboard) printf(__VA_ARGS__);
 
 #define map_key(key) { \
     switch(key) { \
@@ -181,6 +180,10 @@ glfw_xkb_release(_GLFWXKBData *xkb) {
         xkb_keymap_unref(xkb->keymap);
         xkb->keymap = NULL;
     }
+    if (xkb->default_keymap) {
+        xkb_keymap_unref(xkb->default_keymap);
+        xkb->default_keymap = NULL;
+    }
     if (xkb->state) {
         xkb_state_unref(xkb->state);
         xkb->state = NULL;
@@ -189,6 +192,10 @@ glfw_xkb_release(_GLFWXKBData *xkb) {
         xkb_state_unref(xkb->clean_state);
         xkb->clean_state = NULL;
     }
+    if (xkb->default_state) {
+        xkb_state_unref(xkb->default_state);
+        xkb->default_state = NULL;
+    }
     if (xkb->context) {
         xkb_context_unref(xkb->context);
         xkb->context = NULL;
@@ -198,7 +205,6 @@ glfw_xkb_release(_GLFWXKBData *xkb) {
 GLFWbool
 glfw_xkb_create_context(_GLFWXKBData *xkb) {
     xkb->context = xkb_context_new(0);
-    debug_keyboard = getenv("GLFW_DEBUG_KEYBOARD") != NULL;
     if (!xkb->context)
     {
         _glfwInputError(GLFW_PLATFORM_ERROR,
@@ -272,6 +278,21 @@ glfw_xkb_compile_keymap(_GLFWXKBData *xkb, const char *map_str) {
         xkb->modifiers = 0;
         xkb->activeUnknownModifiers = 0;
     }
+    if (!xkb->default_keymap && xkb->context) {
+        // The system default keymap, can be overridden by the XKB_DEFAULT_RULES
+        // env var, see
+        // https://xkbcommon.org/doc/current/structxkb__rule__names.html
+        static struct xkb_rule_names default_rule_names = {0};
+        xkb->default_keymap = xkb_keymap_new_from_names(xkb->context, &default_rule_names, XKB_KEYMAP_COMPILE_NO_FLAGS);
+        if (xkb->default_keymap) {
+            xkb->default_state = xkb_state_new(keymap);
+            if (!xkb->default_state) {
+                _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to create default XKB state, fallback key processing is unavailable");
+            }
+        } else {
+            _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to create default XKB keymap, fallback key processing is unavailable");
+        }
+    }
     return ok;
 }
 
@@ -338,6 +359,10 @@ glfw_xkb_keysym_name(xkb_keysym_t sym) {
     return name;
 }
 
+int
+glfw_xkb_keysym_from_name(const char *name, GLFWbool case_sensitive) {
+    return (int)xkb_keysym_from_name(name, case_sensitive ? XKB_KEYSYM_NO_FLAGS : XKB_KEYSYM_CASE_INSENSITIVE);
+}
 
 static inline const char*
 format_mods(unsigned int mods) {
@@ -379,7 +404,7 @@ format_xkb_mods(_GLFWXKBData *xkb, const char* name, xkb_mod_mask_t mods) {
 
 void
 glfw_xkb_handle_key_event(_GLFWwindow *window, _GLFWXKBData *xkb, xkb_keycode_t scancode, int action) {
-    const xkb_keysym_t *syms, *clean_syms;
+    const xkb_keysym_t *syms, *clean_syms, *default_syms;
     xkb_keysym_t glfw_sym;
     xkb_keycode_t code_for_sym = scancode;
 #ifdef _GLFW_WAYLAND
@@ -422,6 +447,20 @@ glfw_xkb_handle_key_event(_GLFWwindow *window, _GLFWXKBData *xkb, xkb_keycode_t
         if (text[0]) { debug("%s: %s ", text_type, text); }
     }
     int glfw_keycode = glfw_key_for_sym(glfw_sym);
-    debug("%sglfw_key: %s\n", format_mods(xkb->modifiers), _glfwGetKeyName(glfw_keycode));
+    GLFWbool is_fallback = GLFW_FALSE;
+    if (glfw_keycode == GLFW_KEY_UNKNOWN && !text[0]) {
+        int num_default_syms = xkb_state_key_get_syms(xkb->default_state, code_for_sym, &default_syms);
+        if (num_default_syms > 0) {
+            glfw_sym = default_syms[0];
+            glfw_keycode = glfw_key_for_sym(glfw_sym);
+            is_fallback = GLFW_TRUE;
+        }
+    }
+    debug(
+        "%s%s: %s xkb_key_name: %s\n",
+        format_mods(xkb->modifiers),
+        is_fallback ? "glfw_fallback_key" : "glfw_key", _glfwGetKeyName(glfw_keycode),
+        glfw_xkb_keysym_name(glfw_sym)
+    );
     _glfwInputKeyboard(window, glfw_keycode, glfw_sym, action, xkb->modifiers, text, 0);
 }

glfw/xkb_glfw.h

@@ -35,8 +35,10 @@
 typedef struct {
     struct xkb_context*     context;
     struct xkb_keymap*      keymap;
+    struct xkb_keymap*      default_keymap;
     struct xkb_state*       state;
     struct xkb_state*       clean_state;
+    struct xkb_state*       default_state;
     struct xkb_compose_state* composeState;
 
     xkb_mod_index_t         controlIdx;
@@ -81,3 +83,4 @@ GLFWbool glfw_xkb_should_repeat(_GLFWXKBData *xkb, xkb_keycode_t scancode);
 const char* glfw_xkb_keysym_name(xkb_keysym_t sym);
 xkb_keysym_t glfw_xkb_sym_for_key(int key);
 void glfw_xkb_handle_key_event(_GLFWwindow *window, _GLFWXKBData *xkb, xkb_keycode_t scancode, int action);
+int glfw_xkb_keysym_from_name(const char *name, GLFWbool case_sensitive);

graphics-protocol.asciidoc

@@ -1,385 +1 @@
-= The terminal graphics protocol
-:toc:
-:toc-placement!:
-
-The goal of this specification is to create a flexible and performant protocol
-that allows the program running in the terminal, hereafter called the _client_,
-to render arbitrary pixel (raster) graphics to the screen of the terminal
-emulator. The major design goals are
-
- * Should not require terminal emulators to understand image formats.
- * Should allow specifying graphics to be drawn at individual pixel positions.
- * The graphics should integrate with the text, in particular it should be possible to draw graphics
-   below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
- * Should use optimizations when the client is running on the same computer as the terminal emulator.
-
-For some discussion regarding the design choices, see link:../../issues/33[#33].
-
-To see a quick demo, inside a kitty terminal run:
-
-```
-kitty icat path/to/some/image.png
-```
-
-You can also see a screenshot with more sophisticated features such as alpha-blending and text over graphics
-link:https://github.com/kovidgoyal/kitty/issues/33#issuecomment-334436100[here].
-
-Some third-party programs that use the kitty graphics protocol:
-
- * link:https://github.com/dsanson/termpdf[termdpf] - a terminal PDF/DJVU/CBR viewer
- * link:https://github.com/ranger/ranger[ranger] - a terminal file manager, with image previews, see this link:https://github.com/ranger/ranger/pull/1077[PR]
-
-toc::[]
-
-== Getting the window size
-
-In order to know what size of images to display and how to position them, the client must be able to get the
-window size in pixels and the number of cells per row and column. This can be done by using the `TIOCGWINSZ` ioctl.
-Some code to demonstrate its use
-
-In C:
-```C
-struct ttysize ts;
-ioctl(0, TIOCGWINSZ, &ts);
-printf("number of columns: %i, number of rows: %i, screen width: %i, screen height: %i\n", sz.ws_col, sz.ws_row, sz.ws_xpixel, sz.ws_ypixel);
-```
-
-In Python:
-```py
-import array, fcntl, termios
-buf = array.array('H', [0, 0, 0, 0])
-fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf)
-print('number of columns: {}, number of rows: {}, screen width: {}, screen height: {}'.format(*buf))
-```
-
-Note that some terminals return `0` for the width and height values. Such terminals should be modified to return the correct values.
-Examples of terminals that return correct values: `kitty, xterm`
-
-== The graphics escape code
-
-All graphics escape codes are of the form:
-
-```
-<ESC>_G<control data>;<payload><ESC>\
-```
-
-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:
-
-```
-<ESC>_Gf=24,s=10,v=20;<payload><ESC>\
-```
-
-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:
-
-```
-<ESC>_Gf=100;<payload><ESC>\
-
-```
-
-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,
-
-```
-<ESC>_Gf=24,s=10,v=20,o=z;<payload><ESC>\
-```
-
-This is the same as the example from the RGB data section, except that the
-payload is now compressed using deflate. The terminal emulator will decompress
-it before rendering. You can specify compression for any format. The terminal
-emulator will decompress before interpreting the pixel data.
-
-
-=== The transmission medium
-
-The transmission medium is specified using the `t` key. The `t` key defaults to `d`
-and can take the values:
-
-|===
-| Value of `t` | Meaning
-
-| d | Direct (the data is transmitted within the escape code itself)
-| f | A simple file
-| t | A temporary file, the terminal emulator will delete the file after reading the pixel data
-| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data
-|===
-
-==== Local client
-
-First let us consider the local client techniques (files and shared memory). Some examples:
-
-```
-<ESC>_Gf=100,t=f;<encoded /path/to/file.png><ESC>\
-```
-
-Here we tell the terminal emulator to read PNG data from the specified file of
-the specified size.
-
-```
-<ESC>_Gs=10,v=2,t=s,o=z;<encoded /some-shared-memory-name><ESC>\
-```
-
-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:
-
-```
-<ESC>_Gs=10,v=2,t=s,S=80,O=10;<encoded /some-shared-memory-name><ESC>\
-```
-
-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:
-
-```
-<ESC>_Gs=100,v=30,m=1;<encoded pixel data first chunk><ESC>\
-<ESC>_Gm=1;<encoded pixel data second chunk><ESC>\
-<ESC>_Gm=0;<encoded pixel data last chunk><ESC>\
-```
-
-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:
-
-```
-<ESC>_Gi=31,s=10,v=2,t=s;<encoded /some-shared-memory-name><ESC>\
-```
-
-to which the terminal emulator will reply (after trying to load the data):
-
-```
-<ESC>_Gi=31;error message or OK<ESC>\
-```
-
-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:
-
-```
-<ESC>_Gi=<id>;OK<ESC>\
-```
-
-when the image referred to by id was found, or
-
-```
-<ESC>_Gi=<id>;ENOENT:<some detailed error msg><ESC>\
-```
-
-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:
-
-```
-<ESC>_Ga=d<ESC>\   # delete all visible images
-<ESC>_Ga=d,i=10<ESC>\   # delete the image with id=10
-<ESC>_Ga=Z,z=-1<ESC>\   # delete the images with z-index -1, also freeing up image data
-<ESC>_Ga=P,x=3,y=4<ESC>\   # delete all images that intersect the cell at (3, 4)
-```
-
-=== Image persistence and storage quotas
-
-In order to avoid *Denial-of-Service* attacks, terminal emulators should have a
-maximum storage quota for image data. It should allow at least a few full
-screen images.  For example the quota in kitty is 320MB per buffer. When adding
-a new image, if the total size exceeds the quota, the terminal emulator should
-delete older images to make space for the new one.
-
-
-== Control data reference
-
-The table below shows all the control data keys as well as what values they can
-take, and the default value they take when missing. All integers are 32-bit.
-
-[cols="^1,<3,^1,<6"]
-|===
-|Key | Value | Default | Description
-
-| `a` | Single character. `(t, T, q, p, d)` | `t` | The overall action this graphics command is performing.
-
-4+^.^h| Keys for image transmission
-
-| `f` | Positive integer. `(24, 32, 100)`. | `32` | The format in which the image data is sent.
-| `t` | Single character. `(d, f, t, s)`. | `d` | The transmission medium used.
-| `s` | Positive integer. | `0` | The width of the image being sent.
-| `v` | Positive integer. | `0` | The height of the image being sent.
-| `S` | Positive integer. | `0` | The size of data to read from a file.
-| `O` | Positive integer. | `0` | The offset from which to read data from a file.
-| `i` | Positive integer. `(0 - 4294967295)` | `0` | The image id
-| `o` | Single character. `only z` | `null` | The type of data compression.
-| `m` | zero or one | `0` | Whether there is more chunked data available.
-
-4+^.^h| Keys for image display
-
-| `x` | Positive integer | `0` | The left edge (in pixels) of the image area to display
-| `y` | Positive integer | `0` | The top edge (in pixels) of the image area to display
-| `w` | Positive integer | `0` | The width (in pixels) of the image area to display. By default, the entire width is used.
-| `h` | Positive integer | `0` | The height (in pixels) of the image area to display. By default, the entire height is used
-| `X` | Positive integer | `0` | The x-offset within the first cell at which to start displaying the image
-| `Y` | Positive integer | `0` | The y-offset within the first cell at which to start displaying the image
-| `c` | Positive integer | `0` | The number of columns to display the image over
-| `r` | Positive integer | `0` | The number of rows to display the image over
-| `z` | Integer          | `0` | The *z-index* vertical stacking order of the image
-
-4+^.^h| Keys for deleting images
-
-| `d` | Single character. `(a, A, c, C, p, P, q, Q, x, X, y, Y, z, Z)`. | `a` | What to delete.
-
-|===
-
-
-== Interaction with other terminal actions
-
-When resetting the terminal, all images that are visible on the screen must be
-cleared.  When switching from the main screen to the alternate screen buffer
-(1049 private mode) all images in the alternate screen must be cleared, just as
-all text is cleared. The clear screen escape code (usually `<ESC>[2J`) should also
-clear all images. This is so that the clear command works.
-
-The other commands to erase text must have no effect on graphics.
-The dedicated delete graphics commands must be used for those.
-
-When scrolling the screen (such as when using index cursor movement commands,
-or scrolling through the history buffer), images must be scrolled along with
-text. When page margins are defined and the index commands are used, only
-images that are entirely within the page area (between the margins) must be
-scrolled. When scrolling them would cause them to extend outside the page area,
-they must be clipped.
+See https://sw.kovidgoyal.net/kitty/graphics-protocol.html

key_encoding.asciidoc

@@ -1,129 +1 @@
-= Key encoding for extended keyboard protocol
-
-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)
-
-| 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`
-
-|===
+See https://sw.kovidgoyal.net/kitty/key-encoding.html

kittens/ask/main.py

@@ -50,8 +50,10 @@ class HistoryCompleter:
 
     def __enter__(self):
         if self.history_path:
-            if os.path.exists(self.history_path):
+            try:
                 readline.read_history_file(self.history_path)
+            except Exception:
+                pass
             readline.set_completer(self.complete)
         return self
 

kittens/clipboard/main.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+import sys
+from kitty.cli import parse_args
+
+from ..tui.handler import Handler
+from ..tui.loop import Loop
+
+
+class Clipboard(Handler):
+
+    def __init__(self, data_to_send, args):
+        self.args = args
+        self.print_on_fail = None
+        self.clipboard_contents = None
+        self.data_to_send = data_to_send
+
+    def initialize(self):
+        if self.data_to_send is not None:
+            self.cmd.write_to_clipboard(self.data_to_send, self.args.use_primary)
+        if not self.args.get_clipboard:
+            self.quit_loop(0)
+            return
+        self.cmd.request_from_clipboard(self.args.use_primary)
+
+    def on_clipboard_response(self, text, from_primary=False):
+        self.clipboard_contents = text
+        self.quit_loop(0)
+
+
+OPTIONS = r'''
+--get-clipboard
+default=False
+type=bool-set
+Output the current contents of the clipboard to stdout. Note that this
+will not work if you have not enabled the option to allow reading the clipboard
+in kitty.conf
+
+
+--use-primary
+default=False
+type=bool-set
+Use the primary selection rather than the clipboard on systems that support it,
+such as X11.
+'''.format
+help_text = '''\
+Read or write to the system clipboard.
+
+To set the clipboard text, pipe in the new text on stdin. Use the
+:option:`--get-clipboard` option to output the current clipboard contents to
+:file:`stdout`. Note that you must enable reading of clipboard in
+:file:`kitty.conf` first.
+'''
+usage = ''
+
+
+def main(args):
+    args, items = parse_args(args[1:], OPTIONS, usage, help_text, 'kitty +kitten clipboard')
+    if items:
+        raise SystemExit('Unrecognized extra command line arguments')
+    data = None
+    if not sys.stdin.isatty():
+        data = sys.stdin.buffer.read()
+        sys.stdin = open('/dev/tty', 'r')
+    loop = Loop()
+    handler = Clipboard(data, args)
+    loop.loop(handler)
+    if loop.return_code == 0 and handler.clipboard_contents:
+        sys.stdout.write(handler.clipboard_contents)
+        sys.stdout.flush()
+    if handler.print_on_fail:
+        print(handler.print_on_fail, file=sys.stderr)
+        input('Press Enter to quit')
+    raise SystemExit(loop.return_code)
+
+
+if __name__ == '__main__':
+    main(sys.argv)
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = OPTIONS
+    sys.cli_docs['help_text'] = help_text

kittens/diff/README.asciidoc

@@ -1,105 +1 @@
-= kitty-diff - A side-by-side diff tool with syntax highlighting and images
-:toc:
-:toc-placement!:
-
-
-== Major Features
-
-* Displays diffs side-by-side in the kitty terminal.
-
-* Does syntax highlighting of displayed diffs
-
-* Displays images as well as text diffs, even over SSH
-
-* Does recursive directory diffing
-
-
-image::../../screenshots/diff.png?raw=true[Screenshot, showing a sample diff]
-
-toc::[]
-
-
-== Installation
-
-Simply install link:https://github.com/kovidgoyal/kitty[kitty].  You also need
-to have either the link:https://git-scm.com/[git] program or the `diff` program
-installed. Additionally, for syntax highlighting to work,
-link:http://pygments.org/[pygments] must be installed (note that pygments is
-included in the macOS kitty app).
-
-
-== Usage
-
-In the kitty terminal, run:
-
-....
-kitty +kitten diff file1 file2
-....
-
-to see the diff between file1 and file2.
-
-Create an alias in your shell's startup file to shorten the command, for example:
-
-```sh
-alias d="kitty +kitten diff"
-```
-
-Now all you need to do to diff two files is:
-
-```
-d file1 file2
-```
-
-You can also pass directories instead of files to see the recursive diff of the
-directory contents.
-
-
-== Keyboard controls
-
-|===
-|Action |Shortcut
-
-|Quit             | `q, Ctrl+c`
-|Scroll line up   | `k, up`
-|Scroll line down | `j, down`
-|Scroll page up   | `PgUp`
-|Scroll page down | `PgDn`
-|Scroll to top    | `Home`
-|Scroll to bottom | `End`
-|Scroll to next change | `n`
-|Scroll to previous change | `p`
-
-|Increase lines of context | `+`
-|Decrease lines of context | `-`
-|All lines of context      | `a`
-|Restore context to default| `=`
-
-|===
-
-[options="header"]
-
-
-== Integrating with git
-
-Add the following to `~/.gitconfig`:
-
-```gitconfig
-[diff]
-    tool = kitty
-    guitool = kitty.gui
-[difftool]
-    prompt = false
-    trustExitCode = true
-[difftool "kitty"]
-    cmd = kitty +kitten diff $LOCAL $REMOTE
-[difftool "kitty.gui"]
-    cmd = kitty kitty +kitten diff $LOCAL $REMOTE
-```
-
-Now to use kitty-diff to view git diffs, you can simply do:
-
-```
-git difftool --no-symlinks --dir-diff
-```
-
-Once again, creating an alias for this command is useful.
+See https://sw.kovidgoyal.net/kitty/kittens/diff.html

kittens/diff/collect.py

@@ -116,12 +116,9 @@ def collect_files(collection, left, right):
 sanitize_pat = re.compile('[\x00-\x09\x0b-\x1f\x7f\x80-\x9f]')
 
 
-def sanitize_sub(m):
-    return '<{:x}>'.format(ord(m.group()[0]))
-
-
 def sanitize(text):
-    return sanitize_pat.sub(sanitize_sub, text)
+    ntext = text.replace('\r\n', '⏎\n')
+    return sanitize_pat.sub('░', ntext)
 
 
 @lru_cache(maxsize=1024)

kittens/diff/config.py

@@ -4,17 +4,17 @@
 
 import os
 
-from kitty.config_utils import (
-    init_config, load_config as _load_config, merge_dicts, parse_config_base,
-    python_string, resolve_config, to_color
+from kitty.conf.utils import (
+    init_config as _init_config, key_func, load_config as _load_config, merge_dicts,
+    parse_config_base, parse_kittens_key, resolve_config
 )
+from kitty.conf.definition import config_lines
 from kitty.constants import config_dir
 from kitty.rgb import color_as_sgr
 
+from .config_data import type_map, all_options
+
 defaults = None
-default_config_path = os.path.join(
-    os.path.dirname(os.path.abspath(__file__)), 'diff.conf'
-)
 
 formats = {
     'title': '',
@@ -38,34 +38,54 @@ def set_formats(opts):
     formats['added_highlight'] = '48' + color_as_sgr(opts.highlight_added_bg)
 
 
-def syntax_aliases(raw):
-    ans = {}
-    for x in raw.split():
-        a, b = x.partition(':')[::2]
-        if a and b:
-            ans[a.lower()] = b
-    return ans
+func_with_args, args_funcs = key_func()
 
 
-type_map = {
-    'syntax_aliases': syntax_aliases,
-    'num_context_lines': int,
-    'replace_tab_by': python_string,
-}
-
-for name in (
-    'foreground background title_fg title_bg margin_bg margin_fg removed_bg removed_margin_bg added_bg added_margin_bg filler_bg hunk_bg hunk_margin_bg'
-    ' highlight_removed_bg highlight_added_bg'
-).split():
-    type_map[name] = to_color
+@func_with_args('scroll_by')
+def parse_scroll_by(func, rest):
+    try:
+        return func, int(rest)
+    except Exception:
+        return func, 1
 
 
-def special_handling(*a):
-    pass
+@func_with_args('scroll_to')
+def parse_scroll_to(func, rest):
+    rest = rest.lower()
+    if rest not in {'start', 'end', 'next-change', 'prev-change', 'next-page', 'prev-page', 'next-match', 'prev-match'}:
+        rest = 'start'
+    return func, rest
+
+
+@func_with_args('change_context')
+def parse_change_context(func, rest):
+    rest = rest.lower()
+    if rest in {'all', 'default'}:
+        return func, rest
+    try:
+        amount = int(rest)
+    except Exception:
+        amount = 5
+    return func, amount
+
+
+@func_with_args('start_search')
+def parse_start_search(func, rest):
+    rest = rest.lower().split()
+    is_regex = rest and rest[0] == 'regex'
+    is_backward = len(rest) > 1 and rest[1] == 'backward'
+    return func, (is_regex, is_backward)
+
+
+def special_handling(key, val, ans):
+    if key == 'map':
+        action, *key_def = parse_kittens_key(val, args_funcs)
+        ans['key_definitions'][tuple(key_def)] = action
+        return True
 
 
 def parse_config(lines, check_keys=True):
-    ans = {}
+    ans = {'key_definitions': {}}
     parse_config_base(
         lines,
         defaults,
@@ -92,7 +112,7 @@ def parse_defaults(lines, check_keys=False):
     return parse_config(lines, check_keys)
 
 
-Options, defaults = init_config(default_config_path, parse_defaults)
+Options, defaults = _init_config(config_lines(all_options), parse_defaults)
 
 
 def load_config(*paths, overrides=None):

kittens/diff/config_data.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+
+# Utils  {{{
+from gettext import gettext as _
+from functools import partial
+
+from kitty.conf.definition import option_func
+from kitty.conf.utils import (
+    positive_int, python_string, to_color
+)
+
+# }}}
+
+all_options = {}
+o, k, g, all_groups = option_func(all_options, {
+    'colors': [_('Colors')],
+    'diff': [_('Diffing'), ],
+    'shortcuts': [_('Keyboard shortcuts')],
+})
+
+
+g('diff')
+
+
+def syntax_aliases(raw):
+    ans = {}
+    for x in raw.split():
+        a, b = x.partition(':')[::2]
+        if a and b:
+            ans[a.lower()] = b
+    return ans
+
+
+o('syntax_aliases', 'pyj:py recipe:py', option_type=syntax_aliases, long_text=_('''
+File extension aliases for syntax highlight
+For example, to syntax highlight :file:`file.xyz` as
+:file:`file.abc` use a setting of :code:`xyz:abc`
+'''))
+
+o('num_context_lines', 3, option_type=positive_int, long_text=_('''
+The number of lines of context to show around each change.'''))
+
+o('diff_cmd', 'auto', long_text=_('''
+The diff command to use. Must contain the placeholder :code:`_CONTEXT_`
+which will be replaced by the number of lines of context. The default
+is to search the system for either git or diff and use that, if found.
+'''))
+
+o('replace_tab_by', r'\x20\x20\x20\x20', option_type=python_string, long_text=_('''
+The string to replace tabs with. Default is to use four spaces.'''))
+
+
+g('colors')
+
+o('pygments_style', 'default', long_text=_('''
+The pygments color scheme to use for syntax highlighting.
+See :link:`pygments colors schemes <https://help.farbox.com/pygments.html>` for a list of schemes.'''))
+
+
+c = partial(o, option_type=to_color)
+c('foreground', 'black', long_text=_('Basic colors'))
+c('background', 'white')
+
+c('title_fg', 'black', long_text=_('Title colors'))
+c('title_bg', 'white')
+
+c('margin_bg', '#fafbfc', long_text=_('Margin colors'))
+c('margin_fg', '#aaaaaa')
+
+c('removed_bg', '#ffeef0', long_text=_('Removed text backgrounds'))
+c('highlight_removed_bg', '#fdb8c0')
+c('removed_margin_bg', '#ffdce0')
+
+c('added_bg', '#e6ffed', long_text=_('Added text backgrounds'))
+c('highlight_added_bg', '#acf2bd')
+c('added_margin_bg', '#cdffd8')
+
+c('filler_bg', '#fafbfc', long_text=_('Filler (empty) line background'))
+
+c('hunk_margin_bg', '#dbedff', long_text=_('Hunk header colors'))
+c('hunk_bg', '#f1f8ff')
+
+c('search_bg', '#444', long_text=_('Highlighting'))
+c('search_fg', 'white')
+c('select_bg', '#B4D5FE')
+c('select_fg', 'black')
+
+g('shortcuts')
+k('quit', 'q', 'quit', _('Quit'))
+k('quit', 'esc', 'quit', _('Quit'))
+
+k('scroll_down', 'j', 'scroll_by 1', _('Scroll down'))
+k('scroll_down', 'down', 'scroll_by 1', _('Scroll down'))
+k('scroll_up', 'k', 'scroll_by -1', _('Scroll up'))
+k('scroll_up', 'up', 'scroll_by -1', _('Scroll up'))
+
+k('scroll_top', 'home', 'scroll_to start', _('Scroll to top'))
+k('scroll_bottom', 'end', 'scroll_to end', _('Scroll to bottom'))
+
+k('scroll_page_down', 'page_down', 'scroll_to next-page', _('Scroll to next page'))
+k('scroll_page_down', 'space', 'scroll_to next-page', _('Scroll to next page'))
+k('scroll_page_up', 'page_up', 'scroll_to prev-page', _('Scroll to previous page'))
+
+k('next_change', 'n', 'scroll_to next-change', _('Scroll to next change'))
+k('prev_change', 'p', 'scroll_to prev-change', _('Scroll to previous change'))
+
+k('all_context', 'a', 'change_context all', _('Show all context'))
+k('default_context', '=', 'change_context default', _('Show default context'))
+k('increase_context', '+', 'change_context 5', _('Increase context'))
+k('decrease_context', '-', 'change_context -5', _('Decrease context'))
+
+k('search_forward', '/', 'start_search regex forward', _('Search forward'))
+k('search_backward', '?', 'start_search regex backward', _('Search backward'))
+k('next_match', '.', 'scroll_to next-match', _('Scroll to next search match'))
+k('prev_match', ',', 'scroll_to prev-match', _('Scroll to previous search match'))
+k('next_match', '>', 'scroll_to next-match', _('Scroll to next search match'))
+k('prev_match', '<', 'scroll_to prev-match', _('Scroll to previous search match'))
+k('search_forward_simple', 'f', 'start_search substring forward', _('Search forward (no regex)'))
+k('search_backward_simple', 'b', 'start_search substring backward', _('Search backward (no regex)'))
+
+type_map = {o.name: o.option_type for o in all_options.values() if hasattr(o, 'option_type')}

kittens/diff/diff.conf

@@ -1,38 +0,0 @@
-# vim:fileencoding=utf-8:ft=conf
-
-# File extension aliases for syntax highlight
-# For example, to syntax highlight file.xyz as
-# file.abc use a setting of xyz:abc
-syntax_aliases pyj:py recipe:py
-
-# The pygments color scheme to use. See https://help.farbox.com/pygments.html
-# for a list of schemes.
-pygments_style default
-
-# The number of lines of context to show around each change.
-num_context_lines 3
-
-# The diff command to use. Must contain the placeholder _CONTEXT_
-# which will be replaced by the number of lines of context. The default
-# is to search the system for either git or diff and use that, if found.
-diff_cmd auto
-
-# The string to replace tabs with. Default is to use four spaces.
-replace_tab_by \x20\x20\x20\x20
-
-# Colors
-foreground            black
-background            white
-title_fg              black
-title_bg              white
-margin_bg             #fafbfc
-margin_fg             #aaaaaa
-removed_bg            #ffeef0
-highlight_removed_bg  #fdb8c0
-removed_margin_bg     #ffdce0
-added_bg              #e6ffed
-highlight_added_bg    #acf2bd
-added_margin_bg       #cdffd8
-filler_bg             #fafbfc
-hunk_margin_bg        #dbedff
-hunk_bg               #f1f8ff

kittens/diff/highlight.py

@@ -57,7 +57,7 @@ class DiffFormatter(Formatter):
     def format(self, tokensource, outfile):
         for ttype, value in tokensource:
             not_found = True
-            if value != '\n':
+            if value.rstrip('\n'):
                 while ttype and not_found:
                     tok = self.styles.get(ttype)
                     if tok is None:

kittens/diff/main.py

@@ -9,22 +9,24 @@ from collections import defaultdict
 from functools import partial
 from gettext import gettext as _
 
-from kitty.cli import CONFIG_HELP, appname, parse_args
+from kitty.cli import CONFIG_HELP, parse_args
+from kitty.constants import appname
 from kitty.fast_data_types import wcswidth
-from kitty.key_encoding import (
-    DOWN, END, ESCAPE, HOME, PAGE_DOWN, PAGE_UP, RELEASE, UP
-)
+from kitty.key_encoding import ESCAPE, RELEASE, enter_key
 
 from ..tui.handler import Handler
 from ..tui.images import ImageManager
+from ..tui.line_edit import LineEdit
 from ..tui.loop import Loop
 from ..tui.operations import styled
 from .collect import (
-    create_collection, data_for_path, lines_for_path, set_highlight_data
+    create_collection, data_for_path, lines_for_path, sanitize,
+    set_highlight_data
 )
 from .config import init_config
 from .patch import Differ, set_diff_command
 from .render import ImageSupportWarning, LineRef, render_diff
+from .search import BadRegex, Search
 
 try:
     from .highlight import initialize_highlighter, highlight_collection
@@ -32,7 +34,7 @@ except ImportError:
     initialize_highlighter = None
 
 
-INITIALIZING, COLLECTED, DIFFED = range(3)
+INITIALIZING, COLLECTED, DIFFED, COMMAND, MESSAGE = range(5)
 
 
 def generate_diff(collection, context):
@@ -53,6 +55,10 @@ class DiffHandler(Handler):
 
     def __init__(self, args, opts, left, right):
         self.state = INITIALIZING
+        self.message = ''
+        self.current_search_is_regex = True
+        self.current_search = None
+        self.line_edit = LineEdit()
         self.opts = opts
         self.left, self.right = left, right
         self.report_traceback_on_exit = None
@@ -63,6 +69,41 @@ class DiffHandler(Handler):
             self.current_context_count = self.original_context_count = self.opts.num_context_lines
         self.highlighting_done = False
         self.restore_position = None
+        for key_def, action in self.opts.key_definitions.items():
+            self.add_shortcut(action, *key_def)
+
+    def perform_action(self, action):
+        func, args = action
+        if func == 'quit':
+            self.quit_loop(0)
+            return
+        if self.state <= DIFFED:
+            if func == 'scroll_by':
+                return self.scroll_lines(*args)
+            if func == 'scroll_to':
+                where = args[0]
+                if 'change' in where:
+                    return self.scroll_to_next_change(backwards='prev' in where)
+                if 'match' in where:
+                    return self.scroll_to_next_match(backwards='prev' in where)
+                if 'page' in where:
+                    amt = self.num_lines * (1 if 'next' in where else -1)
+                else:
+                    amt = len(self.diff_lines) * (1 if 'end' in where else -1)
+                return self.scroll_lines(amt)
+            if func == 'change_context':
+                new_ctx = self.current_context_count
+                to = args[0]
+                if to == 'all':
+                    new_ctx = 100000
+                elif to == 'default':
+                    new_ctx = self.original_context_count
+                else:
+                    new_ctx += to
+                return self.change_context_count(new_ctx)
+            if func == 'start_search':
+                self.start_search(*args)
+                return
 
     def create_collection(self):
         self.start_job('collect', create_collection, self.left, self.right)
@@ -79,10 +120,13 @@ class DiffHandler(Handler):
 
     def render_diff(self):
         self.diff_lines = tuple(render_diff(self.collection, self.diff_map, self.args, self.screen_size.cols, self.image_manager))
+        self.margin_size = render_diff.margin_size
         self.ref_path_map = defaultdict(list)
         for i, l in enumerate(self.diff_lines):
             self.ref_path_map[l.ref.path].append((i, l.ref))
         self.max_scroll_pos = len(self.diff_lines) - self.num_lines
+        if self.current_search is not None:
+            self.current_search(self.diff_lines, self.margin_size, self.screen_size.cols)
 
     @property
     def current_position(self):
@@ -124,6 +168,19 @@ class DiffHandler(Handler):
                 return
         self.cmd.bell()
 
+    def scroll_to_next_match(self, backwards=False, include_current=False):
+        if self.current_search is not None:
+            offset = 0 if include_current else 1
+            if backwards:
+                r = range(self.scroll_pos - offset, -1, -1)
+            else:
+                r = range(self.scroll_pos + offset, len(self.diff_lines))
+            for i in r:
+                if i in self.current_search:
+                    self.scroll_lines(i - self.scroll_pos)
+                    return
+        self.cmd.bell()
+
     def set_scrolling_region(self):
         self.cmd.set_scrolling_region(self.screen_size, 0, self.num_lines - 2)
 
@@ -150,7 +207,16 @@ class DiffHandler(Handler):
     def init_terminal_state(self):
         self.cmd.set_line_wrapping(False)
         self.cmd.set_window_title(main.title)
-        self.cmd.set_default_colors(self.opts.foreground, self.opts.background)
+        self.cmd.set_default_colors(
+            fg=self.opts.foreground, bg=self.opts.background,
+            cursor=self.opts.foreground, select_fg=self.opts.select_fg,
+            select_bg=self.opts.select_bg)
+        self.cmd.set_cursor_shape('bar')
+
+    def finalize(self):
+        self.cmd.set_default_colors()
+        self.cmd.set_cursor_visible(True)
+        self.cmd.set_scrolling_region()
 
     def initialize(self):
         self.init_terminal_state()
@@ -159,12 +225,7 @@ class DiffHandler(Handler):
         self.create_collection()
 
     def enforce_cursor_state(self):
-        self.cmd.set_cursor_visible(self.state > DIFFED)
-
-    def finalize(self):
-        self.cmd.set_cursor_visible(True)
-        self.cmd.set_default_colors()
-        self.cmd.set_scrolling_region()
+        self.cmd.set_cursor_visible(self.state == COMMAND)
 
     def draw_lines(self, num, offset=0):
         offset += self.scroll_pos
@@ -180,6 +241,8 @@ class DiffHandler(Handler):
                 if line.image_data is not None:
                     image_involved = True
             self.write('\r\x1b[K' + text + '\x1b[0m')
+            if self.current_search is not None:
+                self.current_search.highlight_line(self.write, lpos)
             if i < num - 1:
                 self.write('\n')
         if image_involved:
@@ -234,19 +297,29 @@ class DiffHandler(Handler):
     def draw_status_line(self):
         if self.state < DIFFED:
             return
+        self.enforce_cursor_state()
         self.cmd.set_cursor_position(0, self.num_lines)
         self.cmd.clear_to_eol()
-        scroll_frac = styled('{:.0%}'.format(self.scroll_pos / self.max_scroll_pos), fg=self.opts.margin_fg)
-        counts = '{}{}{}'.format(
-                styled(str(self.added_count), fg=self.opts.highlight_added_bg),
-                styled(',', fg=self.opts.margin_fg),
-                styled(str(self.removed_count), fg=self.opts.highlight_removed_bg)
-        )
-        suffix = counts + '  ' + scroll_frac
-        prefix = styled(':', fg=self.opts.margin_fg)
-        filler = self.screen_size.cols - wcswidth(prefix) - wcswidth(suffix)
-        text = '{}{}{}'.format(prefix, ' ' * filler, suffix)
-        self.write(text)
+        if self.state is COMMAND:
+            self.line_edit.write(self.write)
+        elif self.state is MESSAGE:
+            self.cmd.styled(self.message, reverse=True)
+        else:
+            sp = '{:.0%}'.format(self.scroll_pos/self.max_scroll_pos) if self.scroll_pos and self.max_scroll_pos else '0%'
+            scroll_frac = styled(sp, fg=self.opts.margin_fg)
+            if self.current_search is None:
+                counts = '{}{}{}'.format(
+                        styled(str(self.added_count), fg=self.opts.highlight_added_bg),
+                        styled(',', fg=self.opts.margin_fg),
+                        styled(str(self.removed_count), fg=self.opts.highlight_removed_bg)
+                )
+            else:
+                counts = styled('{} matches'.format(len(self.current_search)), fg=self.opts.margin_fg)
+            suffix = counts + '  ' + scroll_frac
+            prefix = styled(':', fg=self.opts.margin_fg)
+            filler = self.screen_size.cols - wcswidth(prefix) - wcswidth(suffix)
+            text = '{}{}{}'.format(prefix, ' ' * filler, suffix)
+            self.write(text)
 
     def change_context_count(self, new_ctx):
         new_ctx = max(0, new_ctx)
@@ -257,47 +330,80 @@ class DiffHandler(Handler):
             self.restore_position = self.current_position
             self.draw_screen()
 
+    def start_search(self, is_regex, is_backward):
+        if self.state != DIFFED:
+            self.cmd.bell()
+            return
+        self.state = COMMAND
+        self.line_edit.clear()
+        self.line_edit.add_text('?' if is_backward else '/')
+        self.current_search_is_regex = is_regex
+        self.draw_status_line()
+
+    def do_search(self):
+        self.current_search = None
+        query = self.line_edit.current_input
+        if len(query) < 2:
+            return
+        try:
+            self.current_search = Search(self.opts, query[1:], self.current_search_is_regex, query[0] == '?')
+        except BadRegex:
+            self.state = MESSAGE
+            self.message = sanitize(_('Bad regex: {}').format(query[1:]))
+            self.cmd.bell()
+        else:
+            if self.current_search(self.diff_lines, self.margin_size, self.screen_size.cols):
+                self.scroll_to_next_match(include_current=True)
+            else:
+                self.state = MESSAGE
+                self.message = sanitize(_('No matches found'))
+                self.cmd.bell()
+
     def on_text(self, text, in_bracketed_paste=False):
-        if text == 'q':
-            if self.state <= DIFFED:
-                self.quit_loop(0)
-                return
-        if self.state is DIFFED:
-            if text in 'jk':
-                self.scroll_lines(1 if text == 'j' else -1)
-                return
-            if text in 'a+-=':
-                new_ctx = self.current_context_count
-                if text == 'a':
-                    new_ctx = 100000
-                elif text == '=':
-                    new_ctx = self.original_context_count
-                else:
-                    new_ctx += (-1 if text == '-' else 1) * 5
-                self.change_context_count(new_ctx)
-            if text in 'np':
-                self.scroll_to_next_change(backwards=text == 'p')
-                return
+        if self.state is COMMAND:
+            self.line_edit.on_text(text, in_bracketed_paste)
+            self.draw_status_line()
+            return
+        if self.state is MESSAGE:
+            self.state = DIFFED
+            self.draw_status_line()
+            return
+        action = self.shortcut_action(text)
+        if action is not None:
+            return self.perform_action(action)
 
     def on_key(self, key_event):
+        if self.state is MESSAGE:
+            if key_event.type is not RELEASE:
+                self.state = DIFFED
+                self.draw_status_line()
+            return
+        if self.state is COMMAND:
+            if self.line_edit.on_key(key_event):
+                if not self.line_edit.current_input:
+                    self.state = DIFFED
+                self.draw_status_line()
+                return
         if key_event.type is RELEASE:
             return
-        if key_event.key is ESCAPE:
-            if self.state <= DIFFED:
-                self.quit_loop(0)
+        if self.state is COMMAND:
+            if key_event.key is ESCAPE:
+                self.state = DIFFED
+                self.draw_status_line()
                 return
-        if self.state is DIFFED:
-            if key_event.key is UP or key_event.key is DOWN:
-                self.scroll_lines(1 if key_event.key is DOWN else -1)
-                return
-            if key_event.key is PAGE_UP or key_event.key is PAGE_DOWN:
-                amt = self.num_lines * (1 if key_event.key is PAGE_DOWN else -1)
-                self.scroll_lines(amt)
-                return
-            if key_event.key is HOME or key_event.key is END:
-                amt = len(self.diff_lines) * (1 if key_event.key is END else -1)
-                self.scroll_lines(amt)
+            if key_event is enter_key:
+                self.state = DIFFED
+                self.do_search()
+                self.line_edit.clear()
+                self.draw_screen()
                 return
+        if self.state >= DIFFED and self.current_search is not None and key_event.key is ESCAPE:
+            self.current_search = None
+            self.draw_screen()
+            return
+        action = self.shortcut_action(key_event)
+        if action is not None:
+            return self.perform_action(action)
 
     def on_resize(self, screen_size):
         self.screen_size = screen_size
@@ -374,7 +480,7 @@ type=list
 --override -o
 type=list
 Override individual configuration options, can be specified multiple times.
-Syntax: |_ name=value|. For example: |_ -o background=gray|
+Syntax: :italic:`name=value`. For example: :italic:`-o background=gray`
 
 '''.format, config_help=CONFIG_HELP.format(conf_name='diff', appname=appname))
 
@@ -385,12 +491,13 @@ def showwarning(message, category, filename, lineno, file=None, line=None):
 
 
 showwarning.warnings = []
+help_text = 'Show a side-by-side diff of the specified files/directories'
+usage = 'file_or_directory_left file_or_directory_right'
 
 
 def main(args):
     warnings.showwarning = showwarning
-    msg = 'Show a side-by-side diff of the specified files/directories'
-    args, items = parse_args(args[1:], OPTIONS, 'file_or_directory file_or_directory', msg, 'kitty +kitten diff')
+    args, items = parse_args(args[1:], OPTIONS, usage, help_text, 'kitty +kitten diff')
     if len(items) != 2:
         raise SystemExit('You must specify exactly two files/directories to compare')
     left, right = items
@@ -400,6 +507,9 @@ def main(args):
     opts = init_config(args)
     set_diff_command(opts.diff_cmd)
     lines_for_path.replace_tab_by = opts.replace_tab_by
+    for f in left, right:
+        if not os.path.exists(f):
+            raise SystemExit('{} does not exist'.format(f))
 
     loop = Loop()
     handler = DiffHandler(args, opts, left, right)
@@ -414,9 +524,12 @@ def main(args):
         raise SystemExit(loop.return_code)
 
 
-def handle_result(args, current_char, target_window_id, boss):
-    pass
-
-
 if __name__ == '__main__':
     main(sys.argv)
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = OPTIONS
+    sys.cli_docs['help_text'] = help_text
+elif __name__ == '__conf__':
+    from .config import all_options
+    sys.all_options = all_options

kittens/diff/patch.py

@@ -36,8 +36,12 @@ def set_diff_command(opt):
 def run_diff(file1, file2, context=3):
     # returns: ok, is_different, patch
     cmd = shlex.split(set_diff_command.cmd.replace('_CONTEXT_', str(context)))
+    # we resolve symlinks because git diff does not follow symlinks, while diff
+    # does. We want consistent behavior, also for integration with git difftool
+    # we always want symlinks to be followed.
+    path1, path2 = map(os.path.realpath, (file1, file2))
     p = subprocess.Popen(
-            cmd + [file1, file2],
+            cmd + [path1, path2],
             stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.DEVNULL)
     stdout, stderr = p.communicate()
     returncode = p.wait()

kittens/diff/render.py

@@ -9,7 +9,7 @@ from math import ceil
 
 from kitty.fast_data_types import truncate_point_for_length, wcswidth
 
-from ..tui.images import can_display_images, screen_size
+from ..tui.images import can_display_images
 from .collect import (
     Segment, data_for_path, highlights_for_path, is_image, lines_for_path,
     path_name_map, sanitize
@@ -371,12 +371,11 @@ def rename_lines(path, other_path, args, columns, margin_size):
 
 class Image:
 
-    def __init__(self, image_id, width, height, margin_size):
+    def __init__(self, image_id, width, height, margin_size, screen_size):
         self.image_id = image_id
         self.width, self.height = width, height
-        ss = screen_size()
-        self.rows = int(ceil(self.height / ss.cell_height))
-        self.columns = int(ceil(self.width / ss.cell_width))
+        self.rows = int(ceil(self.height / screen_size.cell_height))
+        self.columns = int(ceil(self.width / screen_size.cell_width))
         self.margin_size = margin_size
 
 
@@ -400,7 +399,7 @@ def render_image(path, is_left, available_cols, margin_size, image_manager):
         lnum += 1
 
     try:
-        image_id, width, height = image_manager.send_image(path, available_cols - margin_size, screen_size().rows - 2)
+        image_id, width, height = image_manager.send_image(path, available_cols - margin_size, image_manager.screen_size.rows - 2)
     except Exception as e:
         yield from yield_split(_('Failed to render image, with error:'))
         yield from yield_split(' '.join(str(e).splitlines()))
@@ -409,7 +408,7 @@ def render_image(path, is_left, available_cols, margin_size, image_manager):
             width, height, human_readable(len(data_for_path(path))))
     yield from yield_split(meta)
     bg_line = m + fmt(' ' * available_cols)
-    img = Image(image_id, width, height, margin_size)
+    img = Image(image_id, width, height, margin_size, image_manager.screen_size)
     for r in range(img.rows):
         yield bg_line, Reference(path, LineRef(lnum)), ImagePlacement(img, r)
         lnum += 1
@@ -448,7 +447,7 @@ def render_diff(collection, diff_map, args, columns, image_manager):
             if patch is not None:
                 largest_line_number = max(largest_line_number, patch.largest_line_number)
 
-    margin_size = max(3, len(str(largest_line_number)) + 1)
+    margin_size = render_diff.margin_size = max(3, len(str(largest_line_number)) + 1)
     last_item_num = len(collection) - 1
 
     for i, (path, item_type, other_path) in enumerate(collection):

kittens/diff/search.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+import re
+
+from kitty.fast_data_types import wcswidth
+
+from ..tui.operations import styled
+
+
+class BadRegex(ValueError):
+    pass
+
+
+class Search:
+
+    def __init__(self, opts, query, is_regex, is_backward):
+        self.matches = {}
+        self.count = 0
+        self.style = styled('|', fg=opts.search_fg, bg=opts.search_bg).split('|', 1)[0]
+        if not is_regex:
+            query = re.escape(query)
+        try:
+            self.pat = re.compile(query, flags=re.UNICODE | re.IGNORECASE)
+        except Exception:
+            raise BadRegex('Not a valid regex: {}'.format(query))
+
+    def __call__(self, diff_lines, margin_size, cols):
+        self.matches = {}
+        self.count = 0
+        half_width = cols // 2
+        strip_pat = re.compile('\033[[].*?m')
+        right_offset = half_width + 1 + margin_size
+        find = self.pat.finditer
+        for i, line in enumerate(diff_lines):
+            text = strip_pat.sub('', line.text)
+            left, right = text[margin_size:half_width + 1], text[right_offset:]
+            matches = []
+
+            def add(which, offset):
+                for m in find(which):
+                    before = which[:m.start()]
+                    matches.append((wcswidth(before) + offset, m.group()))
+                    self.count += 1
+
+            add(left, margin_size)
+            add(right, right_offset)
+            if matches:
+                self.matches[i] = matches
+        return bool(self.matches)
+
+    def __contains__(self, i):
+        return i in self.matches
+
+    def __len__(self):
+        return self.count
+
+    def highlight_line(self, write, line_num):
+        highlights = self.matches.get(line_num)
+        if not highlights:
+            return False
+        write(self.style)
+        for start, text in highlights:
+            write('\r\x1b[{}C{}'.format(start, text))
+        write('\x1b[m')
+        return True

kittens/hints/main.py

@@ -6,8 +6,9 @@ import os
 import re
 import string
 import sys
-from functools import lru_cache, partial
+from functools import lru_cache
 from gettext import gettext as _
+from itertools import repeat
 
 from kitty.cli import parse_args
 from kitty.fast_data_types import set_clipboard_string
@@ -23,7 +24,7 @@ HINT_ALPHABET = string.digits + string.ascii_lowercase
 screen_size = screen_size_function()
 
 
-class Mark(object):
+class Mark:
 
     __slots__ = ('index', 'start', 'end', 'text')
 
@@ -62,8 +63,10 @@ def highlight_mark(m, text, current_input):
     )
 
 
-def render(text, current_input, all_marks):
+def render(text, current_input, all_marks, ignore_mark_indices):
     for mark in reversed(all_marks):
+        if mark.index in ignore_mark_indices:
+            continue
         mtext = highlight_mark(mark, text[mark.start:mark.end], current_input)
         text = text[:mark.start] + mtext + text[mark.end:]
 
@@ -77,11 +80,16 @@ class Hints(Handler):
     def __init__(self, text, all_marks, index_map, args):
         self.text, self.index_map = text, index_map
         self.all_marks = all_marks
-        self.current_input = ''
-        self.current_text = None
+        self.ignore_mark_indices = set()
         self.args = args
         self.window_title = _('Choose URL') if args.type == 'url' else _('Choose text')
-        self.chosen = None
+        self.multiple = args.multiple
+        self.chosen = []
+        self.reset()
+
+    def reset(self):
+        self.current_input = ''
+        self.current_text = None
 
     def init_terminal_state(self):
         self.cmd.set_cursor_visible(False)
@@ -100,13 +108,17 @@ class Hints(Handler):
                 changed = True
         if changed:
             matches = [
-                m.text for idx, m in self.index_map.items()
+                m for idx, m in self.index_map.items()
                 if encode_hint(idx).startswith(self.current_input)
             ]
             if len(matches) == 1:
-                self.chosen = matches[0]
-                self.quit_loop(0)
-                return
+                self.chosen.append(matches[0].text)
+                if self.multiple:
+                    self.ignore_mark_indices.add(matches[0].index)
+                    self.reset()
+                else:
+                    self.quit_loop(0)
+                    return
             self.current_text = None
             self.draw_screen()
 
@@ -118,15 +130,20 @@ class Hints(Handler):
         elif key_event is enter_key and self.current_input:
             try:
                 idx = decode_hint(self.current_input)
-                self.chosen = self.index_map[idx].text
+                self.chosen.append(self.index_map[idx].text)
+                self.ignore_mark_indices.add(idx)
             except Exception:
                 self.current_input = ''
                 self.current_text = None
                 self.draw_screen()
             else:
-                self.quit_loop(0)
+                if self.multiple:
+                    self.reset()
+                    self.draw_screen()
+                else:
+                    self.quit_loop(0)
         elif key_event.key is ESCAPE:
-            self.quit_loop(1)
+            self.quit_loop(0 if self.multiple else 1)
 
     def on_interrupt(self):
         self.quit_loop(1)
@@ -140,7 +157,7 @@ class Hints(Handler):
 
     def draw_screen(self):
         if self.current_text is None:
-            self.current_text = render(self.text, self.current_input, self.all_marks)
+            self.current_text = render(self.text, self.current_input, self.all_marks, self.ignore_mark_indices)
         self.cmd.clear_screen()
         self.write(self.current_text)
 
@@ -173,12 +190,16 @@ def url(text, s, e):
             e -= len(url) - idx
     while text[e - 1] in '.,?!' and e > 1:  # remove trailing punctuation
         e -= 1
+    # Restructured Text URLs
+    if e > 3 and text[e-2:e] == '`_':
+        e -= 2
     # Remove trailing bracket if matched by leading bracket
     if s > 0 and e < len(text) and text[s-1] in opening_brackets and text[e-1] == closing_bracket_map[text[s-1]]:
         e -= 1
     # Remove trailing quote if matched by leading quote
     if s > 0 and e < len(text) and text[s-1] in '\'"' and text[e-1] == text[s-1]:
         e -= 1
+
     return s, e
 
 
@@ -239,6 +260,8 @@ def functions_for(args):
         post_processors.extend((brackets, quotes))
     elif args.type == 'line':
         pattern = '(?m)^\\s*(.+)[\\s\0]*$'
+    elif args.type == 'hash':
+        pattern = '[0-9a-f]{7,128}'
     elif args.type == 'word':
         chars = args.word_characters
         if chars is None:
@@ -253,8 +276,12 @@ def functions_for(args):
 
 def convert_text(text, cols):
     lines = []
+    empty_line = '\0' * cols
     for full_line in text.split('\n'):
         if full_line:
+            if not full_line.rstrip('\r'):  # empty lines
+                lines.extend(repeat(empty_line, len(full_line)))
+                continue
             for line in full_line.split('\r'):
                 if line:
                     lines.append(line.ljust(cols, '\0'))
@@ -294,25 +321,26 @@ def run(args, text):
 
 
 # CLI {{{
-OPTIONS = partial(r'''
+OPTIONS = r'''
 --program
 default=default
 What program to use to open matched text. Defaults to the default open program
-for the operating system.  Use a value of - to paste the match into the
-terminal window instead. A value of @ will copy the match to the clipboard.
+for the operating system.  Use a value of :file:`-` to paste the match into the
+terminal window instead. A value of :file:`@` will copy the match to the clipboard.
 
 
 --type
 default=url
-choices=url,regex,path,line,word
+choices=url,regex,path,line,hash,word
 The type of text to search for.
 
 
 --regex
 default=(?m)^\s*(.+)\s*$
-The regular expression to use when --type=regex.  If you specify a group in the
-regular expression only the group will be matched. This allow you to match text
-ignoring a prefix/suffix, as needed. The default expression matches lines.
+The regular expression to use when :option:`kitty +kitten hints --type`=regex.
+If you specify a group in the regular expression only the group
+will be matched. This allow you to match text ignoring a prefix/suffix, as
+needed. The default expression matches lines.
 
 
 --url-prefixes
@@ -330,12 +358,19 @@ Defaults to the select_by_word_characters setting from kitty.conf.
 default=3
 type=int
 The minimum number of characters to consider a match.
-'''.format, ','.join(sorted(URL_PREFIXES)))
+
+
+--multiple
+type=bool-set
+Select multiple matches and perform the action on all of them together at the end.
+In this mode, press :kbd:`Esc` to finish selecting.
+'''.format(','.join(sorted(URL_PREFIXES))).format
+help_text = 'Select text from the screen using the keyboard. Defaults to searching for URLs.'
+usage = ''
 
 
 def parse_hints_args(args):
-    msg = 'Select text from the screen using the keyboard. Defaults to searching for URLs.'
-    return parse_args(args, OPTIONS, '', msg, 'hints')
+    return parse_args(args, OPTIONS, usage, help_text, 'kitty +kitten hints')
 
 
 def main(args):
@@ -364,18 +399,22 @@ def main(args):
 
 def handle_result(args, data, target_window_id, boss):
     program = data['program']
+    matches = tuple(filter(None, data['match']))
     if program == '-':
         w = boss.window_id_map.get(target_window_id)
         if w is not None:
-            w.paste(data['match'])
+            for m in matches:
+                w.paste(m)
     elif program == '@':
-        set_clipboard_string(data['match'])
+        set_clipboard_string(matches[-1])
     else:
         cwd = None
         w = boss.window_id_map.get(target_window_id)
         if w is not None:
             cwd = w.cwd_of_child
-        boss.open_url(data['match'], None if program == 'default' else program, cwd=cwd)
+        program = None if program == 'default' else program
+        for m in matches:
+            boss.open_url(m, program, cwd=cwd)
 
 
 handle_result.type_of_input = 'screen'
@@ -386,4 +425,8 @@ if __name__ == '__main__':
     ans = main(sys.argv)
     if ans:
         print(ans)
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = OPTIONS
+    sys.cli_docs['help_text'] = help_text
 # }}}

kittens/hints/url_regex.py

@@ -1 +1 @@
-url_delimiters = '\x00-\x09\x0b-\x20\x7f-\xa0\xad\u0600-\u0605\u061c\u06dd\u070f\u08e2\u1680\u180e\u2000-\u200f\u2028-\u202f\u205f-\u2064\u2066-\u206f\u3000\ud800-\uf8ff\ufeff\ufff9-\ufffb\U000110bd\U0001bca0-\U0001bca3\U0001d173-\U0001d17a\U000e0001\U000e0020-\U000e007f\U000f0000-\U000ffffd\U00100000-\U0010fffd'  # noqa
+url_delimiters = '\x00-\x09\x0b-\x20\x7f-\xa0\xad\u0600-\u0605\u061c\u06dd\u070f\u08e2\u1680\u180e\u2000-\u200f\u2028-\u202f\u205f-\u2064\u2066-\u206f\u3000\ud800-\uf8ff\ufeff\ufff9-\ufffb\U000110bd\U000110cd\U0001bca0-\U0001bca3\U0001d173-\U0001d17a\U000e0001\U000e0020-\U000e007f\U000f0000-\U000ffffd\U00100000-\U0010fffd'  # noqa

kittens/icat/main.py

@@ -15,14 +15,14 @@ from tempfile import NamedTemporaryFile
 
 from kitty.cli import parse_args
 from kitty.constants import appname
-from kitty.utils import fit_image, read_with_timeout
+from kitty.utils import TTYIO, fit_image, screen_size_function
 
 from ..tui.images import (
-    ConvertFailed, NoImageMagick, OpenFailed, convert, fsenc, identify,
-    screen_size
+    ConvertFailed, NoImageMagick, OpenFailed, convert, fsenc, identify
 )
 from ..tui.operations import clear_images_on_screen, serialize_gr_command
 
+screen_size = None
 OPTIONS = '''\
 --align
 type=choices
@@ -34,14 +34,14 @@ Horizontal alignment for the displayed image.
 --place
 Choose where on the screen to display the image. The image will
 be scaled to fit into the specified rectangle. The syntax for
-specifying rectanges is <|_ width|>x<|_ height|>@<|_ left|>x<|_ top|>. All measurements
-are in cells (i.e. cursor positions) with the origin |_ (0, 0)| at
+specifying rectanges is <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>. All measurements
+are in cells (i.e. cursor positions) with the origin :italic:`(0, 0)` at
 the top-left corner of the screen.
 
 
 --scale-up
 type=bool-set
-When used in combination with |_ --place| it will cause images that
+When used in combination with :option:`--place` it will cause images that
 are smaller than the specified area to be scaled up to use as much
 of the specified area as possible.
 
@@ -56,8 +56,8 @@ type=choices
 choices=detect,file,stream
 default=detect
 Which mechanism to use to transfer images to the terminal. The default is to
-auto-detect. |_ file| means to use a temporary file and |_ stream| means to
-send the data via terminal escape codes. Note that if you use the |_ file|
+auto-detect. :italic:`file` means to use a temporary file and :italic:`stream` means to
+send the data via terminal escape codes. Note that if you use the :italic:`file`
 transfer mode and you are connecting over a remote session then image display
 will not work.
 
@@ -66,7 +66,7 @@ will not work.
 type=bool-set
 Detect support for image display in the terminal. If not supported, will exit
 with exit code 1, otherwise will exit with code 0 and print the supported
-transfer mode to stderr, which can be used with the |_ --transfer-mode| option.
+transfer mode to stderr, which can be used with the :option:`--transfer-mode` option.
 
 
 --detection-timeout
@@ -74,6 +74,13 @@ type=float
 default=10
 The amount of time (in seconds) to wait for a response form the terminal, when
 detecting image display support.
+
+
+--print-window-size
+type=bool-set
+Print out the window size as :italic:`widthxheight` (in pixels) and quit. This is a
+convenience method to query the window size if using kitty icat from a
+scripting language that cannot make termios calls.
 '''
 
 
@@ -222,7 +229,8 @@ def detect_support(wait_for=10, silent=False):
             f.write(b'abcd'), f.flush()
             write_gr_cmd(dict(a='q', s=1, v=1, i=1), standard_b64encode(b'abcd'))
             write_gr_cmd(dict(a='q', s=1, v=1, i=2, t='f'), standard_b64encode(f.name.encode(fsenc)))
-            read_with_timeout(more_needed, timeout=wait_for)
+            with TTYIO() as io:
+                io.recv(more_needed, timeout=float(wait_for))
     finally:
         if not silent:
             sys.stdout.buffer.write(b'\033[J'), sys.stdout.flush()
@@ -238,18 +246,29 @@ def parse_place(raw):
         return namedtuple('Place', 'width height left top')(w, h, l, t)
 
 
-def main(args=sys.argv):
-    msg = (
+help_text = (
         'A cat like utility to display images in the terminal.'
         ' You can specify multiple image files and/or directories.'
-        ' Directories are scanned recursively for image files.')
-    args, items = parse_args(args[1:], options_spec, 'image-file ...', msg, '{} icat'.format(appname))
+        ' Directories are scanned recursively for image files.'
+)
+usage = 'image-file ...'
 
+
+def main(args=sys.argv):
+    global screen_size
+    args, items = parse_args(args[1:], options_spec, usage, help_text, '{} +kitten icat'.format(appname))
+
+    if args.print_window_size:
+        screen_size_function.ans = None
+        with open('/dev/tty') as tty:
+            ss = screen_size_function(tty)()
+        print('{}x{}'.format(ss.width, ss.height), end='')
+        raise SystemExit(0)
+
+    if not sys.stdout.isatty():
+        sys.stdout = open('/dev/tty', 'w')
+    screen_size = screen_size_function()
     signal.signal(signal.SIGWINCH, lambda signum, frame: setattr(screen_size, 'changed', True))
-    if not sys.stdout.isatty() or not sys.stdin.isatty():
-        raise SystemExit(
-            'Must be run in a terminal, stdout and/or stdin is currently not a terminal'
-        )
     if screen_size().width == 0:
         if args.detect_support:
             raise SystemExit(1)
@@ -304,9 +323,9 @@ def main(args=sys.argv):
     raise SystemExit(1)
 
 
-def handle_result(args, current_char, target_window_id, boss):
-    pass
-
-
 if __name__ == '__main__':
     main()
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = options_spec
+    sys.cli_docs['help_text'] = help_text

kittens/panel/main.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+import subprocess
+import sys
+
+from kitty.constants import is_macos, is_wayland
+from kitty.cli import parse_args
+
+
+OPTIONS = r'''
+--lines
+type=int
+default=1
+The number of lines shown in the panel (the height of the panel). Applies to horizontal panels.
+
+
+--columns
+type=int
+default=20
+The number of columns shown in the panel (the width of the panel). Applies to vertical panels.
+
+
+--edge
+choices=top,bottom,left,right
+default=top
+Which edge of the screen to place the panel on. Note that some window managers
+(such as i3) do not support placing docked windows on the left and right edges.
+
+
+--config -c
+type=list
+Path to config file to use for kitty when drawing the panel.
+
+
+--override -o
+type=list
+Override individual kitty configuration options, can be specified multiple times.
+Syntax: :italic:`name=value`. For example: :option:`kitty +kitten panel -o` font_size=20
+'''.format
+
+
+args = None
+help_text = 'Use a command line program to draw a GPU accelerated panel on your X11 desktop'
+usage = 'program-to-run'
+
+
+def parse_panel_args(args):
+    return parse_args(args, OPTIONS, usage, help_text, 'kitty +kitten panel')
+
+
+def call_xprop(*cmd, silent=False):
+    cmd = ['xprop'] + list(cmd)
+    try:
+        cp = subprocess.run(cmd, stdout=subprocess.DEVNULL if silent else None)
+    except FileNotFoundError:
+        raise SystemExit('You must have the xprop program installed')
+    if cp.returncode != 0:
+        raise SystemExit(cp.returncode)
+
+
+def create_strut(
+    win_id,
+    left=0, right=0, top=0, bottom=0, left_start_y=0, left_end_y=0,
+    right_start_y=0, right_end_y=0, top_start_x=0, top_end_x=0,
+    bottom_start_x=0, bottom_end_x=0
+):
+    call_xprop(
+            '-id',
+            str(int(win_id)), '-format', '_NET_WM_STRUT_PARTIAL', '32cccccccccccc',
+            '-set', '_NET_WM_STRUT_PARTIAL',
+            '{left},{right},{top},{bottom},'
+            '{left_start_y},{left_end_y},{right_start_y},{right_end_y},'
+            '{top_start_x},{top_end_x},{bottom_start_x},{bottom_end_x}'.format(**locals())
+    )
+
+
+def create_top_strut(win_id, width, height):
+    create_strut(win_id, top=height, top_end_x=width)
+
+
+def create_bottom_strut(win_id, width, height):
+    create_strut(win_id, bottom=height, bottom_end_x=width)
+
+
+def create_left_strut(win_id, width, height):
+    create_strut(win_id, left=width, left_end_y=height)
+
+
+def create_right_strut(win_id, width, height):
+    create_strut(win_id, right=width, right_end_y=height)
+
+
+def setup_x11_window(win_id):
+    call_xprop(
+            '-id', str(win_id), '-format', '_NET_WM_WINDOW_TYPE', '32a',
+            '-set', '_NET_WM_WINDOW_TYPE', '_NET_WM_WINDOW_TYPE_DOCK'
+    )
+    func = globals()['create_{}_strut'.format(args.edge)]
+    func(win_id, initial_window_size_func.width, initial_window_size_func.height)
+
+
+def initial_window_size_func(opts, *a):
+    from kitty.fast_data_types import glfw_primary_monitor_size, set_smallest_allowed_resize
+
+    def initial_window_size(cell_width, cell_height, dpi_x, dpi_y):
+        monitor_width, monitor_height = glfw_primary_monitor_size()
+        if args.edge in {'top', 'bottom'}:
+            h = initial_window_size_func.height = cell_height * args.lines + 1
+            initial_window_size_func.width = monitor_width
+            set_smallest_allowed_resize(100, h)
+        else:
+            w = initial_window_size_func.width = cell_width * args.columns + 1
+            initial_window_size_func.height = monitor_height
+            set_smallest_allowed_resize(w, 100)
+        return initial_window_size_func.width, initial_window_size_func.height
+
+    return initial_window_size
+
+
+def main(sys_args):
+    global args
+    if is_macos or is_wayland:
+        raise SystemExit('Currently the panel kitten is supported only on X11 desktops')
+    call_xprop('-version', silent=True)  # ensure xprop is available
+    args, items = parse_panel_args(sys_args[1:])
+    if not items:
+        raise SystemExit('You must specify the program to run')
+    sys.argv = ['kitty']
+    if args.config:
+        sys.argv.append('--config={}'.format(args.config))
+    for override in args.override:
+        sys.argv.append('--override={}'.format(override))
+    sys.argv.extend(items)
+    from kitty.main import run_app, main
+    run_app.cached_values_name = 'panel'
+    run_app.first_window_callback = setup_x11_window
+    run_app.initial_window_size_func = initial_window_size_func
+    main()
+
+
+if __name__ == '__main__':
+    main(sys.argv)
+elif __name__ == '__doc__':
+    sys.cli_docs['usage'] = usage
+    sys.cli_docs['options'] = OPTIONS
+    sys.cli_docs['help_text'] = help_text

kittens/resize_window/main.py

@@ -126,10 +126,6 @@ def main(args):
     handler = Resize(args)
     loop.loop(handler)
     if handler.print_on_fail:
-        print(handler.print_on_fail)
+        print(handler.print_on_fail, file=sys.stderr)
         input('Press Enter to quit')
     raise SystemExit(loop.return_code)
-
-
-def handle_result(args, data, target_window_id, boss):
-    pass

kittens/runner.py

@@ -12,7 +12,7 @@ aliases = {'url_hints': 'hints'}
 
 
 def resolved_kitten(k):
-    return aliases.get(k, k)
+    return aliases.get(k, k).replace('-', '_')
 
 
 def import_kitten_main_module(config_dir, kitten):
@@ -28,11 +28,12 @@ def import_kitten_main_module(config_dir, kitten):
         code = compile(src, path, 'exec')
         g = {'__name__': 'kitten'}
         exec(code, g)
-        return {'start': g['main'], 'end': g['handle_result']}
+        hr = g.get('handle_result', lambda *a, **kw: None)
+        return {'start': g['main'], 'end': hr}
     else:
         kitten = resolved_kitten(kitten)
         m = importlib.import_module('kittens.{}.main'.format(kitten))
-        return {'start': m.main, 'end': m.handle_result}
+        return {'start': m.main, 'end': getattr(m, 'handle_result', lambda *a, **k: None)}
 
 
 def create_kitten_handler(kitten, orig_args):
@@ -75,15 +76,60 @@ def launch(args):
 def deserialize(output):
     import json
     if output.startswith('OK: '):
-        prefix, sz, rest = output.split(' ', 2)
-        return json.loads(rest[:int(sz)])
+        try:
+            prefix, sz, rest = output.split(' ', 2)
+            return json.loads(rest[:int(sz)])
+        except Exception:
+            raise ValueError('Failed to parse kitten output: {!r}'.format(output))
 
 
-def run_kitten(kitten):
+def run_kitten(kitten, run_name='__main__'):
     import runpy
     kitten = resolved_kitten(kitten)
     set_debug(kitten)
-    runpy.run_module('kittens.{}.main'.format(kitten), run_name='__main__')
+    try:
+        runpy.run_module('kittens.{}.main'.format(kitten), run_name=run_name)
+    except ImportError:
+        raise SystemExit('No kitten named {}'.format(kitten))
+
+
+def all_kitten_names():
+    ans = getattr(all_kitten_names, 'ans', None)
+    if ans is None:
+        n = []
+        import glob
+        base = os.path.dirname(os.path.abspath(__file__))
+        for x in glob.glob(os.path.join(base, '*', '__init__.py')):
+            q = os.path.basename(os.path.dirname(x))
+            if q != 'tui':
+                n.append(q)
+        all_kitten_names.ans = ans = frozenset(n)
+    return ans
+
+
+def list_kittens():
+    print('You must specify the name of a kitten to run')
+    print('Choose from:')
+    print()
+    for kitten in all_kitten_names():
+        print(kitten)
+
+
+def get_kitten_cli_docs(kitten):
+    sys.cli_docs = {}
+    run_kitten(kitten, run_name='__doc__')
+    ans = sys.cli_docs
+    del sys.cli_docs
+    if 'help_text' in ans and 'usage' in ans and 'options' in ans:
+        return ans
+
+
+def get_kitten_conf_docs(kitten):
+    sys.all_options = None
+    run_kitten(kitten, run_name='__conf__')
+    ans = sys.all_options
+    del sys.all_options
+    return ans
 
 
 def main():

kittens/show_error/main.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+import sys
+
+from kitty.cli import parse_args
+from ..tui.operations import styled
+
+
+OPTIONS = '''\
+--title
+default=ERROR
+The title for the error message.
+'''.format
+
+
+def real_main(args):
+    error_message = sys.stdin.buffer.read().decode('utf-8')
+    sys.stdin = open('/dev/tty')
+    msg = 'Show an error message'
+    args, items = parse_args(args, OPTIONS, '', msg, 'hints')
+    print(styled(args.title, fg_intense=True, fg='red', bold=True))
+    print()
+    print(error_message)
+    print()
+    input('Press Enter to close.')
+
+
+def main(args):
+    try:
+        real_main(args)
+    except KeyboardInterrupt:
+        pass
+    except Exception:
+        import traceback
+        traceback.print_exc()
+        input('Press Enter to close.')
+
+
+if __name__ == '__main__':
+    main(sys.argv)

kittens/ssh/main.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+import os
+import re
+import subprocess
+import sys
+
+SHELL_SCRIPT = '''\
+#!/bin/sh
+# macOS ships with an ancient version of tic that cannot read from stdin, so we
+# create a temp file for it
+tmp=$(mktemp /tmp/terminfo.XXXXXX)
+cat >$tmp << 'TERMEOF'
+TERMINFO
+TERMEOF
+
+tic_out=$(tic -x -o ~/.terminfo $tmp 2>&1)
+rc=$?
+rm $tmp
+if [ "$rc" != "0" ]; then echo "$tic_out"; exit 1; fi
+if [ -z "$USER" ]; then export USER=$(whoami); fi
+EXEC_CMD
+shell_name=$(basename $0)
+
+# We need to pass the first argument to the executed program with a leading -
+# to make sure the shell executes as a login shell. Note that not all shells
+# support exec -a so we use the below to try to detect such shells
+
+case "dash" in
+    *$shell_name*)
+        python=$(command -v python3)
+        if [ -z "$python" ]; then python=$(command -v python2); fi
+        if [ -z "$python" ]; then python=python; fi
+        exec $python -c "import os; os.execlp('$0', '-' '$shell_name')"
+    ;;
+esac
+
+exec -a "-$shell_name" "$0"
+'''
+
+
+def get_ssh_cli():
+    other_ssh_args, boolean_ssh_args = [], []
+    raw = subprocess.Popen(['ssh'], stderr=subprocess.PIPE).stderr.read().decode('utf-8')
+    for m in re.finditer(r'\[(.+?)\]', raw):
+        q = m.group(1)
+        if len(q) < 2 or q[0] != '-':
+            continue
+        if ' ' in q:
+            other_ssh_args.append(q[1])
+        else:
+            boolean_ssh_args.extend(q[1:])
+    return set('-' + x for x in boolean_ssh_args), set('-' + x for x in other_ssh_args)
+
+
+def parse_ssh_args(args):
+    boolean_ssh_args, other_ssh_args = get_ssh_cli()
+    passthrough_args = {'-' + x for x in 'Nnf'}
+    ssh_args = []
+    server_args = []
+    expecting_option_val = False
+    passthrough = False
+    for arg in args:
+        if len(server_args) > 1:
+            server_args.append(arg)
+            continue
+        if arg.startswith('-') and not expecting_option_val:
+            all_args = arg[1:]
+            for i, arg in enumerate(all_args):
+                arg = '-' + arg
+                if arg in passthrough_args:
+                    passthrough = True
+                if arg in boolean_ssh_args:
+                    ssh_args.append(arg)
+                    continue
+                if arg in other_ssh_args:
+                    if i != len(all_args) - 1:
+                        raise SystemExit('Option {} cannot occur in the middle'.format(arg))
+                    ssh_args.append(arg)
+                    expecting_option_val = True
+                    continue
+                raise SystemExit('Unknown option: {}'.format(arg))
+            continue
+        if expecting_option_val:
+            ssh_args.append(arg)
+            expecting_option_val = False
+            continue
+        server_args.append(arg)
+    if not server_args:
+        raise SystemExit('Must specify server to connect to')
+    return ssh_args, server_args, passthrough
+
+
+def main(args):
+    ssh_args, server_args, passthrough = parse_ssh_args(args[1:])
+    if passthrough:
+        cmd = ['ssh'] + ssh_args + server_args
+    else:
+        terminfo = subprocess.check_output(['infocmp']).decode('utf-8')
+        sh_script = SHELL_SCRIPT.replace('TERMINFO', terminfo, 1)
+        if len(server_args) > 1:
+            command_to_execute = ["'{}'".format(c.replace("'", """'"'"'""")) for c in server_args[1:]]
+            command_to_execute = 'cmd=({}); exec "$cmd"'.format(' '.join(command_to_execute))
+        else:
+            command_to_execute = ''
+        sh_script = sh_script.replace('EXEC_CMD', command_to_execute)
+        cmd = ['ssh'] + ssh_args + ['-t', server_args[0], sh_script] + server_args[1:]
+    os.execvp('ssh', cmd)
+
+
+if __name__ == '__main__':
+    main(sys.argv)

kittens/tui/handler.py

@@ -18,6 +18,19 @@ class Handler:
         self.cmd = commander(self)
         self.image_manager = image_manager
 
+    def add_shortcut(self, action, key, mods=None, is_text=False):
+        if not hasattr(self, '_text_shortcuts'):
+            self._text_shortcuts, self._key_shortcuts = {}, {}
+        if is_text:
+            self._text_shortcuts[key] = action
+        else:
+            self._key_shortcuts[(key, mods or 0)] = action
+
+    def shortcut_action(self, key_event_or_text):
+        if isinstance(key_event_or_text, str):
+            return self._text_shortcuts.get(key_event_or_text)
+        return self._key_shortcuts.get((key_event_or_text.key, key_event_or_text.mods))
+
     def __enter__(self):
         if self.image_manager is not None:
             self.image_manager.__enter__()
@@ -67,6 +80,9 @@ class Handler:
     def on_kitty_cmd_response(self, response):
         pass
 
+    def on_clipboard_response(self, text, from_primary=False):
+        pass
+
     def write(self, data):
         if isinstance(data, str):
             data = data.encode('utf-8')

kittens/tui/images.py

@@ -9,7 +9,7 @@ from base64 import standard_b64encode
 from collections import defaultdict, deque
 from itertools import count
 
-from kitty.utils import fit_image, screen_size_function
+from kitty.utils import fit_image
 
 from .operations import cursor
 
@@ -18,7 +18,6 @@ try:
     codecs.lookup(fsenc)
 except Exception:
     fsenc = 'utf-8'
-screen_size = screen_size_function()
 
 
 class ImageData:
@@ -123,6 +122,10 @@ class ImageManager:
     def next_image_id(self):
         return next(self.image_id_counter) + 2
 
+    @property
+    def screen_size(self):
+        return self.handler.screen_size
+
     def __enter__(self):
         import tempfile
         self.tdir = tempfile.mkdtemp(prefix='kitten-images-')
@@ -190,7 +193,7 @@ class ImageManager:
                 self.failed_images[path] = e
                 raise
         m = self.image_data[path]
-        ss = screen_size()
+        ss = self.screen_size
         if max_cols is None:
             max_cols = ss.cols
         if max_rows is None:

kittens/tui/line_edit.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+# vim:fileencoding=utf-8
+# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+
+from kitty.fast_data_types import truncate_point_for_length, wcswidth
+from kitty.key_encoding import RELEASE, HOME, END, BACKSPACE, DELETE, LEFT, RIGHT
+
+
+class LineEdit:
+
+    def __init__(self):
+        self.clear()
+
+    def clear(self):
+        self.current_input = ''
+        self.cursor_pos = 0
+        self.pending_bell = False
+
+    def split_at_cursor(self, delta=0):
+        pos = max(0, self.cursor_pos + delta)
+        x = truncate_point_for_length(self.current_input, pos) if pos else 0
+        before, after = self.current_input[:x], self.current_input[x:]
+        return before, after
+
+    def write(self, write, prompt=''):
+        if self.pending_bell:
+            write('\a')
+            self.pending_bell = False
+        write(prompt)
+        write(self.current_input)
+        write('\r\x1b[{}C'.format(self.cursor_pos + wcswidth(prompt)))
+
+    def add_text(self, text):
+        if self.current_input:
+            x = truncate_point_for_length(self.current_input, self.cursor_pos) if self.cursor_pos else 0
+            self.current_input = self.current_input[:x] + text + self.current_input[x:]
+        else:
+            self.current_input = text
+        self.cursor_pos += wcswidth(text)
+
+    def on_text(self, text, in_bracketed_paste):
+        self.add_text(text)
+
+    def backspace(self, num=1):
+        before, after = self.split_at_cursor()
+        nbefore = before[:-num]
+        if nbefore != before:
+            self.current_input = nbefore + after
+            self.cursor_pos = wcswidth(nbefore)
+            return True
+        self.pending_bell = True
+        return False
+
+    def delete(self, num=1):
+        before, after = self.split_at_cursor()
+        nafter = after[num:]
+        if nafter != after:
+            self.current_input = before + nafter
+            self.cursor_pos = wcswidth(before)
+            return True
+        self.pending_bell = True
+        return False
+
+    def _left(self):
+        if not self.current_input:
+            self.cursor_pos = 0
+            return
+        if self.cursor_pos:
+            before, after = self.split_at_cursor(-1)
+            self.cursor_pos = wcswidth(before)
+
+    def _right(self):
+        if not self.current_input:
+            self.cursor_pos = 0
+            return
+        max_pos = wcswidth(self.current_input)
+        if self.cursor_pos >= max_pos:
+            self.cursor_pos = max_pos
+            return
+        before, after = self.split_at_cursor(1)
+        self.cursor_pos += 1 + int(wcswidth(before) == self.cursor_pos)
+
+    def _move_loop(self, func, num):
+        before = self.cursor_pos
+        while func() and num > 0:
+            num -= 1
+        changed = self.cursor_pos != before
+        if not changed:
+            self.pending_bell = True
+        return changed
+
+    def left(self, num=1):
+        return self._move_loop(self._left, num)
+
+    def right(self, num=1):
+        return self._move_loop(self._right, num)
+
+    def home(self):
+        if self.cursor_pos:
+            self.cursor_pos = 0
+            return True
+        return False
+
+    def end(self):
+        orig = self.cursor_pos
+        self.cursor_pos = wcswidth(self.current_input) + 1
+        return self.cursor_pos != orig
+
+    def on_key(self, key_event):
+        if key_event.type is RELEASE:
+            return False
+        elif key_event.key is HOME:
+            return self.home()
+        elif key_event.key is END:
+            return self.end()
+        elif key_event.key is BACKSPACE:
+            self.backspace()
+            return True
+        elif key_event.key is DELETE:
+            self.delete()
+            return True
+        elif key_event.key is LEFT:
+            self.left()
+            return True
+        elif key_event.key is RIGHT:
+            self.right()
+            return True
+        return False

kittens/tui/loop.py

@@ -3,32 +3,30 @@
 # License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
 
 import codecs
-import fcntl
 import io
 import os
 import re
 import selectors
 import signal
 import sys
-import termios
-import tty
 from collections import namedtuple
 from contextlib import closing, contextmanager
 from functools import partial
 from queue import Empty, Queue
 
-from kitty.fast_data_types import parse_input_from_terminal, safe_pipe
+from kitty.fast_data_types import (
+    close_tty, normal_tty, open_tty, parse_input_from_terminal, raw_tty,
+    safe_pipe
+)
 from kitty.key_encoding import (
     ALT, CTRL, PRESS, RELEASE, REPEAT, SHIFT, C, D, backspace_key,
     decode_key_event, enter_key
 )
-from kitty.utils import screen_size_function
+from kitty.utils import screen_size_function, write_all
 
 from .handler import Handler
 from .operations import init_state, reset_state
 
-screen_size = screen_size_function()
-
 
 def debug(*a, **kw):
     from base64 import standard_b64encode
@@ -43,40 +41,21 @@ def debug(*a, **kw):
         fobj.flush()
 
 
-def write_all(fd, data):
-    if isinstance(data, str):
-        data = data.encode('utf-8')
-    while data:
-        n = os.write(fd, data)
-        if not n:
-            break
-        data = data[n:]
-
-
 class TermManager:
 
-    def __init__(self, input_fd, output_fd):
-        self.input_fd = input_fd
-        self.output_fd = output_fd
-        self.original_fl = fcntl.fcntl(self.input_fd, fcntl.F_GETFL)
+    def __init__(self):
         self.extra_finalize = None
-        self.isatty = os.isatty(self.input_fd)
-        if self.isatty:
-            self.original_termios = termios.tcgetattr(self.input_fd)
 
-    def set_state_for_loop(self):
-        write_all(self.output_fd, init_state())
-        fcntl.fcntl(self.input_fd, fcntl.F_SETFL, self.original_fl | os.O_NONBLOCK)
-        if self.isatty:
-            tty.setraw(self.input_fd)
+    def set_state_for_loop(self, set_raw=True):
+        if set_raw:
+            raw_tty(self.tty_fd, self.original_termios)
+        write_all(self.tty_fd, init_state())
 
     def reset_state_to_original(self):
-        if self.isatty:
-            termios.tcsetattr(self.input_fd, termios.TCSADRAIN, self.original_termios)
-        fcntl.fcntl(self.input_fd, fcntl.F_SETFL, self.original_fl)
+        normal_tty(self.tty_fd, self.original_termios)
         if self.extra_finalize:
-            write_all(self.output_fd, self.extra_finalize)
-        write_all(self.output_fd, reset_state())
+            write_all(self.tty_fd, self.extra_finalize)
+        write_all(self.tty_fd, reset_state())
 
     @contextmanager
     def suspend(self):
@@ -85,11 +64,37 @@ class TermManager:
         self.set_state_for_loop()
 
     def __enter__(self):
-        self.set_state_for_loop()
+        self.tty_fd, self.original_termios = open_tty()
+        self.set_state_for_loop(set_raw=False)
         return self
 
     def __exit__(self, *a):
         self.reset_state_to_original()
+        close_tty(self.tty_fd, self.original_termios)
+        del self.tty_fd, self.original_termios
+
+
+class SignalManager:
+
+    def __init__(self, on_sigwinch, on_sigterm, on_sigint):
+        self.on_sigwinch = on_sigwinch
+        self.on_sigterm = on_sigterm
+        self.on_sigint = on_sigint
+
+    def __enter__(self):
+        for x in ('winch', 'term', 'int'):
+            attr = 'on_sig' + x
+            handler = getattr(self, attr)
+            old_handler = signal.signal(getattr(signal, 'SIG' + x.upper()), handler)
+            setattr(self, attr, old_handler)
+
+    def __exit__(self, *a):
+        for x in ('winch', 'term', 'int'):
+            attr = 'on_sig' + x
+            val = getattr(self, attr)
+            if val is None:
+                val = signal.SIG_DFL
+            signal.signal(getattr(signal, 'SIG' + x.upper()), val)
 
 
 LEFT, MIDDLE, RIGHT, FOURTH, FIFTH = 1, 2, 4, 8, 16
@@ -152,25 +157,19 @@ class UnhandledException(Handler):
 
 class Loop:
 
-    def __init__(self, input_fd=None, output_fd=None,
+    def __init__(self,
                  sanitize_bracketed_paste='[\x03\x04\x0e\x0f\r\x07\x7f\x8d\x8e\x8f\x90\x9b\x9d\x9e\x9f]'):
-        self.input_fd = sys.stdin.fileno() if input_fd is None else input_fd
-        self.output_fd = sys.stdout.fileno() if output_fd is None else output_fd
         self.wakeup_read_fd, self.wakeup_write_fd = safe_pipe()
-        # For some reason on macOS the DefaultSelector fails when input_fd is
+        # For some reason on macOS the DefaultSelector fails when tty_fd is
         # open('/dev/tty')
         self.sel = s = selectors.PollSelector()
-        s.register(self.input_fd, selectors.EVENT_READ, self._read_ready)
-        s.register(
-            self.wakeup_read_fd, selectors.EVENT_READ, self._wakeup_ready
-        )
-        s.register(self.output_fd, selectors.EVENT_WRITE, self._write_ready)
+        s.register(self.wakeup_read_fd, selectors.EVENT_READ)
         self.return_code = 0
         self.read_allowed = True
         self.read_buf = ''
         self.decoder = codecs.getincrementaldecoder('utf-8')('ignore')
         try:
-            self.iov_limit = os.sysconf('SC_IOV_MAX') - 1
+            self.iov_limit = max(os.sysconf('SC_IOV_MAX') - 1, 255)
         except Exception:
             self.iov_limit = 255
         self.parse_input_from_terminal = partial(parse_input_from_terminal, self._on_text, self._on_dcs, self._on_csi, self._on_osc, self._on_pm, self._on_apc)
@@ -198,11 +197,11 @@ class Loop:
         self.jobs_queue.put(entry)
         self._wakeup_write(b'j')
 
-    def _read_ready(self, handler):
+    def _read_ready(self, handler, fd):
         if not self.read_allowed:
             return
         try:
-            data = os.read(self.input_fd, io.DEFAULT_BUFFER_SIZE)
+            data = os.read(fd, io.DEFAULT_BUFFER_SIZE)
         except BlockingIOError:
             return
         if not data:
@@ -236,7 +235,7 @@ class Loop:
                     self.handler.on_eot()
                 else:
                     self.handler.on_text(chunk, self.in_bracketed_paste)
-            else:
+            elif chunk:
                 self.handler.on_text(chunk, self.in_bracketed_paste)
 
     def _on_dcs(self, dcs):
@@ -265,7 +264,15 @@ class Loop:
         pass
 
     def _on_osc(self, osc):
-        pass
+        m = re.match(r'(\d+);', osc)
+        if m is not None:
+            code = int(m.group(1))
+            rest = osc[m.end():]
+            if code == 52:
+                where, rest = rest.partition(';')[::2]
+                from_primary = 'p' in where
+                from base64 import standard_b64decode
+                self.handler.on_clipboard_response(standard_b64decode(rest).decode('utf-8'), from_primary)
 
     def _on_apc(self, apc):
         if apc.startswith('K'):
@@ -286,12 +293,15 @@ class Loop:
             if self.handler.image_manager is not None:
                 self.handler.image_manager.handle_response(apc)
 
-    def _write_ready(self, handler):
+    def _write_ready(self, handler, fd):
         if len(handler.write_buf) > self.iov_limit:
             handler.write_buf[self.iov_limit - 1] = b''.join(handler.write_buf[self.iov_limit - 1:])
             del handler.write_buf[self.iov_limit:]
         sizes = tuple(map(len, handler.write_buf))
-        written = os.writev(self.output_fd, handler.write_buf)
+        try:
+            written = os.writev(fd, handler.write_buf)
+        except BlockingIOError:
+            return
         if not written:
             raise EOFError('The output stream is closed')
         if written >= sum(sizes):
@@ -309,11 +319,11 @@ class Loop:
                 break
             del handler.write_buf[:consumed]
 
-    def _wakeup_ready(self, handler):
-        data = os.read(self.wakeup_read_fd, 1024)
+    def _wakeup_ready(self, handler, fd):
+        data = os.read(fd, 1024)
         if b'r' in data:
-            screen_size.changed = True
-            handler.on_resize(screen_size())
+            self._get_screen_size.changed = True
+            handler.on_resize(self._get_screen_size())
         if b't' in data:
             handler.on_term()
         if b'i' in data:
@@ -351,63 +361,16 @@ class Loop:
     def wakeup(self):
         self._wakeup_write(b'1')
 
-    def _modify_output_selector(self, waiting_for_write):
+    def _modify_output_selector(self, tty_fd, waiting_for_write):
+        events = selectors.EVENT_READ
         if waiting_for_write:
-            try:
-                self.sel.register(self.output_fd, selectors.EVENT_WRITE, self._write_ready)
-            except KeyError:
-                pass
-        else:
-            try:
-                self.sel.unregister(self.output_fd)
-            except KeyError:
-                pass
+            events |= selectors.EVENT_WRITE
+        self.sel.modify(tty_fd, events)
 
-    def loop(self, handler):
+    def loop_impl(self, handler, tty_fd, image_manager=None, waiting_for_write=True):
+        read_ready, write_ready, wakeup_ready = self._read_ready, self._write_ready, self._wakeup_ready
         select = self.sel.select
-        tb = None
-        waiting_for_write = True
-        with closing(self.sel), TermManager(self.input_fd, self.output_fd) as term_manager:
-            signal.signal(signal.SIGWINCH, self._on_sigwinch)
-            signal.signal(signal.SIGTERM, self._on_sigterm)
-            signal.signal(signal.SIGINT, self._on_sigint)
-            handler.write_buf = []
-            handler._term_manager = term_manager
-            image_manager = None
-            if handler.image_manager_class is not None:
-                image_manager = handler.image_manager_class(handler)
-            keep_going = True
-            try:
-                handler._initialize(screen_size(), self.quit, self.wakeup, self.start_job, debug, image_manager)
-                with handler:
-                    while keep_going:
-                        has_data_to_write = bool(handler.write_buf)
-                        if not has_data_to_write and not self.read_allowed:
-                            break
-                        if has_data_to_write != waiting_for_write:
-                            waiting_for_write = has_data_to_write
-                            self._modify_output_selector(waiting_for_write)
-                        events = select()
-                        for key, mask in events:
-                            key.data(handler)
-            except Exception:
-                import traceback
-                tb = traceback.format_exc()
-                self.return_code = 1
-                keep_going = False
-
-            term_manager.extra_finalize = b''.join(handler.write_buf).decode('utf-8')
-
-            if tb is not None:
-                self._report_error_loop(tb, term_manager)
-
-    def _report_error_loop(self, tb, term_manager):
-        select = self.sel.select
-        waiting_for_write = False
-        handler = UnhandledException(tb)
-        handler.write_buf = []
-        handler._term_manager = term_manager
-        handler._initialize(screen_size(), self.quit, self.wakeup, self.start_job, debug)
+        handler._initialize(self._get_screen_size(), self.quit, self.wakeup, self.start_job, debug, image_manager)
         with handler:
             while True:
                 has_data_to_write = bool(handler.write_buf)
@@ -415,7 +378,41 @@ class Loop:
                     break
                 if has_data_to_write != waiting_for_write:
                     waiting_for_write = has_data_to_write
-                    self._modify_output_selector(waiting_for_write)
-                events = select()
-                for key, mask in events:
-                    key.data(handler)
+                    self._modify_output_selector(tty_fd, waiting_for_write)
+                for key, mask in select():
+                    fd = key.fd
+                    if fd == tty_fd:
+                        if mask & selectors.EVENT_READ:
+                            read_ready(handler, fd)
+                        if mask & selectors.EVENT_WRITE:
+                            write_ready(handler, fd)
+                    else:
+                        wakeup_ready(handler, fd)
+
+    def loop(self, handler):
+        tb = None
+        signal_manager = SignalManager(self._on_sigwinch, self._on_sigterm, self._on_sigint)
+        with closing(self.sel), TermManager() as term_manager, signal_manager:
+            self.sel.register(term_manager.tty_fd, selectors.EVENT_READ | selectors.EVENT_WRITE)
+            self._get_screen_size = screen_size_function(term_manager.tty_fd)
+            handler.write_buf = []
+            handler._term_manager = term_manager
+            image_manager = None
+            if handler.image_manager_class is not None:
+                image_manager = handler.image_manager_class(handler)
+            try:
+                self.loop_impl(handler, term_manager.tty_fd, image_manager)
+            except Exception:
+                import traceback
+                tb = traceback.format_exc()
+                self.return_code = 1
+
+            term_manager.extra_finalize = b''.join(handler.write_buf).decode('utf-8')
+            if tb is not None:
+                self._report_error_loop(tb, term_manager)
+
+    def _report_error_loop(self, tb, term_manager):
+        handler = UnhandledException(tb)
+        handler.write_buf = []
+        handler._term_manager = term_manager
+        self.loop_impl(handler, term_manager.tty_fd, waiting_for_write=False)

kittens/tui/operations.py

@@ -78,6 +78,13 @@ def set_cursor_position(x, y) -> str:  # (0, 0) is top left
     return '\033[{};{}H'.format(y + 1, x + 1)
 
 
+def set_cursor_shape(shape='block', blink=True) -> str:
+    val = {'block': 1, 'underline': 3, 'bar': 5}.get(shape, 1)
+    if not blink:
+        val += 1
+    return '\033[{} q'.format(val)
+
+
 def set_scrolling_region(screen_size=None, top=None, bottom=None) -> str:
     if screen_size is None:
         return '\033[r'
@@ -182,10 +189,11 @@ def init_state(alternate_screen=True):
         reset_mode('IRM') + reset_mode('DECKM') + reset_mode('DECSCNM') +
         set_mode('DECARM') + reset_mode('DECOM') + set_mode('DECAWM') +
         set_mode('DECTCEM') + reset_mode('MOUSE_BUTTON_TRACKING') +
-        reset_mode('MOUSE_MOTION_TRACKING') + reset_mode('MOUSE_MOVE_TRACKING')
-        + reset_mode('FOCUS_TRACKING') + reset_mode('MOUSE_UTF8_MODE') +
+        reset_mode('MOUSE_MOTION_TRACKING') + reset_mode('MOUSE_MOVE_TRACKING') +
+        reset_mode('FOCUS_TRACKING') + reset_mode('MOUSE_UTF8_MODE') +
         reset_mode('MOUSE_SGR_MODE') + reset_mode('MOUSE_UTF8_MODE') +
         set_mode('BRACKETED_PASTE') + set_mode('EXTENDED_KEYBOARD') +
+        '\033]30001\033\\' +
         '\033[*x'  # reset DECSACE to default region select
     )
     if alternate_screen:
@@ -200,6 +208,7 @@ def reset_state(normal_screen=True):
         ans += reset_mode('ALTERNATE_SCREEN')
     ans += RESTORE_PRIVATE_MODE_VALUES
     ans += RESTORE_CURSOR
+    ans += '\033]30101\033\\'
     return ans
 
 
@@ -218,19 +227,43 @@ def alternate_screen(f=None):
     print(reset_mode('ALTERNATE_SCREEN'), end='', file=f)
 
 
-def set_default_colors(fg=None, bg=None) -> str:
+def set_default_colors(fg=None, bg=None, cursor=None, select_bg=None, select_fg=None) -> str:
     ans = ''
-    if fg is None:
-        ans += '\x1b]110\x1b\\'
-    else:
-        ans += '\x1b]10;{}\x1b\\'.format(color_as_sharp(fg if isinstance(fg, Color) else to_color(fg)))
-    if bg is None:
-        ans += '\x1b]111\x1b\\'
-    else:
-        ans += '\x1b]11;{}\x1b\\'.format(color_as_sharp(bg if isinstance(bg, Color) else to_color(bg)))
+
+    def item(which, num):
+        nonlocal ans
+        if which is None:
+            ans += '\x1b]1{}\x1b\\'.format(num)
+        else:
+            ans += '\x1b]{};{}\x1b\\'.format(num, color_as_sharp(which if isinstance(which, Color) else to_color(which)))
+
+    item(fg, 10)
+    item(bg, 11)
+    item(cursor, 12)
+    item(select_bg, 17)
+    item(select_fg, 19)
     return ans
 
 
+def write_to_clipboard(data, use_primary=False) -> str:
+    if isinstance(data, str):
+        data = data.encode('utf-8')
+    from base64 import standard_b64encode
+    fmt = 'p' if use_primary else 'c'
+
+    def esc(chunk):
+        return '\x1b]52;{};{}\x07'.format(fmt, chunk)
+    ans = esc('!')  # clear clipboard buffer
+    for chunk in (data[i:i+512] for i in range(0, len(data), 512)):
+        chunk = standard_b64encode(chunk).decode('ascii')
+        ans += esc(chunk)
+    return ans
+
+
+def request_from_clipboard(use_primary=False) -> str:
+    return '\x1b]52;{};?\x07'.format('p' if use_primary else 'c')
+
+
 all_cmds = tuple(
         (name, obj) for name, obj in globals().items()
         if hasattr(obj, '__annotations__') and obj.__annotations__.get('return') is str)

kittens/unicode_input/main.py

@@ -9,13 +9,15 @@ from functools import lru_cache
 from gettext import gettext as _
 
 from kitty.config import cached_values_for
-from kitty.constants import config_dir, editor
+from kitty.constants import config_dir
+from kitty.utils import get_editor
 from kitty.fast_data_types import wcswidth
 from kitty.key_encoding import (
     DOWN, ESCAPE, F1, F2, F3, F4, F12, LEFT, RELEASE, RIGHT, SHIFT, TAB, UP,
-    backspace_key, enter_key
+    enter_key
 )
 
+from ..tui.line_edit import LineEdit
 from ..tui.handler import Handler
 from ..tui.loop import Loop
 from ..tui.operations import (
@@ -246,8 +248,8 @@ class UnicodeInput(Handler):
 
     def __init__(self, cached_values):
         self.cached_values = cached_values
+        self.line_edit = LineEdit()
         self.recent = list(self.cached_values.get('recent', DEFAULT_SET))
-        self.current_input = ''
         self.current_char = None
         self.prompt_template = '{}> '
         self.last_updated_code_point_at = None
@@ -268,9 +270,9 @@ class UnicodeInput(Handler):
             codepoints = load_favorites()
             q = self.mode, tuple(codepoints)
         elif self.mode is NAME:
-            q = self.mode, self.current_input
+            q = self.mode, self.line_edit.current_input
             if q != self.last_updated_code_point_at:
-                words = self.current_input.split()
+                words = self.line_edit.current_input.split()
                 words = [w for w in words if w != INDEX_CHAR]
                 index_words = [i for i, w in enumerate(words) if i > 0 and is_index(w)]
                 if index_words:
@@ -290,10 +292,10 @@ class UnicodeInput(Handler):
         self.current_char = None
         if self.mode is HEX:
             try:
-                if self.current_input.startswith(INDEX_CHAR) and len(self.current_input) > 1:
-                    self.current_char = chr(self.table.codepoint_at_hint(self.current_input[1:]))
+                if self.line_edit.current_input.startswith(INDEX_CHAR) and len(self.line_edit.current_input) > 1:
+                    self.current_char = chr(self.table.codepoint_at_hint(self.line_edit.current_input[1:]))
                 else:
-                    code = int(self.current_input, 16)
+                    code = int(self.line_edit.current_input, 16)
                     self.current_char = chr(code)
             except Exception:
                 pass
@@ -303,8 +305,8 @@ class UnicodeInput(Handler):
                 self.current_char = chr(cc)
         else:
             try:
-                if self.current_input:
-                    self.current_char = chr(self.table.codepoint_at_hint(self.current_input.lstrip(INDEX_CHAR)))
+                if self.line_edit.current_input:
+                    self.current_char = chr(self.table.codepoint_at_hint(self.line_edit.current_input.lstrip(INDEX_CHAR)))
             except Exception:
                 pass
         if self.current_char is not None:
@@ -365,8 +367,7 @@ class UnicodeInput(Handler):
             writeln(_('Enter the hex code for the character'))
         else:
             writeln(_('Enter the index for the character you want from the list below'))
-        self.write(self.prompt)
-        self.write(self.current_input)
+        self.line_edit.write(self.write, self.prompt)
         with cursor(self.write):
             writeln()
             writeln(self.choice_line)
@@ -384,14 +385,34 @@ class UnicodeInput(Handler):
         self.draw_screen()
 
     def on_text(self, text, in_bracketed_paste):
-        self.current_input += text
+        self.line_edit.on_text(text, in_bracketed_paste)
         self.refresh()
 
     def on_key(self, key_event):
-        if key_event is backspace_key:
-            self.current_input = self.current_input[:-1]
+        if self.mode is NAME and key_event.type is not RELEASE and not key_event.mods:
+            if key_event.key is TAB:
+                if key_event.mods == SHIFT:
+                    self.table.move_current(cols=-1), self.refresh()
+                elif not key_event.mods:
+                    self.table.move_current(cols=1), self.refresh()
+                return
+            elif key_event.key is LEFT and not key_event.mods:
+                self.table.move_current(cols=-1), self.refresh()
+                return
+            elif key_event.key is RIGHT and not key_event.mods:
+                self.table.move_current(cols=1), self.refresh()
+                return
+            elif key_event.key is UP and not key_event.mods:
+                self.table.move_current(rows=-1), self.refresh()
+                return
+            elif key_event.key is DOWN and not key_event.mods:
+                self.table.move_current(rows=1), self.refresh()
+                return
+
+        if self.line_edit.on_key(key_event):
             self.refresh()
-        elif key_event is enter_key:
+            return
+        if key_event is enter_key:
             self.quit_loop(0)
         elif key_event.type is RELEASE and not key_event.mods:
             if key_event.key is ESCAPE:
@@ -406,27 +427,13 @@ class UnicodeInput(Handler):
                 self.switch_mode(FAVORITES)
             elif key_event.key is F12 and self.mode is FAVORITES:
                 self.edit_favorites()
-        elif self.mode is NAME:
-            if key_event.key is TAB:
-                if key_event.mods == SHIFT:
-                    self.table.move_current(cols=-1), self.refresh()
-                elif not key_event.mods:
-                    self.table.move_current(cols=1), self.refresh()
-            elif key_event.key is LEFT and not key_event.mods:
-                self.table.move_current(cols=-1), self.refresh()
-            elif key_event.key is RIGHT and not key_event.mods:
-                self.table.move_current(cols=1), self.refresh()
-            elif key_event.key is UP and not key_event.mods:
-                self.table.move_current(rows=-1), self.refresh()
-            elif key_event.key is DOWN and not key_event.mods:
-                self.table.move_current(rows=1), self.refresh()
 
     def edit_favorites(self):
         if not os.path.exists(favorites_path):
             with open(favorites_path, 'wb') as f:
                 f.write(serialize_favorites(load_favorites()).encode('utf-8'))
         with self.suspend():
-            p = subprocess.Popen(editor + [favorites_path])
+            p = subprocess.Popen(get_editor() + [favorites_path])
             if p.wait() == 0:
                 load_favorites(refresh=True)
         self.init_terminal_state()
@@ -436,7 +443,7 @@ class UnicodeInput(Handler):
         if mode is not self.mode:
             self.mode = mode
             self.cached_values['mode'] = mode
-            self.current_input = ''
+            self.line_edit.clear()
             self.current_char = None
             self.choice_line = ''
             self.refresh()

kitty/borders.py

@@ -2,15 +2,23 @@
 # vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2016, Kovid Goyal <kovid at kovidgoyal.net>
 
-from functools import partial
 from itertools import chain
 
 from .fast_data_types import (
-    BORDERS_PROGRAM, add_borders_rect, compile_program, init_borders_program,
-    pt_to_px
+    BORDERS_PROGRAM, add_borders_rect, compile_program, init_borders_program
 )
 from .utils import load_shaders
 
+try:
+    from enum import IntFlag
+except Exception:
+    from enum import IntEnum as IntFlag
+
+
+class BorderColor(IntFlag):
+    # See the border vertex shader for how these flags become actual colors
+    default_bg, active, inactive, window_bg, bell = ((1 << i) for i in range(5))
+
 
 def vertical_edge(os_window_id, tab_id, color, width, top, bottom, left):
     add_borders_rect(os_window_id, tab_id, left, top, left + width, bottom, color)
@@ -20,15 +28,15 @@ def horizontal_edge(os_window_id, tab_id, color, height, left, right, top):
     add_borders_rect(os_window_id, tab_id, left, top, right, top + height, color)
 
 
-def edge(func, os_window_id, tab_id, color, sz, a, b):
-    return partial(func, os_window_id, tab_id, color, sz, a, b)
-
-
-def border(os_window_id, tab_id, color, sz, left, top, right, bottom):
-    horz = edge(horizontal_edge, os_window_id, tab_id, color, sz, left, right)
-    horz(top), horz(bottom - sz)  # top, bottom edges
-    vert = edge(vertical_edge, os_window_id, tab_id, color, sz, top, bottom)
-    vert(left), vert(right - sz)  # left, right edges
+def draw_edges(os_window_id, tab_id, colors, width, geometry, base_width=0):
+    left = geometry.left - (width + base_width)
+    top = geometry.top - (width + base_width)
+    right = geometry.right + (width + base_width)
+    bottom = geometry.bottom + (width + base_width)
+    horizontal_edge(os_window_id, tab_id, colors[1], width, left, right, top)
+    horizontal_edge(os_window_id, tab_id, colors[3], width, left, right, geometry.bottom + base_width)
+    vertical_edge(os_window_id, tab_id, colors[0], width, top, bottom, left)
+    vertical_edge(os_window_id, tab_id, colors[2], width, top, bottom, geometry.right + base_width)
 
 
 def load_borders_program():
@@ -39,11 +47,11 @@ def load_borders_program():
 
 class Borders:
 
-    def __init__(self, os_window_id, tab_id, opts):
+    def __init__(self, os_window_id, tab_id, opts, border_width, padding_width):
         self.os_window_id = os_window_id
         self.tab_id = tab_id
-        self.border_width = pt_to_px(opts.window_border_width)
-        self.padding_width = pt_to_px(opts.window_padding_width)
+        self.border_width = border_width
+        self.padding_width = padding_width
 
     def __call__(
         self,
@@ -53,28 +61,31 @@ class Borders:
         extra_blank_rects,
         draw_window_borders=True
     ):
-        add_borders_rect(self.os_window_id, self.tab_id, 0, 0, 0, 0, 1)
+        add_borders_rect(self.os_window_id, self.tab_id, 0, 0, 0, 0, BorderColor.default_bg)
         for br in chain(current_layout.blank_rects, extra_blank_rects):
-            add_borders_rect(self.os_window_id, self.tab_id, *br, 1)
+            add_borders_rect(self.os_window_id, self.tab_id, *br, BorderColor.default_bg)
         bw, pw = self.border_width, self.padding_width
-        fw = bw + pw
+        if bw + pw <= 0:
+            return
+        draw_borders = bw > 0 and draw_window_borders and len(windows) > 1
+        if draw_borders:
+            border_data = current_layout.resolve_borders(windows, active_window)
 
-        if fw > 0:
-            for w in windows:
-                g = w.geometry
-                if bw > 0 and draw_window_borders:
-                    # Draw the border rectangles
-                    color = 2 if w is active_window else (16 if w.needs_attention else 4)
-                    border(
-                        self.os_window_id, self.tab_id,
-                        color, bw, g.left - fw, g.top - fw, g.right + fw,
-                        g.bottom + fw
-                    )
-                if pw > 0:
-                    # Draw the background rectangles over the padding region
-                    color = w.screen.color_profile.default_bg
-                    border(
-                        self.os_window_id, self.tab_id,
-                        (color << 8) | 8, pw, g.left - pw, g.top - pw, g.right + pw,
-                        g.bottom + pw
-                    )
+        for i, w in enumerate(windows):
+            g = w.geometry
+            window_bg = w.screen.color_profile.default_bg
+            window_bg = (window_bg << 8) | BorderColor.window_bg
+            if draw_borders:
+                # Draw the border rectangles
+                if w is active_window:
+                    color = BorderColor.active
+                else:
+                    color = BorderColor.bell if w.needs_attention else BorderColor.inactive
+                colors = tuple(color if needed else window_bg for needed in next(border_data))
+                draw_edges(
+                    self.os_window_id, self.tab_id, colors, bw, g, base_width=pw)
+            if pw > 0:
+                # Draw the background rectangles over the padding region
+                colors = (window_bg, window_bg, window_bg, window_bg)
+                draw_edges(
+                    self.os_window_id, self.tab_id, colors, pw, g)

kitty/boss.py

@@ -11,38 +11,32 @@ from gettext import gettext as _
 from weakref import WeakValueDictionary
 
 from .cli import create_opts, parse_args
-from .config import (
-    MINIMUM_FONT_SIZE, initial_window_size, prepare_config_file_for_editing
-)
-from .config_utils import to_cmdline
+from .conf.utils import to_cmdline
+from .config import initial_window_size_func, prepare_config_file_for_editing
+from .config_data import MINIMUM_FONT_SIZE
 from .constants import (
-    appname, config_dir, editor, set_boss, supports_primary_selection
+    appname, config_dir, kitty_exe, set_boss, supports_primary_selection
 )
 from .fast_data_types import (
-    ChildMonitor, create_os_window, current_os_window, destroy_global_data,
-    destroy_sprite_map, get_clipboard_string,
-    glfw_post_empty_event, layout_sprite_map, mark_os_window_for_close,
-    set_clipboard_string, set_dpi_from_os_window, set_in_sequence_mode,
-    show_window, toggle_fullscreen, viewport_for_window
+    ChildMonitor, background_opacity_of, change_background_opacity,
+    create_os_window, current_os_window, destroy_global_data,
+    get_clipboard_string, glfw_post_empty_event, global_font_size,
+    mark_os_window_for_close, os_window_font_size, patch_global_colors,
+    set_clipboard_string, set_in_sequence_mode, toggle_fullscreen
 )
-from .fonts.render import prerender, resize_fonts, set_font_family
 from .keys import get_shortcut, shortcut_matches
+from .layout import set_draw_minimal_borders
 from .remote_control import handle_cmd
 from .rgb import Color, color_from_int
 from .session import create_session
 from .tabs import SpecialWindow, SpecialWindowInstance, TabManager
 from .utils import (
-    end_startup_notification, get_primary_selection, init_startup_notification,
-    log_error, open_url, parse_address_spec, remove_socket_file, safe_print,
-    set_primary_selection, single_instance
+    get_editor, get_primary_selection, log_error, open_url, parse_address_spec,
+    remove_socket_file, safe_print, set_primary_selection, single_instance,
+    startup_notification_handler
 )
 
 
-def initialize_renderer():
-    layout_sprite_map()
-    prerender()
-
-
 def listen_on(spec):
     import socket
     family, address, socket_path = parse_address_spec(spec)
@@ -82,12 +76,14 @@ class DumpCommands:  # {{{
 
 class Boss:
 
-    def __init__(self, os_window_id, opts, args, cached_values):
+    def __init__(self, os_window_id, opts, args, cached_values, new_os_window_trigger):
+        set_draw_minimal_borders(opts)
         self.window_id_map = WeakValueDictionary()
         self.startup_colors = {k: opts[k] for k in opts if isinstance(opts[k], Color)}
         self.pending_sequences = None
         self.cached_values = cached_values
         self.os_window_map = {}
+        self.os_window_death_actions = {}
         self.cursor_blinking = True
         self.shutting_down = False
         talk_fd = getattr(single_instance, 'socket', None)
@@ -101,28 +97,24 @@ class Boss:
             talk_fd, listen_fd
         )
         set_boss(self)
-        self.current_font_size = opts.font_size
-        set_font_family(opts)
         self.opts, self.args = opts, args
-        initialize_renderer()
-        startup_session = create_session(opts, args)
+        startup_session = create_session(opts, args, default_session=opts.startup_session)
+        self.keymap = self.opts.keymap.copy()
+        if new_os_window_trigger is not None:
+            self.keymap.pop(new_os_window_trigger, None)
         self.add_os_window(startup_session, os_window_id=os_window_id)
 
-    def add_os_window(self, startup_session, os_window_id=None, wclass=None, wname=None, size=None, startup_id=None):
-        dpi_changed = False
+    def add_os_window(self, startup_session, os_window_id=None, wclass=None, wname=None, opts_for_size=None, startup_id=None):
         if os_window_id is None:
-            w, h = initial_window_size(self.opts, self.cached_values) if size is None else size
+            opts_for_size = opts_for_size or self.opts
             cls = wclass or self.args.cls or appname
-            os_window_id = create_os_window(w, h, appname, wname or self.args.name or cls, cls)
-            if startup_id:
-                ctx = init_startup_notification(os_window_id, startup_id)
-            dpi_changed = show_window(os_window_id)
-            if startup_id:
-                end_startup_notification(ctx)
+            with startup_notification_handler(do_notify=startup_id is not None, startup_id=startup_id) as pre_show_callback:
+                os_window_id = create_os_window(
+                        initial_window_size_func(opts_for_size, self.cached_values),
+                        pre_show_callback,
+                        appname, wname or self.args.name or cls, cls)
         tm = TabManager(os_window_id, self.opts, self.args, startup_session)
         self.os_window_map[os_window_id] = tm
-        if dpi_changed:
-            self.on_dpi_change(os_window_id)
         return os_window_id
 
     def list_os_windows(self):
@@ -250,7 +242,9 @@ class Boss:
                 if not os.path.isabs(args.directory):
                     args.directory = os.path.join(msg['cwd'], args.directory)
                 session = create_session(opts, args, respect_cwd=True)
-                self.add_os_window(session, wclass=args.cls, wname=args.name, size=initial_window_size(opts, self.cached_values), startup_id=startup_id)
+                os_window_id = self.add_os_window(session, wclass=args.cls, wname=args.name, opts_for_size=opts, startup_id=startup_id)
+                if msg.get('notify_on_os_window_death'):
+                    self.os_window_death_actions[os_window_id] = partial(self.notify_on_os_window_death, msg['notify_on_os_window_death'])
             else:
                 log_error('Unknown message received from peer, ignoring')
 
@@ -314,52 +308,99 @@ class Boss:
             tm.activate_tab_at(x)
 
     def on_window_resize(self, os_window_id, w, h, dpi_changed):
-        tm = self.os_window_map.get(os_window_id)
-        if tm is not None:
-            if dpi_changed:
-                if set_dpi_from_os_window(os_window_id):
-                    self.on_dpi_change(os_window_id)
-                else:
-                    tm.resize()
-            else:
+        if dpi_changed:
+            self.on_dpi_change(os_window_id)
+        else:
+            tm = self.os_window_map.get(os_window_id)
+            if tm is not None:
                 tm.resize()
 
-    def increase_font_size(self):
-        self.set_font_size(
-            min(
-                self.opts.font_size * 5, self.current_font_size +
-                self.opts.font_size_delta))
+    def increase_font_size(self):  # legacy
+        cfs = global_font_size()
+        self.set_font_size(min(self.opts.font_size * 5, cfs + 2.0))
 
-    def decrease_font_size(self):
-        self.set_font_size(self.current_font_size - self.opts.font_size_delta)
+    def decrease_font_size(self):  # legacy
+        cfs = global_font_size()
+        self.set_font_size(max(MINIMUM_FONT_SIZE, cfs - 2.0))
 
-    def restore_font_size(self):
+    def restore_font_size(self):  # legacy
         self.set_font_size(self.opts.font_size)
 
-    def _change_font_size(self, new_size=None, on_dpi_change=False):
-        if new_size is not None:
-            self.current_font_size = new_size
-        old_cell_width, old_cell_height = viewport_for_window()[-2:]
-        windows = tuple(filter(None, self.window_id_map.values()))
-        resize_fonts(self.current_font_size, on_dpi_change=on_dpi_change)
-        layout_sprite_map()
-        prerender()
-        for window in windows:
-            window.screen.rescale_images(old_cell_width, old_cell_height)
-            window.screen.refresh_sprite_positions()
-        for tm in self.os_window_map.values():
-            tm.resize()
-            tm.refresh_sprite_positions()
-        glfw_post_empty_event()
+    def set_font_size(self, new_size):  # legacy
+        self.change_font_size(True, None, new_size)
 
-    def set_font_size(self, new_size):
-        new_size = max(MINIMUM_FONT_SIZE, new_size)
-        if new_size == self.current_font_size:
-            return
-        self._change_font_size(new_size)
+    def change_font_size(self, all_windows, increment_operation, amt):
+        def calc_new_size(old_size):
+            new_size = old_size
+            if amt == 0:
+                new_size = self.opts.font_size
+            else:
+                if increment_operation:
+                    new_size += (1 if increment_operation == '+' else -1) * amt
+                else:
+                    new_size = amt
+                new_size = max(MINIMUM_FONT_SIZE, min(new_size, self.opts.font_size * 5))
+            return new_size
+
+        if all_windows:
+            current_global_size = global_font_size()
+            new_size = calc_new_size(current_global_size)
+            if new_size != current_global_size:
+                global_font_size(new_size)
+            os_windows = tuple(self.os_window_map.keys())
+        else:
+            os_windows = []
+            w = self.active_window
+            if w is not None:
+                os_windows.append(w.os_window_id)
+        if os_windows:
+            final_windows = {}
+            for wid in os_windows:
+                current_size = os_window_font_size(wid)
+                if current_size:
+                    new_size = calc_new_size(current_size)
+                    if new_size != current_size:
+                        final_windows[wid] = new_size
+            if final_windows:
+                self._change_font_size(final_windows)
+
+    def _change_font_size(self, sz_map):
+        for os_window_id, sz in sz_map.items():
+            tm = self.os_window_map.get(os_window_id)
+            if tm is not None:
+                os_window_font_size(os_window_id, sz)
+                tm.resize()
 
     def on_dpi_change(self, os_window_id):
-        self._change_font_size()
+        tm = self.os_window_map.get(os_window_id)
+        if tm is not None:
+            sz = os_window_font_size(os_window_id)
+            if sz:
+                os_window_font_size(os_window_id, sz, True)
+                tm.resize()
+
+    def _set_os_window_background_opacity(self, os_window_id, opacity):
+        change_background_opacity(os_window_id, max(0.1, min(opacity, 1.0)))
+
+    def set_background_opacity(self, opacity):
+        window = self.active_window
+        if window is None or not opacity:
+            return
+        if not self.opts.dynamic_background_opacity:
+            return self.show_error(
+                    _('Cannot change background opacity'),
+                    _('You must set the dynamic_background_opacity option in kitty.conf to be able to change background opacity'))
+        os_window_id = window.os_window_id
+        if opacity[0] in '+-':
+            opacity = background_opacity_of(os_window_id)
+            if opacity is None:
+                return
+            opacity += float(opacity)
+        elif opacity == 'default':
+            opacity = self.opts.background_opacity
+        else:
+            opacity = float(opacity)
+        self._set_os_window_background_opacity(os_window_id, opacity)
 
     @property
     def active_tab_manager(self):
@@ -380,7 +421,7 @@ class Boss:
 
     def dispatch_special_key(self, key, scancode, action, mods):
         # Handles shortcuts, return True if the key was consumed
-        key_action = get_shortcut(self.opts.keymap, mods, key, scancode)
+        key_action = get_shortcut(self.keymap, mods, key, scancode)
         if key_action is None:
             sequences = get_shortcut(self.opts.sequence_map, mods, key, scancode)
             if sequences:
@@ -493,19 +534,36 @@ class Boss:
             tm.destroy()
         for window_id in tuple(w.id for w in self.window_id_map.values() if getattr(w, 'os_window_id', None) == os_window_id):
             self.window_id_map.pop(window_id, None)
+        action = self.os_window_death_actions.pop(os_window_id, None)
+        if action is not None:
+            action()
 
-    def display_scrollback(self, window, data):
+    def notify_on_os_window_death(self, address):
+        import socket
+        s = socket.socket(family=socket.AF_UNIX)
+        try:
+            s.connect(address)
+            s.sendall(b'c')
+            try:
+                s.shutdown(socket.SHUT_RDWR)
+            except EnvironmentError:
+                pass
+            s.close()
+        except Exception:
+            pass
+
+    def display_scrollback(self, window, data, cmd):
         tab = self.active_tab
         if tab is not None and window.overlay_for is None:
             tab.new_special_window(
                 SpecialWindow(
-                    self.opts.scrollback_pager, data, _('History'), overlay_for=window.id))
+                    cmd, data, _('History'), overlay_for=window.id))
 
     def edit_config_file(self, *a):
         confpath = prepare_config_file_for_editing()
         # On macOS vim fails to handle SIGWINCH if it occurs early, so add a
         # small delay.
-        cmd = ['kitty', '+runpy', 'import os, sys, time; time.sleep(0.05); os.execvp(sys.argv[1], sys.argv[1:])'] + editor + [confpath]
+        cmd = [kitty_exe(), '+runpy', 'import os, sys, time; time.sleep(0.05); os.execvp(sys.argv[1], sys.argv[1:])'] + get_editor() + [confpath]
         self.new_os_window(*cmd)
 
     def get_output(self, source_window, num_lines=1):
@@ -517,7 +575,7 @@ class Boss:
             output += str(s.linebuf.line(i))
         return output
 
-    def _run_kitten(self, kitten, args=()):
+    def _run_kitten(self, kitten, args=(), input_data=None):
         w = self.active_window
         tab = self.active_tab
         if w is not None and tab is not None and w.overlay_for is None:
@@ -525,21 +583,26 @@ class Boss:
             from kittens.runner import create_kitten_handler
             end_kitten = create_kitten_handler(kitten, orig_args)
             args[0:0] = [config_dir, kitten]
-            type_of_input = end_kitten.type_of_input
-            if type_of_input in ('text', 'history', 'ansi', 'ansi-history', 'screen', 'screen-history', 'screen-ansi', 'screen-ansi-history'):
-                data = w.as_text(
-                        as_ansi='ansi' in type_of_input,
-                        add_history='history' in type_of_input,
-                        add_wrap_markers='screen' in type_of_input
-                ).encode('utf-8')
-            elif type_of_input is None:
-                data = None
+            if input_data is None:
+                type_of_input = end_kitten.type_of_input
+                if type_of_input in ('text', 'history', 'ansi', 'ansi-history', 'screen', 'screen-history', 'screen-ansi', 'screen-ansi-history'):
+                    data = w.as_text(
+                            as_ansi='ansi' in type_of_input,
+                            add_history='history' in type_of_input,
+                            add_wrap_markers='screen' in type_of_input
+                    ).encode('utf-8')
+                elif type_of_input is None:
+                    data = None
+                else:
+                    raise ValueError('Unknown type_of_input: {}'.format(type_of_input))
             else:
-                raise ValueError('Unknown type_of_input: {}'.format(type_of_input))
+                data = input_data
+            if isinstance(data, str):
+                data = data.encode('utf-8')
             copts = {k: self.opts[k] for k in ('select_by_word_characters', 'open_url_with')}
             overlay_window = tab.new_special_window(
                 SpecialWindow(
-                    ['kitty', '+runpy', 'from kittens.runner import main; main()'] + args,
+                    [kitty_exe(), '+runpy', 'from kittens.runner import main; main()'] + args,
                     stdin=data,
                     env={
                         'KITTY_COMMON_OPTS': json.dumps(copts),
@@ -573,6 +636,9 @@ class Boss:
             args = ['--name=tab-title', '--message', _('Enter the new title for this tab below.'), 'do_set_tab_title', str(tab.id)]
             self._run_kitten('ask', args)
 
+    def show_error(self, title, msg):
+        self._run_kitten('show_error', ['--title', title], input_data=msg)
+
     def do_set_tab_title(self, title, tab_id):
         tm = self.active_tab_manager
         if tm is not None and title:
@@ -583,7 +649,7 @@ class Boss:
                     break
 
     def kitty_shell(self, window_type):
-        cmd = ['kitty', '@']
+        cmd = [kitty_exe(), '@']
         if window_type == 'tab':
             window = self._new_tab(cmd).active_window
         elif window_type == 'os_window':
@@ -621,7 +687,6 @@ class Boss:
         for tm in self.os_window_map.values():
             tm.destroy()
         self.os_window_map = {}
-        destroy_sprite_map()
         destroy_global_data()
 
     def paste_to_active_window(self, text):
@@ -753,3 +818,4 @@ class Boss:
                     setattr(self.opts, k, color_from_int(v))
         for tm in self.all_tab_managers:
             tm.tab_bar.patch_colors(spec)
+        patch_global_colors(spec, configured)