version 0.25.1

Fixes #5105

.github/FUNDING.yml

@@ -1,3 +1,4 @@
+github: kovidgoyal
 patreon: kovidgoyal
 liberapay: kovidgoyal
 custom: https://sw.kovidgoyal.net/kitty/support.html

.github/ISSUE_TEMPLATE/bug_report.md

@@ -22,7 +22,7 @@ If applicable, add screenshots to help explain your problem.
 
 **Environment details**
 ```
-Press Ctrl+Shift+F6 in kitty, to copy debug output about kitty and its
+Press Ctrl+Shift+F6 (cmd+option+comma on macOS) in kitty, to copy debug output about kitty and its
 configuration to the clipboard and paste it here. 
 
 On older versions of kitty, run kitty --debug-config instead

.github/workflows/ci.py

@@ -30,28 +30,29 @@ def install_deps():
     print('Installing kitty dependencies...')
     sys.stdout.flush()
     if is_macos:
-        items = (x.strip() for x in open('Brewfile').readlines() if not x.startswith('#'))
-        run('brew', 'install', *items)
+        items = (x.split()[1].strip('"') for x in open('Brewfile').readlines() if x.strip().startswith('brew '))
+        run('brew', 'install', 'fish', *items)
     else:
         run('sudo apt-get update')
-        run('sudo apt-get install -y libgl1-mesa-dev libxi-dev libxrandr-dev libxinerama-dev'
-            ' libxcursor-dev libxcb-xkb-dev libdbus-1-dev libxkbcommon-dev libharfbuzz-dev libx11-xcb-dev'
-            ' libpng-dev liblcms2-dev libfontconfig-dev libxkbcommon-x11-dev libcanberra-dev uuid-dev')
+        run('sudo apt-get install -y libgl1-mesa-dev libxi-dev libxrandr-dev libxinerama-dev ca-certificates'
+            ' libxcursor-dev libxcb-xkb-dev libdbus-1-dev libxkbcommon-dev libharfbuzz-dev libx11-xcb-dev zsh'
+            ' libpng-dev liblcms2-dev libfontconfig-dev libxkbcommon-x11-dev libcanberra-dev librsync-dev uuid-dev'
+            ' zsh bash dash')
+        # for some reason these directories are world writable which causes zsh
+        # compinit to break
+        run('sudo chmod -R og-w /usr/share/zsh')
     if is_bundle:
         install_bundle()
     else:
-        if is_macos:
-            # needed for zlib for pillow, should not be needed after pillow 8.0
-            os.environ['PKG_CONFIG_PATH'] = '/usr/local/opt/zlib/lib/pkgconfig'
-        cmd = 'pip3 install Pillow pygments'
+        cmd = 'python3 -m pip install Pillow pygments'
         if sys.version_info[:2] < (3, 7):
-            cmd += ' importlib-resources'
+            cmd += ' importlib-resources dataclasses'
         run(cmd)
 
 
 def build_kitty():
     python = shutil.which('python3') if is_bundle else sys.executable
-    cmd = '{} setup.py build --verbose'.format(python)
+    cmd = f'{python} setup.py build --verbose'
     if os.environ.get('KITTY_SANITIZE') == '1':
         cmd += ' --debug --sanitize'
     run(cmd)
@@ -62,8 +63,8 @@ def test_kitty():
 
 
 def package_kitty():
-    py = 'python3' if is_macos else 'python'
-    run(py + ' setup.py linux-package --update-check-interval=0 --verbose')
+    python = 'python3' if is_macos else 'python'
+    run(f'{python} setup.py linux-package --update-check-interval=0 --verbose')
     if is_macos:
         run('python3 setup.py kitty.app --update-check-interval=0 --verbose')
         run('kitty.app/Contents/MacOS/kitty +runpy "from kitty.constants import *; print(kitty_exe())"')
@@ -79,11 +80,11 @@ def replace_in_file(path, src, dest):
 def setup_bundle_env():
     global SW
     os.environ['SW'] = SW = '/Users/Shared/kitty-build/sw/sw' if is_macos else os.path.join(os.environ['GITHUB_WORKSPACE'], 'sw')
-    os.environ['PKG_CONFIG_PATH'] = SW + '/lib/pkgconfig'
+    os.environ['PKG_CONFIG_PATH'] = os.path.join(SW, 'lib', 'pkgconfig')
     if is_macos:
         os.environ['PATH'] = '{}:{}'.format('/usr/local/opt/sphinx-doc/bin', os.environ['PATH'])
     else:
-        os.environ['LD_LIBRARY_PATH'] = SW + '/lib'
+        os.environ['LD_LIBRARY_PATH'] = os.path.join(SW, 'lib')
         os.environ['PYTHONHOME'] = SW
     os.environ['PATH'] = '{}:{}'.format(os.path.join(SW, 'bin'), os.environ['PATH'])
 
@@ -114,7 +115,7 @@ def main():
         setup_bundle_env()
     else:
         if not is_macos and 'pythonLocation' in os.environ:
-            os.environ['LD_LIBRARY_PATH'] = '{}/lib'.format(os.environ['pythonLocation'])
+            os.environ['LD_LIBRARY_PATH'] = os.path.join(os.environ['pythonLocation'], 'lib')
     action = sys.argv[-1]
     if action in ('build', 'package'):
         install_deps()
@@ -125,7 +126,7 @@ def main():
     elif action == 'test':
         test_kitty()
     else:
-        raise SystemExit('Unknown action: ' + action)
+        raise SystemExit(f'Unknown action: {action}')
 
 
 if __name__ == '__main__':

.github/workflows/ci.yml

@@ -20,15 +20,15 @@ jobs:
                 cc: [gcc, clang]
                 include:
                     - python: a
-                      pyver: 3.6
+                      pyver: 3.7
                       sanitize: 0
 
                     - python: b
-                      pyver: 3.7
+                      pyver: 3.8
                       sanitize: 1
 
                     - python: c
-                      pyver: 3.8
+                      pyver: 3.9
                       sanitize: 1
 
 
@@ -42,11 +42,11 @@ jobs:
 
         steps:
             - name: Checkout source code
-              uses: actions/checkout@master
+              uses: actions/checkout@v3
               with:
                 fetch-depth: 10
             - name: Set up Python ${{ matrix.pyver }}
-              uses: actions/setup-python@master
+              uses: actions/setup-python@v3
               with:
                 python-version: ${{ matrix.pyver }}
 
@@ -63,7 +63,7 @@ jobs:
             CFLAGS: -funsigned-char
         steps:
             - name: Checkout source code
-              uses: actions/checkout@master
+              uses: actions/checkout@v3
               with:
                 fetch-depth: 10
 
@@ -71,12 +71,12 @@ jobs:
               run: if grep -Inr '\s$' kitty kitty_tests kittens docs *.py *.asciidoc *.rst .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
 
             - name: Set up Python
-              uses: actions/setup-python@master
+              uses: actions/setup-python@v3
               with:
                 python-version: 3.8
 
             - name: Install build-only deps
-              run: pip install flake8 mypy types-requests types-docutils sphinx
+              run: pip install -r docs/requirements.txt flake8 mypy types-requests types-docutils
 
             - name: Run pyflakes
               run: python -m flake8 --count .
@@ -88,10 +88,10 @@ jobs:
               run: python test.py mypy
 
             - name: Build man page
-              run: make FAIL_WARN=-W man
+              run: make FAIL_WARN=1 man
 
             - name: Build HTML docs
-              run: make FAIL_WARN=-W html
+              run: make FAIL_WARN=1 html
 
     bundle:
         name: Bundle test (${{ matrix.os }})

.github/workflows/codeql-analysis.yml

@@ -16,23 +16,18 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         # We must fetch at least the immediate parents so that if this is
         # a pull request then we can checkout the head.
         fetch-depth: 2
 
-    # If this run was triggered by a pull request event, then checkout
-    # the head of the pull request instead of the merge commit.
-    - run: git checkout HEAD^2
-      if: ${{ github.event_name == 'pull_request' }}
-
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
       uses: github/codeql-action/init@v1
-      # Override language selection by uncommenting this and choosing your languages
-      # with:
-      #   languages: go, javascript, csharp, python, cpp, java
+      with:
+        languages: python, c
+        setup-python-dependencies: false
 
     - name: Build kitty
       run: python3 .github/workflows/ci.py build

.gitignore

@@ -19,3 +19,4 @@ __pycache__/
 /.mypy_cache
 .DS_Store
 bypy/b
+bypy/virtual-machines.conf

Brewfile

@@ -1,6 +1,7 @@
-pkg-config
-zlib
-python
-imagemagick
-harfbuzz
-sphinx-doc
+brew "pkg-config"
+brew "zlib"
+brew "librsync"
+brew "python"
+brew "imagemagick"
+brew "harfbuzz"
+brew "sphinx-doc"

CHANGELOG.rst

@@ -1 +1 @@
-See https://sw.kovidgoyal.net/kitty/changelog.html
+See https://sw.kovidgoyal.net/kitty/changelog/

CONTRIBUTING.md

@@ -10,9 +10,9 @@ config to reproduce the issue with).
 
 ### Contributing code
 
-Install [the dependencies](https://sw.kovidgoyal.net/kitty/build.html#dependencies)
+Install [the dependencies](https://sw.kovidgoyal.net/kitty/build/#dependencies)
 using your favorite package manager. Build and run kitty [from
-source](https://sw.kovidgoyal.net/kitty/build.html#install-and-run-from-source).
+source](https://sw.kovidgoyal.net/kitty/build/#install-and-run-from-source).
 
 Make a fork, submit your Pull Request. If it's a large/controversial change, open an issue
 beforehand to discuss it, so that you don't waste your time making a pull

INSTALL.md

@@ -1,3 +1,3 @@
-To build from source: <https://sw.kovidgoyal.net/kitty/build.html>
+[To build from source](https://sw.kovidgoyal.net/kitty/build/)
 
-Pre-built binaries: <https://sw.kovidgoyal.net/kitty/binary.html>
+[Pre-built binaries](https://sw.kovidgoyal.net/kitty/binary/)

LICENSE

@@ -671,4 +671,4 @@ into proprietary programs.  If your program is a subroutine library, you
 may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
-<https://www.gnu.org/philosophy/why-not-lgpl.html>.
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

Makefile

@@ -5,6 +5,10 @@ ifdef VERBOSE
 	VVAL=--verbose
 endif
 
+ifdef FAIL_WARN
+export FAIL_WARN
+endif
+
 all:
 	python3 setup.py $(VVAL)
 
@@ -32,12 +36,22 @@ app:
 	python3 setup.py kitty.app $(VVAL)
 
 man:
-	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs man
+	$(MAKE) -C docs man
 
 html:
-	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs html
+	$(MAKE) -C docs html
+
+dirhtml:
+	$(MAKE) -C docs dirhtml
 
 linkcheck:
-	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs linkcheck
+	$(MAKE) -C docs linkcheck
+
+website:
+	./publish.py --only website
 
 docs: man html
+
+
+develop-docs:
+	$(MAKE) -C docs develop-docs

README.asciidoc

@@ -4,11 +4,11 @@ See https://sw.kovidgoyal.net/kitty/[the kitty website].
 
 image:https://github.com/kovidgoyal/kitty/workflows/CI/badge.svg["Build status", link="https://github.com/kovidgoyal/kitty/actions?query=workflow%3ACI"]
 
-https://sw.kovidgoyal.net/kitty/faq.html[Frequently Asked Questions]
+https://sw.kovidgoyal.net/kitty/faq/[Frequently Asked Questions]
 
 To ask other questions about kitty usage, use either the https://github.com/kovidgoyal/kitty/discussions/[discussions on GitHub] or the
 https://www.reddit.com/r/KittyTerminal[Reddit community]
 
 Packaging status in various repositories:
 
-image:https://repology.org/badge/vertical-allrepos/kitty.svg[https://repology.org/project/kitty/versions]
+image:https://repology.org/badge/vertical-allrepos/kitty.svg["Packaging status", link="https://repology.org/project/kitty/versions"]

__main__.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2015, Kovid Goyal <kovid at kovidgoyal.net>
 
 import os
@@ -24,20 +23,25 @@ def remote_control(args: List[str]) -> None:
 
 
 def runpy(args: List[str]) -> None:
+    if len(args) < 2:
+        raise SystemExit('Usage: kitty +runpy "some python code"')
     sys.argv = ['kitty'] + args[2:]
     exec(args[1])
 
 
 def hold(args: List[str]) -> None:
     import subprocess
-    import tty
-    from contextlib import suppress
-    ret = subprocess.Popen(args[1:]).wait()
-    with suppress(BaseException):
-        print('\n\x1b[1;32mPress any key to exit', end='', flush=True)
-    with suppress(BaseException):
-        tty.setraw(sys.stdin.fileno())
-        sys.stdin.buffer.read(1)
+    ret = 1
+    try:
+        ret = subprocess.Popen(args[1:]).wait()
+    except KeyboardInterrupt:
+        pass
+    except FileNotFoundError:
+        print(f'Could not find {args[1]!r} to execute', file=sys.stderr)
+    except Exception as e:
+        print(e, file=sys.stderr)
+    from kitty.utils import hold_till_enter
+    hold_till_enter()
     raise SystemExit(ret)
 
 
@@ -46,19 +50,56 @@ def complete(args: List[str]) -> None:
     complete_main(args[1:], entry_points, namespaced_entry_points)
 
 
+def open_urls(args: List[str]) -> None:
+    setattr(sys, 'cmdline_args_for_open', True)
+    sys.argv = ['kitty'] + args[1:]
+    from kitty.main import main as kitty_main
+    kitty_main()
+
+
 def launch(args: List[str]) -> None:
     import runpy
     sys.argv = args[1:]
-    exe = args[1]
+    try:
+        exe = args[1]
+    except IndexError:
+        raise SystemExit(
+            'usage: kitty +launch script.py [arguments to be passed to script.py ...]\n\n'
+            'script.py will be run with full access to kitty code. If script.py is '
+            'prefixed with a : it will be searched for in PATH'
+        )
     if exe.startswith(':'):
         import shutil
         q = shutil.which(exe[1:])
         if not q:
-            raise SystemExit('{} not found in PATH'.format(args[1][1:]))
+            raise SystemExit(f'{exe[1:]} not found in PATH')
         exe = q
+    if not os.path.exists(exe):
+        raise SystemExit(f'{exe} does not exist')
     runpy.run_path(exe, run_name='__main__')
 
 
+def shebang(args: List[str]) -> None:
+    script_path = args[1]
+    cmd = args[2:]
+    if cmd == ['__ext__']:
+        cmd = [os.path.splitext(script_path)[1][1:].lower()]
+    try:
+        f = open(script_path)
+    except FileNotFoundError:
+        raise SystemExit(f'The file {script_path} does not exist')
+    with f:
+        if f.read(2) == '#!':
+            line = f.readline().strip()
+            _plat = sys.platform.lower()
+            is_macos: bool = 'darwin' in _plat
+            if is_macos:
+                cmd = line.split(' ')
+            else:
+                cmd = line.split(' ', maxsplit=1)
+    os.execvp(cmd[0], cmd + [script_path])
+
+
 def run_kitten(args: List[str]) -> None:
     try:
         kitten = args[1]
@@ -80,18 +121,20 @@ def edit_config_file(args: List[str]) -> None:
 
 
 def namespaced(args: List[str]) -> None:
-    func = namespaced_entry_points[args[1]]
-    func(args[1:])
+    try:
+        func = namespaced_entry_points[args[1]]
+    except KeyError:
+        pass
+    else:
+        func(args[1:])
+        return
+    raise SystemExit(f'{args[1]} is not a known entry point. Choices are: ' + ', '.join(namespaced_entry_points))
 
 
 entry_points = {
     # These two are here for backwards compat
     'icat': icat,
     'list-fonts': list_fonts,
-    'runpy': runpy,
-    'launch': launch,
-    'kitten': run_kitten,
-    'edit-config': edit_config_file,
 
     '@': remote_control,
     '+': namespaced,
@@ -99,24 +142,30 @@ entry_points = {
 namespaced_entry_points = {k: v for k, v in entry_points.items() if k[0] not in '+@'}
 namespaced_entry_points['hold'] = hold
 namespaced_entry_points['complete'] = complete
+namespaced_entry_points['runpy'] = runpy
+namespaced_entry_points['launch'] = launch
+namespaced_entry_points['open'] = open_urls
+namespaced_entry_points['kitten'] = run_kitten
+namespaced_entry_points['edit-config'] = edit_config_file
+namespaced_entry_points['shebang'] = shebang
 
 
 def setup_openssl_environment() -> None:
-    # 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 https://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'
-            setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_FILE')
-        elif os.path.isdir('/etc/ssl/certs'):
-            os.environ['SSL_CERT_DIR'] = '/etc/ssl/certs'
-            setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_DIR')
+    # Use our bundled CA certificates instead of the system ones, since
+    # many systems come with no certificates in a useable form or have various
+    # locations for the certificates.
+    d = os.path.dirname
+    ext_dir: str = getattr(sys, 'kitty_extensions_dir')
+    if 'darwin' in sys.platform.lower():
+        cert_file = os.path.join(d(d(d(ext_dir))), 'cacert.pem')
+    else:
+        cert_file = os.path.join(d(ext_dir), 'cacert.pem')
+    os.environ['SSL_CERT_FILE'] = cert_file
+    setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_FILE')
 
 
 def main() -> None:
-    if getattr(sys, 'frozen', False) and 'darwin' not in sys.platform.lower():
+    if getattr(sys, 'frozen', False) and getattr(sys, 'kitty_extensions_dir', ''):
         setup_openssl_environment()
     first_arg = '' if len(sys.argv) < 2 else sys.argv[1]
     func = entry_points.get(first_arg)

build-terminfo

@@ -4,7 +4,6 @@
 
 import glob
 import os
-import re
 import shutil
 import subprocess
 import sys
@@ -13,11 +12,10 @@ import tempfile
 
 def compile_terminfo(base):
     with tempfile.TemporaryDirectory() as tdir:
-        proc = subprocess.run(['tic', '-x', '-o' + tdir, 'terminfo/kitty.terminfo'], check=True, stderr=subprocess.PIPE)
-        regex = '^"terminfo/kitty.terminfo", line [0-9]+, col [0-9]+, terminal \'xterm-kitty\': older tic versions may treat the description field as an alias$'
-        for error in proc.stderr.decode('utf-8').splitlines():
-            if not re.match(regex, error):
-                print(error, file=sys.stderr)
+        proc = subprocess.run(['tic', '-x', f'-o{tdir}', 'terminfo/kitty.terminfo'], capture_output=True)
+        if proc.returncode != 0:
+            sys.stderr.buffer.write(proc.stderr)
+            raise SystemExit(proc.returncode)
         tfiles = glob.glob(os.path.join(tdir, '*', 'xterm-kitty'))
         if not tfiles:
             raise SystemExit('tic failed to output the compiled kitty terminfo file')
@@ -40,6 +38,13 @@ def generate_terminfo():
 
     with open('terminfo/kitty.terminfo', 'w') as f:
         f.write(generate_terminfo())
+    proc = subprocess.run(['tic', '-CrT0', 'terminfo/kitty.terminfo'], capture_output=True)
+    if proc.returncode != 0:
+        sys.stderr.buffer.write(proc.stderr)
+        raise SystemExit(proc.returncode)
+    tcap = proc.stdout.decode('utf-8').splitlines()[-1]
+    with open('terminfo/kitty.termcap', 'w') as f:
+        f.write(tcap)
 
     compile_terminfo(os.path.join(base, 'terminfo'))
 

bypy/init_env.py

@@ -26,10 +26,11 @@ def initialize_constants():
     kitty_constants = {}
     src = read_src_file('constants.py')
     nv = re.search(r'Version\((\d+), (\d+), (\d+)\)', src)
-    kitty_constants['version'] = '%s.%s.%s' % (nv.group(1), nv.group(2), nv.group(3))
+    kitty_constants['version'] = f'{nv.group(1)}.{nv.group(2)}.{nv.group(3)}'
     kitty_constants['appname'] = re.search(
             r'appname: str\s+=\s+(u{0,1})[\'"]([^\'"]+)[\'"]', src
     ).group(2)
+    kitty_constants['cacerts_url'] = 'https://curl.haxx.se/ca/cacert.pem'
     return kitty_constants
 
 

bypy/linux.conf

@@ -1,3 +1,3 @@
-image 'https://partner-images.canonical.com/core/xenial/current/ubuntu-xenial-core-cloudimg-{}-root.tar.gz'
+image 'https://cloud-images.ubuntu.com/releases/bionic/release/ubuntu-18.04-server-cloudimg-{}.img'
 
 deps 'bison flex libxcursor-dev libxrandr-dev libxi-dev libxinerama-dev libgl1-mesa-dev libxcb-xkb-dev libfontconfig1-dev libdbus-1-dev'

bypy/linux/__main__.py

@@ -19,7 +19,11 @@ from bypy.freeze import (
 from bypy.utils import get_dll_path, mkdtemp, py_compile, walk
 
 j = os.path.join
-arch = 'x86_64' if is64bit else 'i686'
+machine = (os.uname()[4] or '').lower()
+if machine.startswith('arm64') or machine.startswith('aarch64'):
+    arch = 'arm64'
+else:
+    arch = 'x86_64' if is64bit else 'i686'
 self_dir = os.path.dirname(os.path.abspath(__file__))
 py_ver = '.'.join(map(str, python_major_minor_version()))
 iv = globals()['init_env']
@@ -29,12 +33,16 @@ kitty_constants = iv['kitty_constants']
 def binary_includes():
     return tuple(map(get_dll_path, (
             'expat', 'sqlite3', 'ffi', 'z', 'lzma', 'png16', 'lcms2', 'crypt',
-            'iconv', 'pcre', 'graphite2', 'glib-2.0', 'freetype',
+            'iconv', 'pcre', 'graphite2', 'glib-2.0', 'freetype', 'rsync',
             'harfbuzz', 'xkbcommon', 'xkbcommon-x11',
-            'ncursesw', 'readline', 'brotlicommon', 'brotlienc', 'brotlidec'
+            # fontconfig is not bundled because in typical brain dead Linux
+            # distro fashion, different distros use different default config
+            # paths for fontconfig.
+            'ncursesw', 'readline', 'brotlicommon', 'brotlienc', 'brotlidec',
+            'wayland-client', 'wayland-cursor',
         ))) + (
                 get_dll_path('bz2', 2), get_dll_path('ssl', 2), get_dll_path('crypto', 2),
-                get_dll_path('python' + py_ver, 2),
+                get_dll_path(f'python{py_ver}', 2),
         )
 
 
@@ -43,7 +51,7 @@ class Env:
     def __init__(self, package_dir):
         self.base = package_dir
         self.lib_dir = j(self.base, 'lib')
-        self.py_dir = j(self.lib_dir, 'python' + py_ver)
+        self.py_dir = j(self.lib_dir, f'python{py_ver}')
         os.makedirs(self.py_dir)
         self.bin_dir = j(self.base, 'bin')
         self.obj_dir = mkdtemp('launchers-')
@@ -88,11 +96,22 @@ def copy_libs(env):
     for x in binary_includes():
         dest = env.bin_dir if '/bin/' in x else env.lib_dir
         shutil.copy2(x, dest)
+        dest = os.path.join(dest, os.path.basename(x))
+        subprocess.check_call(['chrpath', '-d', dest])
+
+
+def add_ca_certs(env):
+    print('Downloading CA certs...')
+    from urllib.request import urlopen
+    cdata = urlopen(kitty_constants['cacerts_url']).read()
+    dest = os.path.join(env.lib_dir, 'cacert.pem')
+    with open(dest, 'wb') as f:
+        f.write(cdata)
 
 
 def copy_python(env):
     print('Copying python...')
-    srcdir = j(PREFIX, 'lib/python' + py_ver)
+    srcdir = j(PREFIX, f'lib/python{py_ver}')
 
     for x in os.listdir(srcdir):
         y = j(srcdir, x)
@@ -104,8 +123,7 @@ def copy_python(env):
             shutil.copy2(y, env.py_dir)
 
     srcdir = j(srcdir, 'site-packages')
-    site_packages_dir = j(env.py_dir, 'site-packages')
-    import_site_packages(srcdir, site_packages_dir)
+    import_site_packages(srcdir, env.py_dir)
 
     pdir = os.path.join(env.lib_dir, 'kitty-extensions')
     os.makedirs(pdir, exist_ok=True)
@@ -173,11 +191,11 @@ def strip_files(files, argv_max=(256 * 1024)):
 
 
 def strip_binaries(files):
-    print('Stripping %d files...' % len(files))
+    print(f'Stripping {len(files)} files...')
     before = sum(os.path.getsize(x) for x in files)
     strip_files(files)
     after = sum(os.path.getsize(x) for x in files)
-    print('Stripped %.1f MB' % ((before - after) / (1024 * 1024.)))
+    print('Stripped {:.1f} MB'.format((before - after) / (1024 * 1024.)))
 
 
 def create_tarfile(env, compression_level='9'):
@@ -189,7 +207,7 @@ def create_tarfile(env, compression_level='9'):
         if err.errno != errno.ENOENT:
             raise
     os.mkdir(base)
-    dist = os.path.join(base, '%s-%s-%s.tar' % (kitty_constants['appname'], kitty_constants['version'], arch))
+    dist = os.path.join(base, f'{kitty_constants["appname"]}-{kitty_constants["version"]}-{arch}.tar')
     with tarfile.open(dist, mode='w', format=tarfile.PAX_FORMAT) as tf:
         cwd = os.getcwd()
         os.chdir(env.base)
@@ -199,13 +217,13 @@ def create_tarfile(env, compression_level='9'):
         finally:
             os.chdir(cwd)
     print('Compressing archive...')
-    ans = dist.rpartition('.')[0] + '.txz'
+    ans = f'{dist.rpartition(".")[0]}.txz'
     start_time = time.time()
-    subprocess.check_call(['xz', '--threads=0', '-f', '-' + compression_level, dist])
+    subprocess.check_call(['xz', '--threads=0', '-f', f'-{compression_level}', dist])
     secs = time.time() - start_time
-    print('Compressed in %d minutes %d seconds' % (secs // 60, secs % 60))
-    os.rename(dist + '.xz', ans)
-    print('Archive %s created: %.2f MB' % (
+    print('Compressed in {} minutes {} seconds'.format(secs // 60, secs % 60))
+    os.rename(f'{dist}.xz', ans)
+    print('Archive {} created: {:.2f} MB'.format(
         os.path.basename(ans), os.stat(ans).st_size / (1024.**2)))
 
 
@@ -218,6 +236,7 @@ def main():
     build_launcher(env)
     files = find_binaries(env)
     fix_permissions(files)
+    add_ca_certs(env)
     if not args.dont_strip:
         strip_binaries(files)
     if not args.skip_tests:

bypy/macos/__main__.py

@@ -90,7 +90,7 @@ def strip_files(files, argv_max=(256 * 1024)):
 def files_in(folder):
     for record in os.walk(folder):
         for f in record[-1]:
-            yield os.path.join(record[0], f)
+            yield join(record[0], f)
 
 
 def expand_dirs(items, exclude=lambda x: x.endswith('.so')):
@@ -103,7 +103,7 @@ def expand_dirs(items, exclude=lambda x: x.endswith('.so')):
 
 
 def do_sign(app_dir):
-    with current_dir(os.path.join(app_dir, 'Contents')):
+    with current_dir(join(app_dir, 'Contents')):
         # Sign all .so files
         so_files = {x for x in files_in('.') if x.endswith('.so')}
         codesign(so_files)
@@ -153,7 +153,7 @@ class Freeze(object):
         self.to_strip = []
         self.warnings = []
         self.py_ver = py_ver
-        self.python_stdlib = join(self.resources_dir, 'Python', 'lib', 'python' + self.py_ver)
+        self.python_stdlib = join(self.resources_dir, 'Python', 'lib', f'python{self.py_ver}')
         self.site_packages = self.python_stdlib  # hack to avoid needing to add site-packages to path
         self.obj_dir = mkdtemp('launchers-')
 
@@ -170,16 +170,35 @@ class Freeze(object):
         self.add_stdlib()
         self.add_misc_libraries()
         self.freeze_python()
+        self.add_ca_certs()
         if not self.dont_strip:
             self.strip_files()
         if not self.skip_tests:
             self.run_tests()
         # self.run_shell()
 
-        ret = self.makedmg(self.build_dir, APPNAME + '-' + VERSION)
+        ret = self.makedmg(self.build_dir, f'{APPNAME}-{VERSION}')
 
         return ret
 
+    @flush
+    def add_ca_certs(self):
+        print('\nDownloading CA certs...')
+        from urllib.request import urlopen
+        cdata = None
+        for i in range(5):
+            try:
+                cdata = urlopen(kitty_constants['cacerts_url']).read()
+                break
+            except Exception as e:
+                print(f'Downloading CA certs failed with error: {e}, retrying...')
+
+        if cdata is None:
+            raise SystemExit('Downloading C certs failed, giving up')
+        dest = join(self.contents_dir, 'Resources', 'cacert.pem')
+        with open(dest, 'wb') as f:
+            f.write(cdata)
+
     @flush
     def strip_files(self):
         print('\nStripping files...')
@@ -187,7 +206,7 @@ class Freeze(object):
 
     @flush
     def run_tests(self):
-        iv['run_tests'](os.path.join(self.contents_dir, 'MacOS', 'kitty'))
+        iv['run_tests'](join(self.contents_dir, 'MacOS', 'kitty'))
 
     @flush
     def set_id(self, path_to_lib, new_id):
@@ -212,10 +231,10 @@ class Freeze(object):
     @flush
     def get_local_dependencies(self, path_to_lib):
         for x, is_id in self.get_dependencies(path_to_lib):
-            for y in (PREFIX + '/lib/', PREFIX + '/python/Python.framework/'):
+            for y in (f'{PREFIX}/lib/', f'{PREFIX}/python/Python.framework/', '@rpath/'):
                 if x.startswith(y):
-                    if y == PREFIX + '/python/Python.framework/':
-                        y = PREFIX + '/python/'
+                    if y == f'{PREFIX}/python/Python.framework/':
+                        y = f'{PREFIX}/python/'
                     yield x, x[len(y):], is_id
                     break
 
@@ -229,7 +248,7 @@ class Freeze(object):
         self.to_strip.append(path_to_lib)
         old_mode = flipwritable(path_to_lib)
         for dep, bname, is_id in self.get_local_dependencies(path_to_lib):
-            ndep = self.FID + '/' + bname
+            ndep = f'{self.FID}/{bname}'
             self.change_dep(dep, ndep, is_id, path_to_lib)
         ldeps = list(self.get_local_dependencies(path_to_lib))
         if ldeps:
@@ -242,7 +261,7 @@ class Freeze(object):
     @flush
     def add_python_framework(self):
         print('\nAdding Python framework')
-        src = join(PREFIX + '/python', 'Python.framework')
+        src = join(f'{PREFIX}/python', 'Python.framework')
         x = join(self.frameworks_dir, 'Python.framework')
         curr = os.path.realpath(join(src, 'Versions', 'Current'))
         currd = join(x, 'Versions', basename(curr))
@@ -252,12 +271,12 @@ class Freeze(object):
         shutil.copy2(join(curr, 'Python'), currd)
         self.set_id(
             join(currd, 'Python'),
-            self.FID + '/Python.framework/Versions/%s/Python' % basename(curr))
+            f'{self.FID}/Python.framework/Versions/{basename(curr)}/Python')
         # The following is needed for codesign
         with current_dir(x):
             os.symlink(basename(curr), 'Versions/Current')
             for y in ('Python', 'Resources'):
-                os.symlink('Versions/Current/%s' % y, y)
+                os.symlink(f'Versions/Current/{y}', y)
 
     @flush
     def install_dylib(self, path, set_id=True):
@@ -265,7 +284,7 @@ class Freeze(object):
         if set_id:
             self.set_id(
                 join(self.frameworks_dir, basename(path)),
-                self.FID + '/' + basename(path))
+                f'{self.FID}/{basename(path)}')
         self.fix_dependencies_in_lib(join(self.frameworks_dir, basename(path)))
 
     @flush
@@ -278,13 +297,14 @@ class Freeze(object):
                 'lcms2.2',
                 'crypto.1.1',
                 'ssl.1.1',
+                'rsync.2',
         ):
             print('\nAdding', x)
-            x = 'lib%s.dylib' % x
+            x = f'lib{x}.dylib'
             src = join(PREFIX, 'lib', x)
             shutil.copy2(src, self.frameworks_dir)
             dest = join(self.frameworks_dir, x)
-            self.set_id(dest, self.FID + '/' + x)
+            self.set_id(dest, f'{self.FID}/{x}')
             self.fix_dependencies_in_lib(dest)
 
     @flush
@@ -310,7 +330,7 @@ class Freeze(object):
     @flush
     def add_stdlib(self):
         print('\nAdding python stdlib')
-        src = PREFIX + '/python/Python.framework/Versions/Current/lib/python' + self.py_ver
+        src = f'{PREFIX}/python/Python.framework/Versions/Current/lib/python{self.py_ver}'
         dest = self.python_stdlib
         if not os.path.exists(dest):
             os.makedirs(dest)
@@ -334,19 +354,19 @@ class Freeze(object):
         kitty_dir = join(self.resources_dir, 'kitty')
         bases = ('kitty', 'kittens', 'kitty_tests')
         for x in bases:
-            dest = os.path.join(self.python_stdlib, x)
-            os.rename(os.path.join(kitty_dir, x), dest)
+            dest = join(self.python_stdlib, x)
+            os.rename(join(kitty_dir, x), dest)
             if x == 'kitty':
-                shutil.rmtree(os.path.join(dest, 'launcher'))
-        os.rename(os.path.join(kitty_dir, '__main__.py'), os.path.join(self.python_stdlib, 'kitty_main.py'))
-        shutil.rmtree(os.path.join(kitty_dir, '__pycache__'))
-        pdir = os.path.join(dirname(self.python_stdlib), 'kitty-extensions')
+                shutil.rmtree(join(dest, 'launcher'))
+        os.rename(join(kitty_dir, '__main__.py'), join(self.python_stdlib, 'kitty_main.py'))
+        shutil.rmtree(join(kitty_dir, '__pycache__'))
+        pdir = join(dirname(self.python_stdlib), 'kitty-extensions')
         os.mkdir(pdir)
         print('Extracting extension modules from', self.python_stdlib, 'to', pdir)
         ext_map = extract_extension_modules(self.python_stdlib, pdir)
-        shutil.copy(os.path.join(os.path.dirname(self_dir), 'site.py'), os.path.join(self.python_stdlib, 'site.py'))
+        shutil.copy(join(os.path.dirname(self_dir), 'site.py'), join(self.python_stdlib, 'site.py'))
         for x in bases:
-            iv['sanitize_source_folder'](os.path.join(self.python_stdlib, x))
+            iv['sanitize_source_folder'](join(self.python_stdlib, x))
         self.compile_py_modules()
         freeze_python(self.python_stdlib, pdir, self.obj_dir, ext_map, develop_mode_env_var='KITTY_DEVELOP_FROM', remove_pyc_files=True)
         iv['build_frozen_launcher']([path_to_freeze_dir(), self.obj_dir])
@@ -423,23 +443,23 @@ class Freeze(object):
         ''' Copy a directory d into a dmg named volname '''
         print('\nMaking dmg...')
         sys.stdout.flush()
-        destdir = os.path.join(SW, 'dist')
+        destdir = join(SW, 'dist')
         try:
             shutil.rmtree(destdir)
         except FileNotFoundError:
             pass
         os.mkdir(destdir)
-        dmg = os.path.join(destdir, volname + '.dmg')
+        dmg = join(destdir, f'{volname}.dmg')
         if os.path.exists(dmg):
             os.unlink(dmg)
         tdir = tempfile.mkdtemp()
-        appdir = os.path.join(tdir, os.path.basename(d))
+        appdir = join(tdir, os.path.basename(d))
         shutil.copytree(d, appdir, symlinks=True)
         if self.sign_installers:
             with timeit() as times:
                 sign_app(appdir, self.notarize)
-            print('Signing completed in %d minutes %d seconds' % tuple(times))
-        os.symlink('/Applications', os.path.join(tdir, 'Applications'))
+            print('Signing completed in {} minutes {} seconds'.format(*times))
+        os.symlink('/Applications', join(tdir, 'Applications'))
         size_in_mb = int(
             subprocess.check_output(['du', '-s', '-k', tdir]).decode('utf-8')
             .split()[0]) / 1024.
@@ -455,10 +475,10 @@ class Freeze(object):
         print('\nCreating dmg...')
         with timeit() as times:
             subprocess.check_call(cmd + [dmg])
-        print('dmg created in %d minutes and %d seconds' % tuple(times))
+        print('dmg created in {} minutes and {} seconds'.format(*times))
         shutil.rmtree(tdir)
         size = os.stat(dmg).st_size / (1024 * 1024.)
-        print('\nInstaller size: %.2fMB\n' % size)
+        print(f'\nInstaller size: {size:.2f}MB\n')
         return dmg
 
 
@@ -466,7 +486,7 @@ def main():
     args = globals()['args']
     ext_dir = globals()['ext_dir']
     Freeze(
-        os.path.join(ext_dir, kitty_constants['appname'] + '.app'),
+        join(ext_dir, f'{kitty_constants["appname"]}.app'),
         dont_strip=args.dont_strip,
         sign_installers=args.sign_installers,
         notarize=args.notarize,

bypy/sources.json

@@ -28,6 +28,15 @@
         }
     },
 
+    {
+        "name": "openssl",
+        "unix": {
+            "filename": "openssl-1.1.1i.tar.gz",
+            "hash": "sha256:e8be6a35fe41d10603c3cc635e93289ed00bf34b79671a3a4de64fcee00d5242",
+            "urls": ["https://www.openssl.org/source/{filename}"]
+        }
+    },
+
     {
         "name": "cmake",
         "os": "macos",
@@ -48,25 +57,22 @@
         }
     },
 
-
     {
         "name": "libxml2",
-        "os": "linux",
         "unix": {
-            "filename": "libxml2-2.9.10.tar.gz",
-            "hash": "sha256:aafee193ffb8fe0c82d4afef6ef91972cbaf5feea100edc2f262750611b4be1f",
+            "filename": "libxml2-2.9.12.tar.gz",
+            "hash": "sha256:c8d6681e38c56f172892c85ddc0852e1fd4b53b4209e7f4ebf17f7e2eae71d92",
             "urls": ["ftp://xmlsoft.org/libxml2/{filename}"]
         }
     },
 
-
     {
         "name": "xkbcommon",
         "os": "linux",
         "unix": {
             "filename": "libxkbcommon-1.0.3.tar.xz",
             "hash": "sha256:a2202f851e072b84e64a395212cbd976ee18a8ee602008b0bad02a13247dbc52",
-            "urls": ["http://xkbcommon.org/download/{filename}"]
+            "urls": ["https://xkbcommon.org/download/{filename}"]
         }
     },
 
@@ -90,15 +96,6 @@
         }
     },
 
-    {
-        "name": "openssl",
-        "unix": {
-            "filename": "openssl-1.1.1i.tar.gz",
-            "hash": "sha256:e8be6a35fe41d10603c3cc635e93289ed00bf34b79671a3a4de64fcee00d5242",
-            "urls": ["https://www.openssl.org/source/{filename}"]
-        }
-    },
-
     {
         "name": "ncurses",
         "os": "linux",
@@ -115,7 +112,7 @@
         "unix": {
             "filename": "readline-8.1.tar.gz",
             "hash": "sha256:f8ceb4ee131e3232226a17f51b164afc46cd0b9e6cef344be87c65962cb82b02",
-            "urls": ["http://ftp.gnu.org/gnu/readline/{filename}"]
+            "urls": ["https://ftp.gnu.org/gnu/readline/{filename}"]
         }
     },
 
@@ -128,6 +125,16 @@
         }
     },
 
+    {
+        "name": "librsync",
+        "unix": {
+            "filename": "librsync-2.3.2.tar.gz",
+            "hash": "sha256:ef8ce23df38d5076d25510baa2cabedffbe0af460d887d86c2413a1c2b0c676f",
+            "urls": ["https://github.com/librsync/librsync/releases/download/v2.3.2/{filename}"]
+        }
+    },
+
+
     {
         "name": "xcrypt",
         "os": "linux",
@@ -159,8 +166,8 @@
     {
         "name": "pygments",
         "unix": {
-            "filename": "Pygments-2.7.4.tar.gz",
-            "hash": "sha256:df49d09b498e83c1a73128295860250b0b7edd4c723a32e9bc0d295c7c2ec337",
+            "filename": "Pygments-2.11.2.tar.gz",
+            "hash": "sha256:4e426f72023d88d03b2fa258de560726ce890ff3b630f88c21cbb8b2503b8c6a",
             "urls": ["pypi"]
         }
     },
@@ -170,7 +177,7 @@
         "unix": {
             "filename": "libpng-1.6.37.tar.xz",
             "hash": "sha256:505e70834d35383537b6491e7ae8641f1a4bed1876dbfe361201fc80868d88ca",
-            "urls": ["http://downloads.sourceforge.net/sourceforge/libpng/{filename}"]
+            "urls": ["https://downloads.sourceforge.net/sourceforge/libpng/{filename}"]
         }
     },
 
@@ -189,7 +196,7 @@
         "unix": {
             "filename": "graphite2-1.3.14.tgz",
             "hash": "sha256:f99d1c13aa5fa296898a181dff9b82fb25f6cc0933dbaa7a475d8109bd54209d",
-            "urls": ["http://downloads.sourceforge.net/silgraphite/{filename}"]
+            "urls": ["https://downloads.sourceforge.net/silgraphite/{filename}"]
         }
     },
 
@@ -249,7 +256,7 @@
         "unix": {
             "filename": "fontconfig-2.13.1.tar.bz2",
             "hash": "sha256:f655dd2a986d7aa97e052261b36aa67b0a64989496361eca8d604e6414006741",
-            "urls": ["http://www.fontconfig.org/release/{filename}"]
+            "urls": ["https://www.fontconfig.org/release/{filename}"]
         }
     },
 
@@ -266,8 +273,8 @@
         "name": "wayland",
         "os": "linux",
         "unix": {
-            "filename": "wayland-1.19.0.tar.xz",
-            "hash": "sha256:baccd902300d354581cd5ad3cc49daa4921d55fb416a5883e218750fef166d15",
+            "filename": "wayland-1.20.0.tar.xz",
+            "hash": "sha256:b8a034154c7059772e0fdbd27dbfcda6c732df29cae56a82274f6ec5d7cd8725",
             "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
         }
     },
@@ -276,8 +283,8 @@
         "name": "wayland-protocols",
         "os": "linux",
         "unix": {
-            "filename": "wayland-protocols-1.20.tar.xz",
-            "hash": "sha256:9782b7a1a863d82d7c92478497d13c758f52e7da4f197aa16443f73de77e4de7",
+            "filename": "wayland-protocols-1.25.tar.xz",
+            "hash": "sha256:f1ff0f7199d0a0da337217dd8c99979967808dc37731a1e759e822b75b571460",
             "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
         }
     }

docs/Makefile

@@ -1,8 +1,12 @@
 # Minimal makefile for Sphinx documentation
 #
 
+ifdef FAIL_WARN
+override FAIL_WARN=-W
+endif
+
 # You can set these variables from the command line.
-SPHINXOPTS    = -j auto -T $(FAIL_WARN)
+SPHINXOPTS    = -n -q -j auto -T $(FAIL_WARN) $(OPTS)
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = kitty
 SOURCEDIR     = .
@@ -18,3 +22,7 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+develop-docs:
+	sphinx-autobuild --ignore "$(abspath $(SOURCEDIR))/generated/*" --watch ../kitty --watch ../kittens -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

docs/_static/custom.css

@@ -5,122 +5,32 @@
  * 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;
-}
-
-div.body {
-    min-width: 200px;
-}
-
-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;
-    max-height: 100%;
-    overflow-y: auto;
-}
-
-#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;
+.sidebar-logo {
+    max-height: 128px;
 }
 
-.title {
-    font-size: larger;
-    font-weight: bold
+.major-features li {
+    margin-bottom: 0.75ex;
+    margin-top: 0.75ex;
+}
+
+.sidebar-tree a.current {
+    font-style: italic;
+}
+
+details > summary {
+    color: var(--color-link);
+    cursor: pointer;
+    text-decoration-color: var(--color-link-underline);
+    text-decoration-line: underline;
+}
+
+/* pygments adds an underline to some white-space, this is particularly visible in
+ * dark mode. Remove it. */
+.highlight .w {
+    text-decoration: none
 }

docs/_static/custom.js

@@ -0,0 +1,57 @@
+/* vim:fileencoding=utf-8
+ *
+ * Copyright (C) 2021 Kovid Goyal <kovid at kovidgoyal.net>
+ *
+ * Distributed under terms of the GPLv3 license
+ */
+
+(function() {
+"use strict";
+
+function get_sidebar_tree() {
+    return document.querySelector('.sidebar-tree');
+}
+
+function scroll_sidebar_node_into_view(a) {
+    var ss = get_sidebar_tree().closest('.sidebar-scroll');
+    if (!ss || !a) return;
+    ss.style.position = 'relative';
+    var pos = 0;
+    while (true) {
+        pos += a.offsetTop;
+        a = a.offsetParent;
+        if (!a || a == ss) break;
+    }
+    ss.scrollTo({top: pos, behavior: 'instant'});
+}
+
+function mark_current_link(sidebar_tree, a, onload) {
+    var li = a.closest('li.has-children');
+    while (li) {
+        li.querySelector('input[type=checkbox]').setAttribute('checked', 'checked');
+        li = li.parentNode.closest('li.has-children');
+    }
+    sidebar_tree.querySelectorAll('.current').forEach(function (elem) {
+        elem.classList.remove('current');
+    });
+    if (onload) scroll_sidebar_node_into_view(a);
+    a.classList.add('current');
+}
+
+function show_hash_in_sidebar(onload) {
+    var sidebar_tree = document.querySelector('.sidebar-tree');
+    if (document.location.hash.length > 1) {
+        var a = sidebar_tree.querySelector('a[href="' + document.location.hash + '"]');
+        if (a) mark_current_link(sidebar_tree, a, onload);
+    } else {
+        if (onload) scroll_sidebar_node_into_view(sidebar_tree.querySelector('.current-page a'));
+    }
+}
+
+document.addEventListener("DOMContentLoaded", function() {
+    show_hash_in_sidebar(true);
+    window.addEventListener('hashchange', show_hash_in_sidebar.bind(null, false));
+});
+
+}());
+

docs/_templates/base.html

@@ -0,0 +1,22 @@
+{% extends "!base.html" %}
+{% block extrahead %}
+
+  {{ super() }}
+
+  {%- if analytics_id %}
+      <script type="text/javascript">
+      var _gaq = _gaq || [];
+      _gaq.push(['_setAccount', '{{ analytics_id }}']);
+      _gaq.push(['_setDomainName', 'none']);
+      _gaq.push(['_setAllowLinker', true]);
+      _gaq.push(['_trackPageview']);
+
+      (function() {
+        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+      })();
+    </script>
+  {% endif -%}
+
+{% endblock %}

docs/_templates/layout.html

@@ -1,6 +0,0 @@
-{% extends "!layout.html" %}
-
-{%- block extrahead %}
-<!-- kitty analytics placeholder -->
-  {{ super() }}
-{% endblock %}

docs/_templates/localtoc.html

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

docs/_templates/searchbox.html

@@ -1,22 +0,0 @@
-{#
-    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

@@ -1,7 +0,0 @@
-{% 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/actions.rst

@@ -0,0 +1,10 @@
+Mappable actions
+-----------------------
+
+.. highlight:: conf
+
+The actions described below can be mapped to any key press or mouse action
+using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`. For
+configuration examples, see the default shortcut links for each action.
+
+.. include:: /generated/actions.rst

docs/basic.rst

@@ -1,26 +1,31 @@
 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:
+|kitty| is capable of running multiple programs organized into tabs and windows.
+The top level of organization is the :term:`OS window <os_window>`. Each OS
+window consists of one or more :term:`tabs <tab>`. Each tab consists of one or more
+:term:`kitty windows <window>`. The kitty windows can be arranged in multiple
+different :term:`layouts <layout>`, like windows are organized in a tiling
+window manager. The keyboard controls (which are :ref:`all customizable
+<conf-kitty-shortcuts>`) for tabs and windows are:
 
 Scrolling
 ~~~~~~~~~~~~~~
 
-========================    =======================
+=========================   =======================
 Action                      Shortcut
-========================    =======================
-Scroll line up              :sc:`scroll_line_up` (also :kbd:`⌥+⌘+⇞` and :kbd:`⌘+↑` on macOS)
-Scroll line down            :sc:`scroll_line_down` (also :kbd:`⌥+⌘+⇟` and :kbd:`⌘+↓` on macOS)
-Scroll page up              :sc:`scroll_page_up` (also :kbd:`⌘+⇞` on macOS)
-Scroll page down            :sc:`scroll_page_down` (also :kbd:`⌘+⇟` on macOS)
-Scroll to top               :sc:`scroll_home` (also :kbd:`⌘+↖` on macOS)
-Scroll to bottom            :sc:`scroll_end` (also :kbd:`⌘+↘` on macOS)
-========================    =======================
+=========================   =======================
+Line up                     :sc:`scroll_line_up` (also :kbd:`⌥+⌘+⇞` and :kbd:`⌘+↑` on macOS)
+Line down                   :sc:`scroll_line_down` (also :kbd:`⌥+⌘+⇟` and :kbd:`⌘+↓` on macOS)
+Page up                     :sc:`scroll_page_up` (also :kbd:`⌘+⇞` on macOS)
+Page down                   :sc:`scroll_page_down` (also :kbd:`⌘+⇟` on macOS)
+Top                         :sc:`scroll_home` (also :kbd:`⌘+↖` on macOS)
+Bottom                      :sc:`scroll_end` (also :kbd:`⌘+↘` on macOS)
+Previous shell prompt       :sc:`scroll_to_previous_prompt` (see :ref:`shell_integration`)
+Next shell prompt           :sc:`scroll_to_next_prompt` (see :ref:`shell_integration`)
+Browse scrollback in less   :sc:`show_scrollback`
+Browse last cmd output      :sc:`show_last_command_output` (see :ref:`shell_integration`)
+=========================   =======================
 
 Tabs
 ~~~~~~~~~~~
@@ -30,8 +35,8 @@ Action                      Shortcut
 ========================    =======================
 New tab                     :sc:`new_tab` (also :kbd:`⌘+t` on macOS)
 Close tab                   :sc:`close_tab` (also :kbd:`⌘+w` on macOS)
-Next tab                    :sc:`next_tab` (also :kbd:`^+⇥` and :kbd:`⇧+⌘+]` on macOS)
-Previous tab                :sc:`previous_tab` (also :kbd:`⇧+^+⇥` and :kbd:`⇧+⌘+[` on macOS)
+Next tab                    :sc:`next_tab` (also :kbd:`⌃+⇥` and :kbd:`⇧+⌘+]` on macOS)
+Previous tab                :sc:`previous_tab` (also :kbd:`⇧+⌃+⇥` and :kbd:`⇧+⌘+[` on macOS)
 Next layout                 :sc:`next_layout`
 Move tab forward            :sc:`move_tab_forward`
 Move tab backward           :sc:`move_tab_backward`
@@ -53,13 +58,16 @@ 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`
+Visually focus window       :sc:`focus_visible_window`
+Visually swap window        :sc:`swap_with_window`
 Focus specific window       :sc:`first_window`, :sc:`second_window` ... :sc:`tenth_window`
                             (also :kbd:`⌘+1`, :kbd:`⌘+2` ... :kbd:`⌘+9` on macOS)
                             (clockwise from the top-left)
 ========================    =======================
 
-Additionally, you can define shortcuts in :file:`kitty.conf` to focus neighboring
-windows and move windows around (similar to window movement in vim)::
+Additionally, you can define shortcuts in :file:`kitty.conf` to focus
+neighboring windows and move windows around (similar to window movement in
+:program:`vim`)::
 
    map ctrl+left neighboring_window left
    map shift+left move_window right
@@ -71,18 +79,25 @@ You can also define a shortcut to switch to the previously active window::
 
    map ctrl+p nth_window -1
 
-``nth_window`` will focus the nth window for positive numbers and the
-previously active windows for negative numbers.
+:ac:`nth_window` will focus the nth window for positive numbers (starting from
+zero) and the previously active windows for negative numbers.
+
+To switch to the nth OS window, you can define :ac:`nth_os_window`. Only
+positive numbers are accepted, starting from one.
 
 .. _detach_window:
 
-You can define shortcuts to detach the current window and
-move it to another tab or another OS window::
+You can define shortcuts to detach the current window and move it to another tab
+or another OS window::
 
     # moves the window into a new OS window
     map ctrl+f2 detach_window
-    # moves the window into a new Tab
+    # moves the window into a new tab
     map ctrl+f3 detach_window new-tab
+    # moves the window into the previously active tab
+    map ctrl+f3 detach_window tab-prev
+    # moves the window into the tab at the left of the active tab
+    map ctrl+f3 detach_window tab-left
     # asks which tab to move the window into
     map ctrl+f4 detach_window ask
 
@@ -93,8 +108,8 @@ Similarly, you can detach the current tab, with::
     # asks which OS Window to move the tab into
     map ctrl+f4 detach_tab ask
 
-Finally, you can define a shortcut to close all windows in a tab other than
-the currently active window::
+Finally, you can define a shortcut to close all windows in a tab other than the
+currently active window::
 
     map f9 close_other_windows_in_tab
 
@@ -102,24 +117,27 @@ the currently active window::
 Other keyboard shortcuts
 ----------------------------------
 
+The full list of actions that can be mapped to key presses is available
+:doc:`here </actions>`.
+
 ==================================  =======================
 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`
+Pass selection to program           :sc:`pass_selection_to_program`
 Increase font size                  :sc:`increase_font_size` (also :kbd:`⌘++` on macOS)
 Decrease font size                  :sc:`decrease_font_size` (also :kbd:`⌘+-` on macOS)
 Restore font size                   :sc:`reset_font_size` (also :kbd:`⌘+0` on macOS)
-Toggle fullscreen                   :sc:`toggle_fullscreen` (also :kbd:`^+⌘+f` on macOS)
+Toggle fullscreen                   :sc:`toggle_fullscreen` (also :kbd:`⌃+⌘+f` on macOS)
 Toggle maximized                    :sc:`toggle_maximized`
-Input unicode character             :sc:`input_unicode_character` (also :kbd:`^+⌘+space` on macOS)
-Click URL using the keyboard        :sc:`open_url`
-Reset the terminal                  :sc:`reset_terminal`
-Reload :file:`kitty.conf`           :sc:`reload_config_file`
-Debug :file:`kitty.conf`            :sc:`debug_config`
-Pass current selection to program   :sc:`pass_selection_to_program`
-Edit |kitty| config file            :sc:`edit_config_file`
+Input Unicode character             :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
+Open URL in web browser             :sc:`open_url`
+Reset the terminal                  :sc:`reset_terminal` (also :kbd:`⌥+⌘+r` on macOS)
+Edit :file:`kitty.conf`             :sc:`edit_config_file` (also :kbd:`⌘+,` on macOS)
+Reload :file:`kitty.conf`           :sc:`reload_config_file` (also :kbd:`⌃+⌘+,` on macOS)
+Debug :file:`kitty.conf`            :sc:`debug_config` (also :kbd:`⌥+⌘+,` on macOS)
 Open a |kitty| shell                :sc:`kitty_shell`
 Increase background opacity         :sc:`increase_background_opacity`
 Decrease background opacity         :sc:`decrease_background_opacity`

docs/binary.rst

@@ -1,17 +1,17 @@
-kitty - Binary install
+Install kitty
 ========================
 
-.. |ins| replace:: curl -L :literal:`https://sw.kovidgoyal.net/kitty/installer.sh` | sh /dev/stdin
+Binary install
+----------------
 
 .. 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
+.. code-block:: sh
 
-    |ins|
+    _kitty_install_cmd
 
 
 The binaries will be installed in the standard location for your OS,
@@ -19,17 +19,23 @@ The binaries will be installed in the standard location for your OS,
 Linux. The installer only touches files in that directory. To update kitty,
 simply re-run the command.
 
+.. warning::
+   **Do not** copy the kitty binary out of the installation folder. If you want
+   to add it to your :envvar:`PATH`, create a symlink in :file:`~/.local/bin` or
+   :file:`/usr/bin` or wherever.
+
 
 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
+<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.
 
+
 Desktop integration on Linux
 --------------------------------
 
@@ -41,17 +47,30 @@ particular desktop, but it should work for most major desktop environments.
 .. code-block:: sh
 
     # Create a symbolic link to add kitty to PATH (assuming ~/.local/bin is in
-    # your PATH)
+    # your system-wide PATH)
     ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/
     # Place the kitty.desktop file somewhere it can be found by the OS
     cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/
-    # Update the path to the kitty icon in the kitty.desktop file
-    sed -i "s|Icon=kitty|Icon=/home/$USER/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty.desktop
+    # If you want to open text files and images in kitty via your file manager also add the kitty-open.desktop file
+    cp ~/.local/kitty.app/share/applications/kitty-open.desktop ~/.local/share/applications/
+    # Update the paths to the kitty and its icon in the kitty.desktop file(s)
+    sed -i "s|Icon=kitty|Icon=/home/$USER/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty*.desktop
+    sed -i "s|Exec=kitty|Exec=/home/$USER/.local/kitty.app/bin/kitty|g" ~/.local/share/applications/kitty*.desktop
 
 .. note::
-    If you use the venerable `stow <https://www.gnu.org/software/stow/>`_
+    In :file:`kitty-open.desktop`, kitty is registered to handle some supported
+    MIME types. This will cause kitty to take precedence on some systems where
+    the default apps are not explicitly set. For example, you expect to use
+    other GUI file managers to open dir paths when using commands such as
+    :program:`xdg-open`, you should configure the default opener for the MIME
+    type ``inode/directory``::
+
+        xdg-mime default org.kde.dolphin.desktop inode/directory
+
+.. note::
+    If you use the venerable `stow <https://www.gnu.org/software/stow/>`__
     command to manage your manual installations, the following takes care of the
-    above for you (use with :file:`dest=~/.local/stow`)::
+    above for you (use with :code:`dest=~/.local/stow`)::
 
         cd ~/.local/stow
         stow -v kitty.app
@@ -60,31 +79,46 @@ particular desktop, but it should work for most major desktop environments.
 Customizing the installation
 --------------------------------
 
+.. _nightly:
+
+* You can install the latest nightly kitty build with ``installer``:
+
+  .. code-block:: sh
+
+     _kitty_install_cmd \\
+         installer=nightly
+
+  If you want to install it in parallel to the released kitty specify a
+  different install locations with ``dest``:
+
+  .. code-block:: sh
+
+     _kitty_install_cmd \\
+         installer=nightly dest=/some/other/location
+
 * You can specify a different install location, with ``dest``:
 
-  .. parsed-literal::
-     :class: pre
+  .. code-block:: sh
 
-     |ins| \\
+     _kitty_install_cmd \\
          dest=/some/other/location
 
 * You can tell the installer not to launch |kitty| after installing it with
   ``launch=n``:
 
-  .. parsed-literal::
-     :class: pre
+  .. code-block:: sh
 
-     |ins| \\
+     _kitty_install_cmd \\
          launch=n
 
 * You can use a previously downloaded dmg/tarball, with ``installer``:
 
-  .. parsed-literal::
-     :class: pre
+  .. code-block:: sh
 
-     |ins| \\
+     _kitty_install_cmd \\
          installer=/path/to/dmg or tarball
 
+
 Uninstalling
 ----------------
 

docs/build.rst

@@ -1,23 +1,27 @@
-Building kitty from source
-==============================
+Build from source
+==================
 
 .. image:: https://github.com/kovidgoyal/kitty/workflows/CI/badge.svg
   :alt: Build status
   :target: https://github.com/kovidgoyal/kitty/actions?query=workflow%3ACI
 
+.. highlight:: sh
 
-|kitty| is designed to run from source, for easy hack-ability. Make sure
-the following dependencies are installed first.
-
+|kitty| is designed to run from source, for easy hack-ability. Make sure the
+following dependencies are installed first.
 
 .. note::
-   If you are making small changes only to the python parts of kitty, there is no need to
-   build kitty at all, instead, assuming you have installed the official kitty
-   binaries, you can simply set the KITTY_DEVELOP_FROM enviroment variable to
-   point to the directory into which you have checked out the kitty source
-   code. kitty will then load its python code from there. You should use a
-   version of the source that matches the binary version as closely as
-   possible, since the two are tightly coupled.
+   If you just want to test the latest changes to kitty, you don't need to build
+   from source. Instead install the :ref:`latest nightly build <nightly>`.
+
+.. note::
+   If you are making small changes only to the Python parts of kitty, there is
+   no need to build kitty at all, instead, assuming you have installed the
+   official kitty binaries, you can simply set the :envvar:`KITTY_DEVELOP_FROM`
+   enviroment variable to point to the directory into which you have checked out
+   the kitty source code. kitty will then load its Python code from there. You
+   should use a version of the source that matches the binary version as closely
+   as possible, since the two are tightly coupled.
 
 
 Dependencies
@@ -25,24 +29,40 @@ Dependencies
 
 Run-time dependencies:
 
-    * python >= 3.6
-    * harfbuzz >= 2.2.0
-    * zlib
-    * libpng
-    * liblcms2
-    * freetype (not needed on macOS)
-    * fontconfig (not needed on macOS)
-    * libcanberra (not needed on macOS)
-    * ImageMagick (optional, needed to use the ``kitty +kitten icat`` tool to display images in the terminal)
-    * pygments (optional, need for syntax highlighting in ``kitty +kitten diff``)
+* ``python`` >= 3.6
+* ``harfbuzz`` >= 2.2.0
+* ``zlib``
+* ``libpng``
+* ``liblcms2``
+* ``librsync``
+* ``freetype`` (not needed on macOS)
+* ``fontconfig`` (not needed on macOS)
+* ``libcanberra`` (not needed on macOS)
+* ``ImageMagick`` (optional, needed to use the ``kitty +kitten icat`` tool to display images in the terminal)
+* ``pygments`` (optional, needed 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:
-      ``libdbus-1-dev``, ``libxcursor-dev``, ``libxrandr-dev``, ``libxi-dev``, ``libxinerama-dev``, ``libgl1-mesa-dev``, ``libxkbcommon-x11-dev``, ``libfontconfig-dev``, ``libx11-xcb-dev``, ``liblcms2-dev``, and ``libpython3-dev``,
-      if they are not already installed by your distro.
+* ``gcc`` or ``clang``
+* ``pkg-config``
+* For building on Linux in addition to the above dependencies you might also
+  need to install the following packages, if they are not already installed by
+  your distro:
+
+  - ``libdbus-1-dev``
+  - ``libxcursor-dev``
+  - ``libxrandr-dev``
+  - ``libxi-dev``
+  - ``libxinerama-dev``
+  - ``libgl1-mesa-dev``
+  - ``libxkbcommon-x11-dev``
+  - ``libfontconfig-dev``
+  - ``libx11-xcb-dev``
+  - ``liblcms2-dev``
+  - ``libpython3-dev``
+  - ``librsync-dev``
+
 
 Install and run from source
 ------------------------------
@@ -59,9 +79,8 @@ You can run |kitty|, as::
 
     ./kitty/launcher/kitty
 
-If that works, you can create a symlink to the launcher in :file:`~/bin` or
-some other directory on your PATH so that you can run |kitty| using
-just ``kitty``.
+If that works, you can create a symlink to the launcher in :file:`~/bin` or some
+other directory on your PATH so that you can run |kitty| using just ``kitty``.
 
 
 Building kitty.app on macOS from source
@@ -72,74 +91,100 @@ 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.
+Python and the other dependencies. So if you ever un-install/upgrade those
+dependencies you might have to rebuild the app.
 
 .. note::
    The released :file:`kitty.dmg` includes all dependencies, unlike the
    :file:`kitty.app` built above and is built automatically by using the
-   <https://github.com/kovidgoyal/bypy>`_ however, that is designed to
-   run on Linux and is not for the faint of heart.
-
+   `bypy framework <https://github.com/kovidgoyal/bypy>`__ however, that is
+   designed to run on Linux and is not for the faint of heart.
 
 .. note::
-   Apple disallows certain functionality, such as notifications for unsigned applications.
-   If you need this functionality, you can try signing the built kitty.app with
-   a self signed certificate, see for example, `here
-   <https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`_.
+   Apple disallows certain functionality, such as notifications for unsigned
+   applications. If you need this functionality, you can try signing the built
+   :file:`kitty.app` with a self signed certificate, see for example, `here
+   <https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`__.
+
+.. note::
+   If you are facing issues with ``linker`` while building, try with a ``brew``
+   installed Python instead, see :iss:`289` for more discussion.
+
 
 Build and run from source with Nix
 -------------------------------------------
 
 On NixOS or any other Linux or macOS system with the Nix package manager
 installed, execute `nix-shell
-<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`_ to create
+<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`__ to create
 the correct environment to build kitty or use ``nix-shell --pure`` instead to
 eliminate most of the influence of the outside system, e.g. globally installed
 packages. ``nix-shell`` will automatically fetch all required dependencies and
 make them available in the newly spawned shell.
 
-Then proceed with ``make`` or ``make app`` according to the platform specific instructions above.
+Then proceed with ``make`` or ``make app`` according to the platform specific
+instructions above.
 
 
-Note for Linux/macOS packagers
+Debug builds
+--------------
+
+A basic debug build can be done with::
+
+    make debug
+
+This includes debug info in the binary for better traces. To build with address
+sanitizer, use::
+
+    make asan
+
+Which will result in a debug binary that uses the address sanitizer as well.
+
+.. _packagers:
+
+Notes 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>`_.
+`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`__.
 
-While |kitty| does use python, it is not a traditional python package, so please
+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`.
+This will install |kitty| into the directory :file:`linux-package`. You can run
+|kitty| with :file:`linux-package/bin/kitty`. All the files needed to run kitty
+will be in :file:`linux-package/lib/kitty`. The terminfo file will be installed
+into :file:`linux-package/share/terminfo`. Simply copy these files into
+:file:`/usr` to install |kitty|. In other words, :file:`linux-package` is the
+staging area into which |kitty| is installed. You can choose a different staging
+area, by passing the ``--prefix`` argument to :file:`setup.py`.
 
-You should probably split |kitty| into two packages, :file:`kitty-terminfo` that
-installs the terminfo file and :file:`kitty` that installs the main program.
-This allows users to install the terminfo file on servers into which they ssh,
-without needing to install all of |kitty|.
+You should probably split |kitty| into three packages:
+
+:code:`kitty-terminfo`
+    Installs the terminfo file
+
+:code:`kitty-shell-integration`
+    Installs the shell integration scripts (the contents of the
+    shell-integration directory in the kitty source code), probably to
+    :file:`/usr/share/kitty/shell-integration`
+
+:code:`kitty`
+    Installs the main program
+
+This allows users to install the terminfo and shell integration files 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 from
-        a git checkout instead of the released source code tarball, you will
-        need :file:`sphinx-build` from the `Sphinx documentation generator
-        <https://www.sphinx-doc.org/>`_.
+   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 from a git checkout instead of the
+   released source code tarball, you will need to install the dependencies from
+   :file:`docs/requirements.txt` to build the kitty documentation. They can be
+   installed most easily with ``python -m pip -r docs/requirements.txt``.
 
 This applies to creating packages for |kitty| for macOS package managers such as
-brew or MacPorts as well.
-
-
-.. note::
-        |kitty| has its own update check mechanism, if you would like to turn
-        it off for your package, use
-        ``python3 setup.py linux-package --update-check-interval=0``
+Homebrew or MacPorts as well.

docs/color-stack.rst

@@ -0,0 +1,26 @@
+Saving and restoring 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 and the ANSI
+color table. 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 themselves, then running the full screen application will
+lose those 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 colors, default background, default
+foreground, selection background, selection foreground and cursor color and the
+256 colors of the ANSI color table.
+
+.. note:: In July 2020, after several years, xterm copied this protocol
+   extension, without acknowledgement, and using incompatible escape codes
+   (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not
+   just the dynamic colors but the entire ANSI color table. In the interests of
+   promoting interoperability, kitty added support for xterm's escape codes as
+   well, and changed this extension to also save/restore the entire ANSI color
+   table.

docs/conf.py

@@ -13,7 +13,7 @@ import subprocess
 import sys
 import time
 from functools import partial
-from typing import Any, Callable, Dict, Iterable, List, Match, Optional, Tuple
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
 
 from docutils import nodes
 from docutils.parsers.rst.roles import set_classes
@@ -21,16 +21,15 @@ from pygments.lexer import RegexLexer, bygroups  # type: ignore
 from pygments.token import (  # type: ignore
     Comment, Keyword, Literal, Name, Number, String, Whitespace
 )
-from sphinx import addnodes, version_info  # type: ignore
-from sphinx.environment.adapters.toctree import TocTree  # type: ignore
-from sphinx.util.logging import getLogger  # type: ignore
+from sphinx import addnodes, version_info
+from sphinx.util.logging import getLogger
 
 kitty_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if kitty_src not in sys.path:
     sys.path.insert(0, kitty_src)
 
-from kitty.conf.types import Definition  # noqa
-from kitty.constants import str_version  # noqa
+from kitty.conf.types import Definition, expand_opt_references  # noqa
+from kitty.constants import str_version, website_url  # noqa
 
 # config {{{
 # -- Project information -----------------------------------------------------
@@ -60,8 +59,15 @@ extensions = [
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.extlinks',
+    'sphinx_copybutton',
+    'sphinx_inline_tabs',
+    "sphinxext.opengraph",
 ]
 
+# URL for OpenGraph tags
+ogp_site_url = website_url()
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -85,25 +91,22 @@ language: Optional[str] = None
 # 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'
+    '_build', 'Thumbs.db', '.DS_Store', 'basic.rst',
+    'generated/cli-*.rst', 'generated/conf-*.rst', 'generated/actions.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)
+smartquotes_action = 'qe'  # educate quotes and ellipses but not dashes
+
+string_replacements = {
+    '_kitty_install_cmd': 'curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin',
+}
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -111,32 +114,26 @@ rst_prolog = '''
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
+html_title = 'kitty'
 
 # 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',
+html_theme_options: Dict[str, Any] = {
+    'sidebar_hide_name': True,
+    'navigation_with_keys': True,
 }
 
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static', '../logo/kitty.png']
-html_favicon = '../logo/kitty.png'
+html_static_path = ['_static']
+html_favicon = html_logo = '../logo/kitty.svg'
+html_css_files = ['custom.css']
+html_js_files = ['custom.js']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -146,17 +143,9 @@ html_favicon = '../logo/kitty.png'
 # 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
-
+html_show_sphinx = False
+manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
 
 # -- Options for manual page output ------------------------------------------
 
@@ -183,25 +172,16 @@ texinfo_documents = [
 
 # GitHub linking inline roles {{{
 
-def num_role(which: str, name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
-    ' 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], []
+extlinks = {
+    'iss': ('https://github.com/kovidgoyal/kitty/issues/%s', '#%s'),
+    'pull': ('https://github.com/kovidgoyal/kitty/pull/%s', '#%s'),
+    'disc': ('https://github.com/kovidgoyal/kitty/discussions/%s', '#%s'),
+}
 
 
-def commit_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+def commit_role(
+    name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []
+) -> Tuple[List[nodes.reference], List[nodes.problematic]]:
     ' Link to a github commit '
     try:
         commit_id = subprocess.check_output(
@@ -220,32 +200,17 @@ def commit_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, o
 # }}}
 
 
-# Sidebar ToC {{{
-def create_toc(app: Any, pagename: str) -> Optional[Any]:
-    tt = TocTree(app.env)
-    toctree = tt.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 None  # 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: Any, pagename: str, templatename: str, context: Any, *args: Any) -> None:
-    if 'toc' in context:
-        context['toc'] = create_toc(app, pagename) or context['toc']
-# }}}
-
-
 # CLI docs {{{
 def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
     from kitty.cli import option_spec_as_rst
     from kitty.launch import options_spec as launch_options_spec
+    from kittens.ssh.copy import option_text
+    from kittens.ssh.options.definition import copy_message
+    with open('generated/ssh-copy.rst', 'w') as f:
+        f.write(option_spec_as_rst(
+            appname='copy', ospec=option_text, heading_char='^',
+            usage='file-or-dir-to-copy ...', message=copy_message
+        ))
     with open('generated/launch.rst', 'w') as f:
         f.write(option_spec_as_rst(
             appname='launch', ospec=launch_options_spec, heading_char='_',
@@ -263,7 +228,8 @@ if you specify a program-to-run you can use the special placeholder
     from kitty.remote_control import cli_msg, global_options_spec
     with open('generated/cli-kitty-at.rst', 'w') as f:
         p = partial(print, file=f)
-        p('kitty @\n' + '-' * 80)
+        p('kitty @')
+        p('-' * 80)
         p('.. program::', 'kitty @')
         p('\n\n' + as_rst(
             global_options_spec, message=cli_msg, usage='command ...', appname='kitty @'))
@@ -271,7 +237,8 @@ if you specify a program-to-run you can use the special placeholder
         for cmd_name in sorted(all_command_names()):
             func = command_for_name(cmd_name)
             p(f'.. _at_{func.name}:\n')
-            p('kitty @', func.name + '\n' + '-' * 120)
+            p('kitty @', func.name)
+            p('-' * 120)
             p('.. program::', 'kitty @', func.name)
             p('\n\n' + as_rst(*cli_params_for(func)))
     from kittens.runner import get_kitten_cli_docs
@@ -280,7 +247,12 @@ if you specify a program-to-run you can use the special placeholder
         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('.. program::', 'kitty +kitten', kitten)
+                p('\nSource code for', kitten)
+                p('-' * 72)
+                p(f'\nThe source code for this kitten is `available on GitHub <https://github.com/kovidgoyal/kitty/tree/master/kittens/{kitten}>`_.')
+                p('\nCommand Line Interface')
+                p('-' * 72)
                 p('\n\n' + option_spec_as_rst(
                     data['options'], message=data['help_text'], usage=data['usage'], appname=f'kitty +kitten {kitten}',
                     heading_char='^'))
@@ -294,7 +266,7 @@ def write_remote_control_protocol_docs() -> None:  # {{{
     )
     field_pat = re.compile(r'\s*([a-zA-Z0-9_+]+)\s*:\s*(.+)')
 
-    def format_cmd(p: Callable, name: str, cmd: RemoteCommand) -> None:
+    def format_cmd(p: Callable[..., None], name: str, cmd: RemoteCommand) -> None:
         p(name)
         p('-' * 80)
         lines = (cmd.__doc__ or '').strip().splitlines()
@@ -332,9 +304,17 @@ def write_remote_control_protocol_docs() -> None:  # {{{
 # }}}
 
 
+def replace_string(app: Any, docname: str, source: List[str]) -> None:  # {{{
+    src = source[0]
+    for k, v in app.config.string_replacements.items():
+        src = src.replace(k, v)
+    source[0] = src
+# }}}
+
 # config file docs {{{
 
-class ConfLexer(RegexLexer):
+
+class ConfLexer(RegexLexer):  # type: ignore
     name = 'Conf'
     aliases = ['conf']
     filenames = ['*.conf']
@@ -347,6 +327,8 @@ class ConfLexer(RegexLexer):
             (r'(include)(\s+)(.+?)$', bygroups(Comment.Preproc, Whitespace, Name.Namespace)),
             (r'(map)(\s+)(\S+)(\s+)', bygroups(
                 Keyword.Declaration, Whitespace, String, Whitespace), 'action'),
+            (r'(mouse_map)(\s+)(\S+)(\s+)(\S+)(\s+)(\S+)(\s+)', bygroups(
+                Keyword.Declaration, Whitespace, String, Whitespace, Name.Variable, 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(
@@ -371,7 +353,7 @@ class ConfLexer(RegexLexer):
     }
 
 
-class SessionLexer(RegexLexer):
+class SessionLexer(RegexLexer):  # type: ignore
     name = 'Session'
     aliases = ['session']
     filenames = ['*.session']
@@ -387,7 +369,9 @@ class SessionLexer(RegexLexer):
     }
 
 
-def link_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+def link_role(
+    name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []
+) -> Tuple[List[nodes.reference], List[nodes.problematic]]:
     text = text.replace('\n', ' ')
     m = re.match(r'(.+)\s+<(.+?)>', text)
     if m is None:
@@ -401,19 +385,6 @@ def link_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, opt
     return [node], []
 
 
-def expand_opt_references(conf_name: str, text: str) -> str:
-    conf_name += '.'
-
-    def expand(m: Match) -> str:
-        ref = m.group(1)
-        if '<' not in ref and '.' not in ref:
-            full_ref = conf_name + ref
-            return ':opt:`{} <{}>`'.format(ref, full_ref)
-        return str(m.group())
-
-    return re.sub(r':opt:`(.+?)`', expand, text)
-
-
 opt_aliases: Dict[str, str] = {}
 shortcut_slugs: Dict[str, Tuple[str, str]] = {}
 
@@ -436,7 +407,7 @@ def parse_opt_node(env: Any, sig: str, signode: Any) -> str:
             opt_aliases[optname] = firstname
         count += 1
     if not firstname:
-        raise ValueError('{} is not a valid opt'.format(sig))
+        raise ValueError(f'{sig} is not a valid opt')
     return firstname
 
 
@@ -447,23 +418,33 @@ def parse_shortcut_node(env: Any, sig: str, signode: Any) -> str:
     return sig
 
 
+def parse_action_node(env: Any, sig: str, signode: Any) -> str:
+    """Transform an action description into RST nodes."""
+    signode += addnodes.desc_name(sig, sig)
+    return sig
+
+
 def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
     conf_name, opt = target.partition('.')[::2]
     if not opt:
         conf_name, opt = 'kitty', conf_name
-    full_name = conf_name + '.' + opt
+    full_name = f'{conf_name}.{opt}'
     return title, opt_aliases.get(full_name, full_name)
 
 
+def process_action_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
+    return title, target
+
+
 def process_shortcut_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
     conf_name, slug = target.partition('.')[::2]
     if not slug:
         conf_name, slug = 'kitty', conf_name
-    full_name = conf_name + '.' + slug
+    full_name = f'{conf_name}.{slug}'
     try:
         target, stitle = shortcut_slugs[full_name]
     except KeyError:
-        logger.warning('Unknown shortcut: {}'.format(target), location=refnode)
+        logger.warning(f'Unknown shortcut: {target}', location=refnode)
     else:
         if not has_explicit_title:
             title = stitle
@@ -492,6 +473,15 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
     sc_role.process_link = process_shortcut_link
     shortcut_slugs.clear()
 
+    app.add_object_type(
+        'action', 'ac',
+        indextemplate="pair: %s; Action",
+        parse_node=parse_action_node,
+    )
+    ac_role = app.registry.domain_roles['std']['ac']
+    ac_role.warn_dangling = True
+    ac_role.process_link = process_action_link
+
     def generate_default_config(definition: Definition, name: str) -> None:
         with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f:
             print('.. highlight:: conf\n', file=f)
@@ -510,9 +500,27 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
         definition = get_kitten_conf_docs(kitten)
         if definition:
             generate_default_config(definition, f'kitten-{kitten}')
+
+    from kitty.actions import as_rst
+    with open('generated/actions.rst', 'w', encoding='utf-8') as f:
+        f.write(as_rst())
 # }}}
 
 
+def add_html_context(app: Any, pagename: str, templatename: str, context: Any, doctree: Any, *args: Any) -> None:
+    context['analytics_id'] = app.config.analytics_id
+    if 'toctree' in context:
+        # this is needed with furo to use all titles from pages
+        # in the sidebar (global) toc
+        original_toctee_function = context['toctree']
+
+        def include_sub_headings(**kwargs: Any) -> Any:
+            kwargs['titles_only'] = False
+            return original_toctee_function(**kwargs)
+
+        context['toctree'] = include_sub_headings
+
+
 def setup(app: Any) -> None:
     os.makedirs('generated/conf', exist_ok=True)
     from kittens.runner import all_kitten_names
@@ -520,10 +528,14 @@ def setup(app: Any) -> None:
     write_cli_docs(kn)
     write_remote_control_protocol_docs()
     write_conf_docs(app, kn)
-    app.add_css_file('custom.css')
+    app.add_config_value('string_replacements', {}, True)
+    app.connect('source-read', replace_string)
+    app.add_config_value('analytics_id', '', 'env')
+    app.connect('html-page-context', add_html_context)
     app.add_lexer('session', SessionLexer() if version_info[0] < 3 else 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)
+    # monkey patch sphinx_inline_tabs to avoid a warning about parallel reads
+    # see https://github.com/pradyunsg/sphinx-inline-tabs/issues/26
+    inline_tabs = app.extensions['sphinx_inline_tabs']
+    inline_tabs.parallel_read_safe = inline_tabs.parallel_write_safe = True

docs/conf.rst

@@ -1,55 +1,78 @@
-:tocdepth: 2
-
-Configuring kitty
-===============================
+kitty.conf
+-----------------------
 
 .. highlight:: conf
 
-|kitty| is highly customizable, everything from keyboard shortcuts, to
-rendering frames-per-second. See below for an overview of all customization
-possibilities.
+|kitty| is highly customizable, everything from keyboard shortcuts, to rendering
+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 reload the config file within kitty by pressing
-:sc:`reload_config_file` or sending kitty the ``SIGUSR1`` signal.  You can also
-display the current configuration by pressing the :sc:`debug_config` key.
+You can open the config file within kitty by pressing :sc:`edit_config_file`
+(:kbd:`⌘+,` on macOS). A :file:`kitty.conf` with commented default
+configurations and descriptions will be created if the file does not exist.
+You can reload the config file within kitty by pressing :sc:`reload_config_file`
+(:kbd:`⌃+⌘+,` on macOS) or sending kitty the ``SIGUSR1`` signal.
+You can also display the current configuration by pressing :sc:`debug_config`
+(:kbd:`⌥+⌘+,` on macOS).
 
 .. _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.
+:option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
+environment variable. See :option:`kitty --config` for full details.
 
 Comments can be added to the config file as lines starting with the ``#``
-character. This works only if the ``#`` character is the first character
-in the line.
+character. This works only if the ``#`` character is the first character in the
+line.
+
+.. _include:
 
 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
+you use a relative path for :code:`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::
+:code:`USER=name`. Also, you can use :code:`globinclude` to include files
+matching a shell glob pattern and :code:`envinclude` to include configuration
+from environment variables. For example::
 
      include other.conf
+     # Include *.conf files from all subdirs of kitty.d inside the kitty config dir
+     globinclude kitty.d/**/*.conf
+     # Include the *contents* of all env vars starting with KITTY_CONF_
+     envinclude KITTY_CONF_*
+
+
+.. note:: Syntax highlighting for :file:`kitty.conf` in vim is available via
+   `vim-kitty <https://github.com/fladson/vim-kitty>`__.
 
 
 .. include:: /generated/conf-kitty.rst
 
 
 Sample kitty.conf
-^^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 .. only:: html
 
-    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>`.
+    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>`.
 
 .. only:: man
 
    You can edit a fully commented sample kitty.conf by pressing the
-   :sc:`edit_config_file` shortcut in kitty. This will generate a config
-   file with full documentation and all settings commented out. If you
-   have a pre-existing kitty.conf, then that will be used instead, delete
-   it to see the sample file.
+   :sc:`edit_config_file` shortcut in kitty. This will generate a config file
+   with full documentation and all settings commented out. If you have a
+   pre-existing :file:`kitty.conf`, then that will be used instead, delete it to
+   see the sample file.
+
+
+All mappable actions
+------------------------
+
+See the :doc:`list of all the things you can make kitty can do </actions>`.
+
+.. toctree::
+   :hidden:
+
+   actions

docs/deccara.rst

@@ -0,0 +1,20 @@
+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 :iss:`this discussion <160#issuecomment-346470545>`
+and `this FAQ <https://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

docs/desktop-notifications.rst

@@ -0,0 +1,121 @@
+.. _desktop_notifications:
+
+
+Desktop notifications
+=======================
+
+|kitty| implements an extensible escape code (OSC 99) to show desktop
+notifications. It is easy to use from shell scripts and fully extensible to show
+title and body. Clicking on the notification can optionally focus the window it
+came from, and/or send an escape code back to the application running in that
+window.
+
+The design of the escape code is partially based on the discussion in the
+defunct `terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`__
+
+The escape code has the form::
+
+    <OSC> 99 ; metadata ; payload <terminator>
+
+Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is
+:code:`<ESC><backslash>`. The ``metadata`` is a section of colon separated
+:code:`key=value` pairs. Every key must be a single character from the set
+:code:`a-zA-Z` and every value must be a word consisting of characters from
+the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
+interpreted based on the metadata section. The two semi-colons *must* always be
+present even when no metadata is present.
+
+Before going into details, lets see how one can display a simple, single line
+notification from a shell script::
+
+    printf '\x1b]99;;Hello world\x1b\\'
+
+To show a message with a title and a body::
+
+    printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
+    printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\'
+
+The most important key in the metadata is the ``p`` key, it controls how the
+payload is interpreted. A value of ``title`` means the payload is setting the
+title for the notification. A value of ``body`` means it is setting the body,
+and so on, see the table below for full details.
+
+The design of the escape code is fundamentally chunked, this is because
+different terminal emulators have different limits on how large a single escape
+code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
+key is the *notification id* which can be any string containing the characters
+``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and can only take the
+values ``0`` and ``1``. A value of ``0`` means the notification is not yet done
+and the terminal emulator should hold off displaying it. A value of ``1`` means
+the notification is done, and should be displayed. You can specify the title or
+body multiple times and the terminal emulator will concatenate them, thereby
+allowing arbitrarily long text (terminal emulators are free to impose a sensible
+limit to avoid Denial-of-Service attacks).
+
+Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
+text with no embedded escape codes, or UTF-8 text that is Base64 encoded, in
+which case there must be an ``e=1`` key in the metadata to indicate the payload
+is Base64 encoded.
+
+When the user clicks the notification, a couple of things can happen, the
+terminal emulator can focus the window from which the notification came, and/or
+it can send back an escape code to the application indicating the notification
+was activated. This is controlled by the ``a`` key which takes a comma separated
+set of values, ``report`` and ``focus``. The value ``focus`` means focus the
+window from which the notification was issued and is the default. ``report``
+means send an escape code back to the application. The format of the returned
+escape code is::
+
+    <OSC> 99 ; i=identifier ; <terminator>
+
+The value of ``identifier`` comes from the ``i`` key in the escape code sent by
+the application. If the application sends no identifier, then the terminal
+*must* use ``i=0``. Actions can be preceded by a negative sign to turn them
+off, so for example if you do not want any action, turn off the default
+``focus`` action with::
+
+    a=-focus
+
+Complete specification of all the metadata keys is in the table below. If a
+terminal emulator encounters a key in the metadata it does not understand,
+the key *must* be ignored, to allow for future extensibility of this escape
+code. Similarly if values for known keys are unknown, the terminal emulator
+*should* either ignore the entire escape code or perform a best guess effort
+to display it based on what it does understand.
+
+.. note::
+   It is possible to extend this escape code to allow specifying an icon for
+   the notification, however, given that some platforms, such as legacy versions
+   of macOS, don't allow displaying custom images on a notification, it was
+   decided to leave it out of the spec for the time being.
+
+   Similarly, features such as scheduled notifications could be added in future
+   revisions.
+
+
+=======  ====================  =========  =================
+Key      Value                 Default    Description
+=======  ====================  =========  =================
+``a``    Comma separated list  ``focus``  What action to perform when the
+         of ``report``,                   notification is clicked
+         ``focus``, with
+         optional leading
+         ``-``
+
+``d``    ``0`` or ``1``        ``1``      Indicates if the notification is
+                                          complete or not.
+
+``e``    ``0`` or ``1``        ``0``      If set to ``1`` means the payload is Base64 encoded UTF-8,
+                                          otherwise it is plain UTF-8 text with no C0 control codes in it
+
+``i``    ``[a-zA-Z0-9-_+.]``   ``0``      Identifier for the notification
+
+``p``    One of ``title`` or   ``title``  Whether the payload is the notification title or body. If a
+         ``body``.                        notification has no title, the body will be used as title.
+=======  ====================  =========  =================
+
+
+.. note::
+   |kitty| also supports the `legacy OSC 9 protocol developed by iTerm2
+   <https://iterm2.com/documentation-escape-codes.html>`__ for desktop
+   notifications.

docs/faq.rst

@@ -3,40 +3,39 @@ Frequently Asked Questions
 
 .. highlight:: sh
 
-.. contents::
-   :local:
-
 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
+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
+Some programs, like Powerline, vim with fancy gutter symbols/status-bar, etc.
+use Unicode characters from the private use area to represent symbols. Often
+these symbols are wide 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.
+makes use of the extra cell to render them in two cells. This behavior can be
+turned off for specific symbols using :opt:`narrow_symbols`.
 
 
 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::
+First make sure you have not changed the :envvar:`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.
+See :doc:`here <deccara>` 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?
@@ -48,38 +47,33 @@ terminfo files to the server::
 
     kitty +kitten ssh myserver
 
-This ssh kitten takes all the same command line arguments
-as ssh, you can alias it to ssh in your shell's rc files to avoid having to
-type it each time::
+This :doc:`ssh kitten <kittens/ssh>` takes all the same command line arguments
+as :program:`ssh`, you can alias it to something small in your shell's rc files
+to avoid having to type it each time::
 
-    alias ssh="kitty +kitten ssh"
+    alias s="kitty +kitten ssh"
 
-If for some reason that does not work (typically because the server is using a
-non POSIX compliant shell), you can try using it with python instead::
-
-    kitty +kitten ssh use-python myserver
-
-If that also fails, perhaps because python is not installed on the remote
-server, use the following one-liner instead (it
-is slower as it needs to ssh into the server twice, but will work with most
-servers)::
+If the ssh kitten fails, 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 -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
 
-If you are behind a proxy (like Balabit) that prevents this, you must redirect the
-1st command to a file, copy that to the server and run ``tic`` manually.  If you
-connect to a server, embedded or Android system that doesn't have ``tic``, copy over
-your local file terminfo to the other system as :file:`~/.terminfo/x/xterm-kitty`.
+If you are behind a proxy (like Balabit) that prevents this, or :program:`tic`
+comes with macOS that does not support reading from STDIN, you must redirect the
+first command to a file, copy that to the server and run :program:`tic`
+manually. If you connect to a server, embedded or Android system that doesn't
+have :program:`tic`, copy over your local file terminfo to the other system as
+:file:`~/.terminfo/x/xterm-kitty`.
 
 Really, the correct solution for this is to convince the OpenSSH maintainers to
-have ssh do this automatically, if possible, when connecting to a server, so that
-all terminals work transparently.
+have :program:`ssh` do this automatically, if possible, when connecting to a
+server, so that all terminals work transparently.
 
 If the server is running FreeBSD, or another system that relies on termcap
 rather than terminfo, you will need to convert the terminfo file on your local
 machine by running (on local machine with |kitty|)::
 
-    infocmp -C xterm-kitty
+    infocmp -CrT0 xterm-kitty
 
 The output of this command is the termcap description, which should be appended
 to :file:`/usr/share/misc/termcap` on the remote server. Then run the following
@@ -91,22 +85,29 @@ command to apply your change (on the server)::
 Keys such as arrow keys, backspace, delete, home/end, etc. do not work when using su or sudo?
 -------------------------------------------------------------------------------------------------
 
-Make sure the TERM environment variable, is ``xterm-kitty``.  And either the
-TERMINFO environment variable points to a directory containing :file:`x/xterm-kitty`
-or that file is under :file:`~/.terminfo/x/`.
+Make sure the :envvar:`TERM` environment variable, is ``xterm-kitty``.  And
+either the :envvar:`TERMINFO` environment variable points to a directory
+containing :file:`x/xterm-kitty` or that file is under :file:`~/.terminfo/x/`.
 
-Note that ``sudo`` might remove TERMINFO.  Then setting it at the shell prompt can
-be too late, because command line editing may not be reinitialized.  In that case
-you can either ask ``sudo`` to set it or if that is not supported, insert an ``env``
-command before starting the shell, or, if not possible, after sudo start another
-Shell providing the right terminfo path::
+For macOS, you may also need to put that file under :file:`~/.terminfo/78/`::
+
+    mkdir -p ~/.terminfo/{78,x}
+    ln -snf ../x/xterm-kitty ~/.terminfo/78/xterm-kitty
+    tic -x -o ~/.terminfo "$KITTY_INSTALLATION_DIR/terminfo/kitty.terminfo"
+
+Note that :program:`sudo` might remove :envvar:`TERMINFO`. Then setting it at
+the shell prompt can be too late, because command line editing may not be
+reinitialized. In that case you can either ask :program:`sudo` to set it or if
+that is not supported, insert an :program:`env` command before starting the
+shell, or, if not possible, after sudo start another shell providing the right
+terminfo path::
 
     sudo … TERMINFO=$HOME/.terminfo bash -i
     sudo … env TERMINFO=$HOME/.terminfo bash -i
     TERMINFO=/home/ORIGINALUSER/.terminfo exec bash -i
 
-You can configure sudo to preserve TERMINFO by running ``sudo
-visudo`` and adding the following line::
+You can configure :program:`sudo` to preserve :envvar:`TERMINFO` by running
+``sudo visudo`` and adding the following line::
 
     Defaults env_keep += "TERM TERMINFO"
 
@@ -119,20 +120,27 @@ explicitly set a UTF-8 locale, like::
 How do I change the colors in a running kitty instance?
 ------------------------------------------------------------
 
-You can either use the
-`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands>`_
-to set colors or you can define keyboard shortcuts to set colors, for example::
+The easiest way to do it is to use the :doc:`themes kitten </kittens/themes>`,
+to choose a new color theme. Simply run::
+
+    kitty +kitten themes
+
+And choose your theme from the list.
+
+You can also define keyboard shortcuts to set colors, for example::
 
     map f1 set_colors --configured /path/to/some/config/file/colors.conf
 
-Or you can enable :doc:`remote control <remote-control>` for |kitty| and use :ref:`at_set-colors`.
-The shortcut mapping technique has the same syntax as the remote control
-command, for details, see :ref:`at_set-colors`.
+Or you can enable :doc:`remote control <remote-control>` for |kitty| and use
+:ref:`at_set-colors`. The shortcut mapping technique has the same syntax as the
+remote control command, for details, see :ref:`at_set-colors`.
 
-A list of pre-made color themes for kitty is available at:
-`kitty-themes <https://github.com/dexpota/kitty-themes>`_
+To change colors when SSHing into a remote host, use the :opt:`color_scheme
+<kitten-ssh.color_scheme>` setting for the :doc:`ssh kitten <kittens/ssh>`.
 
-Examples of using OSC escape codes to set colors::
+Additionally, You can use the
+`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`__
+to set colors. Examples of using OSC escape codes to set colors::
 
     Change the default foreground color:
     printf '\x1b]10;#ff0000\x1b\\'
@@ -148,7 +156,7 @@ Examples of using OSC escape codes to set colors::
     printf '\x1b]4;n;green\x1b\\'
 
 You can use various syntaxes/names for color specifications in the above
-examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`_
+examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`__
 for full details.
 
 If a ``?`` is given rather than a color specification, kitty will respond
@@ -161,14 +169,15 @@ 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.
+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`.
+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 :envvar:`PATH`.
 
-And within |kitty| itself, you can always run |kitty| using just `kitty` as it
-cleverly adds itself to the ``PATH``.
 
 I catted a binary file and now kitty is hung?
 -----------------------------------------------
@@ -176,10 +185,10 @@ I catted a binary file and now kitty is hung?
 **Never** output unknown binary data directly into a terminal.
 
 Terminals have a single channel for both data and control. Certain bytes
-are control codes. Some of these control codes are of arbitrary length, so
-if the binary data you output into the terminal happens to contain the starting
-sequence for one of these control codes, the terminal will hang waiting for
-the closing sequence. Press :kbd:`ctrl+shift+delete` to reset the terminal.
+are control codes. Some of these control codes are of arbitrary length, so if
+the binary data you output into the terminal happens to contain the starting
+sequence for one of these control codes, the terminal will hang waiting for the
+closing sequence. Press :sc:`reset_terminal` to reset the terminal.
 
 If you do want to cat unknown data, use ``cat -v``.
 
@@ -188,19 +197,33 @@ 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.
-Furthermore, it needs fonts to be freely resizable, so it does not support
-bitmapped fonts.
+character on the GPU, and rendering them all in parallel. 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. Furthermore, it needs
+fonts to be freely resizable, so it does not support bitmapped fonts.
 
-If your font is not listed in ``kitty list-fonts`` it means that it is not
-monospace or is a bitmapped font. On Linux you can list all monospace fonts with::
+.. note::
+   If you are trying to use a font patched with `Nerd Fonts
+   <https://nerdfonts.com/>`__ symbols, don't do that as patching destroys
+   fonts. There is no need, simply install the standalone ``Symbols Nerd Font``
+   (the file :file:`NerdFontsSymbolsOnly.zip` from the `Nerd Fonts releases page
+   <https://github.com/ryanoasis/nerd-fonts/releases>`__). kitty should pick up
+   symbols from it automatically, and you can tell it to do so explicitly in
+   case it doesn't with the :opt:`symbol_map` directive::
+
+        symbol_map U+23FB-U+23FE,U+2665,U+26A1,U+2B58,U+E000-U+E00A,U+E0A0-U+E0A3,U+E0B0-U+E0C8,U+E0CA,U+E0CC-U+E0D2,U+E0D4,U+E200-U+E2A9,U+E300-U+E3E3,U+E5FA-U+E62F,U+E700-U+E7C5,U+F000-U+F2E0,U+F300-U+F31C,U+F400-U+F4A9,U+F500-U+F8FF Symbols Nerd Font
+
+   Those Unicode symbols beyond the ``E000-F8FF`` Unicode private use area are
+   not included.
+
+If your font is not listed in ``kitty +list-fonts`` it means that it is not
+monospace or is a bitmapped font. On Linux you can list all monospace fonts
+with::
 
     fc-list : family spacing outline scalable | grep -e spacing=100 -e spacing=90 | grep -e outline=True | grep -e scalable=True
 
-Note that the spacing property is calculated by fontconfig based on actual
-glyph widths in the font. If for some reason fontconfig concludes your favorite
+Note that the spacing property is calculated by fontconfig based on actual glyph
+widths in the font. If for some reason fontconfig concludes your favorite
 monospace font does not have ``spacing=100`` you can override it by using the
 following :file:`~/.config/fontconfig/fonts.conf`::
 
@@ -222,7 +245,7 @@ command to rebuild your fontconfig cache::
 
     fc-cache -r
 
-Then, the font will be available in ``kitty list-fonts``.
+Then, the font will be available in ``kitty +list-fonts``.
 
 
 How can I assign a single global shortcut to bring up the kitty terminal?
@@ -231,7 +254,42 @@ How can I assign a single global shortcut to bring up the kitty terminal?
 Bringing up applications on a single key press is the job of the window
 manager/desktop environment. For ways to do it with kitty (or indeed any
 terminal) in different environments,
-see `here <https://github.com/kovidgoyal/kitty/issues/45>`_.
+see :iss:`here <45>`.
+
+
+I do not like the kitty icon!
+-------------------------------
+
+There are many alternate icons available, click on an icon to visit its
+homepage:
+
+.. image:: https://github.com/k0nserv/kitty-icon/raw/main/icon_512x512.png
+   :target: https://github.com/k0nserv/kitty-icon
+   :width: 256
+
+.. image:: https://github.com/DinkDonk/kitty-icon/raw/main/kitty-dark.png
+   :target: https://github.com/DinkDonk/kitty-icon
+   :width: 256
+
+.. image:: https://github.com/DinkDonk/kitty-icon/raw/main/kitty-light.png
+   :target: https://github.com/DinkDonk/kitty-icon
+   :width: 256
+
+.. image:: https://github.com/hristost/kitty-alternative-icon/raw/main/kitty_icon.png
+   :target: https://github.com/hristost/kitty-alternative-icon
+   :width: 256
+
+.. image:: https://github.com/igrmk/whiskers/raw/main/whiskers.svg
+   :target: https://github.com/igrmk/whiskers
+   :width: 256
+
+On macOS you can change the icon by following the steps:
+
+#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+I`
+#. Drag :file:`kitty.icns` onto the application icon in the kitty info pane
+#. Delete the icon cache and restart Dock::
+
+    $ rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock
 
 
 How do I map key presses in kitty to different keys in the terminal program?
@@ -247,7 +305,10 @@ the :sc:`send_text <send_text>` you can use the ``show_key`` kitten. Run::
 
     kitty +kitten show_key
 
-Then press the key you want to emulate.
+Then press the key you want to emulate. Note that this kitten will only show
+keys that actually reach the terminal program, in particular, keys mapped to
+actions in kitty will not be shown. To check those first map them to
+:ac:`no_op`.
 
 How do I open a new window or tab with the same working directory as the current window?
 --------------------------------------------------------------------------------------------
@@ -255,7 +316,7 @@ How do I open a new window or tab with the same working directory as the current
 In :file:`kitty.conf` add the following::
 
     map f1 launch --cwd=current
-    map f2  launch --cwd=current --type=tab
+    map f2 launch --cwd=current --type=tab
 
 Pressing :kbd:`F1` will open a new kitty window with the same working directory
 as the current window. The :doc:`launch command <launch>` is very powerful,
@@ -274,8 +335,8 @@ variables which kitty will now inherit.
 You need to make sure that the environment variables you define in your shell's
 rc files are either also defined system wide or via the :opt:`env` directive in
 :file:`kitty.conf`. Common environment variables that cause issues are those
-related to localization, such as ``LANG, LC_*`` and loading of configuration
-files such as ``XDG_*, KITTY_CONFIG_DIRECTORY``.
+related to localization, such as :envvar:`LANG`, ``LC_*`` and loading of
+configuration files such as ``XDG_*``, :envvar:`KITTY_CONFIG_DIRECTORY`.
 
 To see the environment variables that kitty sees, you can add the following
 mapping to :file:`kitty.conf`::
@@ -292,42 +353,42 @@ sorts of places where they may or may not work.
 I am using tmux and have a problem
 --------------------------------------
 
-First, terminal multiplexers are `a bad idea
-<https://github.com/kovidgoyal/kitty/issues/391#issuecomment-638320745>`_, do
-not use them, if at all possible. kitty contains features that do all of what
+First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`,
+do not use them, if at all possible. kitty contains features that do all of what
 tmux does, but better, with the exception of remote persistence (:iss:`391`).
 If you still want to use tmux, read on.
 
 Image display will not work, see `tmux issue
-<https://github.com/tmux/tmux/issues/1391>`_.
+<https://github.com/tmux/tmux/issues/1391>`__.
 
-If you are using tmux with multiple terminals or you start it under one
-terminal and then switch to another and these terminals have different TERM
-variables, tmux will break. You will need to restart it as tmux does not
-support multiple terminfo definitions.
+Using ancient versions of tmux such as 1.8 will cause gibberish on screen when
+pressing keys (:iss:`3541`).
 
-Copying to clipboard via OSC 52 will not work, because tmux does not support
-the extended version of that protocol, you will need to add ``no-append`` to
-:opt:`clipboard_control` in kitty.conf.
+If you are using tmux with multiple terminals or you start it under one terminal
+and then switch to another and these terminals have different :envvar:`TERM`
+variables, tmux will break. You will need to restart it as tmux does not support
+multiple terminfo definitions.
 
 If you use any of the advanced features that kitty has innovated, such as
-styled underlines, desktop notifications, extended keyboard support, etc.
-they may or may not work, depending on the whims of tmux's maintainer, your
-version of tmux, etc.
+:doc:`styled underlines </underlines>`, :doc:`desktop notifications
+</desktop-notifications>`, :doc:`extended keyboard support
+</keyboard-protocol>`, etc. they may or may not work, depending on the whims of
+tmux's maintainer, your version of tmux, etc.
 
 
 I opened and closed a lot of windows/tabs and top shows kitty's memory usage is very high?
 -------------------------------------------------------------------------------------------
 
-``top`` is not a good way to measure process memory usage. That is because on
-modern systems, when allocating memory to a process, the C library functions
-will typically allocate memory in large blocks, and give the process chunks of
-these blocks. When the process frees a chunk, the C library will not
+:program:`top` is not a good way to measure process memory usage. That is
+because on modern systems, when allocating memory to a process, the C library
+functions will typically allocate memory in large blocks, and give the process
+chunks of these blocks. When the process frees a chunk, the C library will not
 necessarily release the underlying block back to the OS. So even though the
-application has released the memory, ``top`` will still claim the process is
-using it.
+application has released the memory, :program:`top` will still claim the process
+is using it.
 
-To check for memory leaks, instead use a tool like ``valgrind``. Run::
+To check for memory leaks, instead use a tool like `Valgrind
+<https://valgrind.org/>`__. Run::
 
     PYTHONMALLOC=malloc valgrind --tool=massif kitty
 
@@ -340,14 +401,40 @@ that window, maybe run yes or find again. Then quit kitty and run::
 You will see the allocations graph goes up when you opened the windows, then
 goes back down when you closed them, indicating there were no memory leaks.
 
-For those interested, you can get a similar profile out of ``valgrind`` as you get
-with ``top`` by adding ``--pages-as-heap=yes`` then you will see that memory
-allocated in malloc is not freed in free. This can be further refined if you
-use `glibc`` as your C library by setting the environment variable
-``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free memory
-allocated in sizes of more than 64 bytes. With this set, memory usage will
-climb high, then fall when closing windows, but not fall all the way back. The
-remaining used memory can be investigated using valgrind again, and it will
+For those interested, you can get a similar profile out of :program:`valgrind`
+as you get with :program:`top` by adding ``--pages-as-heap=yes`` then you will
+see that memory allocated in malloc is not freed in free. This can be further
+refined if you use ``glibc`` as your C library by setting the environment
+variable ``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free
+memory allocated in sizes of more than 64 bytes. With this set, memory usage
+will climb high, then fall when closing windows, but not fall all the way back.
+The remaining used memory can be investigated using valgrind again, and it will
 come from arenas in the GPU drivers and the per thread arenas glibc's malloc
-maintains. These too allocate memory in large blocks and dont release it back
+maintains. These too allocate memory in large blocks and don't release it back
 to the OS immediately.
+
+
+Why does kitty sometimes start slowly on my Linux system?
+-------------------------------------------------------------------------------------------
+
+|kitty| takes no longer (within 100ms) to start than other similar GPU terminal
+emulators, (and may be faster than some). If |kitty| occasionally takes a long
+time to start, it could be a power management issue with the graphics card. On
+a multi-GPU system (which many modern laptops are, having a power efficient GPU
+that's built into the processor and a power hungry dedicated one that's usually
+off), even if the answer of the GPU will only be "don't use me".
+
+For example, if you have a system with an AMD CPU and an NVIDIA GPU, and you
+know that you want to use the lower powered card to save battery life and
+because kitty does not require a powerful GPU to function, you can choose not
+to wake up the dedicated card, which has been reported on at least one system
+(:iss:`4292`) to take ≈2 seconds, by running |kitty| as::
+
+    MESA_LOADER_DRIVER_OVERRIDE=radeonsi __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json kitty
+
+The correct command will depend on your situation and hardware.
+``__EGL_VENDOR_LIBRARY_FILENAMES`` instructs the GL dispatch library to use
+:file:`libEGL_mesa.so` and ignore :file:`libEGL_nvidia.so` also available on the
+system, which will wake the NVIDIA card during device enumeration.
+``MESA_LOADER_DRIVER_OVERRIDE`` also assures that Mesa won't offer any NVIDIA
+card during enumeration, and will instead just use :file:`radeonsi_dri.so`.

docs/file-transfer-protocol.rst

@@ -0,0 +1,535 @@
+File transfer over the TTY
+===============================
+
+There are sometimes situations where the TTY is the only convenient pipe
+between two connected systems, for example, nested SSH sessions, a serial
+line, etc. In such scenarios, it is useful to be able to transfer files
+over the TTY.
+
+This protocol provides the ability to transfer regular files, directories and
+links (both symbolic and hard) preserving most of their metadata. It can
+optionally use compression and transmit only binary diffs to speed up
+transfers. However, since all data is base64 encoded for transmission over the
+TTY, this protocol will never be competitive with more direct file transfer
+mechanisms.
+
+Overall design
+----------------
+
+The basic design of this protocol is around transfer "sessions". Since
+untrusted software should not be able to read/write to another machines
+filesystem, a session must be approved by the user in the terminal emulator
+before any actual data is transmitted, unless a :ref:`pre-shared password is
+provided <bypass_auth>`.
+
+There can be either send or receive sessions. In send sessions files are sent
+from remote client to the terminal emulator and vice versa for receive sessions.
+Every session basically consists of sending metadata for the files first and
+then sending the actual data. The session is a series of commands, every command
+carrying the session id (which should be a random unique-ish identifier, to
+avoid conflicts). The session is bi-directional with commands going both to and
+from the terminal emulator. Every command in a session also carries an
+``action`` field that specifies what the command does. The remaining fields in
+the command are dependent on the nature of the command.
+
+Let's look at some simple examples of sessions to get a feel for the protocol.
+
+
+Sending files to the computer running the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The client starts by sending a start send command::
+
+    → action=send id=someid
+
+It then waits for a status message from the terminal either
+allowing the transfer or refusing it. Until this message is received
+the client is not allowed to send any more commands for the session.
+The terminal emulator should drop a session if it receives any commands
+before sending an ``OK`` response. If the user accepts the transfer,
+the terminal will send::
+
+    ← action=status id=someid status=OK
+
+Or if the transfer is refused::
+
+    ← action=status id=someid status=EPERM:User refused the transfer
+
+The client then sends one or more ``file`` commands with the metadata of the file it wants
+to transfer::
+
+    → action=file id=someid file_id=f1 name=/path/to/destination
+    → action=file id=someid file_id=f2 name=/path/to/destination2 ftype=directory
+
+The terminal responds with either ``OK`` for directories or ``STARTED`` for
+files::
+
+    ← action=status id=someid file_id=f1 status=STARTED
+    ← action=status id=someid file_id=f2 status=OK
+
+If there was an error with the file, for example, if the terminal does not have
+permission to write to the specified location, it will instead respond with an
+error, such as::
+
+    ← action=status id=someid file_id=f1 status=EPERM:No permission
+
+The client sends data for files using ``data`` commands. It does not need to
+wait for the ``STARTED`` from the terminal for this, the terminal must discard data
+for files that are not ``STARTED``. Data for a file is sent in individual
+chunks of no larger than ``4096`` bytes. For example::
+
+
+    → action=data id=someid file_id=f1 data=chunk of bytes
+    → action=data id=someid file_id=f1 data=chunk of bytes
+    ...
+    → action=end_data id=someid file_id=f1 data=chunk of bytes
+
+The sequence of data transmission for a file is ended with an ``end_data``
+command. After each data packet is received the terminal replies with
+an acknowledgement of the form::
+
+    ← action=status id=someid file_id=f1 status=PROGRESS size=bytes written
+
+After ``end_data`` the terminal replies with::
+
+    ← action=status id=someid file_id=f1 status=OK size=bytes written
+
+If an error occurs while writing the data, the terminal replies with an error
+code and ignores further commands about that file, for example::
+
+    ← action=status id=someid file_id=f1 status=EIO:Failed to write to file
+
+Once the client has finished sending as many files as it wants to, it ends
+the session with::
+
+    → action=finish id=someid
+
+At this point the terminal commits the session, applying file metadata,
+creating links, etc. If any errors occur it responds with an error message,
+such as::
+
+    ← action=status id=someid status=Some error occurred
+
+
+Receiving files from the computer running terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The client starts by sending a start receive command::
+
+    → action=receive id=someid size=num_of_paths
+
+It then sends a list of ``num_of_paths`` paths it is interested in
+receiving::
+
+    → action=file id=someid file_id=f1 name=/some/path
+    → action=file id=someid file_id=f2 name=/some/path2
+    ...
+
+The client must then wait for responses from the terminal emulator. It
+is an error to send anymore commands to to the terminal until an ``OK``
+response is received from the terminal. The terminal wait for the user to accept
+the request. If accepted, it sends::
+
+    ← action=status id=someid status=OK
+
+If permission is denied it sends::
+
+    ← action=status id=someid status=EPERM:User refused the transfer
+
+The terminal then sends the metadata for all requested files. If any of them
+are directories, it traverses the directories recursively, listing all files.
+Note that symlinks must not be followed, but sent as symlinks::
+
+    ← action=file id=someid file_id=f1 mtime=XXX permissions=XXX name=/absolute/path status=file_id1 size=size_in_bytes file_type=type parent=file_id of parent
+    ← action=file id=someid file_id=f1 mtime=XXX permissions=XXX name=/absolute/path2 status=file_id2 size=size_in_bytes file_type=type parent=file_id of parent
+    ...
+
+Here the ``file_id`` field is set to the ``file_id`` value sent from the client
+and the ``status`` field is set to the actual file id for each file. This is
+because a file query sent from the client can result in multiple actual files if
+it is a directory. The ``parent`` field is the actual ``file_id`` of the directory
+containing this file and is set for entries that are generated from client
+requests that match directories. This allows the client to build an unambiguous picture
+of the file tree.
+
+Once all the files are listed, the terminal sends an ``OK`` response that also
+specifies the absolute path to the home directory for the user account running
+the terminal::
+
+    ← action=status id=someid status=OK name=/path/to/home
+
+If an error occurs while listing any of the files asked for by the client,
+the terminal will send an error response like::
+
+    ← action=status id=someid file_id=f1 status=ENOENT: Does not exist
+
+Here, ``file_id`` is the same as was sent by the client in its initial query.
+
+Now, the client can send requests for file data using the paths sent by the
+terminal emulator::
+
+    → action=file id=someid file_id=f1 name=/some/path
+    ...
+
+The terminal emulator replies with the data for the files, as a sequence of
+``data`` commands each with a chunk of data no larger than ``4096`` bytes,
+for each file (the terminal emulator should send the data for
+one file at a time)::
+
+
+    ← action=data id=someid file_id=f1 data=chunk of bytes
+    ...
+    ← action=end_data id=someid file_id=f1 data=chunk of bytes
+
+If any errors occur reading file data, the terminal emulator sends an error
+message for the file, for example::
+
+    ← action=status id=someid file_id=f1 status=EIO:Could not read
+
+Once the client is done reading data for all the files it expects, it
+terminates the session with::
+
+    → action=finished id=someid
+
+Canceling a session
+----------------------
+
+A client can decide to cancel a session at any time (for example if the user
+presses :kbd:`ctrl+c`). To cancel a session it sends a ``cancel`` action to the
+terminal emulator::
+
+    → action=cancel id=someid
+
+The terminal emulator drops the session and sends a cancel acknowledgement::
+
+    ← action=status id=someid status=CANCELED
+
+The client **must** wait for the canceled response from the emulator discarding
+any other responses till the cancel is received. If it does not wait, after
+it quits the responses might end up being printed to screen.
+
+Quieting responses from the terminal
+-------------------------------------
+
+The above protocol includes lots of messages from the terminal acknowledging
+receipt of data, granting permission etc., acknowledging cancel requests, etc.
+For extremely simple clients like shell scripts, it might be useful to suppress
+these responses, which can be done by adding the ``quiet`` key to the start
+session command::
+
+    → action=send id=someid quiet=1
+
+The key can take the values ``1`` - meaning suppress acknowledgement responses
+or ``2`` - meaning suppress all responses including errors. Only actual data
+responses are sent. Note that in particular this means acknowledgement of
+permission for the transfer to go ahead is suppressed, so this is typically
+useful only with :ref:`bypass_auth`.
+
+.. _file_metadata:
+
+File metadata
+-----------------
+
+File metadata includes file paths, permissions and modification times. They are
+somewhat tricky as different operating systems support different kinds of
+metadata. This specification defines a common minimum set which should work
+across most operating systems.
+
+File paths
+    File paths must be valid UTF-8 encoded POSIX paths (i.e. using the forward slash
+    ``/`` as a separator). Linux systems allow non UTF-8 file paths, these
+    are not supported. A leading ``~/`` means a path is relative to the
+    ``HOME`` directory. All path must be either absolute (i.e. with a leading
+    ``/``) or relative to the HOME directory. Individual components of the
+    path must be no longer than 255 UTF-8 bytes. Total path length must be no
+    more than 4096 bytes. Paths from Windows systems must use the forward slash
+    as the separator, the first path component must be the drive letter with a
+    colon. For example: :file:`C:\some\file.txt` is represented as
+    :file:`/C:/some/file.txt`. For maximum portability, the following
+    characters *should* be omitted from paths (however implementations are free
+    to try to support them returning errors for non-representable paths)::
+
+        \ * : < > ? | /
+
+File modification times
+    Must be represented as the number of nanoseconds since the UNIX epoch. An
+    individual file system may not store file metadata with this level of
+    accuracy in which case it should use the closest possible approximation.
+
+File permissions
+    Represented as a number with the usual UNIX read, write and execute bits.
+    In addition, the sticky, set-group-id and set-user-id bits may be present.
+    Implementations should make a best effort to preserve as many bits as
+    possible. On Windows, there is only a read-only bit. When reading file
+    metadata all the ``WRITE`` bits should be set if the read only bit is clear
+    and cleared if it is set. When writing files, the read-only bit should be
+    set if the bit indicating write permission for the user is clear. The other
+    UNIX bits must be ignored when writing. When reading, all the ``READ`` bits
+    should always be set and all the ``EXECUTE`` bits should be set if the file is
+    directly executable by the Windows Operating system. There is no attempt to
+    map Window's ACLs to permission bits.
+
+
+Symbolic and hard links
+---------------------------
+
+Symbolic and hard links can be preserved by this protocol.
+
+.. note::
+   In the following when target paths of symlinks are sent as actual paths, they must be
+   encoded in the same way as discussed in :ref:`file_metadata`. It is up to
+   the receiving side to translate them into appropriate paths for the local
+   operating system. This may not always be possible, in which case either the
+   symlink should not be created or a broken symlink should be created.
+
+
+Sending links to the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When sending files to the terminal emulator, the file command has the form::
+
+    → action=file id=someid file_id=f1 name=/path/to/link file_type=link
+    → action=file id=someid file_id=f2 name=/path/to/symlink file_type=symlink
+
+Then, when the client is sending data for the files, for hardlinks, the data
+will be the ``file_id`` of the target file (assuming the target file is also
+being transmitted, otherwise the hard link should be transmitted as a plain
+file)::
+
+    → action=end_data id=someid file_id=f1 data=target_file_id_encoded_as_utf8
+
+For symbolic links, the data is a little more complex. If the symbolic link is
+to a destination being transmitted, the data has the form::
+
+    → action=end_data id=someid file_id=f1 data=fid:target_file_id_encoded_as_utf8
+    → action=end_data id=someid file_id=f1 data=fid_abs:target_file_id_encoded_as_utf8
+
+The ``fid_abs`` form is used if the symlink uses an absolute path, ``fid`` if
+it uses a relative path. If the symlink is to a destination that is not being
+transmitted, then the prefix ``path:`` and the actual path in the symlink is
+transmitted.
+
+Receiving links from the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When receiving files from the terminal emulator, link data is transmitted in
+two parts. First when the emulator sends the initial file listing to the
+client, the ``file_type`` is set to the link type and the ``data`` field is set
+to file_id of the target file if the target file is included in the listing.
+For example::
+
+    ← action=file id=someid file_id=f1 status=file_id1 ...
+    ← action=file id=someid file_id=f1 status=file_id2 file_type=symlink data=file_id1 ...
+
+Here the rest of the metadata has been left out for clarity. Notice that the
+second file is symlink whose ``data`` field is set to the file id of the first
+file (the value of the ``status`` field of the first file). The same technique
+is used for hard links.
+
+The client should not request data for hard links, instead creating them
+directly after transmission is complete. For symbolic links the terminal
+must send the actual symbolic link target as a UTF-8 encoded path in the
+data field. The client can use this path either as-is (when the target is not
+a transmitted file) or to decide whether to create the symlink with a relative
+or absolute path when the target is a transmitted file.
+
+
+Transmitting binary deltas
+-----------------------------
+
+Repeated transfer of large files that have only changed a little between
+the receiving and sending side can be sped up significantly by transmitting
+binary deltas of only the changed portions. This protocol has built-in support
+for doing that. This support uses the `rsync algorithm
+<https://github.com/librsync/librsync>`__. In this algorithm first the
+receiving side sends a file signature that contains hashes of blocks
+in the file. Then the sending side sends only those blocks that have changed.
+The receiving side applies these deltas to the file to update it till it matches
+the file on the sending side.
+
+The modification to the basic protocol consists of setting the
+``transmission_type`` key to ``rsync`` when requesting a file. This triggers
+transmission of signatures and deltas instead of file data. The details are
+different for sending and receiving.
+
+Sending to the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When sending the metadata of the file it wants to transfer, the client adds the
+``transmission_type`` key::
+
+    → action=file id=someid file_id=f1 name=/path/to/destination transmission_type=rsync
+
+The ``STARTED`` response from the terminal will have ``transmission_type`` set
+to ``rsync`` if the file exists and the terminal is able to send signature data::
+
+    ← action=status id=someid file_id=f1 status=STARTED transmission_type=rsync
+
+The terminal then transmits the signature using ``data`` commands::
+
+    ← action=data id=someid file_id=f1 data=...
+    ...
+    ← action=end_data id=someid file_id=f1 data=...
+
+Once the client receives and processes the full signature, it transmits the
+file delta to the terminal as ``data`` commands::
+
+    → action=data id=someid file_id=f1 data=...
+    → action=data id=someid file_id=f1 data=...
+    ...
+    → action=end_data id=someid file_id=f1 data=...
+
+The terminal then uses this delta to update the file.
+
+Receiving from the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the client requests file data from the terminal emulator, it can
+add the ``transmission_type=rsync`` key to indicate it will be sending
+a signature for that file::
+
+    → action=file id=someid file_id=f1 name=/some/path transmission_type=rsync
+
+The client then sends the signature using ``data`` commands::
+
+    → action=data id=someid file_id=f1 data=...
+    ...
+    → action=end_data id=someid file_id=f1 data=...
+
+After receiving the signature the terminal replies with the delta as a series
+of ``data`` commands::
+
+    ← action=data id=someid file_id=f1 data=...
+    ...
+    ← action=end_data id=someid file_id=f1 data=...
+
+The client then uses this delta to update the file.
+
+The format of signatures and deltas
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These come from `librsync <https://github.com/librsync/librsync>`__. If this
+specification gains wider adoption, these formats should be documented here.
+
+Compression
+--------------
+
+Individual files can be transmitted compressed if needed.
+Currently, only :rfc:`1950` ZLIB based deflate compression is
+supported, which is specified using the ``compression=zlib`` key when
+requesting a file. For example when sending files to the terminal emulator,
+when sending the file metadata the ``compression`` key can also be
+specified::
+
+    → action=file id=someid file_id=f1 name=/path/to/destination compression=zlib
+
+Similarly when receiving files from the terminal emulator, the final file
+command that the client sends to the terminal requesting the start of the
+transfer of data for the file can include the ``compression`` key::
+
+    → action=file id=someid file_id=f1 name=/some/path compression=zlib
+
+.. _bypass_auth:
+
+Bypassing explicit user authorization
+------------------------------------------
+
+In order to bypass the requirement of interactive user authentication,
+this protocol has the ability to use a pre-shared secret (password).
+When initiating a transfer session the client sends a hash of the password and
+the session id::
+
+    → action=send id=someid bypass=sha256:hash_value
+
+For example, suppose that the session id is ``mysession`` and the
+shared secret is ``mypassword``. Then the value of the ``bypass``
+key above is ``sha256:SHA256("mysession" + ";" + "mypassword")``, which
+is::
+
+    → action=send id=mysession bypass=sha256:192bd215915eeaa8c2b2a4c0f8f851826497d12b30036d8b5b1b4fc4411caf2c
+
+The value of ``bypass`` is of the form ``hash_function_name : hash_value``
+(without spaces). Currently, only the SHA256 hash function is supported.
+
+.. warning::
+   Hashing does not effectively hide the value of the password. So this
+   functionality should only be used in secure/trusted contexts. While there
+   exist hash functions harder to compute than SHA256, they are unsuitable as
+   they will introduce a lot of latency to starting a session and in any case
+   there is no mathematical proof that **any** hash function is not brute-forceable.
+
+Encoding of transfer commands as escape codes
+------------------------------------------------
+
+Transfer commands are encoded as ``OSC`` escape codes of the form::
+
+    <OSC> 5113 ; key=value ; key=value ... <ST>
+
+Here ``OSC`` is the bytes ``0x1b 0x5d`` and ``ST`` is the bytes
+``0x1b 0x5c``. Keys are words containing only the characters ``[a-zA-Z0-9_]``
+and ``value`` is arbitrary data, whose encoding is dependent on the value of
+``key``. Unknown keys **must** be ignored when decoding a command.
+The number ``5113`` is a constant and is unused by any known OSC codes. It is
+the numeralization of the word ``file``.
+
+
+.. table:: The keys and value types for this protocol
+    :align: left
+
+    ================= ======== ============== =======================================================================
+    Key               Key name Value type     Notes
+    ================= ======== ============== =======================================================================
+    action            ac       enum           send, file, data, end_data, receive, cancel, status, finish
+    compression       zip      enum           none, zlib
+    file_type         ft       enum           regular, directory, symlink, link
+    transmission_type tt       enum           simple, rsync
+    id                id       safe_string    A unique-ish value, to avoid collisions
+    file_id           fid      safe_string    Must be unique per file in a session
+    bypass            pw       safe_string    hash of the bypass password and the session id
+    quiet             q        integer        0 - verbose, 1 - only errors, 2 - totally silent
+    mtime             mod      integer        the modification time of file in nanoseconds since the UNIX epoch
+    permissions       prm      integer        the UNIX file permissions bits
+    size              sz       integer        size in bytes
+    name              n        base64_string  The path to a file
+    status            st       base64_string  Status messages
+    parent            pr       safe_string    The file id of the parent directory
+    data              d        base64_bytes   Binary data
+    ================= ======== ============== =======================================================================
+
+The ``Key name`` is the actual serialized name of the key sent in the escape
+code. So for example, ``permissions=123`` is serialized as ``prm=123``. This
+is done to reduce overhead.
+
+The value types are:
+
+enum
+    One from a permitted set of values, for example::
+
+        ac=file
+
+safe_string
+    A string consisting only of characters from the set ``[0-9a-zA-Z_:.,/!@#$%^&*()[]{}~`?"'\\|=+-]``
+    Note that the semi-colon is missing from this set.
+
+integer
+    A base-10 number composed of the characters ``[0-9]`` with a possible
+    leading ``-`` sign
+
+base64_string
+    A base64 encoded UTF-8 string using the standard base64 encoding
+
+base64_bytes
+    Binary data encoded using the standard base64 encoding
+
+
+An example of serializing an escape code is shown below::
+
+    action=send id=test name=somefile size=3 data=01 02 03
+
+becomes::
+
+    <OSC> 5113 ; ac=send ; id=test ; n=c29tZWZpbGU= ; sz=3 ; d=AQID <ST>
+
+Here ``c29tZWZpbGU`` is the base64 encoded form of somefile and ``AQID`` is the
+base64 encoded form of the bytes ``0x01 0x02 0x03``. The spaces in the encoded
+form are present for clarity and should be ignored.

docs/glossary.rst

@@ -0,0 +1,215 @@
+:orphan:
+
+Glossary
+=========
+
+.. glossary::
+
+   os_window
+     kitty has two kinds of windows. Operating System windows, refered to as :term:`OS
+     Window <os_window>`, and *kitty windows*. An OS Window consists of one or more kitty
+     :term:`tabs <tab>`. Each tab in turn consists of one or more *kitty
+     windows* organized in a :term:`layout`.
+
+   tab
+     A *tab* refers to a group of :term:`kitty windows <window>`, organized in
+     a :term:`layout`. Every :term:`OS Window <os_window>` contains one or more tabs.
+
+   layout
+     A *layout* is a system of organizing :term:`kitty windows <window>` in
+     groups inside a tab. The layout automatically maintains the size and
+     position of the windows, think of a layout as a tiling window manager for
+     the terminal. See :doc:`layouts` for details.
+
+   window
+     kitty has two kinds of windows. Operating System windows, refered to as :term:`OS
+     Window <os_window>`, and *kitty windows*. An OS Window consists of one or more kitty
+     :term:`tabs <tab>`. Each tab in turn consists of one or more *kitty
+     windows* organized in a :term:`layout`.
+
+   overlay
+      An *overlay window* is a :term:`kitty window <window>` that is placed on
+      top of an existing kitty window, entirely covering it. Overlays are used
+      throught kitty, for example, to display the :ref:`the scrollback buffer <scrollback>`,
+      to display :doc:`hints </kittens/hints>`, for :doc:`unicode input
+      </kittens/unicode_input>` etc.
+
+   hyperlinks
+      Terminals can have hyperlinks, just like the internet. In kitty you can
+      :doc:`control exactly what happens <open_actions>` when clicking on a
+      hyperlink, based on the type of link and its URL. See also `Hyperlinks in terminal
+      emulators <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`__.
+
+.. _env_vars:
+
+Environment variables
+------------------------
+
+Variables that influence kitty behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. envvar:: KITTY_CONFIG_DIRECTORY
+
+   Controls where kitty looks for :file:`kitty.conf` and other configuration
+   files. Defaults to :file:`~/.config/kitty`. For full details of the config
+   directory lookup mechanism see, :option:`kitty --config`.
+
+.. envvar:: KITTY_CACHE_DIRECTORY
+
+   Controls where kitty stores cache files. Defaults to :file:`~/.cache/kitty`
+   or :file:`~/Library/Caches/kitty` on macOS.
+
+.. envvar:: KITTY_RUNTIME_DIRECTORY
+
+   Controls where kitty stores runtime files like sockets. Defaults to
+   the :code:`XDG_RUNTIME_DIR` environment variable if that is defined
+   otherwise the run directory inside the kitty cache directory is used.
+
+.. envvar:: VISUAL
+
+   The terminal based text editor (such as :program:`vi` or :program:`nano`)
+   kitty uses, when, for instance, opening :file:`kitty.conf` in response to
+   :sc:`edit_config_file`.
+
+.. envvar:: EDITOR
+
+   Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set.
+
+.. envvar:: GLFW_IM_MODULE
+
+   Set this to ``ibus`` to enable support for IME under X11.
+
+.. envvar:: KITTY_WAYLAND_DETECT_MODIFIERS
+
+   When set to a non-empty value, kitty attempts to autodiscover XKB modifiers
+   under Wayland. This is useful if using non-standard modifers like hyper. It
+   is possible for the autodiscovery to fail; the default Wayland XKB mappings
+   are used in this case. See :pull:`3943` for details.
+
+.. envvar:: SSH_ASKPASS
+
+   Specify the program for SSH to ask for passwords. When this is set, :doc:`ssh
+   kitten </kittens/ssh>` will use this environment variable by default. See
+   :opt:`askpass <kitten-ssh.askpass>` for details.
+
+.. envvar:: KITTY_CLONE_SOURCE_CODE
+
+   Set this to some shell code that will be executed in the cloned window with
+   :code:`eval` when :ref:`clone-in-kitty <clone_shell>` is used.
+
+.. envvar:: KITTY_CLONE_SOURCE_PATH
+
+   Set this to the path of a file that will be sourced in the cloned window when
+   :ref:`clone-in-kitty <clone_shell>` is used.
+
+.. envvar:: KITTY_DEVELOP_FROM
+
+   Set this to the directory path of the kitty source code and its Python code
+   will be loaded from there. Only works with official binary builds.
+
+
+Variables that kitty sets when running child programs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. envvar:: LANG
+
+   This is only set on macOS. If the country and language from the macOS user
+   settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
+
+
+.. envvar:: PATH
+
+   kitty prepends itself to the PATH of its own environment to ensure the
+   functions calling :program:`kitty` will work properly.
+
+
+.. envvar:: KITTY_WINDOW_ID
+
+   An integer that is the id for the kitty :term:`window` the program is running in.
+   Can be used with the :doc:`kitty remote control facility <remote-control>`.
+
+
+.. envvar:: KITTY_PID
+
+   An integer that is the process id for the kitty process in which the program
+   is running. Allows programs to tell kitty to reload its config by sending it
+   the SIGUSR1 signal.
+
+
+.. envvar:: WINDOWID
+
+   The id for the :term:`OS Window <os_window>` the program is running in. Only available
+   on platforms that have ids for their windows, such as X11 and macOS.
+
+
+.. envvar:: TERM
+
+   The name of the terminal, defaults to ``xterm-kitty``. See :opt:`term`.
+
+
+.. envvar:: TERMINFO
+
+   Path to a directory containing the kitty terminfo database.
+
+
+.. envvar:: KITTY_INSTALLATION_DIR
+
+   Path to the kitty installation directory.
+
+
+.. envvar:: COLORTERM
+
+   Set to the value ``truecolor`` to indicate that kitty supports 16 million
+   colors.
+
+
+.. envvar:: KITTY_LISTEN_ON
+
+   Set when the :doc:`remote control <remote-control>` facility is enabled and
+   the a socket is used for control via :option:`kitty --listen-on` or :opt:`listen_on`.
+   Contains the path to the socket. Avoid the need to use :option:`kitty @ --to` when
+   issuing remote control commands.
+
+
+.. envvar:: KITTY_PIPE_DATA
+
+   Set to data describing the layout of the screen when running child
+   programs using :option:`launch --stdin-source` with the contents of the
+   screen/scrollback piped to them.
+
+
+.. envvar:: KITTY_CHILD_CMDLINE
+
+   Set to the command line of the child process running in the kitty
+   window when calling the notification callback program on terminal bell, see
+   :opt:`command_on_bell`.
+
+
+.. envvar:: KITTY_COMMON_OPTS
+
+   Set with the values of some common kitty options when running
+   kittens, so kittens can use them without needing to load :file:`kitty.conf`.
+
+
+.. envvar:: KITTY_SHELL_INTEGRATION
+
+   Set when enabling :ref:`shell_integration`. It is automatically removed by
+   the shell integration scripts.
+
+
+.. envvar:: ZDOTDIR
+
+   Set when enabling :ref:`shell_integration` with :program:`zsh`, allowing
+   :program:`zsh` to automatically load the integration script.
+
+
+.. envvar:: XDG_DATA_DIRS
+
+   Set when enabling :ref:`shell_integration` with :program:`fish`, allowing
+   :program:`fish` to automatically load the integration script.
+
+
+.. envvar:: ENV
+
+   Set when enabling :ref:`shell_integration` with :program:`bash`, allowing
+   :program:`bash` to automatically load the integration script.

docs/graphics-protocol.rst

@@ -1,21 +1,18 @@
-:tocdepth: 3
-
-The terminal graphics protocol
-==================================
+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
+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.
+* 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>`_.
+For some discussion regarding the design choices, see :iss:`33`.
 
 To see a quick demo, inside a |kitty| terminal run::
 
@@ -30,23 +27,28 @@ alpha-blending and text over graphics.
 
 Some programs and libraries that use the kitty graphics protocol:
 
- * `termpdf.py <https://github.com/dsanson/termpdf.py>`_ - 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
- * `pixcat <https://github.com/mirukana/pixcat>`_ - a third party CLI and python library that wraps the graphics protocol
- * `neofetch <https://github.com/dylanaraps/neofetch>`_ - A command line system
-   information tool
- * `viu <https://github.com/atanunq/viu>`_ - a terminal image viewer
- * `glkitty <https://github.com/michaeljclark/glkitty>`_ - C library to draw OpenGL shaders in the terminal with a glgears demo
- * `ctx.graphics <https://ctx.graphics/>`_ - Library for drawing graphics
- * `timg <https://github.com/hzeller/timg>`_ - a terminal image and video viewer
- * `notcurses <https://github.com/dankamongmen/notcurses>`_ - C library for terminal graphics with bindings for C++, Rust and Python
- * `rasterm <https://github.com/BourgeoisBear/rasterm>`_  - Go library to display images in the the terminal
+* `termpdf.py <https://github.com/dsanson/termpdf.py>`_ - 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
+* `tpix <https://github.com/jesvedberg/tpix>` - a statically compiled binary that can be used to display images and easily installed on remote servers without root access
+* `pixcat <https://github.com/mirukana/pixcat>`_ - a third party CLI and python library that wraps the graphics protocol
+* `neofetch <https://github.com/dylanaraps/neofetch>`_ - A command line system
+  information tool
+* `viu <https://github.com/atanunq/viu>`_ - a terminal image viewer
+* `glkitty <https://github.com/michaeljclark/glkitty>`_ - C library to draw OpenGL shaders in the terminal with a glgears demo
+* `ctx.graphics <https://ctx.graphics/>`_ - Library for drawing graphics
+* `timg <https://github.com/hzeller/timg>`_ - a terminal image and video viewer
+* `notcurses <https://github.com/dankamongmen/notcurses>`_ - C library for terminal graphics with bindings for C++, Rust and Python
+* `rasterm <https://github.com/BourgeoisBear/rasterm>`_  - Go library to display images in the terminal
+* `chafa <https://github.com/hpjansson/chafa>`_  - a terminal image viewer
+* `hologram.nvim <https://github.com/edluffy/hologram.nvim>`_  - view images inside nvim
 
+Other terminals that have implemented the graphics protocol:
 
-.. contents::
-   :local:
+* `WezTerm <https://github.com/wez/wezterm/issues/986>`_
+* `Konsole <https://invent.kde.org/utilities/konsole/-/merge_requests/594>`_
+* `wayst <https://github.com/91861/wayst>`_
 
 
 Getting the window size
@@ -57,28 +59,33 @@ 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:
+.. tab:: C
 
-.. code-block:: c
+    .. code-block:: c
 
-    #include <stdio.h>
-    #include <sys/ioctl.h>
+        #include <stdio.h>
+        #include <sys/ioctl.h>
 
-    int main(int argc, char **argv) {
-        struct winsize sz;
-        ioctl(0, TIOCGWINSZ, &sz);
-        printf("number of rows: %i, number of columns: %i, screen width: %i, screen height: %i\n", sz.ws_row, sz.ws_col, sz.ws_xpixel, sz.ws_ypixel);
-        return 0;
-    }
+        int main(int argc, char **argv) {
+            struct winsize sz;
+            ioctl(0, TIOCGWINSZ, &sz);
+            printf(
+                "number of rows: %i, number of columns: %i, screen width: %i, screen height: %i\n",
+                sz.ws_row, sz.ws_col, sz.ws_xpixel, sz.ws_ypixel);
+            return 0;
+        }
 
-In Python:
 
-.. code-block:: python
+.. tab:: Python
 
-    import array, fcntl, sys, termios
-    buf = array.array('H', [0, 0, 0, 0])
-    fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf)
-    print('number of rows: {}, number of columns: {}, screen width: {}, screen height: {}'.format(*buf))
+    .. code-block:: python
+
+        import array, fcntl, sys, termios
+        buf = array.array('H', [0, 0, 0, 0])
+        fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf)
+        print((
+            'number of rows: {} number of columns: {}'
+            '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
@@ -98,32 +105,36 @@ features of the graphics protocol:
 
 .. code-block:: python
 
-   import sys
-   from base64 import standard_b64encode
+    import sys
+    from base64 import standard_b64encode
 
-   def serialize_gr_command(cmd, payload=None):
-      cmd = ','.join('{}={}'.format(k, v) for k, v in cmd.items())
-      ans = []
-      w = ans.append
-      w(b'\033_G'), w(cmd.encode('ascii'))
-      if payload:
-         w(b';')
-         w(payload)
-      w(b'\033\\')
-      return b''.join(ans)
 
-   def write_chunked(cmd, data):
-      data = standard_b64encode(data)
-      while data:
-         chunk, data = data[:4096], data[4096:]
-         m = 1 if data else 0
-         cmd['m'] = m
-         sys.stdout.buffer.write(serialize_gr_command(cmd, chunk))
-         sys.stdout.flush()
-         cmd.clear()
+    def serialize_gr_command(**cmd):
+        payload = cmd.pop('payload', None)
+        cmd = ','.join(f'{k}={v}' for k, v in cmd.items())
+        ans = []
+        w = ans.append
+        w(b'\033_G'), w(cmd.encode('ascii'))
+        if payload:
+            w(b';')
+            w(payload)
+        w(b'\033\\')
+        return b''.join(ans)
 
-   with open(sys.argv[-1], 'rb') as f:
-      write_chunked({'a': 'T', 'f': 100}, f.read())
+
+    def write_chunked(**cmd):
+        data = standard_b64encode(cmd.pop('data'))
+        while data:
+            chunk, data = data[:4096], data[4096:]
+            m = 1 if data else 0
+            sys.stdout.buffer.write(serialize_gr_command(payload=chunk, m=m,
+                                                        **cmd))
+            sys.stdout.flush()
+            cmd.clear()
+
+
+    with open(sys.argv[-1], 'rb') as f:
+        write_chunked(a='T', f=100, data=f.read())
 
 
 Save this script as :file:`png.py`, then you can use it to display any PNG
@@ -220,20 +231,25 @@ and can take the values:
 Value of `t`          Meaning
 ==================    ============
 ``d``                 Direct (the data is transmitted within the escape code itself)
-``f``                 A simple file
+``f``                 A simple file (regular files only, not named pipes or similar)
 ``t``                 A temporary file, the terminal emulator will delete the file after reading the pixel data. For security reasons
                       the terminal emulator should only delete the file if it
                       is in a known temporary directory, such as :file:`/tmp`,
                       :file:`/dev/shm`, :file:`TMPDIR env var if present` and any platform
                       specific temporary directories.
-``s``                 A *shared memory object*, which on POSIX systems is a `POSIX shared memory object
-                      <http://man7.org/linux/man-pages/man7/shm_overview.7.html>`_ and on Windows is a
+``s``                 A *shared memory object*, which on POSIX systems is a
+                      `POSIX shared memory object <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shm_open.html>`_
+                      and on Windows is a
                       `Named shared memory object <https://docs.microsoft.com/en-us/windows/win32/memory/creating-named-shared-memory>`_.
                       The terminal emulator must read the data from the memory
                       object and then unlink and close it on POSIX and just
                       close it on Windows.
 ==================    ============
 
+When opening files, the terminal emulator must follow symlinks. In case of
+symlink loops or too many symlinks, it should fail and respond with an error,
+similar to reporting any other kind of I/O error.
+
 Local client
 ^^^^^^^^^^^^^^
 
@@ -312,14 +328,14 @@ 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.
 
-While as of May 2020, kitty is the only terminal emulator to support this
-graphics protocol, we intend that any terminal emulator that wishes to support
-it can. To check if a terminal emulator supports the graphics protocol the best way
-is to send the above *query action* followed by a request for the
-`primary device attributes <https://vt100.net/docs/vt510-rm/DA1.html>`_. If you
-get back an answer for the device attributes without getting back an answer for
-the *query action* the terminal emulator does not support the graphics
-protocol.
+As of April 2022, kitty and WezTerm are the only terminal emulators to
+support this graphics protocol completely, with Konsole and wayst having partial support.
+We intend that any terminal emulator that wishes to support it can do so. To
+check if a terminal emulator supports the graphics protocol the best way is to
+send the above *query action* followed by a request for the `primary device
+attributes <https://vt100.net/docs/vt510-rm/DA1.html>`_. If you get back an
+answer for the device attributes without getting back an answer for the *query
+action* the terminal emulator does not support the graphics protocol.
 
 This means that terminal emulators that support the graphics protocol, **must**
 reply to *query actions* immediately without processing other input. Most
@@ -590,7 +606,7 @@ Clients can control animations by using the ``a=a`` key in the escape code sent
 to the terminal.
 
 The simplest is client driven animations, where the client transmits the frame
-data and the also instructs the terminal to make a particular frame the current
+data and then also instructs the terminal to make a particular frame the current
 frame.  To change the current frame, use the ``c`` key::
 
     <ESC>_Ga=a,i=3,c=7<ESC>\
@@ -632,6 +648,45 @@ static background.
 In particular, the first frame or *root frame* is created with the base image
 data and has no gap, so its gap must be set using this control code.
 
+Composing animation frames
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.22.0
+   Support for frame composition
+
+Clients can *compose* animation frames, this means that they can compose pixels
+in rectangular regions from one frame onto another frame. This allows for fast
+and low band-width modification of frames.
+
+To achieve this use the ``a=c`` key. The source frame is specified with
+``r=frame number`` and the destination frame as ``c=frame number``. The size of
+the rectangle is specified as ``w=width,h=height`` pixels. If unspecified, the
+full image width and height are used. The offset of the rectangle from the
+top-left corner for the source frame is specified by the ``x,y`` keys and the
+destination frame by the ``X,Y`` keys. The composition operation is specified
+by the ``C`` key with the default being to alpha blend the source rectangle
+onto the destination rectangle. With ``C=1`` it will be a simple replacement
+of pixels. For example::
+
+    <ESC>_Gi=1,r=7,c=9,w=23,h=27,X=4,Y=8,x=1,y=3<ESC>\
+
+Will compose a ``23x27`` rectangle located at ``(4, 8)`` in the ``7th frame``
+onto the rectangle located at ``(1, 3)`` in the ``9th frame``. These will be
+in the image with ``id=1``.
+
+If the frames or the image are not found the terminal emulator must
+respond with `ENOENT`. If the rectangles go out of bounds of the image
+the terminal must respond with `EINVAL`. If the source and destination frames are
+the same and the rectangles overlap, the terminal must respond with `EINVAL`.
+
+
+.. note::
+   In kitty, doing a composition will cause a frame to be *fully rendered*
+   potentially increasing its storage requirements, when the frame was previously
+   stored as a set of operations on other frames. If this happens and there
+   is not enough storage space, kitty will respond with ENOSPC.
+
+
 Image persistence and storage quotas
 -----------------------------------------
 
@@ -654,10 +709,10 @@ 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)``              ``t`` - transmit data, ``T`` - transmit data and display image,
-                                          ``q`` - query terminal, ``p`` - put (display) previous transmitted image,
+         ``(a, c, d, f, ``                ``t`` - transmit data, ``T`` - transmit data and display image,
+         ``p, q, t, T)``                  ``q`` - query terminal, ``p`` - put (display) previous transmitted image,
                                           ``d`` - delete image, ``f`` - transmit data for animation frames,
-                                          ``a`` - control animation
+                                          ``a`` - control animation, ``c`` - compose animation frames
 
 ``q``    ``0, 1, 2``           ``0``      Suppress responses from the terminal to this graphics command.
 
@@ -711,6 +766,20 @@ Key      Value                 Default    Description
 ``Y``    Positive integer      ``0``      The background color for pixels not
                                           specified in the frame data. Must be in 32-bit RGBA format
 
+**Keys for animation frame composition**
+-----------------------------------------------------------
+
+``c``    Positive integer      ``0``      The 1-based frame number of the frame whose image data serves as the overlaid data
+``r``    Positive integer      ``0``      The 1-based frame number of the frame that is being edited.
+``x``    Positive integer      ``0``      The left edge (in pixels) of the destination rectangle
+``y``    Positive integer      ``0``      The top edge (in pixels) of the destination rectangle
+``w``    Positive integer      ``0``      The width (in pixels) of the source and destination rectangles. By default, the entire width is used
+``h``    Positive integer      ``0``      The height (in pixels) of the source and destination rectangles. By default, the entire height is used
+``X``    Positive integer      ``0``      The left edge (in pixels) of the source rectangle
+``Y``    Positive integer      ``0``      The top edge (in pixels) of the source rectangle
+``C``    Positive integer      ``0``      The composition mode for blending
+                                          pixels. Default is full alpha blending. ``1`` means a simple overwrite.
+
 
 **Keys for animation control**
 -----------------------------------------------------------

docs/index.rst

@@ -1,421 +1,74 @@
-:tocdepth: 2
-
-==========================================================
-kitty - the fast, featureful, GPU based terminal emulator
+kitty
 ==========================================================
 
-.. 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
-      <https://gist.github.com/XVilka/8346728>`_,
-      OpenType ligatures, mouse protocol, :doc:`hyperlinks <open_actions>`,
-      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.
-
-    * Has :ref:`multiple copy/paste buffers <cpbuf>`, like vim.
-
-
-.. 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
-
-
-
-.. contents::
-   :local:
-   :depth: 1
-
-
-.. _quickstart:
-
-Quickstart
---------------
-
-Pre-built binaries of |kitty| are available for both macOS and Linux.
-See the :doc:`binary install instructions </binary>`. You can also
-:doc:`build from source </build>`.
-
-Additionally, you can use your favorite package manager to install the |kitty|
-package, but note that some Linux distribution packages are woefully outdated.
-|kitty| is available in a vast number of package repositories for macOS
-and Linux.
-
-.. image:: https://repology.org/badge/tiny-repos/kitty.svg
-   :target: https://repology.org/project/kitty/versions
-   :alt: Number of repositories kitty is available in
-
-See :doc:`Configuring kitty <conf>` for help on configuring |kitty| and
-:doc:`Invocation <invocation>` for the command line arguments |kitty| supports.
-
-
-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 little effort.
-
-.. include:: basic.rst
-
-.. _layouts:
-
-Layouts
-----------
-
-A layout is an arrangement of multiple kitty *windows* inside a top-level OS window. You can create a new window
-using the :sc:`new_window` key combination.
-
-Currently, there are seven layouts available:
-
-* **Fat** -- One (or optionally more) windows are 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
-* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits
-* **Stack** -- Only a single maximized window is shown at a time
-* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right
-* **Vertical** -- All windows are shown one below the other
-
-By default, all layouts are enabled and 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. The first layout listed in
-:opt:`enabled_layouts` becomes the default layout.
-
-For more details on the layouts and how to use them see :doc:`layouts`.
-
-.. _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:`Remote file <kittens/remote_file>`
-    Edit, open, or download remote files over SSH easily, by simply clicking on
-    the filename.
-
-
-:doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
-    Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`_
-    and open the results directly in your favorite editor in the terminal,
-    at the line containing the search result, simply by clicking on the result you want.
-
-
-:doc:`Broadcast <kittens/broadcast>`
-    Type in one kitty window and have it broadcast to all (or a subset) of
-    other kitty windows.
-
-
-: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.
-
-You can also :doc:`Learn to create your own kittens <kittens/custom>`.
-
-
-Configuring kitty
--------------------
-
-|kitty| is highly configurable, everything from keyboard shortcuts to
-painting frames-per-second. Press :sc:`edit_config_file` in kitty
-to open its fully commented sample config file in your text editor.
-For details see the :doc:`configuration docs <conf>`.
-
-
-Remote control
-------------------
-
-|kitty| has a very powerful system that allows you to control it from the
-:doc:`shell prompt, even over SSH <remote-control>`. You can change colors,
-fonts, open new windows, tabs, set their titles, change window layout, get text
-from one window and send text to another, etc, etc. The possibilities are
-endless. See the :doc:`tutorial <remote-control>` to get started.
-
-.. _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
-    launch --title "Chat with x" 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
-
-    # Create a new OS window
-    new_os_window
-    # set new window size to 80x25 cells
-    os_window_size 80c 25c
-    # set the --class for the new OS window
-    os_window_class mywindow
-    launch sh
-    # Make the current window the active (focused) window
-    focus
-    launch emacs
-
-.. note::
-    The :doc:`launch <launch>` command when used in a session file
-    cannot create new OS windows, or tabs.
-
-
-Mouse features
--------------------
-
-* You can click on a URL to open it in a browser.
-* You can double click to select a word and then drag to select more words.
-* You can triple click to select a line and then drag to select more lines.
-* You can triple click while holding :kbd:`ctrl+alt` to select from clicked
-  point to end of line.
-* You can right click to extend a previous selection.
-* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in
-  columns.
-* Selecting text automatically copies it to the primary clipboard (on
-  platforms with a primary clipboard).
-* You can middle click to paste from the primary clipboard (on platforms
-  with a primary clipboard).
-* You can select text with kitty even when a terminal program has grabbed
-  the mouse by holding down the :kbd:`shift` key.
-
-All these actions can be customized in :file:`kitty.conf` as described
-:ref:`here <conf-kitty-mouse.mousemap>`.
-
-
-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.
-
-Additionally, you can pipe the contents of the scrollback buffer to an
-arbitrary, command running in a new window, tab or overlay, for example::
-
-   map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
-
-Would open the scrollback buffer in a new window when you press the :kbd:`F1`
-key. See :sc:`show_scrollback` for details.
-
-If you want to use it with an editor such as vim to get more powerful features,
-you can see tips for doing so, in
-`this thread <https://github.com/kovidgoyal/kitty/issues/719>`_.
-
-If you wish to store very large amounts of scrollback to view using the piping or
-:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size`
-option.
-
-.. _cpbuf:
-
-Multiple copy/paste buffers
------------------------------
-
-In addition to being able to copy/paste from the system clipboard, in |kitty| you
-can also setup an arbitrary number of copy paste buffers. To do so, simply add
-something like the following to your :file:`kitty.conf`::
-
-   map f1 copy_to_buffer a
-   map f2 paste_from_buffer a
-
-This will allow you to press :kbd:`F1` to copy the current selection to an
-internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
-names are arbitrary strings, so you can define as many such buffers as you
-need.
-
-Marks
--------------
-
-kitty has the ability to mark text on the screen based on regular expressions.
-This can be useful to highlight words or phrases when browsing output from long
-running programs or similar. To learn how this feature works, see :doc:`marks`.
-
-
-Frequently Asked Questions
----------------------------------
-
-The list of Frequently Asked Questions (*FAQ*) is :doc:`available here <faq>`.
-
-.. _completion:
-
-
-Cool integrations for kitty with other CLI tools
---------------------------------------------------
-
-kitty provides extremely powerful interfaces such as :doc:`remote-control` and
-:doc:`kittens/custom` and :doc:`kittens/icat`
-that allow it to be integrated with other tools seamlessly. For a list of such
-user created integrations, see: :doc:`integrations`.
-
-Completion for kitty
----------------------------------
-
-|kitty| comes with completion for the ``kitty`` command for popular shells.
-
-
-bash
-~~~~~~~~
-
-Add the following to your :file:`~/.bashrc`
-
-.. code-block:: sh
-
-   source <(kitty + complete setup bash)
-
-Older versions of bash (for example, v3.2) do not support
-process substitution with the source command, in which
-case you can try an alternative:
-
-.. code-block:: sh
-
-    source /dev/stdin <<<"$(kitty + complete setup bash)"
-
-
-zsh
-~~~~~~~~~
-
-Add the following to your :file:`~/.zshrc`
-
-.. code-block:: sh
-
-    autoload -Uz compinit
-    compinit
-    # Completion for kitty
-    kitty + complete setup zsh | source /dev/stdin
-
-The important thing above is to make sure the call to |kitty| to load the zsh
-completions happens after the call to :file:`compinit`.
-
-
-fish
-~~~~~~~~
-
-For versions of fish earlier than 3.0.0, add the following to your
-:file:`~/.config/fish/config.fish`. Later versions source completions by default.
-
-.. code-block:: sh
-
-   kitty + complete setup fish | source
-
-
-Changelog
-------------------
-
-See :doc:`changelog`.
+*The fast, feature-rich, GPU based terminal emulator*
 
 .. toctree::
     :hidden:
-    :glob:
 
-    *
-    kittens/*
-    generated/rc
+    quickstart
+    overview
+    faq
+    support
+    performance
+    changelog
+    integrations
+    protocol-extensions
+    press-mentions
+
+
+.. tab:: Fast
+
+   * Offloads rendering to the GPU for :doc:`lower system load <performance>`
+   * Uses threaded rendering for :iss:`absolutely minimal latency <2701#issuecomment-636497270>`
+   * Performance tradeoffs can be :ref:`tuned <conf-kitty-performance>`
+
+.. tab:: Capable
+
+   * Graphics, with :doc:`images and animations <graphics-protocol>`
+   * Ligatures and emoji, with :opt:`per glyph font substitution <symbol_map>`
+   * :term:`Hyperlinks<hyperlinks>`, with :doc:`configurable actions <open_actions>`
+
+.. tab:: Scriptable
+
+   * Control from :doc:`scripts or the shell <remote-control>`
+   * Extend with :ref:`kittens <kittens>` using the Python language
+   * Use :ref:`startup sessions <sessions>` to specify working environments
+
+.. tab:: Composable
+
+   * Programmable tabs, :ref:`splits <splits_layout>` and multiple :doc:`layouts <layouts>` to manage windows
+   * Browse the :ref:`entire history <scrollback>` or the :sc:`output from the last command <show_last_command_output>`
+     comfortably in pagers and editors
+   * Edit or download :doc:`remote files <kittens/remote_file>` in an existing SSH session
+
+.. tab:: Cross-platform
+
+   * Linux
+   * macOS
+   * Various BSDs
+
+.. tab:: Innovative
+
+   Pioneered various extensions to move the entire terminal ecosystem forward
+
+   * :doc:`graphics-protocol`
+   * :doc:`keyboard-protocol`
+   * Lots more in :doc:`protocol-extensions`
+
+
+.. only:: dirhtml
+
+    .. raw:: html
+
+        <video controls width="640" height="360" poster="_static/poster.png">
+            <source src="https://download.calibre-ebook.com/videos/kitty.mp4" type="video/mp4">
+            <source src="https://download.calibre-ebook.com/videos/kitty.webm" type="video/webm">
+        </video>
+
+    .. rst-class:: caption caption-text
+
+        Watch kitty in action!
+
+
+To get started see :doc:`quickstart`.

docs/installer.py

@@ -1,249 +0,0 @@
-#!/usr/bin/env python3
-# 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()
-if is_macos:
-    mac_ver = tuple(map(int, platform.mac_ver()[0].split('.')))
-    if mac_ver[:2] < (10, 12):
-        raise SystemExit('Your version of macOS is too old, at least 10.12 is required')
-
-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'})
-    try:
-        res = urllib.urlopen(req).read().decode('utf-8')
-    except Exception as err:
-        raise SystemExit('Failed to contact {} with error: {}'.format(req.get_full_url(), err))
-    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
-    with open(__file__, 'rb') as f:
-        src = f.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

@@ -1,30 +1,173 @@
 #!/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
+{ \unalias command; \unset -f command; } >/dev/null 2>&1
+tdir=''
+cleanup() {
+    [ -n "$tdir" ] && {
+        command rm -rf "$tdir"
+        tdir=''
+    }
+}
 
-echo Using python executable: $python
+die() {
+    cleanup
+    printf "\033[31m%s\033[m\n\r" "$*" > /dev/stderr;
+    exit 1;
+}
 
-$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
+detect_network_tool() {
+    if command -v curl 2> /dev/null > /dev/null; then
+        fetch() {
+            command curl -fL "$1"
+        }
+        fetch_quiet() {
+            command curl -fsSL "$1"
+        }
+    elif command -v wget 2> /dev/null > /dev/null; then
+        fetch() {
+            command wget -O- "$1"
+        }
+        fetch_quiet() {
+            command wget --quiet -O- "$1"
+        }
+    else
+        die "Neither curl nor wget available, cannot download kitty"
+    fi
+}
+
+
+detect_os() {
+    arch=""
+    case "$(command uname)" in
+        'Darwin') OS="macos";;
+        'Linux')
+            OS="linux"
+            case "$(command uname -m)" in
+                x86_64) arch="x86_64";;
+                aarch64*) arch="arm64";;
+                armv8*) arch="arm64";;
+                i386) arch="i686";;
+                i686) arch="i686";;
+                *) die "Unknown CPU architecture $(command uname -m)";;
+            esac
+            ;;
+        *) die "kitty binaries are not available for $(command uname)"
+    esac
+}
+
+expand_tilde() {
+    tilde_less="${1#\~/}"
+    [ "$1" != "$tilde_less" ] && tilde_less="$HOME/$tilde_less"
+    printf '%s' "$tilde_less"
+}
+
+parse_args() {
+    dest='~/.local'
+    [ "$OS" = "macos" ] && dest="/Applications"
+    launch='y'
+    installer=''
+    while :; do
+        case "$1" in
+            dest=*) dest="${1#*=}";;
+            launch=*) launch="${1#*=}";;
+            installer=*) installer="${1#*=}";;
+            "") break;;
+            *) die "Unrecognized command line option: $1";;
+        esac
+        shift
+    done
+    dest=$(expand_tilde "${dest}")
+    [ "$launch" != "y" -a "$launch" != "n" ] && die "Unrecognized command line option: launch=$launch"
+    dest="$dest/kitty.app"
+}
+
+
+get_file_url() {
+    url="https://github.com/kovidgoyal/kitty/releases/download/$1/kitty-$2"
+    if [ "$OS" = "macos" ]; then
+        url="$url.dmg"
+    else
+        url="$url-$arch.txz"
+    fi
+}
+
+get_release_url() {
+    release_version=$(fetch_quiet "https://sw.kovidgoyal.net/kitty/current-version.txt")
+    [ $? -ne 0 -o -z "$release_version" ] && die "Could not get kitty latest release version"
+    get_file_url "v$release_version" "$release_version"
+}
+
+
+get_nightly_url() {
+    get_file_url "nightly" "nightly"
+}
+
+get_download_url() {
+    installer_is_file="n"
+    case "$installer" in
+        "nightly") get_nightly_url ;;
+        "") get_release_url ;;
+        *) installer_is_file="y" ;;
+    esac
+}
+
+linux_install() {
+    if [ "$installer_is_file" = "y" ]; then
+        command tar -C "$dest" "-xJof" "$installer"
+    else
+        printf '%s\n\n' "Downloading from: $url"
+        fetch "$url" | command tar -C "$dest" "-xJof" "-"
+    fi
+}
+
+macos_install() {
+    tdir=$(command mktemp -d "/tmp/kitty-install-XXXXXXXXXXXX")
+    [ "$installer_is_file" != "y" ] && {
+        installer="$tdir/kitty.dmg"
+        printf '%s\n\n' "Downloading from: $url"
+        fetch "$url" > "$installer" || die "Failed to download: $url"
+    }
+    command mkdir "$tdir/mp"
+    command hdiutil attach "$installer" "-mountpoint" "$tdir/mp" || die "Failed to mount kitty.dmg"
+    command ditto -v "$tdir/mp/kitty.app" "$dest"
+    rc="$?"
+    command hdiutil detach "$tdir/mp"
+    command rm -rf "$tdir"
+    tdir=''
+    [ "$rc" != "0" ] && die "Failed to copy kitty.app from mounted dmg"
+}
+
+prepare_install_dest() {
+    printf "%s\n" "Installing to $dest"
+    command rm -rf "$dest"
+    command mkdir -p "$dest" || die "Failed to create the directory: $dest"
+}
+
+exec_kitty() {
+    if [ "$OS" = "macos" ]; then
+        exec "open" "$dest"
+    else
+        exec "$dest/bin/kitty" "--detach"
+    fi
+    die "Failed to launch kitty"
+}
+
+main() {
+    detect_os
+    parse_args "$@"
+    detect_network_tool
+    get_download_url
+    prepare_install_dest
+    if [ "$OS" = "macos" ]; then
+        macos_install
+    else
+        linux_install
+    fi
+    [ "$launch" = "y" ] && exec_kitty
+    exit 0
+}
+
+main "$@"

docs/integrations.rst

@@ -1,9 +1,11 @@
+:tocdepth: 2
+
 Integrations with other tools
 ================================
 
 kitty provides extremely powerful interfaces such as :doc:`remote-control` and
-:doc:`kittens/custom` and :doc:`kittens/icat`
-that allow it to be integrated with other tools seamlessly.
+:doc:`kittens/custom` and :doc:`kittens/icat` that allow it to be integrated
+with other tools seamlessly.
 
 
 Image and document viewers
@@ -12,149 +14,251 @@ Image and document viewers
 Powered by kitty's :doc:`graphics-protocol` there exist many tools for viewing
 images and other types of documents directly in your terminal, even over SSH.
 
+.. _tool_termpdf:
+
 `termpdf.py <https://github.com/dsanson/termpdf.py>`_
-    a terminal PDF/DJVU/CBR viewer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A terminal PDF/DJVU/CBR viewer
+
+.. _tool_mdcat:
 
 `mdcat <https://github.com/lunaryorn/mdcat>`_
-    Display markdown files nicely formatted with images in the terminal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Display markdown files nicely formatted with images in the terminal
+
+.. _tool_ranger:
 
 `ranger <https://github.com/ranger/ranger>`_
-    a terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A terminal file manager, with previews of file contents powered by kitty's
+graphics protocol.
+
+.. _tool_nnn:
 
 `nnn <https://github.com/jarun/nnn/>`_
-    another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Another terminal file manager, with previews of file contents powered by kitty's
+graphics protocol.
+
+.. _tool_hunter:
 
 `hunter <https://github.com/rabite0/hunter>`_
-    another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Another terminal file manager, with previews of file contents powered by kitty's
+graphics protocol.
+
+.. _tool_koneko:
 
 `koneko <https://github.com/twenty5151/koneko>`_
-    browse images from the pixiv artist community directly in kitty.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Browse images from the pixiv artist community directly in kitty.
+
+.. _tool_viu:
 
 `viu <https://github.com/atanunq/viu>`_
-    view images in the terminal, similar to kitty's icat.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+View images in the terminal, similar to kitty's icat.
+
+.. _tool_nb:
+
 
 `nb <https://github.com/xwmx/nb>`_
-    command line and local web note-taking, bookmarking, archiving, and
-    knowledge base application that uses kitty's graphics protocol for images.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Command line and local web note-taking, bookmarking, archiving, and knowledge
+base application that uses kitty's graphics protocol for images.
+
+.. _tool_w3m:
 
 `w3m <https://github.com/tats/w3m>`_
-    A text mode WWW browser that supports kitty's graphics protocol to display
-    images.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A text mode WWW browser that supports kitty's graphics protocol to display
+images.
+
+.. _tool_timg:
 
 `timg <https://github.com/hzeller/timg>`_
-    A terminal image and video viewer, that displays static and animated
-    images or plays videos. Fast multi-threaded loading, JPEG exif rotation,
-    grid view and connecting to the webcam make it a versatile terminal utility.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A terminal image and video viewer, that displays static and animated images or
+plays videos. Fast multi-threaded loading, JPEG exif rotation, grid view and
+connecting to the webcam make it a versatile terminal utility.
 
 
 System and data visualisation tools
 ---------------------------------------
 
+.. _tool_neofetch:
+
 `neofetch <https://github.com/dylanaraps/neofetch>`_
-    A command line system information tool that shows images using kitty's graphics protocol
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A command line system information tool that shows images using kitty's graphics
+protocol
+
+.. _tool_matplotlib:
 
 `matplotlib <https://github.com/jktr/matplotlib-backend-kitty>`_
-    show matplotlib plots directly in kitty
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Show matplotlib plots directly in kitty
+
+.. _tool_KittyTerminalImage:
 
 `KittyTerminalImages.jl <https://github.com/simonschoelly/KittyTerminalImages.jl>`_
-    show images from Julia directly in kitty
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Show images from Julia directly in kitty
+
+.. _tool_euporie:
 
 `euporie <https://github.com/joouha/euporie>`_
-    a text-based user interface for running and editing Jupyter notebooks,
-    powered by kitty's graphics protocol for displaying plots
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A text-based user interface for running and editing Jupyter notebooks, powered
+by kitty's graphics protocol for displaying plots
+
+.. _tool_gnuplot:
 
 `gnuplot <http://www.gnuplot.info/>`_
-    a graphing and data visualization tool that can be made to display its
-    output in kitty with the following bash snippet::
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        function iplot {
-            cat <<EOF | gnuplot
-            set terminal pngcairo enhanced font 'Fira Sans,10'
-            set autoscale
-            set samples 1000
-            set output '|kitty +kitten icat --stdin yes'
-            set object 1 rectangle from screen 0,0 to screen 1,1 fillcolor rgb"#fdf6e3" behind
-            plot $@
-            set output '/dev/null'
-            EOF
-        }
+A graphing and data visualization tool that can be made to display its output in
+kitty with the following bash snippet:
 
-   Add this to bashrc and then to plot a function, simply do::
+.. code-block:: sh
 
-        iplot 'sin(x*3)*exp(x*.2)'
+    function iplot {
+        cat <<EOF | gnuplot
+        set terminal pngcairo enhanced font 'Fira Sans,10'
+        set autoscale
+        set samples 1000
+        set output '|kitty +kitten icat --stdin yes'
+        set object 1 rectangle from screen 0,0 to screen 1,1 fillcolor rgb"#fdf6e3" behind
+        plot $@
+        set output '/dev/null'
+        EOF
+    }
+
+Add this to bashrc and then to plot a function, simply do:
+
+.. code-block:: sh
+
+    iplot 'sin(x*3)*exp(x*.2)'
+
+.. tool_onefetch:
 
 `onefetch <https://github.com/o2sh/onefetch>`_
-    a tool to fetch information about your git repositories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A tool to fetch information about your git repositories
+
+.. tool_patat:
 
 `patat <https://github.com/jaspervdj/patat>`_
-    terminal based presentations using pandoc and kitty's image protocol for
-    images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Terminal based presentations using pandoc and kitty's image protocol for
+images
+
+.. tool_wttr:
 
 `wttr.in <https://github.com/chubin/wttr.in>`_
-    a tool to display weather information in your terminal with curl
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A tool to display weather information in your terminal with curl
+
+.. tool_wl_clipboard:
 
 `wl-clipboard-manager <https://github.com/maximbaz/wl-clipboard-manager>`_
-    view and manage the system clipboard under Wayland in your kitty terminal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+View and manage the system clipboard under Wayland in your kitty terminal
+
+.. tool_dmenu_term:
 
 `dmenu-term <https://github.com/maximbaz/dmenu-term>`_
-    run applications on your system with fuzzy find inside a kitty window
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Run applications on your system with fuzzy find inside a kitty window
 
 
 Editor integration
 -----------------------
 
-kitty can be integrated into many different terminal editors to add features
-such a split windows, previews, REPLs etc.
+|kitty| can be integrated into many different terminal based text editors to add
+features such a split windows, previews, REPLs etc.
 
+.. tool_kakoune:
 
 `kakoune <https://kakoune.org/>`_
-    integrates with kitty to use native kitty windows for its windows/panels and REPLs.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Integrates with kitty to use native kitty windows for its windows/panels and
+REPLs.
+
+.. tool_vim_slime:
 
 `vim-slime <https://github.com/jpalardy/vim-slime#kitty>`_
-    uses kitty remote control for a Lisp REPL.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Uses kitty remote control for a Lisp REPL.
+
+.. tool_vim_kitty_navigator:
 
 `vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
-    allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Allows you to navigate seamlessly between vim and kitty splits using a
+consistent set of hotkeys.
+
+.. tool_vim_test:
 
 `vim-test <https://github.com/vim-test/vim-test>`_
-    allows easily running tests in a terminal window
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Allows easily running tests in a terminal window
+
+.. tool_hologram:
 
 `hologram.nvim <https://github.com/edluffy/hologram.nvim>`_
-    terminal image viewer for nvim
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Terminal image viewer for Neovim
 
 
 Scrollback manipulation
 -------------------------
 
+.. tool_kitty_search:
+
 `kitty-search <https://github.com/trygveaa/kitty-kitten-search>`_
-    Live incremental search of the scrollback buffer.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Live incremental search of the scrollback buffer.
+
+.. tool_kitty_grab:
 
 `kitty-grab <https://github.com/yurikhan/kitty_grab>`_
-    keyboard based text selection for the kitty scrollback buffer.
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Keyboard based text selection for the kitty scrollback buffer.
 
 
 Miscellaneous
 ------------------
 
+.. tool_kitty_smart_tab:
+
 `kitty-smart-tab <https://github.com/yurikhan/kitty-smart-tab>`_
-    use keys to either control tabs or pass them onto running applications if
-    no tabs are present
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Use keys to either control tabs or pass them onto running applications if no
+tabs are present
+
+.. tool_kitty_smart_scroll:
 
 `kitty-smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
-    use keys to either scroll or pass them onto running applications if
-    no scrollback buffer is present
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Use keys to either scroll or pass them onto running applications if no
+scrollback buffer is present
 
-`reload keybindings <https://github.com/kovidgoyal/kitty/issues/1292#issuecomment-582388769>`_
-    reload key bindings from :file:`kitty.conf` without needing to restart
-    kitty
+.. tool_kitti3:
 
 `kitti3 <https://github.com/LandingEllipse/kitti3>`_
-    allow using kitty as a drop-down terminal under the i3 window manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Allow using kitty as a drop-down terminal under the i3 window manager
+
+.. tool_weechat_hints:
 
 `weechat-hints <https://github.com/GermainZ/kitty-weechat-hints>`_
-    URL hints kitten for WeeChat that works without having to use WeeChat's
-    raw-mode.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+URL hints kitten for WeeChat that works without having to use WeeChat's
+raw-mode.
+
+.. tool_glkitty:
 
 `glkitty <https://github.com/michaeljclark/glkitty>`_
-    C library to draw OpenGL shaders in the terminal with a glgears demo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+C library to draw OpenGL shaders in the terminal with a glgears demo

docs/invocation.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 The kitty command line interface
 ====================================
 

docs/keyboard-protocol.rst

@@ -1,5 +1,5 @@
-A protocol for comprehensive keyboard handling in terminals
-=================================================================
+Comprehensive keyboard handling in terminals
+==============================================
 
 There are various problems with the current state of keyboard handling in
 terminals. They include:
@@ -32,6 +32,15 @@ You can see this protocol with all enhancements in action by running::
 
 inside the kitty terminal to report key events.
 
+In addition to kitty, this protocol is also implemented in:
+
+* The `foot terminal <https://codeberg.org/dnkl/foot/issues/319>`__
+* The `notcurses library
+  <https://github.com/dankamongmen/notcurses/issues/2131>`__
+* The `neovim text editor <https://github.com/neovim/neovim/pull/18181>`__
+* The `kakoune text editor <https://github.com/mawww/kakoune/issues/4103>`__
+* The `dte text editor <https://gitlab.com/craigbarnes/dte/-/issues/138>`__
+
 .. versionadded:: 0.20.0
 
 Quickstart
@@ -41,12 +50,14 @@ If you are an application or library developer just interested in using this
 protocol to make keyboard handling simpler and more robust in your application,
 without too many changes, do the following:
 
-#. Emit the escape code ``CSI > 1 u`` at application startup or when entering
-   alternate screen mode
+#. Emit the escape code ``CSI > 1 u`` at application startup if using the main
+   screen or when entering alternate screen mode, if using the alternate
+   screen.
 #. All key events will now be sent in only a few forms to your application,
    that are easy to parse unambiguously.
-#. Emit the escape sequence ``CSI < u`` at application exit or just before
-   leaving alternate screen mode to restore the previously used keyboard mode.
+#. Emit the escape sequence ``CSI < u`` at application exit if using the main
+   screen or just before leaving alternate screen mode if using the alternate screen,
+   to restore the previously used keyboard mode.
 
 Key events will all be delivered to your application either as plain UTF-8
 text, or using the following escape codes, for those keys that do not produce
@@ -64,10 +75,11 @@ key, such as ``97`` for the :kbd:`a` key, or one of the numbers from the
 modifiers pressed for the key event. The encoding is described in the
 :ref:`modifiers` section.
 
-The second form is used for a few functional keys, such as the :kbd:`Home, End,
-Arrow keys and F1-F4`, they are enumerated in the :ref:`functional` table below.
-Note that if no modifiers are present the parameters are omitted entirely
-giving an escape code of the form ``CSI [ABCDEFHPQRS]``.
+The second form is used for a few functional keys, such as the :kbd:`Home`,
+:kbd:`End`, :kbd:`Arrow` keys and :kbd:`F1` ... :kbd:`F4`, they are enumerated in
+the :ref:`functional` table below.  Note that if no modifiers are present the
+parameters are omitted entirely giving an escape code of the form ``CSI
+[ABCDEFHPQRS]``.
 
 If you want support for more advanced features such as repeat and release
 events, alternate keys for shortcut matching et cetera, these can be turned on
@@ -140,11 +152,13 @@ sub-field for the shifted key, like this::
 Modifiers
 ~~~~~~~~~~~~~~
 
-This protocol supports six modifier keys, :kbd:`shift, alt, ctrl, super, hyper
-and meta` as well as :kbd:`num_lock and caps_lock`. Here :kbd:`super` is either
-the *Windows/Linux* key or the *Cmd* key on mac keyboards. :kbd:`hyper` and
-:kbd:`meta` are typically present only on X11 based systems with special XKB
-rules. Modifiers are encoded as a bit field with::
+This protocol supports six modifier keys, :kbd:`shift`, :kbd:`alt`,
+:kbd:`ctrl`, :kbd:`super`, :kbd:`hyper`, :kbd:`meta`, :kbd:`num_lock` and
+:kbd:`caps_lock`. Here :kbd:`super` is either the *Windows/Linux* key or the
+:kbd:`command` key on mac keyboards. The :kbd:`alt` key is the :kbd:`option`
+key on mac keyboards. :kbd:`hyper` and :kbd:`meta` are typically present only
+on X11/Wayland based systems with special XKB rules. Modifiers are encoded as a
+bit field with::
 
     shift     0b1         (1)
     alt       0b10        (2)
@@ -207,9 +221,9 @@ Non-Unicode keys
 
 There are many keys that don't correspond to letters from human languages, and
 thus aren't represented in Unicode. Think of functional keys, such as
-:kbd:`Escape, Play, Pause, F1, Home, etc`. These are encoded using Unicode code
-points from the Private Use Area (``57344 - 63743``). The mapping of key
-names to code points for these keys is in the
+:kbd:`Escape`, :kbd:`Play`, :kbd:`Pause`, :kbd:`F1`, :kbd:`Home`, etc. These
+are encoded using Unicode code points from the Private Use Area (``57344 -
+63743``). The mapping of key names to code points for these keys is in the
 :ref:`Functional key definition table below <functional>`.
 
 
@@ -266,10 +280,14 @@ and alternate screens. If a pop request is received that empties the stack,
 all flags are reset. If a push request is received and the stack is full, the
 oldest entry from the stack must be evicted.
 
-.. note:: In the interests of interoperation, the XTerm specific sequences
-   `CSI > 4; 1 m` and `CSI > 4; 0 m` are treated as `CSI > 1 u` and `CSI < 1 u`.
-   These codes cause XTerm to use the CSI u encoding for more keys and are therefore
-   treated as similar to the disambiguate progressive enhancement.
+.. note:: The main and alternate screens in the terminal emulator must maintain
+   their own, independent, keyboard mode stacks. This is so that a program that
+   uses the alternate screen such as an editor, can change the keyboard mode
+   in the alternate screen only, without affecting the mode in the main screen
+   or even knowing what that mode is. Without this, and if no stack is
+   implemented for keyboard modes (such as in some legacy terminal emulators)
+   the editor would have to somehow know what the keyboard mode of the main
+   screen is and restore to that mode on exit.
 
 .. _disambiguate:
 
@@ -282,8 +300,8 @@ encodings overlapping with other control codes. For instance, pressing the
 start of an escape code. Similarly pressing the key :kbd:`alt+[` will generate
 the bytes used for CSI control codes.
 
-Turning on this flag will cause the terminal to report the :kbd:`Esc, alt+key,
-ctrl+key, ctrl+alt+key, shift+alt+key` keys using ``CSI u`` sequences instead
+Turning on this flag will cause the terminal to report the :kbd:`Esc`, :kbd:`alt+key`,
+:kbd:`ctrl+key`, :kbd:`ctrl+alt+key`, :kbd:`shift+alt+key` keys using ``CSI u`` sequences instead
 of legacy ones. Here key is any ASCII key as described in :ref:`legacy_text`.
 Additionally, all keypad keys will be reported as separate keys with ``CSI u``
 encoding, using dedicated numbers from the :ref:`table below <functional>`.
@@ -298,7 +316,7 @@ This makes it very easy to parse key events in an application. In particular,
 :kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
 delivered as a ``CSI u`` escape code. This has the nice side effect of making it
 much easier to integrate into the application event loop. The only exceptions
-are the :kbd:`Enter, Tab and Backspace` keys which still generate the same
+are the :kbd:`Enter`, :kbd:`Tab` and :kbd:`Backspace` keys which still generate the same
 bytes as in legacy mode this is to allow the user to type and execute commands
 in the shell such as ``reset`` after a program that sets this mode crashes
 without clearing it.
@@ -338,8 +356,8 @@ only key events are sent. If the text is needed as well, combine with the
 Report associated text enhancement below.
 
 Additionally, with this mode, events for pressing modifier keys are reported.
-Note that *all* keys are reported as escape codes, including :kbd:`Enter, Tab,
-Backspace` etc.
+Note that *all* keys are reported as escape codes, including :kbd:`Enter`,
+:kbd:`Tab`, :kbd:`Backspace` etc.
 
 .. _report_text:
 
@@ -360,7 +378,7 @@ An application can query the terminal for support of this protocol by sending
 the escape code querying for the :ref:`current progressive enhancement
 <progressive_enhancement>` status
 followed by request for the `primary device attributes
-<https://vt100.net/docs/vt510-rm/DA1.html>`. If an answer for the device
+<https://vt100.net/docs/vt510-rm/DA1.html>`__. If an answer for the device
 attributes is received without getting back an answer for the progressive
 enhancement the terminal does not support this protocol.
 
@@ -425,6 +443,7 @@ mode* (the ``smkx/rmkx`` terminfo capabilities). This form is used only in
     "F10",       "kf10",       "CSI 21 ~"
     "F11",       "kf11",       "CSI 23 ~"
     "F12",       "kf12",       "CSI 24 ~"
+    "MENU",      "kf16",       "CSI 29 ~"
 
 There are a few more functional keys that have special cased legacy encodings.
 These are present because they are commonly used and for the sake of legacy
@@ -451,10 +470,11 @@ distinguish these, use the :ref:`disambiguate <disambiguate>` flag.
 Legacy text keys
 ~~~~~~~~~~~~~~~~~~~
 
-For legacy compatibility, the keys
-:kbd:`a-z 0-9 \` - = [ ] \ ; ' , . /` with the modifiers
-:kbd:`shift, alt, ctrl, shift+alt, ctrl+alt` are output using the
-following algorithm:
+For legacy compatibility, the keys :kbd:`a`-:kbd:`z` :kbd:`0`-:kbd:`9`
+:kbd:`\`` :kbd:`-` :kbd:`=` :kbd:`[` :kbd:`]` :kbd:`\\` :kbd:`;` :kbd:`'`
+:kbd:`,` :kbd:`.` :kbd:`/` with the modifiers :kbd:`shift`, :kbd:`alt`,
+:kbd:`ctrl`, :kbd:`shift+alt`, :kbd:`ctrl+alt` are output using the following
+algorithm:
 
 #. If the :kbd:`alt` key is pressed output the byte for ``ESC (0x1b)``
 #. If the :kbd:`ctrl` modifier is pressed map the key using the table
@@ -626,8 +646,8 @@ specification.
 * Incorrectly encoding shifted keys when shift modifier is used, for instance,
   for :kbd:`ctrl+shift+i` is encoded as :kbd:`ctrl+I`.
 
-* No way to have non-conflicting escape codes for :kbd:`alt+letter,
-  ctrl+letter, ctrl+alt+letter` key presses
+* No way to have non-conflicting escape codes for :kbd:`alt+letter`,
+  :kbd:`ctrl+letter`, :kbd:`ctrl+alt+letter` key presses
 
 * No way to specify both shifted and unshifted keys for robust shortcut
   matching (think matching :kbd:`ctrl+shift+equal` and :kbd:`ctrl+plus`)

docs/kittens/broadcast.rst

@@ -1,23 +1,25 @@
-broadcast - type text in all kitty windows
+broadcast
 ==================================================
 
-The ``broadcast`` kitten can be used to type text simultaneously in
-all kitty windows (or a subset as desired).
+*Type text in all kitty windows simultaneously*
+
+The ``broadcast`` kitten can be used to type text simultaneously in all
+:term:`kitty windows <window>` (or a subset as desired).
 
 To use it, simply create a mapping in :file:`kitty.conf` such as::
 
-    map F1 launch --allow-remote-control kitty +kitten broadcast
+    map f1 launch --allow-remote-control kitty +kitten broadcast
 
-Then press the :kbd:`F1` key and whatever you type in the newly created widow
+Then press the :kbd:`F1` key and whatever you type in the newly created window
 will be sent to all kitty windows.
 
-You can use the options described below to control which windows
-are selected.
+You can use the options described below to control which windows are selected.
+
+For example, only broadcast to other windows in the current tab::
+
+    map f1 launch --allow-remote-control kitty +kitten broadcast --match-tab state:focused
 
 .. program:: kitty +kitten broadcast
 
 
-Command Line Interface
---------------------------
-
 .. include:: /generated/cli-kitten-broadcast.rst

docs/kittens/clipboard.rst

@@ -1,6 +1,8 @@
-clipboard - copy/paste to the system clipboard
+clipboard
 ==================================================
 
+*Copy/paste to the system clipboard from shell scripts*
+
 .. highlight:: sh
 
 
@@ -21,7 +23,4 @@ use::
 .. program:: kitty +kitten clipboard
 
 
-Command Line Interface
---------------------------
-
 .. include:: /generated/cli-kitten-clipboard.rst

docs/kittens/custom.rst

@@ -1,21 +1,20 @@
 Custom kittens
 =================
 
-You can easily create your own kittens to extend kitty. They are just
-terminal programs written in Python. When launching a kitten, kitty will
-open an overlay window over the current window and optionally pass the
-contents of the current window/scrollback to the kitten over its :file:`STDIN`.
-The kitten can then perform whatever actions it likes, just as a normal
-terminal program. After execution of the kitten is complete, it has access
-to the running kitty instance so it can perform arbitrary actions
-such as closing windows, pasting text, etc.
+You can easily create your own kittens to extend kitty. They are just terminal
+programs written in Python. When launching a kitten, kitty will open an overlay
+window over the current window and optionally pass the contents of the current
+window/scrollback to the kitten over its :file:`STDIN`. The kitten can then
+perform whatever actions it likes, just as a normal terminal program. After
+execution of the kitten is complete, it has access to the running kitty instance
+so it can perform arbitrary actions such as closing windows, pasting text, etc.
 
 Let's see a simple example of creating a kitten. It will ask the user for some
 input and paste it into the terminal window.
 
-Create a file in the kitty config folder, :file:`~/.config/kitty/mykitten.py`
-(you might need to adjust the path to wherever the kitty config folder is on
-your machine).
+Create a file in the kitty config directory, :file:`~/.config/kitty/mykitten.py`
+(you might need to adjust the path to wherever the :ref:`kitty config directory
+<confloc>` is on your machine).
 
 
 .. code-block:: python
@@ -35,7 +34,7 @@ your machine).
         # get the kitty window into which to paste answer
         w = boss.window_id_map.get(target_window_id)
         if w is not None:
-            w.paste(answer)
+            w.paste_text(answer)
 
 
 Now in :file:`kitty.conf` add the lines::
@@ -43,11 +42,12 @@ Now in :file:`kitty.conf` add the lines::
     map ctrl+k kitten mykitten.py
 
 
-Start kitty and press :kbd:`ctrl+k` and you should see the kitten running.
-The best way to develop your own kittens is to modify one of the built in
-kittens. Look in the kittens sub-directory of the kitty source code for those.
-Or see below for a list of :ref:`third-party kittens <external_kittens>`,
-that other kitty users have created.
+Start kitty and press :kbd:`Ctrl+K` and you should see the kitten running.
+The best way to develop your own kittens is to modify one of the built-in
+kittens. Look in the `kittens sub-directory
+<https://github.com/kovidgoyal/kitty/tree/master/kittens>`__ of the kitty source
+code for those. Or see below for a list of :ref:`third-party kittens
+<external_kittens>`, that other kitty users have created.
 
 
 Passing arguments to kittens
@@ -60,61 +60,100 @@ You can pass arguments to kittens by defining them in the map directive in
 
 These will be available as the ``args`` parameter in the ``main()`` and
 ``handle_result()`` functions. Note also that the current working directory
-of the kitten is set to the working directory of whatever program is
-running in the active kitty window. The special argument ``@selection``
-is replaced by the currently selected text in the active kitty window.
+of the kitten is set to the working directory of whatever program is running in
+the active kitty window. The special argument ``@selection`` is replaced by the
+currently selected text in the active kitty window.
 
 
 Passing the contents of the screen to the kitten
 ---------------------------------------------------
 
 If you would like your kitten to have access to the contents of the screen
-and/or the scrollback buffer, you just need to add an annotation to the ``handle_result()``
-function, telling kitty what kind of input your kitten would like. For example:
+and/or the scrollback buffer, you just need to add an annotation to the
+``handle_result()`` function, telling kitty what kind of input your kitten would
+like. For example:
 
 .. code-block:: py
 
+    from typing import List
+    from kitty.boss import Boss
+
     # in main, STDIN is for the kitten process and will contain
     # the contents of the screen
-    def main(args):
+    def main(args: List[str]) -> str:
         return sys.stdin.read()
 
     # in handle_result, STDIN is for the kitty process itself, rather
     # than the kitten process and should not be read from.
     from kittens.tui.handler import result_handler
     @result_handler(type_of_input='text')
-    def handle_result(args, stdin_data, target_window_id, boss):
+    def handle_result(args: List[str], stdin_data: str, target_window_id: int, boss: Boss) -> None:
         pass
 
 
 This will send the plain text of the active window to the kitten's
-:file:`STDIN`. For text with formatting escape codes, use ``ansi``
-instead. If you want line wrap markers as well, use ``screen-ansi``
-or just ``screen``. For the scrollback buffer as well, use
-``history``, ``ansi-history`` or ``screen-history``. To get
-the currently selected text, use ``selection``.
+:file:`STDIN`. There are many other types of input you can ask for, described in
+the table below:
+
+.. table:: Types of input to kittens
+    :align: left
+
+    =========================== =======================================================================================================
+    Keyword                     Type of :file:`STDIN` input
+    =========================== =======================================================================================================
+    ``text``                    Plain text of active window
+    ``ansi``                    Formatted text of active window
+    ``screen``                  Plain text of active window with line wrap markers
+    ``screen-ansi``             Formatted text of active window with line wrap markers
+
+    ``history``                 Plain text of active window and its scrollback
+    ``ansi-history``            Formatted text of active window and its scrollback
+    ``screen-history``          Plain text of active window and its scrollback with line wrap markers
+    ``screen-ansi-history``     Formatted text of active window and its scrollback with line wrap markers
+
+    ``output``                  Plain text of the output from the last run command
+    ``output-screen``           Plain text of the output from the last run command with wrap markers
+    ``output-ansi``             Formatted text of the output from the last run command
+    ``output-screen-ansi``      Formatted text of the output from the last run command with wrap markers
+
+    ``selection``               The text currently selected with the mouse
+    =========================== =======================================================================================================
+
+In addition to ``output``, that gets the output of the last run command,
+``last_visited_output`` gives the output of the command last jumped to
+and ``first_output`` gives the output of the first command currently on screen.
+These can also be combined with ``screen`` and ``ansi`` for formatting.
+
+.. note::
+   For the types based on the output of a command, :ref:`shell_integration` is
+   required.
 
 
 Using kittens to script kitty, without any terminal UI
 -----------------------------------------------------------
 
 If you would like your kitten to script kitty, without bothering to write a
-terminal program, you can tell the kittens system to run the
-``handle_result()`` function without first running the ``main()`` function.
+terminal program, you can tell the kittens system to run the ``handle_result()``
+function without first running the ``main()`` function.
 
-For example, here is a kitten that "zooms/unzooms" the current terminal window
-by switching to the stack layout or back to the previous layout.
+For example, here is a kitten that "zooms in/zooms out" the current terminal
+window by switching to the stack layout or back to the previous layout. This is
+equivalent to the builtin :ac:`toggle_layout` action.
 
-Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
+Create a Python file in the :ref:`kitty config directory <confloc>`,
+:file:`~/.config/kitty/zoom_toggle.py`
 
 .. code-block:: py
 
-    def main(args):
+    from typing import List
+    from kitty.boss import Boss
+
+    def main(args: List[str]) -> str:
         pass
 
     from kittens.tui.handler import result_handler
     @result_handler(no_ui=True)
-    def handle_result(args, answer, target_window_id, boss):
+    def handle_result(args: List[str], answer: str, target_window_id: int, boss: Boss) -> None:
         tab = boss.active_tab
         if tab is not None:
             if tab.current_layout.name == 'stack':
@@ -123,7 +162,7 @@ Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
                 tab.goto_layout('stack')
 
 
-Now in kitty.conf add::
+Now in :file:`kitty.conf` add::
 
     map f11 kitten zoom_toggle.py
 
@@ -134,7 +173,7 @@ layout, by simply adding the line::
     boss.toggle_fullscreen()
 
 
-To the ``handle_result()`` function, above.
+to the ``handle_result()`` function, above.
 
 
 .. _send_mouse_event:
@@ -142,7 +181,7 @@ To the ``handle_result()`` function, above.
 Sending mouse events
 --------------------
 
-If the program running in a window is receiving mouse events you can simulate
+If the program running in a window is receiving mouse events, you can simulate
 those using::
 
     from kitty.fast_data_types import send_mouse_event
@@ -169,15 +208,15 @@ that type, and will return ``True`` if it sent the event, and ``False`` if not.
 Debugging kittens
 --------------------
 
-The part of the kitten that runs in ``main()`` is just a normal program and
-the output of print statements will be visible in the kitten window. Or
-alternately, you can use::
+The part of the kitten that runs in ``main()`` is just a normal program and the
+output of print statements will be visible in the kitten window. Or alternately,
+you can use::
 
     from kittens.tui.loop import debug
     debug('whatever')
 
-The ``debug()`` function is just like ``print()`` except that the output
-will appear in the ``STDOUT`` of the kitty process inside which the kitten is
+The ``debug()`` function is just like ``print()`` except that the output will
+appear in the ``STDOUT`` of the kitty process inside which the kitten is
 running.
 
 The ``handle_result()`` part of the kitten runs inside the kitty process.
@@ -185,18 +224,119 @@ The output of print statements will go to the ``STDOUT`` of the kitty process.
 So if you run kitty from another kitty instance, the output will be visible
 in the first kitty instance.
 
+
+Adding options to kittens
+----------------------------
+
+If you would like to use kitty's config framework to make your kittens
+configurable, you will need some boilerplate. Put the following files in the
+directory of your kitten.
+
+:file:`kitten_options_definition.py`
+
+.. code-block:: python
+
+    from kitty.conf.types import Action, Definition
+
+    definition = Definition(
+        '!kitten_options_utils',
+        Action(
+            'map', 'parse_map',
+            {'key_definitions': 'kitty.conf.utils.KittensKeyMap'},
+            ['kitty.types.ParsedShortcut', 'kitty.conf.utils.KeyAction']
+        ),
+    )
+
+    agr = definition.add_group
+    egr = definition.end_group
+    opt = definition.add_option
+    map = definition.add_map
+
+    # main options {{{
+    agr('main', 'Main')
+
+    opt('some_option', '33',
+        option_type='some_option_parser',
+        long_text='''
+    Help text for this option
+    '''
+        )
+    egr()  # }}}
+
+    # shortcuts {{{
+    agr('shortcuts', 'Keyboard shortcuts')
+
+    map('Quit', 'quit q quit')
+    egr()  # }}}
+
+
+:file:`kitten_options_utils.py`
+
+.. code-block:: python
+
+    from kitty.conf.utils import KittensKeyDefinition, key_func, parse_kittens_key
+
+    func_with_args, args_funcs = key_func()
+    FuncArgsType = Tuple[str, Sequence[Any]]
+
+    def some_option_parser(val: str) -> int:
+        return int(val) + 3000
+
+    def parse_map(val: str) -> Iterable[KittensKeyDefinition]:
+        x = parse_kittens_key(val, args_funcs)
+        if x is not None:
+            yield x
+
+Then run::
+
+    kitty +runpy 'from kitty.conf.generate import main; main()' /path/to/kitten_options_definition.py
+
+You can parse and read the options in your kitten using the following code:
+
+.. code-block:: python
+
+    from .kitten_options_types import Options, defaults
+    from kitty.conf.utils import load_config as _load_config, parse_config_base
+    from typing import Optional, Iterable, Dict, Any
+
+    def load_config(*paths: str, overrides: Optional[Iterable[str]] = None) -> Options:
+        from .kitten_options_parse import  (
+            create_result_dict, merge_result_dicts, parse_conf_item
+        )
+
+        def parse_config(lines: Iterable[str]) -> Dict[str, Any]:
+            ans: Dict[str, Any] = create_result_dict()
+            parse_config_base(
+                lines,
+                parse_conf_item,
+                ans,
+            )
+            return ans
+
+        overrides = tuple(overrides) if overrides is not None else ()
+        opts_dict, paths = _load_config(defaults, parse_config, merge_result_dicts, *paths, overrides=overrides)
+        opts = Options(opts_dict)
+        opts.config_paths = paths
+        opts.config_overrides = overrides
+        return opts
+
+See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
+for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
+options and keyboard shortcuts.
+
 .. _external_kittens:
 
 Kittens created by kitty users
 ---------------------------------------------
 
 `vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
-    Allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
+    Allows you to navigate seamlessly between vim and kitty splits using a
+    consistent set of hotkeys.
 
 `smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
     Makes the kitty scroll bindings work in full screen applications
 
-`insert password <https://github.com/kovidgoyal/kitty/issues/1222>`_
+:iss:`insert password <1222>`
     Insert a password from a CLI password manager, taking care to only do it at
     a password prompt.
 

docs/kittens/diff.rst

@@ -1,6 +1,8 @@
-kitty-diff - A fast side-by-side diff tool with syntax highlighting and images
+kitty-diff
 ================================================================================
 
+*A fast side-by-side diff tool with syntax highlighting and images*
+
 .. highlight:: sh
 
 Major Features
@@ -10,8 +12,8 @@ Major Features
 
     * Displays diffs side-by-side in the kitty terminal
 
-    * Does syntax highlighting of the displayed diffs, asynchronously, for maximum
-      speed
+    * Does syntax highlighting of the displayed diffs, asynchronously, for
+      maximum speed
 
     * Displays images as well as text diffs, even over SSH
 
@@ -21,22 +23,19 @@ Major Features
 .. figure:: ../screenshots/diff.png
    :alt: Screenshot, showing a sample diff
    :align: center
-   :scale: 100%
+   :width: 100%
 
    Screenshot, showing a sample diff
 
-.. contents::
-   :local:
-
 
 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).
+Simply :ref:`install kitty <quickstart>`.  You also need to have either the `git
+<https://git-scm.com/>`__ program or the :program:`diff` program installed.
+Additionally, for syntax highlighting to work, `pygments
+<https://pygments.org/>`__ must be installed (note that pygments is included in
+the official kitty binary builds).
 
 
 Usage
@@ -46,9 +45,10 @@ In the kitty terminal, run::
 
     kitty +kitten diff file1 file2
 
-to see the diff between file1 and file2.
+to see the diff between :file:`file1` and :file:`file2`.
 
-Create an alias in your shell's startup file to shorten the command, for example:
+Create an alias in your shell's startup file to shorten the command, for
+example:
 
 .. code-block:: sh
 
@@ -68,33 +68,33 @@ Keyboard controls
 =========================   ===========================
 Action                      Shortcut
 =========================   ===========================
-Quit                        :kbd:`q, Ctrl+c, Esc`
-Scroll line up              :kbd:`k, up`
-Scroll line down            :kbd:`j, down`
+Quit                        :kbd:`Q`, :kbd:`Ctrl+C`, :kbd:`Esc`
+Scroll line up              :kbd:`K`, :kbd:`Up`
+Scroll line down            :kbd:`J`, :kbd:`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 next page         :kbd:`Space`, :kbd:`PgDn`
 Scroll to previous page     :kbd:`PgUp`
-Scroll to next change       :kbd:`n`
-Scroll to previous change   :kbd:`p`
+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`
+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:`<, ,`
+Scroll to next match        :kbd:`>`, :kbd:`.`
+Scroll to previous match    :kbd:`<`, :kbd:`,`
 =========================   ===========================
 
 
 Integrating with git
 -----------------------
 
-Add the following to `~/.gitconfig`:
+Add the following to :file:`~/.gitconfig`:
 
 .. code-block:: ini
 
@@ -120,36 +120,31 @@ 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).
+</protocol-extensions>`, such as the :doc:`kitty graphics protocol
+</graphics-protocol>`, the :doc:`extended keyboard protocol
+</keyboard-protocol>`, etc. It also leverages terminal program infrastructure
+I created for all of kitty's other kittens to reduce the amount of code needed
+(the entire implementation is under 2000 lines of code).
 
 And fundamentally, it's kitty only because I wrote it for myself, and I am
 highly unlikely to use any other terminals :)
 
 
-
 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.
+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
 -----------------
 

docs/kittens/hints.rst

@@ -1,54 +1,63 @@
 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
+|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 default web
 browser.
 
 .. figure:: ../screenshots/hints_mode.png
     :alt: URL hints mode
     :align: center
-    :scale: 100%
+    :width: 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.
+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 :program:`git` or :program:`ls` command
+and adding them to the command line for the next command.
 
-You can also press :sc:`goto_file_line` to select anything that looks
-like a path or filename followed by a colon and a line number and open
-the file in vim at the specified line number. The patterns and editor
-to be used can be modified using options passed to the kitten. For example::
+You can also press :sc:`goto_file_line` to select anything that looks like a
+path or filename followed by a colon and a line number and open the file in
+:program:`vim` at the specified line number. The patterns and editor to be used
+can be modified using options passed to the kitten. For example::
 
     map ctrl+g kitten hints --type=linenum --linenum-action=tab nvim +{line} {path}
 
-will open the selected file in a new tab inside neovim when you press
-:kbd:`ctrl+g`.
+will open the selected file in a new tab inside `Neovim <https://neovim.io/>`__
+when you press :kbd:`Ctrl+G`.
 
-Pressing :sc:`open_selected_hyperlink` will open hyperlinks, i.e. a URL
+Pressing :sc:`open_selected_hyperlink` will open :term:`hyperlinks`, i.e. a URL
 that has been marked as such by the program running in the terminal,
-for example, by ``ls --hyperlink=auto``. You can also :doc:`customize what actions are
-taken for different types of URLs <../open_actions>`.
+for example, by ``ls --hyperlink=auto``. If :program:`ls` comes with your OS
+does not support hyperlink, you may need to install `GNU Coreutils
+<https://www.gnu.org/software/coreutils/>`__.
+
+You can also :doc:`customize what actions are taken for different types of URLs
+<../open_actions>`.
+
+.. note:: If there are more hints than letters, hints will use multiple
+   letters. In this case, when you press the first letter, only hints
+   starting with that letter are displayed. Pressing the second letter will
+   select that hint or press :kbd:`Enter` or :kbd:`Space` to select the empty
+   hint.
 
 The hints kitten is very powerful to see more detailed help on its various
 options and modes of operation, see below. You can use these options to
 create mappings in :file:`kitty.conf` to select various different text
-snippets. See :sc:`insert_selected_path` for examples.
+snippets. See :sc:`insert_selected_path <insert_selected_path>` for examples.
 
 
 Completely customizing the matching and actions of the kitten
 ---------------------------------------------------------------
 
-The hints kitten supports writing simple python scripts that can be used to
+The hints kitten supports writing simple Python scripts that can be used to
 completely customize how it finds matches and what happens when a match is
-selected. This allows the hints kitten to provide the user interface, while
-you can provide the logic for finding matches and performing actions on them.
-This is best illustrated with an example. Create the file
-:file:`custom-hints.py` in the kitty config directory with the following
-contents:
+selected. This allows the hints kitten to provide the user interface, while you
+can provide the logic for finding matches and performing actions on them. This
+is best illustrated with an example. Create the file :file:`custom-hints.py` in
+the :ref:`kitty config directory <confloc>` with the following contents:
 
 .. code-block:: python
 
@@ -88,8 +97,14 @@ Now run kitty with::
 When you press the :kbd:`F1` key you will be able to select a word to
 look it up in the Google dictionary.
 
-
-Command Line Interface
--------------------------
-
 .. include:: ../generated/cli-kitten-hints.rst
+
+.. note::
+
+    To avoid having to specify the same command line options on every
+    invocation, you can use the :opt:`action_alias` option in
+    :file:`kitty.conf`, creating aliases that have common sets of options.
+    For example::
+
+        action_alias myhints kitten hints --alphabet qfjdkslaureitywovmcxzpq1234567890
+        map f1 myhints --customize-processing custom-hints.py

docs/kittens/hyperlinked_grep.rst

@@ -1,11 +1,10 @@
 Hyperlinked grep
 =================
 
-
 This kitten allows you to search your files using `ripgrep
-<https://www.google.com/search?q=ripgrep>`_ and open the results
-directly in your favorite editor in the terminal, at the line containing
-the search result, simply by clicking on the result you want.
+<https://github.com/BurntSushi/ripgrep>`__ and open the results directly in your
+favorite editor in the terminal, at the line containing the search result,
+simply by clicking on the result you want.
 
 .. versionadded:: 0.19.0
 
@@ -25,19 +24,19 @@ following contents:
     mime text/*
     action launch --type=overlay ${EDITOR} ${FILE_PATH}
 
-
 Now, run a search with::
 
     kitty +kitten hyperlinked_grep something
 
-Hold down the :kbd:`ctrl+shift` keys and click on any of the
-result lines, to open the file in vim at the matching line. If
-you use some editor other than vim, you should adjust the
-:file:`open-actions.conf` file accordingly.
+Hold down the :kbd:`Ctrl+Shift` keys and click on any of the result lines, to
+open the file in :program:`vim` at the matching line. If you use some editor
+other than :program:`vim`, you should adjust the :file:`open-actions.conf` file
+accordingly.
 
-Finally, add an alias to your shell's rc files to invoke the kitten as ``hg``::
+Finally, add an alias to your shell's rc files to invoke the kitten as
+:command:`hg`::
 
-    alias hg='kitty +kitten hyperlinked_grep'
+    alias hg="kitty +kitten hyperlinked_grep"
 
 
 You can now run searches with::
@@ -45,27 +44,42 @@ You can now run searches with::
     hg some-search-term
 
 If you want to enable completion, for the kitten, you can delegate completion
-to rg. For that, instead of using an alias create a simple wrapper script named
-:file:`hg` somewhere in your ``PATH``:
+to :program:`rg`. How to do that varies based on the shell:
 
-.. code-block:: sh
 
-    #!/bin/sh
-    exec kitty +kitten hyperlinked_grep "$@"
+.. tab:: zsh
 
-Then, for example, for ZSH, add the following to :file:`.zshrc`::
+    Instead of using an alias, create a simple wrapper script named
+    :program:`hg` somewhere in your :envvar:`PATH`:
 
-    compdef _rg hg
+    .. code-block:: sh
+
+        #!/bin/sh
+        exec kitty +kitten hyperlinked_grep "$@"
+
+    Then, add the following to :file:`.zshrc`::
+
+        compdef _rg hg
+
+.. tab:: fish
+
+    You can combine both the aliasing/wrapping and pointing fish to ripgrep's
+    autocompletion with a fish wrapper function in your :file:`config.fish`
+    or :file:`~/.config/fish/functions/hg.fish`:
+
+    .. code-block:: fish
+
+        function hg --wraps rg; kitty +kitten hyperlinked_grep $argv; end
 
 To learn more about kitty's powerful framework for customizing URL click
-actions, :doc:`see here <../open_actions>`.
+actions, see :doc:`here </open_actions>`.
 
 Hopefully, someday this functionality will make it into some `upstream grep
-<https://github.com/BurntSushi/ripgrep/issues/665>`_
-program directly removing the need for this kitten.
+<https://github.com/BurntSushi/ripgrep/issues/665>`__ program directly removing
+the need for this kitten.
 
 
 .. note::
    While you can pass any of ripgrep's comand line options to the kitten and
-   they will be forwarded to rg, do not use options that change the output
-   formatting as the kitten works by parsing the output from ripgrep.
+   they will be forwarded to :program:`rg`, do not use options that change the
+   output formatting as the kitten works by parsing the output from ripgrep.

docs/kittens/icat.rst

@@ -1,14 +1,16 @@
-icat - Display images in the terminal
+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>`.
+<https://www.imagemagick.org>`__. It even works over SSH. For details, see the
+:doc:`kitty graphics protocol </graphics-protocol>`.
 
 You might want to create an alias in your shell's configuration files::
 
@@ -18,14 +20,14 @@ Then you can simply use ``icat image.png`` to view images.
 
 .. note::
 
-    `ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
-    work.
+    `ImageMagick <https://www.imagemagick.org>`__ must be installed for icat
+    kitten to work.
 
 .. note::
 
     kitty's image display protocol may not work when used within a terminal
-    multiplexer such as ``screen`` or ``tmux``, depending on whether the
-    multiplexer has added support for it or not.
+    multiplexer such as :program:`screen` or :program:`tmux`, depending on
+    whether the multiplexer has added support for it or not.
 
 
 .. program:: kitty +kitten icat
@@ -33,9 +35,19 @@ Then you can simply use ``icat image.png`` to view images.
 
 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`.
+:option:`--detect-support`, :option:`--silent` and
+:option:`--print-window-size`.
+
+If you are trying to integrate icat into a complex program like a file manager
+or editor, there are a few things to keep in mind. icat works by communicating
+over the TTY device, it both writes to and reads from the TTY. So it is
+imperative that while it is running the host program does not do any TTY I/O.
+Any key presses or other input from the user on the TTY device will be
+discarded. At a minimum, you should use the :option:`--silent` and
+:option:`--transfer-mode` command line arguments. To be really robust you should
+consider writing proper support for the :doc:`kitty graphics protocol
+</graphics-protocol>` in the program instead. Nowadays there are many libraries
+that have support for it.
 
-Command Line Interface
---------------------------
 
 .. include:: /generated/cli-kitten-icat.rst

docs/kittens/panel.rst

@@ -4,8 +4,8 @@ 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.
+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.
@@ -14,7 +14,7 @@ using terminal programs instead of GUI toolkits.
 .. figure:: ../screenshots/panel.png
    :alt: Screenshot, showing a sample panel
    :align: center
-   :scale: 100%
+   :width: 100%
 
    Screenshot, showing a sample panel
 
@@ -32,12 +32,9 @@ 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
+seconds. Here the terminal program we are running is :program:`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/query_terminal.rst

@@ -1,21 +1,18 @@
 Query terminal
 =================
 
-Used to query kitty from terminal programs about version, values of various
-runtime options controlling its features, etc.
+This kitten is used to query |kitty| from terminal programs about version, values
+of various runtime options controlling its features, etc.
 
 The querying is done using the (*semi*) standard XTGETTCAP escape sequence
-pioneered by XTerm, so it works over SSH as well. The downside is that it
-is slow, since it requires a roundtrip to the terminal emulator and back.
+pioneered by xterm, so it works over SSH as well. The downside is that it is
+slow, since it requires a roundtrip to the terminal emulator and back.
 
 If you want to do some of the same querying in your terminal program without
 depending on the kitten, you can do so, by processing the same escape codes.
-Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`_
-for *XTGETTCAP* to see the syntax for the escape code and read the source
-of this kitten to find the values of the keys for the various queries.
+Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`__
+for *XTGETTCAP* to see the syntax for the escape code and read the source of
+this kitten to find the values of the keys for the various queries.
 
 
-Command Line Interface
--------------------------
-
 .. include:: ../generated/cli-kitten-query_terminal.rst

docs/kittens/remote_file.rst

@@ -1,37 +1,44 @@
 Remote files
 ==============
 
-|kitty| has the ability to easily *Edit*, *Open* or *Download* files
-from a computer into which you are SSHed. In your SSH session run::
+|kitty| has the ability to easily *Edit*, *Open* or *Download* files from a
+computer into which you are SSHed. In your SSH session run::
 
     ls --hyperlink=auto
 
-Then hold down :kbd:`ctrl+shift` and click the name of the file.
+Then hold down :kbd:`Ctrl+Shift` and click the name of the file.
 
 .. figure:: ../screenshots/remote_file.png
     :alt: Remote file actions
     :align: center
-    :scale: 100%
+    :width: 100%
 
     Remote file actions
 
 |kitty| will ask you what you want to do with the remote file. You can choose
 to *Edit* it in which case kitty will download it and open it locally in your
-``EDITOR``. As you make changes to the file, they are automatically transferred
-to the remote computer. Note that this happens without needing to install *any*
-special software on the server, beyond ``ls`` that supports hyperlinks.
+:envvar:`EDITOR`. As you make changes to the file, they are automatically
+transferred to the remote computer. Note that this happens without needing
+to install *any* special software on the server, beyond :program:`ls` that
+supports hyperlinks.
+
+.. seealso:: See the :doc:`transfer` kitten
 
 .. versionadded:: 0.19.0
 
 .. note::
-   Nested SSH sessions are not supported. The kitten will always try to copy
-   remote files from the first SSH host. This is because there is no way for
-   |kitty| to detect and follow a nested SSH session robustly.
+   For best results, use this kitten with the :doc:`ssh kitten <./ssh>`.
+   Otherwise, nested SSH sessions are not supported. The kitten will always try to copy
+   remote files from the first SSH host. This is because, without the ssh
+   kitten, there is no way for
+   |kitty| to detect and follow a nested SSH session robustly. Use the
+   :doc:`transfer` kitten for such situations.
 
 .. note::
-   If you have not setup automatic password-less SSH access, then, when
-   editing starts you will be asked to enter your password just once,
-   thereafter the SSH connection will be re-used.
+   If you have not setup automatic password-less SSH access, and are not using
+   the ssh kitten, then, when editing
+   starts you will be asked to enter your password just once, thereafter the SSH
+   connection will be re-used.
 
 Similarly, you can choose to save the file to the local computer or download
 and open it in its default file handler.

docs/kittens/ssh.rst

@@ -0,0 +1,154 @@
+Truly convenient SSH
+=========================================
+
+* Automatic :ref:`shell_integration` on remote hosts
+
+* Easily :ref:`clone local shell/editor config <real_world_ssh_kitten_config>` on remote hosts
+
+* Automatic :opt:`re-use of existing connections <kitten-ssh.share_connections>` to avoid connection setup latency
+
+* Make kitty itself available in the remote host :opt:`on demand <kitten-ssh.remote_kitty>`
+
+* Easily :opt:`change terminal colors <kitten-ssh.color_scheme>` when connecting to remote hosts
+
+.. versionadded:: 0.25.0
+   Automatic shell integration, file transfer and reuse of connections
+
+The ssh kitten allows you to login easily to remote hosts, and automatically
+setup the environment there to be as comfortable as your local shell. You can
+specify environment variables to set on the remote host and files to copy there,
+making your remote experience just like your local shell. Additionally, it
+automatically sets up :ref:`shell_integration` on the remote host and copies the
+kitty terminfo database there.
+
+The ssh kitten is a thin wrapper around the traditional `ssh <https://man.openbsd.org/ssh>`__
+command line program and supports all the same options and arguments and configuration.
+In interactive usage scenarios it is a drop in replacement for :program:`ssh`.
+To try it out, simply run:
+
+.. code-block:: sh
+
+    kitty +kitten ssh some-hostname-to-connect-to
+
+You should end up at a shell prompt on the remote host, with shell integration
+enabled. If you like it you can add an alias to it in your shell's rc files:
+
+.. code-block:: sh
+
+    alias s="kitty +kitten ssh"
+
+So now you can just type ``s hostname`` to connect.
+
+If you define a mapping in :file:`kitty.conf` such as::
+
+    map f1 new_window_with_cwd
+
+Then, pressing :kbd:`F1` will open a new window automatically logged into the
+same host using the ssh kitten, at the same directory.
+
+The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf` file
+where you can specify environment variables to set on the remote host and files
+to copy from the local to the remote host. Let's see a quick example:
+
+.. code-block:: conf
+
+   # Copy the files and directories needed to setup some common tools
+   copy .zshrc .vimrc .vim
+   # Setup some environment variables
+   env SOME_VAR=x
+   # COPIED_VAR will have the same value on the remote host as it does locally
+   env COPIED_VAR=_kitty_copy_env_var_
+
+   # Create some per hostname settings
+   hostname someserver-*
+   copy env-files
+   env SOMETHING=else
+
+   hostname someuser@somehost
+   copy --dest=foo/bar some-file
+   copy --glob some/files.*
+
+
+See below for full details on the syntax and options of :file:`ssh.conf`.
+Additionally, you can pass config options on the command line:
+
+.. code-block:: sh
+
+   kitty +kitten ssh --kitten interpreter=python servername
+
+The :code:`--kitten` argument can be specified multiple times, with directives
+from :file:`ssh.conf`. These are merged with :file:`ssh.conf` as if they were
+appended to the end of that file. They apply only to the host being SSHed to by
+this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are
+ignored.
+
+.. warning::
+
+   Due to limitations in the design of SSH, any typing you do before the
+   shell prompt appears may be lost. So ideally don't start typing till you see
+   the shell prompt. 😇
+
+
+.. _real_world_ssh_kitten_config:
+
+A real world example
+----------------------
+
+Suppose you often SSH into a production server, and you would like to setup
+your shell and editor there using your custom settings. However, other people
+could SSH in as well and you don't want to clobber their settings. Here is how
+this could be achieved using the ssh kitten with :program:`zsh` and
+:program:`vim` as the shell and editor, respectively:
+
+.. code-block:: conf
+
+   # Have these settings apply to servers in my organization
+   hostname myserver-*
+
+   # Setup zsh to read its files from my-conf/zsh
+   env ZDOTDIR $HOME/my-conf/zsh
+   copy --dest my-conf/zsh/.zshrc .zshrc
+   copy --dest my-conf/zsh/.zshenv .zshenv
+   # If you use other zsh init files add them in a similar manner
+
+   # Setup vim to read its config from my-conf/vim
+   env VIMINIT $HOME/my-conf/vim/vimrc
+   env VIMRUNTIME $HOME/my-conf/vim
+   copy --dest my-conf/vim .vim
+   copy --dest my-conf/vim/vimrc .vimrc
+
+
+How it works
+----------------
+
+The ssh kitten works by having SSH transmit and execute a POSIX sh (or
+:opt:`optionally <kitten-ssh.interpreter>` Python) bootstrap script on the
+remote host using an :opt:`interpreter <kitten-ssh.interpreter>`. This script
+reads setup data over the TTY device, which kitty sends as a Base64 encoded
+compressed tarball. The script extracts it and places the :opt:`files <kitten-ssh.copy>`
+and sets the :opt:`environment variables <kitten-ssh.env>` before finally
+launching the :opt:`login shell <kitten-ssh.login_shell>` with :opt:`shell
+integration <kitten-ssh.shell_integration>` enabled. The data is requested by
+the kitten over the TTY with a random one time password. kitty reads the request
+and if the password matches a password pre-stored in shared memory on the
+localhost by the kitten, the transmission is allowed. If your local
+`OpenSSH <https://www.openssh.com/>`__ version is >= 8.4 then the data is
+transmitted instantly without any roundtrip delay.
+
+.. note::
+
+   When connecting to BSD hosts, it is possible the bootstrap script will fail
+   or run slowly, because the default shells are crippled in various ways.
+   Your best bet is to install Python on the remote, make sure the login shell
+   is something POSIX sh compliant, and use :code:`python` as the
+   :opt:`interpreter <kitten-ssh.interpreter>` in :file:`ssh.conf`.
+
+.. include:: /generated/conf-kitten-ssh.rst
+
+
+.. _ssh_copy_command:
+
+The copy command
+--------------------
+
+.. include:: /generated/ssh-copy.rst

docs/kittens/themes.rst

@@ -0,0 +1,79 @@
+Changing kitty colors
+========================
+
+The themes kitten allows you to easily change color themes, from a collection of
+over two hundred pre-built themes available at `kitty-themes
+<https://github.com/kovidgoyal/kitty-themes>`_. To use it, simply run::
+
+    kitty +kitten themes
+
+
+.. image:: ../screenshots/themes.png
+   :alt: The themes kitten in action
+   :width: 600
+
+The kitten allows you to pick a theme, with live previews of the colors. You can
+choose between light and dark themes and search by theme name by just typing a
+few characters from the name.
+
+The kitten maintains a list of recently used themes to allow quick switching.
+
+If you want to restore the colors to default, you can do so by choosing the
+``Default`` theme.
+
+.. versionadded:: 0.23.0
+   The themes kitten
+
+
+How it works
+----------------
+
+A theme in kitty is just a :file:`.conf` file containing kitty settings.
+When you select a theme, the kitten simply copies the :file:`.conf` file
+to :file:`~/.config/kitty/current-theme.conf` and adds an include for
+:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out any
+existing color settings in :file:`kitty.conf` so they do not interfere.
+
+Once that's done, the kitten sends kitty a signal to make it reload its config.
+
+Using your own themes
+-----------------------
+
+You can also create your own themes as :file:`.conf` files. Put them in the
+:file:`themes` sub-directory of the :ref:`kitty config directory <confloc>`,
+usually, :file:`~/.config/kitty/themes`. The kitten will automatically add them
+to the list of themes. You can use this to modify the builtin themes, by giving
+the conf file the name :file:`Some theme name.conf` to override the builtin
+theme of that name. Note that after doing so you have to run the kitten and
+choose that theme once for your changes to be applied.
+
+
+Contributing new themes
+-------------------------
+
+If you wish to contribute a new theme to the kitty theme repository, start by
+going to the `kitty-themes <https://github.com/kovidgoyal/kitty-themes>`__
+repository. `Fork it
+<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__, and use the
+file :download:`template.conf
+<https://github.com/kovidgoyal/kitty-themes/raw/master/template.conf>` as a
+template when creating your theme. Once you are satisfied with how it looks,
+`submit a pull request
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`__
+to have your theme merged into the `kitty-themes
+<https://github.com/kovidgoyal/kitty-themes>`__ repository, which will make it
+available in this kitten automatically.
+
+
+Changing the theme non-interactively
+---------------------------------------
+
+You can specify the theme name as an argument when invoking the kitten to have
+it change to that theme instantly. For example::
+
+    kitty +kitten themes --reload-in=all Dimmed Monokai
+
+Will change the theme to ``Dimmed Monokai`` in all running kitty instances. See
+below for more details on non-interactive operation.
+
+.. include:: ../generated/cli-kitten-themes.rst

docs/kittens/transfer.rst

@@ -0,0 +1,99 @@
+Transfer files
+================
+
+.. _rsync: https://en.wikipedia.org/wiki/Rsync
+
+.. warning::
+   This kitten is currently experimental, use with care.
+
+Transfer files to and from remote computers over the ``TTY`` device itself.
+This means that file transfer works over nested SSH sessions, serial links,
+etc. Anywhere you have a terminal device, you can transfer files.
+
+.. image:: ../screenshots/transfer.png
+   :alt: The transfer kitten at work
+
+This kitten supports transferring entire directory trees, preserving soft and
+hard links, file permissions, times, etc. It even supports the rsync_ protocol
+to transfer only changes to large files.
+
+.. seealso:: See the :doc:`remote_file` kitten
+
+.. note::
+   This kitten (which practically means kitty) must be installed on the other
+   machine as well. If that is not possible you can use the :doc:`remote_file`
+   kitten instead. Or write your own script to use the underlying
+   :doc:`file transfer protocol </file-transfer-protocol>`.
+
+.. versionadded:: 0.24.0
+
+
+Basic usage
+---------------
+
+In what follows, the *local computer* is the computer running this kitten and
+the *remote computer* is the computer connected to the other end of the TTY
+pipe.
+
+To send a file from the local computer to the remote computer, simply run::
+
+    kitty +kitten transfer /path/to/local/file /path/to/destination/on/remote/computer
+
+You will be prompted by kitty for confirmation on allowing the transfer, and if
+you grant permission, the file will be copied.
+
+Similarly, to get a file from the remote computer to the local computer, use
+the :option:`--direction <kitty +kitten transfer --direction>` option::
+
+    kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer
+
+Multiple files and even directories can be transferred::
+
+    kitty +kitten transfer file1 dir1 destination/
+
+Here :file:`file1` will be copied inside :file:`destination` and :file:`dir1`
+will be recursively copied into :file:`destination`. Note the trailing slash on
+:file:`destination`. This tells kitty the destination is a directory. While not
+strictly necessary (kitty will infer the need for a destination directory from
+the fact that you are copying multiple things) it is good practice to always
+use a trailing slash when the destination is supposed to be a directory.
+
+Also, when transferring multiple files/directories it is a good idea to
+use the :option:`--confirm-paths <kitty +kitten transfer --confirm-paths>`
+option which will give you an opportunity to review and confirm the files that
+will be touched.
+
+
+Avoiding the confirmation prompt
+------------------------------------
+
+Normally, when you start a file transfer kitty will prompt you for confirmation.
+This is to ensure that hostile programs running on a remote machine cannot
+read/write files on your computer without your permission. If the remote machine
+is trusted and the connection between your computer and the remote machine is
+secure, then you can disable the confirmation prompt by:
+
+#. Setting the :opt:`file_transfer_confirmation_bypass` option to some password.
+
+#. When invoking the kitten use the :option:`--permissions-bypass
+   <kitty +kitten transfer --permissions-bypass>` to supply the password you set
+   in step one.
+
+.. warning:: Using a password to bypass confirmation means any software running
+   on the remote machine could potentially learn that password and use it to
+   gain full access to your computer. Also anyone that can intercept the data
+   stream between your computer and the remote machine can also learn this
+   password. So use it only with secure connections to trusted computers.
+
+
+Delta transfers
+-----------------------------------
+
+This kitten has the ability to use the rsync_ protocol to only transfer the
+differences between files. To turn it on use the :option:`--transmit-deltas
+<kitty +kitten transfer --transmit-deltas>` option. Note that this will actually
+be slower when transferring small files because of round trip overhead, so use
+with care.
+
+
+.. include:: ../generated/cli-kitten-transfer.rst

docs/kittens/unicode-input.rst

@@ -1,34 +0,0 @@
-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.
-The up and down arrow keys can be used to choose the previous and next unicode
-symbol respectively.
-
-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 space followed by a period and the index for the match if you don't
-like to use arrow keys.
-
-You can switch between modes using either the function keys or by pressing
-:kbd:`Ctrl+[` and :kbd:`Ctrl+]` or by pressing :kbd:`Ctrl+Tab` and
-:kbd:`Ctrl+Shift+Tab`.
-
-
-Command Line Interface
--------------------------
-
-.. include:: ../generated/cli-kitten-unicode_input.rst

docs/kittens/unicode_input.rst

@@ -0,0 +1,33 @@
+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 kitten, shown below.
+
+.. figure:: ../screenshots/unicode.png
+    :alt: A screenshot of the unicode input kitten
+    :align: center
+    :width: 100%
+
+    A screenshot of the unicode input kitten
+
+In :guilabel:`Code` mode, you enter a Unicode character by typing in the hex
+code for the character and pressing :kbd:`Enter`. For example, type in ``2716``
+and press :kbd:`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 :kbd:`Enter`.
+The :kbd:`Up` and :kbd:`Down` arrow keys can be used to choose the previous and
+next Unicode symbol respectively.
+
+In :guilabel:`Name` mode you instead type words from the character name and use
+the :kbd:`ArrowKeys` / :kbd:`Tab` to select the character from the displayed
+matches. You can also type a space followed by a period and the index for the
+match if you don't like to use arrow keys.
+
+You can switch between modes using either the keys :kbd:`F1` ... :kbd:`F4` or
+:kbd:`Ctrl+1` ... :kbd:`Ctrl+4` or by pressing :kbd:`Ctrl+[` and :kbd:`Ctrl+]`
+or by pressing :kbd:`Ctrl+Tab` and :kbd:`Ctrl+Shift+Tab`.
+
+
+.. include:: ../generated/cli-kitten-unicode_input.rst

docs/kittens_intro.rst

@@ -0,0 +1,81 @@
+.. _kittens:
+
+Extend with kittens
+-----------------------
+
+.. toctree::
+   :hidden:
+   :glob:
+
+   kittens/icat
+   kittens/diff
+   kittens/unicode_input
+   kittens/themes
+   kittens/hints
+   kittens/remote_file
+   kittens/hyperlinked_grep
+   kittens/transfer
+   kittens/ssh
+   kittens/custom
+   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:`Remote file <kittens/remote_file>`
+    Edit, open, or download remote files over SSH easily, by simply clicking on
+    the filename.
+
+
+:doc:`Transfer files <kittens/transfer>`
+    Transfer files and directories seamlessly and easily from remote machines
+    over your existing SSH sessions with a simple command.
+
+
+:doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
+    Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`__
+    and open the results directly in your favorite editor in the terminal,
+    at the line containing the search result, simply by clicking on the result
+    you want.
+
+
+:doc:`Broadcast <kittens/broadcast>`
+    Type in one :term:`kitty window <window>` and have it broadcast to all (or a
+    subset) of other :term:`kitty windows <window>`.
+
+
+:doc:`SSH <kittens/ssh>`
+    SSH with automatic :ref:`shell integration <shell_integration>`, connection
+    re-use for low latency and easy cloning of local shell and editor
+    configuration to the remote host.
+
+
+: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.
+
+You can also :doc:`Learn to create your own kittens <kittens/custom>`.

docs/launch.rst

@@ -1,26 +1,25 @@
-Launching programs in new windows/tabs
-========================================
+The :command:`launch` command
+--------------------------------
 
 .. program:: launch
 
 
 |kitty| has a :code:`launch` action that can be used to run arbitrary programs
-in new windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
-It is very powerful and allows sending the contents of
-the current window to the launched program, as well as many other options.
+in new windows/tabs. It can be mapped to user defined shortcuts in
+:file:`kitty.conf`. It is very powerful and allows sending the contents of the
+current window to the launched program, as well as many other options.
 
 In the simplest form, you can use it to open a new kitty window running the
 shell, as shown below::
 
     map f1 launch
 
-To run a different program simply pass the command line as arguments to
-launch::
+To run a different program simply pass the command line as arguments to launch::
 
     map f1 launch vim path/to/some/file
 
-To open a new window with the same working directory as the currently
-active window::
+To open a new window with the same working directory as the currently active
+window::
 
     map f1 launch --cwd=current
 
@@ -30,20 +29,33 @@ To open the new window in a new tab::
 
 To run multiple commands in a shell, use::
 
-    map f1 launch sh -c "ls && zsh"
+    map f1 launch sh -c "ls && exec zsh"
 
-To pass the contents of the current screen and scrollback to the started process::
+To pass the contents of the current screen and scrollback to the started
+process::
 
     map f1 launch --stdin-source=@screen_scrollback less
 
 There are many more powerful options, refer to the complete list below.
 
+.. note::
+    To avoid duplicating launch actions with frequently used parameters, you can
+    use :opt:`action_alias` to define launch action aliases. For example::
+
+        action_alias launch_tab launch --cwd=current --type=tab
+        map f1 launch_tab vim
+        map f2 launch_tab emacs
+
+    The :kbd:`F1` key will now open :program:`vim` in a new tab with the current
+    windows working directory.
+
+
 The piping environment
 --------------------------
 
 When using :option:`launch --stdin-source`, the program to which the data is
-piped has a special environment variable declared, ``KITTY_PIPE_DATA`` whose
-contents are::
+piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA`
+whose contents are::
 
    KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
 
@@ -61,27 +73,33 @@ the command line:
 
 
 ``@selection``
-    replaced by the currently selected text
+    Replaced by the currently selected text.
 
 ``@active-kitty-window-id``
-    replaced by the id of the currently active kitty window
+    Replaced by the id of the currently active kitty window.
 
 ``@line-count``
-    replaced by the number of lines in STDIN. Only present when passing some
-    data to STDIN
+    Replaced by the number of lines in STDIN. Only present when passing some
+    data to STDIN.
 
 ``@input-line-number``
-    replaced the number of lines a pager should scroll to match the current
-    scroll position in kitty. See :opt:`scrollback_pager` for details
+    Replaced the number of lines a pager should scroll to match the current
+    scroll position in kitty. See :opt:`scrollback_pager` for details.
 
 ``@scrolled-by``
-    replaced by the number of lines kitty is currently scrolled by
+    Replaced by the number of lines kitty is currently scrolled by.
 
 ``@cursor-x``
-    replaced by the current cursor x position with 1 being the leftmost cell
+    Replaced by the current cursor x position with 1 being the leftmost cell.
 
 ``@cursor-y``
-    replaced by the current cursor y position with 1 being the topmost cell
+    Replaced by the current cursor y position with 1 being the topmost cell.
+
+``@first-line-on-screen``
+    Replaced by the first line on screen. Can be used for pager positioning.
+
+``@last-line-on-screen``
+    Replaced by the last line on screen. Can be used for pager positioning.
 
 
 For example::
@@ -89,47 +107,57 @@ For example::
     map f1 launch my-program @active-kitty-window-id
 
 
+.. _watchers:
+
 Watching launched windows
 ---------------------------
 
-The :option:`launch --watcher` option allows you to specify python functions
+The :option:`launch --watcher` option allows you to specify Python functions
 that will be called at specific events, such as when the window is resized or
-closed. Simply specify the path to a python module that specifies callback
+closed. Simply specify the path to a Python module that specifies callback
 functions for the events you are interested in, for example:
 
 .. code-block:: python
 
-    def on_resize(boss, window, data):
+    from typing import Any, Dict
+
+    from kitty.boss import Boss
+    from kitty.window import Window
+
+
+    def on_resize(boss: Boss, window: Window, data: Dict[str, Any]) -> None:
         # Here data will contain old_geometry and new_geometry
 
-    def on_focus_change(boss, window, data):
-        # Here data kill contain focused
+    def on_focus_change(boss: Boss, window: Window, data: Dict[str, Any])-> None:
+        # Here data will contain focused
 
-    def on_close(boss, window, data):
+    def on_close(boss: Boss, window: Window, data: Dict[str, Any])-> None:
         # called when window is closed, typically when the program running in
         # it exits.
 
 
 Every callback is passed a reference to the global ``Boss`` object as well as
-the ``Window`` object the action is occurring on. The ``data`` object is
-mapping that contains event dependent data. Some useful methods and attributes
-for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
+the ``Window`` object the action is occurring on. The ``data`` object is a dict
+that contains event dependent data. Some useful methods and attributes for the
+``Window`` object are: ``as_text(as_ans=False, add_history=False,
 add_wrap_markers=False, alternate_screen=False)`` with which you can get the
 contents of the window and its scrollback buffer. Similarly,
 ``window.child.pid`` is the PID of the processes that was launched
-in the window and ``window.id`` is the internal kitty ``id`` of the
-window.
+in the window and ``window.id`` is the internal kitty ``id`` of the window.
 
 
 Finding executables
 -----------------------
 
 When you specify a command to run as just a name rather than an absolute path,
-it is searched for in the system-wide ``PATH`` environment variable. Note that
-this **may not** be the value of ``PATH`` inside a shell, as shell startup scripts
-often change the value of this variable. If it is not found there, then a
-system specific list of default paths is searched. If it is still not found,
-then your shell is run and the value of ``PATH`` inside the shell is used.
+it is searched for in the system-wide :envvar:`PATH` environment variable. Note
+that this **may not** be the value of :envvar:`PATH` inside a shell, as shell
+startup scripts often change the value of this variable. If it is not found
+there, then a system specific list of default paths is searched. If it is still
+not found, then your shell is run and the value of :envvar:`PATH` inside the
+shell is used.
+
+See :opt:`exe_search_path` for details and how to control this.
 
 Syntax reference
 ------------------

docs/layouts.rst

@@ -1,5 +1,5 @@
-Layouts
-============
+Arrange windows
+-------------------
 
 kitty has the ability to define its own windows that can be tiled next to each
 other in arbitrary arrangements, based on *Layouts*, see below for examples:
@@ -8,34 +8,33 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
 .. figure:: screenshots/screenshot.png
     :alt: Screenshot, showing three programs in the 'Tall' layout
     :align: center
-    :scale: 100%
+    :width: 100%
 
-    Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
+    Screenshot, showing :program:`vim`, :program:`tig` and :program:`git`
+    running in |kitty| with the *Tall* layout
 
 
 .. figure:: screenshots/splits.png
     :alt: Screenshot, showing windows in the 'Splits' layout
     :align: center
-    :scale: 100%
+    :width: 100%
 
-    Screenshot, showing windows with arbitrary arrangement in the 'Splits'
+    Screenshot, showing windows with arbitrary arrangement in the *Splits*
     layout
 
 
-There are many different layouts available. They are all enabled by default,
-you can switch layouts using :sc:`next_layout`. To control which layouts
-are available use :opt:`enabled_layouts`, the first listed layout becomes
-the default. Individual layouts and how to use them are described below.
-
-.. contents::
-   :local:
+There are many different layouts available. They are all enabled by default, you
+can switch layouts using :ac:`next_layout` (:sc:`next_layout` by default). To
+control which layouts are available use :opt:`enabled_layouts`, the first listed
+layout becomes the default. Individual layouts and how to use them are described
+below.
 
 
 The Stack Layout
 ------------------
 
-This is the simplest layout it displays a single window using all available
-space, other windows are hidden behind it. It has no options::
+This is the simplest layout. It displays a single window using all available
+space, other windows are hidden behind it. This layout has no options::
 
     enabled_layouts stack
 
@@ -43,14 +42,14 @@ space, other windows are hidden behind it. It has no options::
 The Tall Layout
 ------------------
 
-Displays one (or optionally more) full height windows on the left half of the
+Displays one (or optionally more) full-height windows on the left half of the
 screen. Remaining windows are tiled vertically on the right half of the screen.
 There are options to control how the screen is split horizontally ``bias``
 (an integer between ``10`` and ``90``) and options to control how many
 full-height windows there are ``full_size`` (a positive integer). The
-``mirrored`` option when set to ``true`` will cause the short windows to be
-on the left side of the screen instead of the right. The syntax
-for the options is shown below::
+``mirrored`` option when set to ``true`` will cause the full-height windows to
+be on the right side of the screen instead of the left. The syntax
+for the options is::
 
     enabled_layouts tall:bias=50;full_size=1;mirrored=false
 
@@ -68,7 +67,7 @@ for the options is shown below::
     │              │               │
     └──────────────┴───────────────┘
 
-In addition, you can map keys to increase or decrease the number of full size
+In addition, you can map keys to increase or decrease the number of full-height
 windows, for example::
 
    map ctrl+[ layout_action decrease_num_full_size_windows
@@ -78,14 +77,13 @@ windows, for example::
 The Fat Layout
 ----------------
 
-Displays one (or optionally more) full width windows on the top half of the
-screen. Remaining windows are tiled horizontally on the bottom half of the screen.
-There are options to control how the screen is split vertically ``bias``
+Displays one (or optionally more) full-width windows on the top half of the
+screen. Remaining windows are tiled horizontally on the bottom half of the
+screen. There are options to control how the screen is split vertically ``bias``
 (an integer between ``10`` and ``90``) and options to control how many
-full-height windows there are ``full_size`` (a positive integer). The
-``mirrored`` option when set to ``true`` will cause the narrow windows to be
-on the top of the screen instead of the bottom. The syntax for the options is
-shown below::
+full-width windows there are ``full_size`` (a positive integer). The
+``mirrored`` option when set to ``true`` will cause the full-width windows to be
+on the bottom of the screen instead of the top. The syntax for the options is::
 
     enabled_layouts fat:bias=50;full_size=1;mirrored=false
 
@@ -103,11 +101,16 @@ shown below::
     └─────────┴──────────┴─────────┘
 
 
+This layout also supports ``decrease_num_full_size_windows`` layout action like
+the *Tall* layout, shown above.
+
+
 The Grid Layout
 --------------------
 
 Display windows in a balanced grid with all windows the same size except the
-last column if there are not enough windows to fill the grid. Has no options::
+last column if there are not enough windows to fill the grid. This layout has no
+options::
 
     enabled_layouts grid
 
@@ -131,30 +134,47 @@ The Splits Layout
 
 This is the most flexible layout. You can create any arrangement of windows
 by splitting exiting windows repeatedly. To best use this layout you should
-define a few extra keybindings in :file:`kitty.conf`::
+define a few extra key bindings in :file:`kitty.conf`::
 
-    map F5 launch --location=hsplit
-    map F6 launch --location=vsplit
-    map F7 layout_action rotate
+    # Create a new window splitting the space used by the existing one so that
+    # the two windows are placed one above the other
+    map f5 launch --location=hsplit
 
+    # Create a new window splitting the space used by the existing one so that
+    # the two windows are placed side by side
+    map f6 launch --location=vsplit
+
+    # Create a new window splitting the space used by the existing one so that
+    # the two windows are placed side by side if the existing window is wide or
+    # one above the other if the existing window is tall.
+    map f4 launch --location=split
+
+    # Rotate the current split, chaging its split axis from vertical to
+    # horizontal or vice versa
+    map f7 layout_action rotate
+
+    # Move the active window in the indicated direction
     map shift+up move_window up
     map shift+left move_window left
     map shift+right move_window right
     map shift+down move_window down
 
+    # Switch focus to the neighboring window in the indicated direction
     map ctrl+left neighboring_window left
     map ctrl+right neighboring_window right
     map ctrl+up neighboring_window up
     map ctrl+down neighboring_window down
 
-Now you can create horizontal and vertical splits by using :kbd:`F5` and
-:kbd:`F6`. You can move them around using :kbd:`shift+arrow keys`
-and you can move focus to neighboring windows using :kbd:`ctrl+arrow keys`.
-You can switch an existing split from horizontal to vertical and vice versa
-using :kbd:`F7`. Finally, windows can be resized using :ref:`window_resizing`.
+Windows can be resized using :ref:`window_resizing`. You can swap the windows
+in a split using the ``rotate`` action with an argument of ``180`` and rotate
+and swap with an argument of ``270``.
 
 This layout takes one option, ``split_axis`` that controls whether new windows
-are placed into vertical or horizontal splits, by default::
+are placed into vertical or horizontal splits when a :option:`--location <launch
+--location>` is not specified. A value of ``horizontal`` (same as
+``--location=vsplit``) means when a new split is created the two windows will be
+placed side by side and a value of ``vertical`` (same as ``--location=hsplit``)
+means the two windows will be placed one on top of the other. By default::
 
     enabled_layouts splits:split_axis=horizontal
 
@@ -179,7 +199,7 @@ are placed into vertical or horizontal splits, by default::
 The Horizontal Layout
 ------------------------
 
-All windows are shown side by side. Has no options::
+All windows are shown side by side. This layout has no options::
 
     enabled_layouts horizontal
 
@@ -199,7 +219,7 @@ All windows are shown side by side. Has no options::
 The Vertical Layout
 -----------------------
 
-All windows are shown one below the other. Has no options::
+All windows are shown one below the other. This layout has no options::
 
     enabled_layouts vertical
 
@@ -225,37 +245,38 @@ Resizing windows
 
 You can resize windows inside layouts. Press :sc:`start_resizing_window` (also
 :kbd:`⌘+r` on macOS) 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
+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.
 
 You can also define shortcuts in :file:`kitty.conf` to make the active window
-wider, narrower, taller, or shorter by mapping to the ``resize_window``
+wider, narrower, taller, or shorter by mapping to the :ac:`resize_window`
 action, for example::
 
    map ctrl+left resize_window narrower
    map ctrl+right resize_window wider
    map ctrl+up resize_window taller
    map ctrl+down resize_window shorter 3
+   # reset all windows in the tab to default sizes
+   map ctrl+home resize_window reset
 
-The ``resize_window`` action has a second, optional argument to control
+The :ac:`resize_window` action has a second optional argument to control
 the resizing increment (a positive integer that defaults to 1).
 
-
-Some layouts take options to control their behavior. For example, the ``fat``
-and ``tall`` layouts accept the ``bias`` and ``full_size`` options to control
-how the available space is split up.
-To specify the option, in :opt:`kitty.conf <enabled_layouts>` use::
+Some layouts take options to control their behavior. For example, the *Fat*
+and *Tall* layouts accept the ``bias`` and ``full_size`` options 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;full_size=2
 
 This will have ``2`` instead of a single tall window, that occupy ``70%``
-instead of ``50%`` of available width. ``bias`` can be any number between 10
-and 90.
+instead of ``50%`` of available width. ``bias`` can be any number between ``10``
+and ``90``.
 
 Writing a new layout only requires about two hundred lines of code, so if there
 is some layout you want, take a look at one of the existing layouts in the
-`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`_
+`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`__
 package and submit a pull request!

docs/marks.rst

@@ -1,17 +1,20 @@
-Marks
-=================
+Mark text on screen
+---------------------
 
 
 kitty has the ability to mark text on the screen based on regular expressions.
 This can be useful to highlight words or phrases when browsing output from long
 running programs or similar. Lets start with a few examples:
 
-Suppose we want to be able to highlight the word ERROR in the current window.
-Add the following to :file:`kitty.conf`::
+Examples
+----------
+
+Suppose we want to be able to highlight the word :code:`ERROR` in the current
+window. Add the following to :file:`kitty.conf`::
 
     map f1 toggle_marker text 1 ERROR
 
-Now when you press :kbd:`F1` all instances of the word :code:`ERROR` will be
+Now when you press :kbd:`F1`, all instances of the word :code:`ERROR` will be
 highlighted. To turn off the highlighting, press :kbd:`F1` again.
 If you want to make it case-insensitive, use::
 
@@ -36,41 +39,40 @@ can control the colors used for these groups in :file:`kitty.conf` with::
 
 
 .. note::
-    For performance reasons, matching is done per line only, and only when that line is
-    altered in any way. So you cannot match text that stretches across multiple
-    lines.
+    For performance reasons, matching is done per line only, and only when that
+    line is altered in any way. So you cannot match text that stretches across
+    multiple lines.
 
 
 Creating markers dynamically
 ---------------------------------
 
 If you want to create markers dynamically rather than pre-defining them in
-:file:`kitty.conf` you can do so as follows::
+:file:`kitty.conf`, you can do so as follows::
 
     map f1 create_marker
     map f2 remove_marker
 
-Then pressing :kbd:`F1` will allow you to enter the marker definition and set
-it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
-the same syntax as ``toggle_marker`` above. Note that while creating
-markers, the prompt has history so you can easily re-use previous marker
-expressions.
+Then pressing :kbd:`F1` will allow you to enter the marker definition and set it
+and pressing :kbd:`F2` will remove the marker. :ac:`create_marker` accepts the
+same syntax as :ac:`toggle_marker` above. Note that while creating markers, the
+prompt has history so you can easily re-use previous marker expressions.
 
-You can also use the facilities for :doc:`remote-control` to dynamically
-add/remove markers.
+You can also use the facilities for :doc:`remote-control` to dynamically add or
+remove markers.
 
 
 Scrolling to marks
 --------------------
 
-kitty has an action to scroll to the next line that contains a mark. You can
-use it by mapping it to some shortcut in :file:`kitty.conf`::
+kitty has a :ac:`scroll_to_mark` action to scroll to the next line that contains
+a mark. You can use it by mapping it to some shortcut in :file:`kitty.conf`::
 
     map ctrl+p scroll_to_mark prev
     map ctrl+n scroll_to_mark next
 
-Then pressing :kbd:`ctrl+p` will scroll to the first line in the scrollback
-buffer above the current top line that contains a mark. Pressing :kbd:`ctrl+n`
+Then pressing :kbd:`Ctrl+P` will scroll to the first line in the scrollback
+buffer above the current top line that contains a mark. Pressing :kbd:`Ctrl+N`
 will scroll to show the first line below the current last line that contains
 a mark. If you wish to jump to a mark of a specific type, you can add that to
 the mapping::
@@ -83,27 +85,26 @@ Which will scroll only to marks of type 1.
 The full syntax for creating marks
 -------------------------------------
 
-The syntax of the :code:`toggle_marker` command is::
+The syntax of the :ac:`toggle_marker` action is::
 
     toggle_marker <marker-type> <specification>
 
 Here :code:`marker-type` is one of:
 
-    * :code:`text` - simple substring matching
-    * :code:`itext` - case-insensitive substring matching
-    * :code:`regex` - A python regular expression
-    * :code:`iregex` - A case-insensitive python regular expression
-    * :code:`function` - An arbitrary function defined in a python file, see
-      :ref:`marker_funcs`.
+* :code:`text` - Simple substring matching
+* :code:`itext` - Case-insensitive substring matching
+* :code:`regex` - A Python regular expression
+* :code:`iregex` - A case-insensitive Python regular expression
+* :code:`function` - An arbitrary function defined in a Python file, see :ref:`marker_funcs`.
 
 .. _marker_funcs:
 
 Arbitrary marker functions
 -----------------------------
 
-You can create your own marker functions. Create a python file named
-:file:`mymarker.py` and in it create a :code:`marker` function. This
-function receives the text of the line as input and must yield three numbers,
+You can create your own marker functions. Create a Python file named
+:file:`mymarker.py` and in it create a :code:`marker` function. This function
+receives the text of the line as input and must yield three numbers,
 the starting character position, the ending character position and the mark
 group (1-3). For example:
 
@@ -120,6 +121,7 @@ Save this file somewhere and in :file:`kitty.conf`, use::
 
     map f1 toggle_marker function /path/to/mymarker.py
 
-If you save the file in the kitty config directory, you can use::
+If you save the file in the :ref:`kitty config directory <confloc>`, you can
+use::
 
     map f1 toggle_marker function mymarker.py

docs/open_actions.rst

@@ -1,14 +1,14 @@
-Customizing the actions taken when clicking on links
+Scripting the mouse click
 ======================================================
 
-|kitty| has support for `terminal hyperlinks <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
-are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
-``mdcat``, etc. You can customize exactly what happens when clicking on these hyperlinks
-in |kitty|.
+|kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
+generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
+:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on
+these hyperlinks in |kitty|.
 
-You can tell kitty to take arbitrarily many, complex actions
-when a link is clicked. Let us illustrate with some examples, first. Create
-the file :file:`~/.config/kitty/open-actions.conf` with the following:
+You can tell kitty to take arbitrarily many, complex actions when a link is
+clicked. Let us illustrate with some examples, first. Create the file
+:file:`~/.config/kitty/open-actions.conf` with the following:
 
 .. code:: conf
 
@@ -21,6 +21,13 @@ Now, run ``ls --hyperlink=auto`` in kitty and click on the filename of an
 image, holding down :kbd:`ctrl+shift`. It will be opened over the current
 window. Press any key to close it.
 
+.. note::
+
+    The :program:`ls` comes with macOS does not support hyperlink, you need to
+    install `GNU Coreutils <https://www.gnu.org/software/coreutils/>`__. If you
+    install it via `Homebrew <https://formulae.brew.sh/formula/coreutils>`__, it
+    will be :program:`gls`.
+
 Each entry in :file:`open-actions.conf` consists of one or more
 :ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
 ``action`` entries. In the example above kitty uses the :doc:`launch <launch>`
@@ -28,8 +35,8 @@ action which can be used to run external programs. Entries are separated by
 blank lines.
 
 Actions are very powerful, anything that you can map to a key combination in
-`kitty.conf` can be used as an action. You can specify more than one action per
-entry if you like, for example:
+:file:`kitty.conf` can be used as an action. You can specify more than one
+action per entry if you like, for example:
 
 
 .. code:: conf
@@ -57,6 +64,12 @@ some special variables, documented below:
 ``FRAGMENT``
     The fragment (unquoted), if any of the URL or the empty string.
 
+
+.. note::
+   You can use the :opt:`action_alias` option just as in :file:`kitty.conf` to
+   define aliases for frequently used actions.
+
+
 .. _matching_criteria:
 
 Matching criteria
@@ -70,7 +83,7 @@ lines. The various available criteria are:
 
 ``protocol``
     A comma separated list of protocols, for example: ``http, https``. If
-    absent, there is no constraint on protocol
+    absent, there is no constraint on protocol.
 
 ``url``
     A regular expression that must match against the entire (unquoted) URL
@@ -81,11 +94,12 @@ lines. The various available criteria are:
 
 ``mime``
     A comma separated list of MIME types, for example: ``text/*, image/*,
-    application/pdf``. You can add MIME types to kitty by creating the
-    :file:`mime.types` in the kitty configuration directory. Useful if your
-    system MIME database does not have definitions you need. This file is
-    in the standard format of one definition per line, like: ``text/plain rst
-    md``.
+    application/pdf``. You can add MIME types to kitty by creating a file named
+    :file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
+    Useful if your system MIME database does not have definitions you need. This
+    file is in the standard format of one definition per line, like:
+    ``text/plain rst md``. Note that the MIME type for directories is
+    ``inode/directory``.
 
 ``ext``
     A comma separated list of file extensions, for example: ``jpeg, tar.gz``
@@ -93,3 +107,70 @@ lines. The various available criteria are:
 ``file``
     A shell glob pattern that must match the filename, for example:
     ``image-??.png``
+
+
+.. _launch_actions:
+
+Scripting the opening of files with kitty on macOS
+-------------------------------------------------------
+
+On macOS you can use :guilabel:`Open With` in Finder or drag and drop files and
+URLs onto the kitty dock icon to open them with kitty. The default actions are:
+
+* Open text files in your editor and images using the icat kitten.
+* Run shell scripts in a shell
+* Open SSH urls using the ssh command
+
+These actions can also be executed from the command line by running::
+
+    kitty +open file_or_url another_url ...
+
+    # macOS only
+    open -a kitty.app file_or_url another_url ...
+
+Since macOS lacks an official interface to set default URL scheme handlers,
+kitty has a command you can use for it. The first argument for is the URL
+scheme, and the second optional argument is the bundle id of the app, which
+defaults to kitty, if not specified. For example:
+
+.. code-block:: sh
+
+    # Set kitty as the handler for ssh:// URLs
+    kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' ssh
+    # Set someapp as the handler for xyz:// URLs
+    kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier
+
+You can customize these actions by creating a :file:`launch-actions.conf` file
+in the :ref:`kitty config directory <confloc>`, just like the
+:file:`open-actions.conf` file above. For example:
+
+.. code:: conf
+
+    # Open script files based on their shebangs
+    protocol file
+    ext sh,command,tool
+    action launch --hold --type=os-window kitty +shebang $FILE_PATH {SHELL}
+
+    # Open shell specific script files
+    protocol file
+    ext fish,bash,zsh
+    action launch --hold --type=os-window kitty +shebang $FILE_PATH __ext__
+
+    # Open directories
+    protocol file
+    mime inode/directory
+    action launch --type=os-window --cwd $FILE_PATH
+
+    # Open text files without fragments in the editor
+    protocol file
+    mime text/*
+    action launch --type=os-window $EDITOR $FILE_PATH
+
+    # Open image files with icat
+    protocol file
+    mime image/*
+    action launch --type=os-window kitty +kitten icat --hold $FILE_PATH
+
+    # Open ssh URLs with ssh command
+    protocol ssh
+    action launch --type=os-window ssh $URL

docs/overview.rst

@@ -0,0 +1,305 @@
+Overview
+==============
+
+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 little effort.
+
+.. include:: basic.rst
+
+
+Configuring kitty
+-------------------
+
+|kitty| is highly configurable, everything from keyboard shortcuts to painting
+frames-per-second. Press :sc:`edit_config_file` in kitty to open its fully
+commented sample config file in your text editor. For details see the
+:doc:`configuration docs <conf>`.
+
+.. toctree::
+   :hidden:
+
+   conf
+
+
+.. _layouts:
+
+Layouts
+----------
+
+A :term:`layout` is an arrangement of multiple :term:`kitty windows <window>`
+inside a top-level :term:`OS window <os_window>`. The layout manages all its
+windows automatically, resizing and moving them as needed. You can create a new
+:term:`window` using the :sc:`new_window` key combination.
+
+Currently, there are seven layouts available:
+
+* **Fat** -- One (or optionally more) windows are 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
+
+* **Splits** -- Windows arranged in arbitrary patterns created using horizontal
+  and vertical splits
+
+* **Stack** -- Only a single maximized window is shown at a time
+
+* **Tall** -- One (or optionally more) windows are shown full height on the
+  left, the rest of the windows are shown one below the other on the right
+
+* **Vertical** -- All windows are shown one below the other
+
+By default, all layouts are enabled and 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, see
+:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in
+:opt:`enabled_layouts` becomes the default layout.
+
+For more details on the layouts and how to use them see :doc:`the documentation
+<layouts>`.
+
+.. toctree::
+   :hidden:
+
+   layouts
+
+Extending kitty
+------------------
+
+kitty has a powerful framework for scripting. You can create small terminal
+programs called :doc:`kittens <kittens_intro>`. These can used to add features
+to kitty, for example, :doc:`editing remote files <kittens/remote_file>` or
+:doc:`inputting Unicode characters <kittens/unicode_input>`. They can also be
+used to create programs that leverage kitty's powerful features, for example,
+:doc:`viewing images <kittens/icat>` or :doc:`diffing files with image support
+<kittens/diff>`.
+
+You can :doc:`create your own kittens to scratch your own itches
+<kittens/custom>`.
+
+For a list of all the builtin kittens, :ref:`see here <kittens>`.
+
+.. toctree::
+   :hidden:
+
+   kittens_intro
+
+
+Remote control
+------------------
+
+|kitty| has a very powerful system that allows you to control it from the
+:doc:`shell prompt, even over SSH <remote-control>`. You can change colors,
+fonts, open new :term:`windows <window>`, :term:`tabs <tab>`, set their titles,
+change window layout, get text from one window and send text to another, etc.
+The possibilities are endless. See the :doc:`tutorial <remote-control>` to get
+started.
+
+.. toctree::
+   :hidden:
+
+   remote-control
+
+
+.. _sessions:
+
+Startup Sessions
+------------------
+
+You can control the :term:`tabs <tab>`, :term:`kitty window <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 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
+    launch --title "Chat with x" irssi --profile x
+
+    # Create a new tab
+    # The part after new_tab is the optional tab title 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
+
+    # Create a new OS window
+    # Any definitions specifed before the first new_os_window will apply to first OS window.
+    new_os_window
+    # Set new window size to 80x24 cells
+    os_window_size 80c 24c
+    # Set the --class for the new OS window
+    os_window_class mywindow
+    launch sh
+    # Make the current window the active (focused) window
+    focus
+    launch emacs
+
+.. note::
+    The :doc:`launch <launch>` command when used in a session file cannot create
+    new OS windows, or tabs.
+
+
+Creating tabs/windows
+-------------------------------
+
+kitty can be told to run arbitrary programs in new :term:`tabs <tab>`,
+:term:`windows <window>` or :term:`overlays <overlay>` at a keypress.
+To learn how to do this, see :doc:`here <launch>`.
+
+.. toctree::
+   :hidden:
+
+   launch
+
+
+Mouse features
+-------------------
+
+* You can click on a URL to open it in a browser.
+* You can double click to select a word and then drag to select more words.
+* You can triple click to select a line and then drag to select more lines.
+* You can triple click while holding :kbd:`Ctrl+Alt` to select from clicked
+  point to end of line.
+* You can right click to extend a previous selection.
+* You can hold down :kbd:`Ctrl+Alt` and drag with the mouse to select in
+  columns.
+* Selecting text automatically copies it to the primary clipboard (on platforms
+  with a primary clipboard).
+* You can middle click to paste from the primary clipboard (on platforms with a
+  primary clipboard).
+* You can right click while holding :kbd:`Ctrl+Shift` to open the output of the
+  clicked on command in a pager (requires :ref:`shell_integration`)
+* You can select text with kitty even when a terminal program has grabbed the
+  mouse by holding down the :kbd:`Shift` key
+
+All these actions can be customized in :file:`kitty.conf` as described
+:ref:`here <conf-kitty-mouse.mousemap>`.
+
+You can also customize what happens when clicking on :term:`hyperlinks` in
+kitty, having it open files in your editor, download remote files, open things
+in your browser, etc.
+
+For details, see :doc:`here <open_actions>`.
+
+.. toctree::
+   :hidden:
+
+   open_actions
+
+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 comein 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` shortcut, which will open the scrollback buffer in
+your favorite pager program (which is :program:`less` by default). Colors and
+text formatting are preserved. You can explore the scrollback buffer comfortably
+within the pager.
+
+Additionally, you can pipe the contents of the scrollback buffer to an
+arbitrary, command running in a new :term:`window`, :term:`tab` or
+:term:`overlay`. For example::
+
+   map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
+
+Would open the scrollback buffer in a new :term:`window` when you press the
+:kbd:`F1` key. See :sc:`show_scrollback <show_scrollback>` for details.
+
+If you want to use it with an editor such as :program:`vim` to get more powerful
+features, you can see tips for doing so, in :iss:`this thread <719>`.
+
+If you wish to store very large amounts of scrollback to view using the piping
+or :sc:`show_scrollback <show_scrollback>` features, you can use the
+:opt:`scrollback_pager_history_size` option.
+
+
+Integration with shells
+---------------------------------
+
+kitty has the ability to integrate closely within common shells, such as `zsh
+<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
+<https://www.gnu.org/software/bash/>`__ to enable features such as jumping to
+previous prompts in the scrollback, viewing the output of the last command in
+:program:`less`, using the mouse to move the cursor while editing prompts, etc.
+See :doc:`shell-integration` for details.
+
+.. toctree::
+   :hidden:
+
+   shell-integration
+
+.. _cpbuf:
+
+Multiple copy/paste buffers
+-----------------------------
+
+In addition to being able to copy/paste from the system clipboard, in |kitty|
+you can also setup an arbitrary number of copy paste buffers. To do so, simply
+add something like the following to your :file:`kitty.conf`::
+
+   map f1 copy_to_buffer a
+   map f2 paste_from_buffer a
+
+This will allow you to press :kbd:`F1` to copy the current selection to an
+internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
+names are arbitrary strings, so you can define as many such buffers as you need.
+
+
+Marks
+-------------
+
+kitty has the ability to mark text on the screen based on regular expressions.
+This can be useful to highlight words or phrases when browsing output from long
+running programs or similar. To learn how this feature works, see :doc:`marks`.
+
+.. toctree::
+   :hidden:
+
+   marks

docs/performance.rst

@@ -1,31 +1,32 @@
-|kitty| Performance
+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
+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. :opt:`repaint_delay`
-and :opt:`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 :opt:`sync_to_monitor` option to further decrease latency at the cost
-of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
+There are two config options you can tune to adjust the performance,
+:opt:`repaint_delay` and :opt:`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 :opt:`sync_to_monitor`
+option to further decrease latency at the cost of some `screen 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`. Run kitty 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.
+You can generate detailed per-function performance data using
+`gperftools <https://github.com/gperftools/gperftools>`__. Build |kitty| with
+``make profile``. Run kitty and perform the task you want to analyse, for
+example, scrolling a large file with :program:`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
+Here are some CPU usage numbers for the task of scrolling a file continuously in
+:program:`less`. The CPU usage is for the terminal process and X together and is
+measured using :program:`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.
 
 ==============   =========================
@@ -49,11 +50,11 @@ admittedly biased, eyes).
 
 .. 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.
+    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/pipe.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Working with the screen and history buffer contents
 ======================================================
 

docs/press-mentions.rst

@@ -0,0 +1,18 @@
+Press mentions of kitty
+========================
+
+`Python Bytes 272 <https://youtu.be/8HKliSbA-gQ?t=815>`__ (Feb 2022)
+    A podcast demoing some of kitty's coolness
+
+`Console #88 <https://console.substack.com/p/console-88>`__ (Jan 2022)
+    An interview with Kovid about kitty
+
+
+Video reviews
+--------------
+
+`Review (Jan 2021) <https://www.youtube.com/watch?v=TTzP2zYJn2k>`__
+    A kitty review by distrotube
+
+`Review (Dec 2020) <https://www.youtube.com/watch?v=KUMkLhFeBrI>`__
+    A kitty review/intro by TechHut

docs/protocol-extensions.rst

@@ -1,319 +1,34 @@
-Extensions to the xterm protocol
+Terminal protocol extensions
 ===================================
 
-|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.
+|kitty| has extensions to the legacy terminal 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 and 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
+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
-<https://github.com/kovidgoyal/kitty/issues>`_ bug tracker.
-
-.. contents::
-   :local:
-
-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
-
-The underline color must remain the same under reverse video, if it has a
-color, if not, it should follow the foreground color.
-
-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
--------------------
-
-kitty has a :doc:`keyboard protocol <keyboard-protocol>` for reporting key
-presses to terminal applications that solves all key handling issues in
-terminal applications.
-
-.. _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 <https://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 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 and the
-ANSI color table. 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 colors, default
-background, default foreground, selection background, selection foreground and
-cursor color and the 256 colors of the ANSI color table.
-
-.. note:: In July 2020, after several years, XTerm copied this protocol
-   extension, without acknowledgement, and using incompatible escape codes
-   (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not
-   just the dynamic colors but the entire ANSI color table. In the interests of
-   promoting interoperability, kitty added support for XTerm's escape codes as
-   well, and changed this extension to also save/restore the entire ANSI color
-   table.
-
-
-Pasting to clipboard
-----------------------
-
-|kitty| implements the OSC 52 escape code protocol to get/set the clipboard
-contents (controlled via the :opt:`clipboard_control` setting). There is one
-difference in kitty's implementation compared to some other terminal emulators.
-|kitty| allows sending arbitrary amounts of text to the clipboard. It does so
-by modifying the protocol slightly. Successive OSC 52 escape codes to set the
-clipboard will concatenate, so::
-
-    <ESC>]52;c;<payload1><ESC>\
-    <ESC>]52;c;<payload2><ESC>\
-
-will result in the clipboard having the contents ``payload1 + payload2``. To
-send a new string to the clipboard send an OSC 52 sequence with an invalid payload
-first, for example::
-
-    <ESC>]52;c;!<ESC>\
-
-Here ``!`` is not valid base64 encoded text, so it clears the clipboard.
-Further, since it is invalid, it should be ignored by terminal emulators
-that do not support this extension, thereby making it safe to use, simply
-always send it before starting a new OSC 52 paste, even if you aren't chunking
-up large pastes, that way kitty won't concatenate your paste, and it will have
-no ill-effects in other terminal emulators.
-
-In case you're using software that can't be easily adapted to this
-protocol extension, it can be disabled by specifying ``no-append`` to the
-:opt:`clipboard_control` setting.
-
-
-.. _unscroll:
-
-Unscrolling the screen
------------------------
-
-This is a small extension to the `SD (Pan up) escape code
-<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The
-``SD`` escape code normally causes the text on screen to scroll down by the
-specified number of lines, with empty lines appearing at the top of the screen.
-This extension allows the new lines to be filled in from the scrollback buffer
-instead of being blank.
-
-The motivation for this is that many modern shells will show completions in a
-block of lines under the cursor, this causes some of the on-screen text to be
-lost even after the completion is completed, because it has scrolled off
-screen. This escape code allows that text to be restored.
-
-If the scrollback buffer is empty or there is no scrollback buffer, such as for
-the alternate screen, then the newly inserted lines must be empty, just as with
-the original ``SD`` escape code. The maximum number of lines that can be
-scrolled down is implementation defined, but must be at least one screen worth.
-
-The syntax of the escape code is identical to that of ``SD`` except that it has
-a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
-<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`_
-and unused for any other purpose as far as I can tell. So for example, to
-unscroll three lines, the escape code would be::
-
-    CSI 3 + T
-
-See `discussion here
-<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`_.
-
-.. versionadded:: 0.20.2
-
-
-.. _desktop_notifications:
-
-
-Desktop notifications
----------------------------------
-
-|kitty| implements an extensible escape code (OSC 99) to show desktop
-notifications. It is easy to use from shell scripts and fully extensible to
-show title and body.  Clicking on the notification can optionally focus the
-window it came from, and/or send an escape code back to the application running
-in that window.
-
-The design of the escape code is partially based on the discussion in
-the defunct
-`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_
-
-The escape code has the form::
-
-    <OSC> 99 ; metadata ; payload <terminator>
-
-Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is
-:code:`<ESC><backslash>`.  The metadata is a section of colon separated
-:code:`key=value` pairs. Every key must be a single character from the set
-:code:`a-zA-Z` and every value must be a word consisting of characters from
-the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
-interpreted based on the metadata section. The two semi-colons *must* always be
-present even when no metadata is present.
-
-Before going into details, lets see how one can display a simple, single line
-notification from a shell script::
-
-    printf '\x1b]99;;Hello world\x1b\\'
-
-To show a message with a title and a body::
-
-    printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
-    printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\'
-
-The most important key in the metadata is the ``p`` key, it controls how the
-payload is interpreted. A value of ``title`` means the payload is setting the
-title for the notification. A value of ``body`` means it is setting the body,
-and so on, see the table below for full details.
-
-The design of the escape code is fundamentally chunked, this is because
-different terminal emulators have different limits on how large a single escape
-code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
-key is the *notification id* which can be any string containing the characters
-``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
-can only take the values ``0`` and ``1``. A value of ``0`` means the
-notification is not yet done and the terminal emulator should hold off
-displaying it. A value of ``1`` means the notification is done, and should be
-displayed. You can specify the title or body multiple times and the terminal
-emulator will concatenate them, thereby allowing arbitrarily long text
-(terminal emulators are free to impose a sensible limit to avoid
-Denial-of-Service attacks).
-
-Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
-text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
-which case there must be an ``e=1`` key in the metadata to indicate the payload
-is base64 encoded.
-
-When the user clicks the notification, a couple of things can happen, the
-terminal emulator can focus the window from which the notification came, and/or
-it can send back an escape code to the application indicating the notification
-was activated. This is controlled by the ``a`` key which takes a comma
-separated set of values, ``report`` and ``focus``. The value ``focus`` means
-focus the window from which the notification was issued and is the default.
-``report`` means send an escape code back to the application. The format of the
-returned escape code is::
-
-    <OSC> 99 ; i=identifier ; <terminator>
-
-The value of ``identifier`` comes from the ``i`` key in the escape code sent by
-the application. If the application sends no identifier, then the terminal
-*must* use ``i=0``. Actions can be preceded by a negative sign to turn them
-off, so for example if you do not want any action, turn off the default
-``focus`` action with::
-
-    a=-focus
-
-Complete specification of all the metadata keys is in the table below. If a
-terminal emulator encounters a key in the metadata it does not understand,
-the key *must* be ignored, to allow for future extensibility of this escape
-code. Similarly if values for known keys are unknown, the terminal emulator
-*should* either ignore the entire escape code or perform a best guess effort
-to display it based on what it does understand.
-
-.. note::
-   It is possible to extend this escape code to allow specifying an icon for
-   the notification, however, given that some platforms, such as macOS, dont
-   allow displaying custom icons on a notification, at all, it was decided to
-   leave it out of the spec for the time being.
-
-   Similarly, features such as scheduled notifications could be added in future
-   revisions.
-
-
-=======  ====================  =========  =================
-Key      Value                 Default    Description
-=======  ====================  =========  =================
-``a``    Comma separated list  ``focus``  What action to perform when the
-         of ``report``,                   notification is clicked
-         ``focus``, with
-         optional leading
-         ``-``
-
-``d``    ``0`` or ``1``        ``1``      Indicates if the notification is
-                                          complete or not.
-
-``e``    ``0`` or ``1``        ``0``      If set to ``1`` means the payload is base64 encoded UTF-8,
-                                          otherwise it is plain UTF-8 text with no C0 control codes in it
-
-``i``    ``[a-zA-Z0-9-_+.]``   ``0``      Identifier for the notification
-
-``p``    One of ``title`` or   ``title``  Whether the payload is the notification title or body. If a
-         ``body``.                        notification has no title, the body will be used as title.
-=======  ====================  =========  =================
-
-
-.. note::
-   |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
-   desktop notifications.
+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 or changes to them,
+please do so by opening issues in the `GitHub bug tracker
+<https://github.com/kovidgoyal/kitty/issues>`__.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   underlines
+   graphics-protocol
+   keyboard-protocol
+   file-transfer-protocol
+   desktop-notifications
+   unscroll
+   color-stack
+   deccara

docs/quickstart.rst

@@ -0,0 +1,28 @@
+.. _quickstart:
+
+Quickstart
+===========
+
+.. toctree::
+   :hidden:
+
+   binary
+   build
+
+Pre-built binaries of |kitty| are available for both macOS and Linux. See the
+:doc:`binary install instructions </binary>`. You can also :doc:`build from
+source </build>`.
+
+Additionally, you can use your favorite package manager to install the |kitty|
+package, but note that some Linux distribution packages are woefully outdated.
+|kitty| is available in a vast number of package repositories for macOS
+and Linux.
+
+.. image:: https://repology.org/badge/tiny-repos/kitty.svg
+   :target: https://repology.org/project/kitty/versions
+   :alt: Number of repositories kitty is available in
+
+See :doc:`Configuring kitty <conf>` for help on configuring |kitty| and
+:doc:`Invocation <invocation>` for the command line arguments |kitty| supports.
+
+For a tour of kitty's design and features, see the :doc:`overview`.

docs/rc_protocol.rst

@@ -1,5 +1,5 @@
-Documentation for the kitty remote control protocol
-======================================================
+The kitty remote control protocol
+==================================
 
 The kitty remote control protocol is a simple protocol that involves sending
 data to kitty in the form of JSON. Any individual command of kitty has the
@@ -16,26 +16,26 @@ Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form::
         "payload": <Optional JSON object>,
     }
 
-The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are developing a
-standalone client, use the kitty version that you are developing against. Using
-a version greater than the version of the kitty instance you are talking to,
-will cause a failure.
+The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are
+developing a standalone client, use the kitty version that you are developing
+against. Using a version greater than the version of the kitty instance you are
+talking to, will cause a failure.
 
 Set ``no_response`` to ``true`` if you don't want a response from kitty.
 
-The optional payload is a JSON object that is specific to the actual command being sent.
-The fields in the object for every command are documented below.
+The optional payload is a JSON object that is specific to the actual command
+being sent. The fields in the object for every command are documented below.
 
 As a quick example showing how easy to use this protocol is, we will implement
-the ``@ ls`` command from the shell using only shell tools. First, run kitty
-as::
+the ``@ ls`` command from the shell using only shell tools.
+
+First, run kitty as::
 
     kitty -o allow_remote_control=socket-only --listen-on unix:/tmp/test
 
 Now, in a different terminal, you can get the pretty printed ``@ ls`` output
 with the following command line::
 
-    echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
-
+    echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
 
 .. include:: generated/rc.rst

docs/remote-control.rst

@@ -1,17 +1,18 @@
-:tocdepth: 2
-
-Controlling kitty from scripts or the shell
-==============================================
+Control kitty from scripts
+----------------------------
 
 .. 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.
+windows, send arbitrary text input to any window, change the title of windows
+and tabs, etc.
+
 Let's walk through a few examples of controlling |kitty|.
 
+
+Tutorial
+------------
+
 Start by running |kitty| as::
 
     kitty -o allow_remote_control=yes -o enabled_layouts=tall
@@ -23,43 +24,44 @@ Now, in the new |kitty| window, enter the command::
 
     kitty @ launch --title Output --keep-focus cat
 
-This will open a new window, running the ``cat`` program that will appear next
-to the current window.
+This will open a new window, running the :program:`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.
+This will make ``Hello, World`` show up in the window running the :program:`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 :ref:`kitty @ send-text --help <at_send-text>` 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
+    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.
+This will show the output of :program:`ls` in the output window instead of the
+current window. You can use this technique to, for example, show the output of
+running :program:`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
+    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.
+window. Type :kbd:`Ctrl+D` when you are ready to stop.
 
 Now, let's open a new tab::
 
    kitty @ launch --type=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::
+We can change the title of the tab to "New Title" with::
 
-   kitty @ set-tab-title --match title:My  New Title
+   kitty @ set-tab-title --match title:^My New Title
 
 Let's change the title of the current tab::
 
@@ -67,96 +69,102 @@ Let's change the title of the current tab::
 
 Now lets switch to the newly opened tab::
 
-   kitty @ focus-tab --match title:New
+   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
+   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.
+:term:`OS windows <os_window>`. Each OS window has an id and a list of
+:term:`tabs <tab>`. Each tab has its own id, a title and a list of :term:`kitty
+windows <window>`. 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.
+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::
+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::
+The :option:`kitty --listen-on` option tells |kitty| to listen for control
+messages at the specified UNIX-domain socket. 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 if 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.
+Note that if 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 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).
 
 .. note:: This has the added advantage that you don't need to use
-   ``allow_remote_control`` to make it work.
+   :opt:`allow_remote_control` to make it work.
 
 
 Allowing only some windows to control kitty
 ----------------------------------------------
 
-If you do not want to allow all programs running in |kitty| to control it, you can selectively
-enable remote control for only some |kitty| windows. Simply create a shortcut
-such as::
+If you do not want to allow all programs running in |kitty| to control it, you
+can selectively enable remote control for only some |kitty| windows. Simply
+create a shortcut such as::
 
     map ctrl+k launch --allow-remote-control some_program
 
 Then programs running in windows created with that shortcut can use ``kitty @``
 to control kitty. Note that any program with the right level of permissions can
-still write to the pipes of any other program on the same computer and
-therefore can control |kitty|. It can, however, be useful to block programs
-running on other computers (for example, over ssh) or as other users.
+still write to the pipes of any other program on the same computer and therefore
+can control |kitty|. It can, however, be useful to block programs running on
+other computers (for example, over SSH) or as other users.
 
-.. note:: You dont need ``allow_remote_control`` to make this work as it is
+.. note:: You don't need :opt:`allow_remote_control` to make this work as it is
    limited to only programs running in that specific window. Be careful with
    what programs you run in such windows, since they can effectively control
-   kitty, as if you were running with ``allow_remote_control`` turned on.
+   kitty, as if you were running with :opt:`allow_remote_control` turned on.
 
 
+.. _rc_mapping:
+
 Mapping key presses to remote control commands
 --------------------------------------------------
 
 If you wish to trigger a remote control command easily with just a keypress,
 you can map it in :file:`kitty.conf`. For example::
 
-    map F1 remote_control set-spacing margin=30
+    map f1 remote_control set-spacing margin=30
 
-Then pressing the :kbd:`F1` key will set the active window margins to 30.
-The syntax for what follows :code:`remote_control` is exactly the same
+Then pressing the :kbd:`F1` key will set the active window margins to
+:code:`30`. The syntax for what follows :ac:`remote_control` is exactly the same
 as the syntax for what follows :code:`kitty @` above.
 
-.. note:: You do not need ``allow_remote_control`` to use these mappings,
-   as they are not actual remote programs, but are simply a way to resuse
-   the remote control infrastructure via keybings.
+.. note:: You do not need :opt:`allow_remote_control` to use these mappings,
+   as they are not actual remote programs, but are simply a way to resuse the
+   remote control infrastructure via keybings.
 
 
 Broadcasting what you type to all kitty windows
@@ -166,16 +174,40 @@ As a simple illustration of the power of remote control, lets
 have what we type sent to all open kitty windows. To do that define the
 following mapping in :file:`kitty.conf`::
 
-    map F1 launch --allow-remote-control kitty +kitten broadcast
+    map f1 launch --allow-remote-control kitty +kitten broadcast
 
-Now press, F1 and start typing, what you type will be sent to all windows,
+Now press :kbd:`F1` and start typing, what you type will be sent to all windows,
 live, as you type it.
 
 
-Documentation for the remote control protocol
+The remote control protocol
 -----------------------------------------------
 
-If you wish to develop your own client to talk to |kitty|, you
-can use the :doc:`rc_protocol`.
+If you wish to develop your own client to talk to |kitty|, you can use the
+:doc:`remote control protocol specification <rc_protocol>`.
+
+
+.. _search_syntax:
+
+Matching windows and tabs
+----------------------------
+
+Many remote control operations operate on windows or tabs. To select these, the
+:code:`--match` option is often used. This allows matching using various
+sophisticated criteria such as title, ids, cmdlines, etc. These criteria are
+expressions of the form :code:`field:query`. Where :italic:`field` is the field
+against which to match and :italic:`query` is the expression to match. They can
+be further combined using Boolean operators, best illustrated with some
+examples::
+
+    title:"My special window" or id:43
+    title:bash and env:USER=kovid
+    not id:1
+    (id:2 or id:3) and title:something
+
+.. toctree::
+   :hidden:
+
+   rc_protocol
 
 .. include:: generated/cli-kitty-at.rst

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx
+furo
+sphinx-copybutton
+sphinxext-opengraph
+sphinx-inline-tabs

docs/shell-integration.rst

@@ -0,0 +1,356 @@
+.. _shell_integration:
+
+Shell integration
+-------------------
+
+kitty has the ability to integrate closely within common shells, such as `zsh
+<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
+<https://www.gnu.org/software/bash/>`__ to enable features such as jumping to
+previous prompts in the scrollback, viewing the output of the last command in
+:program:`less`, using the mouse to move the cursor while editing prompts, etc.
+
+.. versionadded:: 0.24.0
+
+Features
+-------------
+
+* Open the output of the last command in a pager such as :program:`less`
+  (:sc:`show_last_command_output`)
+
+* Jump to the previous/next prompt in the scrollback
+  (:sc:`scroll_to_previous_prompt` /  :sc:`scroll_to_next_prompt`)
+
+* Click with the mouse anywhere in the current command to move the cursor there
+
+* Hold :kbd:`Ctrl+Shift` and right-click on any command output in the scrollback
+  to view it in a pager
+
+* The current working directory or the command being executed are automatically
+  displayed in the kitty window titlebar/tab title
+
+* The text cursor is changed to a bar when editing commands at the shell prompt
+
+* :ref:`clone_shell` with all environment variables and the working directory
+  copied
+
+* Glitch free window resizing even with complex prompts. Achieved by erasing
+  the prompt on resize and allowing the shell to redraw it cleanly.
+
+* Sophisticated completion for the :program:`kitty` command in the shell.
+
+* When confirming a quit command if a window is sitting at a shell prompt,
+  it is optionally, not counted (see :opt:`confirm_os_window_close`)
+
+
+Configuration
+---------------
+
+Shell integration is controlled by the :opt:`shell_integration` option. By
+default, all integration features are enabled. Individual features can be turned
+off or it can be disabled entirely as well. The :opt:`shell_integration` option
+takes a space separated list of keywords:
+
+disabled
+    Turn off all shell integration. The shell's launch environment is not
+    modified and :envvar:`KITTY_SHELL_INTEGRATION` is not set. Useful for
+    :ref:`manual integration <manual_shell_integration>`.
+
+no-rc
+    Do not modify the shell's launch environment to enable integration. Useful
+    if you prefer to load the kitty shell integration code yourself, either as
+    part of :ref:`manually integration <manual_shell_integration>` or because
+    you have some other software that sets up shell integration.
+    This will still set the :envvar:`KITTY_SHELL_INTEGRATION` environment
+    variable when kitty runs the shell.
+
+no-cursor
+    Turn off changing of the text cursor to a bar when editing shell command
+    line.
+
+no-title
+    Turn off setting the kitty window/tab title based on shell state.
+    Note that for the fish shell kitty relies on fish's native title setting
+    functionality instead.
+
+no-cwd
+    Turn off reporting the current working directory. This is used to allow
+    :ac:`new_window_with_cwd` and similar to open windows logged into remote
+    machines using the :doc:`ssh kitten <kittens/ssh>` automatically with the
+    same working directory as the current window.
+    Note that for the fish shell this will not disable its built-in current
+    working directory reporting.
+
+no-prompt-mark
+    Turn off marking of prompts. This disables jumping to prompt, browsing
+    output of last command and click to move cursor functionality.
+
+no-complete
+    Turn off completion for the kitty command.
+    Note that for the fish shell this does not take effect, since fish already
+    comes with a kitty completion script.
+
+
+More ways to browse command output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can add further key and mouse bindings to browse the output of commands
+easily. For example to select the output of a command by right clicking the
+mouse on the output, define the following in :file:`kitty.conf`:
+
+.. code:: conf
+
+    mouse_map right press ungrabbed mouse_select_command_output
+
+Now, when you right click on the output, the entire output is selected, ready
+to be copied.
+
+The feature to jump to previous prompts (
+:sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse
+actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`)
+can be integrated with browsing command output as well. For example, define the
+following mapping in :file:`kitty.conf`:
+
+.. code:: conf
+
+    map f1 show_last_visited_command_output
+
+Now, pressing :kbd:`F1` will cause the output of the last jumped to command or
+the last mouse clicked command output to be opened in a pager for easy browsing.
+
+In addition, You can define shortcut to get the first command output on screen.
+For example, define the following in :file:`kitty.conf`:
+
+.. code:: conf
+
+    map f1 show_first_command_output_on_screen
+
+Now, pressing :kbd:`F1` will cause the output of the first command output on
+screen to be opened in a pager.
+
+You can also add shortcut to scroll to the last jumped position. For example,
+define the following in :file:`kitty.conf`:
+
+.. code:: conf
+
+    map f1 scroll_to_prompt 0
+
+
+How it works
+-----------------
+
+At startup, kitty detects if the shell you have configured (either system wide
+or the :opt:`shell` option in :file:`kitty.conf`) is a supported shell. If so,
+kitty injects some shell specific code into the shell, to enable shell
+integration. How it does so varies for different shells.
+
+
+.. tab:: zsh
+
+   For zsh, kitty sets the :envvar:`ZDOTDIR` environment variable to make zsh
+   load kitty's :file:`.zshenv` which restores the original value of
+   :envvar:`ZDOTDIR` and sources the original :file:`.zshenv`. It then loads
+   the shell integration code. The remainder of zsh's startup process proceeds
+   as normal.
+
+.. tab:: fish
+
+    For fish, to make it automatically load the integration code provided by
+    kitty, the integration script directory path is prepended to the
+    :envvar:`XDG_DATA_DIRS` environment variable. This is only applied to the
+    fish process and will be cleaned up by the integration script after startup.
+    No files are added or modified.
+
+.. tab:: bash
+
+    For bash, kitty starts bash in POSIX mode, using the environment variable
+    :envvar:`ENV` to load the shell integration script. This prevents bash from
+    loading any startup files itself. The loading of the startup files is done
+    by the integration script, after disabling POSIX mode. From the perspective
+    of those scripts there should be no difference to running vanilla bash.
+
+
+Then, when launching the shell, kitty sets the environment variable
+:envvar:`KITTY_SHELL_INTEGRATION` to the value of the :opt:`shell_integration`
+option. The shell integration code reads the environment variable, turns on the
+specified integration functionality and then unsets the variable so as to not
+pollute the system.
+
+The actual shell integration code uses hooks provided by each shell to send
+special escape codes to kitty, to perform the various tasks. You can see the
+code used for each shell below:
+
+.. raw:: html
+
+    <details>
+    <summary>Click to toggle shell integration code</summary>
+
+.. tab:: zsh
+
+    .. literalinclude:: ../shell-integration/zsh/kitty-integration
+        :language: zsh
+
+
+.. tab:: fish
+
+    .. literalinclude:: ../shell-integration/fish/vendor_conf.d/kitty-shell-integration.fish
+        :language: fish
+        :force:
+
+.. tab:: bash
+
+    .. literalinclude:: ../shell-integration/bash/kitty.bash
+        :language: bash
+
+.. raw:: html
+
+   </details>
+
+
+Shell integration over SSH
+----------------------------
+
+The easiest way to have shell integration work when SSHing into remote systems
+is to use the :doc:`ssh kitten <kittens/ssh>`. Simply run::
+
+    kitty +kitten ssh hostname
+
+And, by magic, you will be logged into the remote system with fully functional
+shell integration. Alternately, you can :ref:`setup shell integration manually
+<manual_shell_integration>`, by copying the kitty shell integration scripts to
+the remote server and editing the shell rc files there, as described below.
+
+
+.. _clone_shell:
+
+Clone the current shell into a new window
+-----------------------------------------------
+
+You can clone the current shell into a new kitty window by simply running the
+:command:`clone-in-kitty` command, for example:
+
+.. code-block:: sh
+
+    clone-in-kitty
+    clone-in-kitty --type=tab
+    clone-in-kitty --title "I am a clone"
+
+This will open a new window running a new shell instance but with all
+environment variables and the current working directory copied. This even works
+over SSH when using :doc:`kittens/ssh`.
+
+The :command:`clone-in-kitty` command takes almost all the same arguments as the
+:doc:`launch <launch>` command, so you can open a new tab instead or a new OS
+window, etc. Arguments of launch that can cause code execution or that don't
+make sense when cloning are ignored. Most prominently, the following options are
+ignored: :option:`--allow-remote-control <launch --allow-remote-control>`,
+:option:`--copy-cmdline <launch --copy-cmdline>`, :option:`--copy-env <launch
+--copy-env>`, :option:`--stdin-source <launch --stdin-source>`,
+:option:`--marker <launch --marker>` and :option:`--watcher <launch --watcher>`.
+
+:command:`clone-in-kitty` can be configured to source arbitrary code in the
+cloned window using environment variables. It will automatically clone virtual
+environments created by the :link:`Python venv module
+<https://docs.python.org/3/library/venv.html>` or :link:`Conda
+<https://conda.io/>`. In addition, setting the
+env var :envvar:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that
+code to be run in the cloned window with :code:`eval`. Similarly, setting
+:envvar:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause that file to
+be sourced in the cloned window. This can be controlled by
+:opt:`clone_source_strategies`.
+
+:command:`clone-in-kitty` works by asking the shell to serialize its internal
+state (mainly CWD and env vars) and this state is transmitted to kitty and
+restored by the shell integration scripts in the cloned window.
+
+
+.. _manual_shell_integration:
+
+Manual shell integration
+----------------------------
+
+The automatic shell integration is designed to be minimally intrusive, as such
+it wont work for sub-shells, terminal multiplexers, containers, etc.
+For such systems, you should setup manual shell integration by adding some code
+to your shells startup files to load the shell integration script.
+
+First, in :file:`kitty.conf` set:
+
+.. code-block:: conf
+
+    shell_integration disabled
+
+Then in your shell's rc file, add the lines:
+
+.. tab:: zsh
+
+    .. code-block:: sh
+
+        if test -n "$KITTY_INSTALLATION_DIR"; then
+            export KITTY_SHELL_INTEGRATION="enabled"
+            autoload -Uz -- "$KITTY_INSTALLATION_DIR"/shell-integration/zsh/kitty-integration
+            kitty-integration
+            unfunction kitty-integration
+        fi
+
+.. tab:: fish
+
+    .. code-block:: fish
+
+        if set -q KITTY_INSTALLATION_DIR
+            set --global KITTY_SHELL_INTEGRATION enabled
+            source "$KITTY_INSTALLATION_DIR/shell-integration/fish/vendor_conf.d/kitty-shell-integration.fish"
+            set --prepend fish_complete_path "$KITTY_INSTALLATION_DIR/shell-integration/fish/vendor_completions.d"
+        end
+
+
+.. tab:: bash
+
+    .. code-block:: sh
+
+        if test -n "$KITTY_INSTALLATION_DIR"; then
+            export KITTY_SHELL_INTEGRATION="enabled"
+            source "$KITTY_INSTALLATION_DIR/shell-integration/bash/kitty.bash"
+        fi
+
+The value of :envvar:`KITTY_SHELL_INTEGRATION` is the same as that for
+:opt:`shell_integration`, except if you want to disable shell integration
+completely, in which case simply do not set the
+:envvar:`KITTY_SHELL_INTEGRATION` variable at all.
+
+In a container, you will need to install the kitty shell integration scripts
+and make sure the :envvar:`KITTY_INSTALLATION_DIR` environment variable is set
+to point to the location of the scripts.
+
+Integration with other shells
+-------------------------------
+
+There exist third-party integrations to use these features for various other
+shells:
+
+* Jupyter console and IPython via a patch (:iss:`4475`)
+* `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__
+
+
+Notes for shell developers
+-----------------------------
+
+The protocol used for marking the prompt is very simple. You should consider
+adding it to your shell as a builtin. Many modern terminals make use of it, for
+example: kitty, iTerm2, WezTerm, DomTerm
+
+Just before starting to draw the PS1 prompt send the escape code::
+
+    <OSC>133;A<ST>
+
+Just before starting to draw the PS2 prompt send the escape code::
+
+    <OSC>133;A;k=s<ST>
+
+Just before running a command/program, send the escape code::
+
+    <OSC>133;C<ST>
+
+Here ``<OSC>`` is the bytes ``0x1b 0x5d`` and ``<ST>`` is the bytes ``0x1b
+0x5c``. This is exactly what is needed for shell integration in kitty. For the
+full protocol, that also marks the command region, see `the iTerm2 docs
+<https://iterm2.com/documentation-escape-codes.html>`_.

docs/support.html

@@ -1,7 +1,12 @@
 <style>
+#support-buttons {
+    display: flex;
+    flex-wrap: wrap;
+}
+
 .support-button {
+    box-sizing: border-box;
     border-radius: 6px;
-    box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
     display: inline-block;
     cursor: pointer;
     color: rgb(51, 51, 51);
@@ -10,15 +15,16 @@
     font-weight: bold;
     padding: 8px 24px;
     text-decoration: none;
+    margin-left: 1em;
+    outline: 0;
+    border-width: 0;
 }
 
 .support-button:hover {
-    transform: scale(1.5);
+    transform: scale(1.2);
+    border: solid 1px rgb(92, 184, 92);
 }
 
-.support-button {
-    outline: 0;
-}
 .support-button:visited {
     color: rgb(51, 51, 51);
     outline: 0;
@@ -30,28 +36,34 @@
 }
 
 #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);
+    background: linear-gradient(rgb(92, 184, 92) 5%, rgb(62, 142, 62) 100%) rgb(92, 184, 92);
+    padding-top: 10px; padding-bottom: 10px;
+    color: rgb(51, 51, 51);
+    border: 1px solid rgb(92, 184, 92);
 }
 
-#liberapay a {
+a.support-button {
     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="github">
+    <a class="support-button" href="https://github.com/sponsors/kovidgoyal">Patronage via GitHub</a>
+</div>
+
+
 <div id="patreon">
     <a class="support-button" href="https://www.patreon.com/bePatron?u=917933">Patronage via Patreon</a>
 </div>
 
+<div id="liberapay">
+    <a class="support-button" href="https://liberapay.com/kovidgoyal/donate">Patronage via Liberapay</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" />
@@ -61,9 +73,5 @@
     </form>
 </div>
 
-<div id="liberapay">
-    <a class="support-button" href="https://liberapay.com/kovidgoyal/donate">Patronage via Liberapay</a>
-</div>
-
 </div>
 

docs/support.rst

@@ -1,5 +1,5 @@
-Support kitty development
-===========================
+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
@@ -7,7 +7,7 @@ end kitty has many foundational features, such as: :doc:`image support
 :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>`.
+<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.
@@ -15,8 +15,7 @@ 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:
+*patron* of kitty development via one of the services below:
 
 
 .. raw:: html

docs/underlines.rst

@@ -0,0 +1,37 @@
+Colored and styled underlines
+================================
+
+|kitty| supports colored and styled (wavy) underlines. This is of particular use
+in terminal based text editors such as :program:`vim` and :program:`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_(Control_Sequence_Introducer)_sequences>`__)
+
+To set the underline style::
+
+    <ESC>[4:0m  # no underline
+    <ESC>[4:1m  # straight underline
+    <ESC>[4:2m  # double underline
+    <ESC>[4:3m  # curly underline
+    <ESC>[4:4m  # dotted underline
+    <ESC>[4:5m  # dashed underline
+    <ESC>[4m    # straight underline (for backwards compat)
+    <ESC>[24m   # 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
+
+The underline color must remain the same under reverse video, if it has a color,
+if not, it should follow the foreground color.
+
+To detect support for this feature in a terminal emulator, query the terminfo
+database for the ``Su`` boolean capability.

docs/unscroll.rst

@@ -0,0 +1,38 @@
+.. _unscroll:
+
+Unscrolling the screen
+========================
+
+This is a small extension to the `SD (Pan up) escape code
+<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The ``SD``
+escape code normally causes the text on screen to scroll down by the specified
+number of lines, with empty lines appearing at the top of the screen. This
+extension allows the new lines to be filled in from the scrollback buffer
+instead of being blank.
+
+The motivation for this is that many modern shells will show completions in a
+block of lines under the cursor, this causes some of the on-screen text to be
+lost even after the completion is completed, because it has scrolled off
+screen. This escape code allows that text to be restored.
+
+If the scrollback buffer is empty or there is no scrollback buffer, such as for
+the alternate screen, then the newly inserted lines must be empty, just as with
+the original ``SD`` escape code. The maximum number of lines that can be
+scrolled down is implementation defined, but must be at least one screen worth.
+
+The syntax of the escape code is identical to that of ``SD`` except that it has
+a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
+<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`__
+and unused for any other purpose as far as I can tell. So for example, to
+unscroll three lines, the escape code would be::
+
+    CSI 3 + T
+
+See `discussion here
+<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`__.
+
+.. versionadded:: 0.20.2
+
+Also supported by the terminals:
+
+* `mintty <https://github.com/mintty/mintty/releases/tag/3.5.2>`__

gen-apc-parsers.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
 
+import os
 import subprocess
 from collections import defaultdict
 from typing import Any, DefaultDict, Dict, FrozenSet, List, Tuple, Union
@@ -43,7 +43,7 @@ def parse_flag(keymap: KeymapType, type_map: Dict[str, Any], command_class: str)
     lines = []
     for ch in type_map['flag']:
         attr, allowed_values = keymap[ch]
-        q = ' && '.join(f"g.{attr} != '{x}'" for x in allowed_values)
+        q = ' && '.join(f"g.{attr} != '{x}'" for x in sorted(allowed_values))
         lines.append(f'''
             case {attr}: {{
                 g.{attr} = screen->parser_buf[pos++] & 0xff;
@@ -68,7 +68,7 @@ def cmd_for_report(report_name: str, keymap: KeymapType, type_map: Dict[str, Any
         flag_fmt, flag_attrs = [], []
         cv = {'flag': 'c', 'int': 'i', 'uint': 'I'}[atype]
         for ch in type_map[atype]:
-            flag_fmt.append('s' + cv)
+            flag_fmt.append(f's{cv}')
             attr = keymap[ch][0]
             flag_attrs.append(f'"{attr}", {conv}g.{attr}')
         return ' '.join(flag_fmt), ', '.join(flag_attrs)
@@ -241,7 +241,7 @@ static inline void
 
 def write_header(text: str, path: str) -> None:
     with open(path, 'w') as f:
-        print(f'// This file is generated by {__file__} do not edit!', file=f, end='\n\n')
+        print(f'// This file is generated by {os.path.basename(__file__)} do not edit!', file=f, end='\n\n')
         print('#pragma once', file=f)
         print(text, file=f)
     subprocess.check_call(['clang-format', '-i', path])
@@ -250,7 +250,7 @@ def write_header(text: str, path: str) -> None:
 def graphics_parser() -> None:
     flag = frozenset
     keymap: KeymapType = {
-        'a': ('action', flag('tTqpdfa')),
+        'a': ('action', flag('tTqpdfac')),
         'd': ('delete_action', flag('aAiIcCfFnNpPqQxXyYzZ')),
         't': ('transmission_type', flag('dfts')),
         'o': ('compressed', flag('z')),

gen-config.py

@@ -1,434 +1,45 @@
 #!/usr/bin/env python
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
-import inspect
-import os
-import pprint
+
 import re
-import textwrap
-from typing import (
-    Any, Callable, Dict, Iterator, List, Set, Tuple, Union, get_type_hints
-)
+from typing import List
 
-from kitty.conf.types import Definition, MultiOption, Option, unset
+from kitty.conf.generate import write_output
 
 
-def chunks(lst: List, n: int) -> Iterator[List]:
-    for i in range(0, len(lst), n):
-        yield lst[i:i + n]
-
-
-def atoi(text: str) -> str:
-    return f'{int(text):08d}' if text.isdigit() else text
-
-
-def natural_keys(text: str) -> Tuple[str, ...]:
-    return tuple(atoi(c) for c in re.split(r'(\d+)', text))
-
-
-def generate_class(defn: Definition, loc: str) -> Tuple[str, str]:
-    class_lines: List[str] = []
-    tc_lines: List[str] = []
-    a = class_lines.append
-    t = tc_lines.append
-    a('class Options:')
-    t('class Parser:')
-    choices = {}
-    imports: Set[Tuple[str, str]] = set()
-    tc_imports: Set[Tuple[str, str]] = set()
-
-    def type_name(x: type) -> str:
-        ans = x.__name__
-        if x.__module__ and x.__module__ != 'builtins':
-            imports.add((x.__module__, x.__name__))
-        return ans
-
-    def option_type_as_str(x: Any) -> str:
-        if hasattr(x, '__name__'):
-            return type_name(x)
-        ans = repr(x)
-        ans = ans.replace('NoneType', 'None')
-        return ans
-
-    def option_type_data(option: Union[Option, MultiOption]) -> Tuple[Callable, str]:
-        func = option.parser_func
-        if func.__module__ == 'builtins':
-            return func, func.__name__
-        th = get_type_hints(func)
-        rettype = th['return']
-        typ = option_type_as_str(rettype)
-        if isinstance(option, MultiOption):
-            typ = typ[typ.index('[') + 1:-1]
-            typ = typ.replace('Tuple', 'Dict', 1)
-        return func, typ
-
-    is_mutiple_vars = {}
-    option_names = set()
-    color_table = list(map(str, range(256)))
-
-    def parser_function_declaration(option_name: str) -> None:
-        t('')
-        t(f'    def {option_name}(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:')
-
-    for option in sorted(defn.iter_all_options(), key=lambda a: natural_keys(a.name)):
-        option_names.add(option.name)
-        parser_function_declaration(option.name)
-        if isinstance(option, MultiOption):
-            mval: Dict[str, Dict[str, Any]] = {'macos': {}, 'linux': {}, '': {}}
-            func, typ = option_type_data(option)
-            for val in option:
-                if val.add_to_default:
-                    gr = mval[val.only]
-                    for k, v in func(val.defval_as_str):
-                        gr[k] = v
-            is_mutiple_vars[option.name] = typ, mval
-            sig = inspect.signature(func)
-            tc_imports.add((func.__module__, func.__name__))
-            if len(sig.parameters) == 1:
-                t(f'        for k, v in {func.__name__}(val):')
-                t(f'            ans["{option.name}"][k] = v')
-            else:
-                t(f'        for k, v in {func.__name__}(val, ans["{option.name}"]):')
-                t(f'            ans["{option.name}"][k] = v')
-            continue
-
-        if option.choices:
-            typ = 'typing.Literal[{}]'.format(', '.join(repr(x) for x in option.choices))
-            ename = f'choices_for_{option.name}'
-            choices[ename] = typ
-            typ = ename
-            func = str
-        elif defn.has_color_table and option.is_color_table_color:
-            func, typ = option_type_data(option)
-            t(f'        ans[{option.name!r}] = {func.__name__}(val)')
-            tc_imports.add((func.__module__, func.__name__))
-            cnum = int(option.name[5:])
-            color_table[cnum] = '0x{:06x}'.format(func(option.defval_as_string).__int__())
-            continue
-        else:
-            func, typ = option_type_data(option)
-            try:
-                params = inspect.signature(func).parameters
-            except Exception:
-                params = {}
-            if 'dict_with_parse_results' in params:
-                t(f'        {func.__name__}(val, ans)')
-            else:
-                t(f'        ans[{option.name!r}] = {func.__name__}(val)')
-            if func.__module__ != 'builtins':
-                tc_imports.add((func.__module__, func.__name__))
-
-        defval = repr(func(option.defval_as_string))
-        if option.macos_defval is not unset:
-            md = repr(func(option.macos_defval))
-            defval = f'{md} if is_macos else {defval}'
-            imports.add(('kitty.constants', 'is_macos'))
-        a(f'    {option.name}: {typ} = {defval}')
-        if option.choices:
-            t('        val = val.lower()')
-            t(f'        if val not in self.choices_for_{option.name}:')
-            t(f'            raise ValueError(f"The value {{val}} is not a valid choice for {option.name}")')
-            t(f'        ans["{option.name}"] = val')
-            t('')
-            t(f'    choices_for_{option.name} = frozenset({option.choices!r})')
-
-    for option_name, (typ, mval) in is_mutiple_vars.items():
-        a(f'    {option_name}: {typ} = ' '{}')
-
-    for parser, aliases in defn.deprecations.items():
-        for alias in aliases:
-            parser_function_declaration(alias)
-            tc_imports.add((parser.__module__, parser.__name__))
-            t(f'        {parser.__name__}({alias!r}, val, ans)')
-
-    action_parsers = {}
-
-    def resolve_import(ftype: str) -> str:
-        if '.' in ftype:
-            fmod, ftype = ftype.rpartition('.')[::2]
-        else:
-            fmod = f'{loc}.options.utils'
-        imports.add((fmod, ftype))
-        return ftype
-
-    for aname, action in defn.actions.items():
-        option_names.add(aname)
-        action_parsers[aname] = func = action.parser_func
-        th = get_type_hints(func)
-        rettype = th['return']
-        typ = option_type_as_str(rettype)
-        typ = typ[typ.index('[') + 1:-1]
-        a(f'    {aname}: typing.List[{typ}] = []')
-        for imp in action.imports:
-            resolve_import(imp)
-        for fname, ftype in action.fields.items():
-            ftype = resolve_import(ftype)
-            a(f'    {fname}: {ftype} = ' '{}')
-        parser_function_declaration(aname)
-        t(f'        for k in {func.__name__}(val):')
-        t(f'            ans[{aname!r}].append(k)')
-        tc_imports.add((func.__module__, func.__name__))
-
-    if defn.has_color_table:
-        imports.add(('array', 'array'))
-        a('    color_table: array = array("L", (')
-        for grp in chunks(color_table, 8):
-            a('        ' + ', '.join(grp) + ',')
-        a('    ))')
-
-    a('    config_paths: typing.Tuple[str, ...] = ()')
-    a('    config_overrides: typing.Tuple[str, ...] = ()')
-    a('')
-    a('    def __init__(self, options_dict: typing.Optional[typing.Dict[str, typing.Any]] = None) -> None:')
-    a('        if options_dict is not None:')
-    a('            for key in option_names:')
-    a('                setattr(self, key, options_dict[key])')
-
-    a('')
-    a('    @property')
-    a('    def _fields(self) -> typing.Tuple[str, ...]:')
-    a('        return option_names')
-
-    a('')
-    a('    def __iter__(self) -> typing.Iterator[str]:')
-    a('        return iter(self._fields)')
-
-    a('')
-    a('    def __len__(self) -> int:')
-    a('        return len(self._fields)')
-
-    a('')
-    a('    def _copy_of_val(self, name: str) -> typing.Any:')
-    a('        ans = getattr(self, name)')
-    a('        if isinstance(ans, dict):\n            ans = ans.copy()')
-    a('        elif isinstance(ans, list):\n            ans = ans[:]')
-    a('        return ans')
-
-    a('')
-    a('    def _asdict(self) -> typing.Dict[str, typing.Any]:')
-    a('        return {k: self._copy_of_val(k) for k in self}')
-
-    a('')
-    a('    def _replace(self, **kw: typing.Any) -> "Options":')
-    a('        ans = Options()')
-    a('        for name in self:')
-    a('            setattr(ans, name, self._copy_of_val(name))')
-    a('        for name, val in kw.items():')
-    a('            setattr(ans, name, val)')
-    a('        return ans')
-
-    a('')
-    a('    def __getitem__(self, key: typing.Union[int, str]) -> typing.Any:')
-    a('        k = option_names[key] if isinstance(key, int) else key')
-    a('        try:')
-    a('            return getattr(self, k)')
-    a('        except AttributeError:')
-    a('            pass')
-    a('        raise KeyError(f"No option named: {k}")')
-
-    if defn.has_color_table:
-        a('')
-        a('    def __getattr__(self, key: str) -> typing.Any:')
-        a('        if key.startswith("color"):')
-        a('            q = key[5:]')
-        a('            if q.isdigit():')
-        a('                k = int(q)')
-        a('                if 0 <= k <= 255:')
-        a('                    x = self.color_table[k]')
-        a('                    return Color((x >> 16) & 255, (x >> 8) & 255, x & 255)')
-        a('        raise AttributeError(key)')
-        a('')
-        a('    def __setattr__(self, key: str, val: typing.Any) -> typing.Any:')
-        a('        if key.startswith("color"):')
-        a('            q = key[5:]')
-        a('            if q.isdigit():')
-        a('                k = int(q)')
-        a('                if 0 <= k <= 255:')
-        a('                    self.color_table[k] = int(val)')
-        a('                    return')
-        a('        object.__setattr__(self, key, val)')
-
-    a('')
-    a('')
-    a('defaults = Options()')
-    for option_name, (typ, mval) in is_mutiple_vars.items():
-        a(f'defaults.{option_name} = {mval[""]!r}')
-        if mval['macos']:
-            imports.add(('kitty.constants', 'is_macos'))
-            a('if is_macos:')
-            a(f'    defaults.{option_name}.update({mval["macos"]!r}')
-        if mval['macos']:
-            imports.add(('kitty.constants', 'is_macos'))
-            a('if not is_macos:')
-            a(f'    defaults.{option_name}.update({mval["linux"]!r}')
-
-    for aname, func in action_parsers.items():
-        a(f'defaults.{aname} = [')
-        only: Dict[str, List[Tuple[str, Callable]]] = {}
-        for sc in defn.iter_all_maps(aname):
-            if not sc.add_to_default:
-                continue
-            text = sc.parseable_text
-            if sc.only:
-                only.setdefault(sc.only, []).append((text, func))
-            else:
-                for val in func(text):
-                    a(f'    # {sc.name}')
-                    a(f'    {val!r},')
-        a(']')
-        if only:
-            imports.add(('kitty.constants', 'is_macos'))
-            for cond, items in only.items():
-                cond = 'is_macos' if cond == 'macos' else 'not is_macos'
-                a(f'if {cond}:')
-                for (text, func) in items:
-                    for val in func(text):
-                        a(f'    defaults.{aname}.append({val!r})')
-
-    t('')
-    t('')
-    t('def create_result_dict() -> typing.Dict[str, typing.Any]:')
-    t('    return {')
-    for oname in is_mutiple_vars:
-        t(f'        {oname!r}: {{}},')
-    for aname in defn.actions:
-        t(f'        {aname!r}: [],')
-    t('    }')
-
-    t('')
-    t('')
-    t(f'actions = frozenset({tuple(defn.actions)!r})')
-    t('')
-    t('')
-    t('def merge_result_dicts(defaults: typing.Dict[str, typing.Any], vals: typing.Dict[str, typing.Any]) -> typing.Dict[str, typing.Any]:')
-    t('    ans = {}')
-    t('    for k, v in defaults.items():')
-    t('        if isinstance(v, dict):')
-    t('            ans[k] = merge_dicts(v, vals.get(k, {}))')
-    t('        elif k in actions:')
-    t('            ans[k] = v + vals.get(k, [])')
-    t('        else:')
-    t('            ans[k] = vals.get(k, v)')
-    t('    return ans')
-    tc_imports.add(('kitty.conf.utils', 'merge_dicts'))
-
-    t('')
-    t('')
-    t('parser = Parser()')
-    t('')
-    t('')
-    t('def parse_conf_item(key: str, val: str, ans: typing.Dict[str, typing.Any]) -> bool:')
-    t('    func = getattr(parser, key, None)')
-    t('    if func is not None:')
-    t('        func(val, ans)')
-    t('        return True')
-    t('    return False')
-
-    preamble = ['# generated by gen-config.py DO NOT edit', '# vim:fileencoding=utf-8', '']
-    a = preamble.append
-
-    def output_imports(imports: Set, add_module_imports: bool = True) -> None:
-        a('import typing')
-        seen_mods = {'typing'}
-        mmap: Dict[str, List[str]] = {}
-        for mod, name in imports:
-            mmap.setdefault(mod, []).append(name)
-        for mod in sorted(mmap):
-            names = sorted(mmap[mod])
-            lines = textwrap.wrap(', '.join(names), 100)
-            if len(lines) == 1:
-                s = lines[0]
-            else:
-                s = '\n    '.join(lines)
-                s = f'(\n    {s}\n)'
-            a(f'from {mod} import {s}')
-            if add_module_imports and mod not in seen_mods and mod != s:
-                a(f'import {mod}')
-                seen_mods.add(mod)
-
-    output_imports(imports)
-    a('')
-    if choices:
-        a('if typing.TYPE_CHECKING:')
-        for name, cdefn in choices.items():
-            a(f'    {name} = {cdefn}')
-        a('else:')
-        for name in choices:
-            a(f'    {name} = str')
-
-    a('')
-    a('option_names = (  # {{''{')
-    a(' ' + pprint.pformat(tuple(sorted(option_names, key=natural_keys)))[1:] + '  # }}''}')
-    class_def = '\n'.join(preamble + ['', ''] + class_lines)
-
-    preamble = ['# generated by gen-config.py DO NOT edit', '# vim:fileencoding=utf-8', '']
-    a = preamble.append
-    output_imports(tc_imports, False)
-
-    return class_def, '\n'.join(preamble + ['', ''] + tc_lines)
-
-
-def generate_c_conversion(loc: str, ctypes: List[Option]) -> str:
-    lines: List[str] = []
-    basic_converters = {
-        'int': 'PyLong_AsLong', 'uint': 'PyLong_AsUnsignedLong', 'bool': 'PyObject_IsTrue',
-        'float': 'PyFloat_AsFloat', 'double': 'PyFloat_AsDouble',
-        'time': 'parse_s_double_to_monotonic_t', 'time-ms': 'parse_ms_long_to_monotonic_t'
-    }
-
-    for opt in ctypes:
-        lines.append('')
-        lines.append(f'static void\nconvert_from_python_{opt.name}(PyObject *val, Options *opts) ''{')
-        is_special = opt.ctype.startswith('!')
-        if is_special:
-            func = opt.ctype[1:]
-            lines.append(f'    {func}(val, opts);')
-        else:
-            func = basic_converters.get(opt.ctype, opt.ctype)
-            lines.append(f'    opts->{opt.name} = {func}(val);')
-        lines.append('}')
-        lines.append('')
-        lines.append(f'static void\nconvert_from_opts_{opt.name}(PyObject *py_opts, Options *opts) ''{')
-        lines.append(f'    PyObject *ret = PyObject_GetAttrString(py_opts, "{opt.name}");')
-        lines.append('    if (ret == NULL) return;')
-        lines.append(f'    convert_from_python_{opt.name}(ret, opts);')
-        lines.append('    Py_DECREF(ret);')
-        lines.append('}')
-
-    lines.append('')
-    lines.append('static bool\nconvert_opts_from_python_opts(PyObject *py_opts, Options *opts) ''{')
-    for opt in ctypes:
-        lines.append(f'    convert_from_opts_{opt.name}(py_opts, opts);')
-        lines.append('    if (PyErr_Occurred()) return false;')
-    lines.append('    return true;')
-    lines.append('}')
-
-    preamble = ['// generated by gen-config.py DO NOT edit', '// vim:fileencoding=utf-8', '#pragma once', '#include "to-c.h"']
-    return '\n'.join(preamble + ['', ''] + lines)
-
-
-def write_output(loc: str, defn: Definition) -> None:
-    cls, tc = generate_class(defn, loc)
-    with open(os.path.join(*loc.split('.'), 'options', 'types.py'), 'w') as f:
-        f.write(cls + '\n')
-    with open(os.path.join(*loc.split('.'), 'options', 'parse.py'), 'w') as f:
-        f.write(tc + '\n')
-    ctypes = []
-    for opt in defn.root_group.iter_all_non_groups():
-        if isinstance(opt, Option) and opt.ctype:
-            ctypes.append(opt)
-    if ctypes:
-        c = generate_c_conversion(loc, ctypes)
-        with open(os.path.join(*loc.split('.'), 'options', 'to-c-generated.h'), 'w') as f:
-            f.write(c + '\n')
+def patch_color_list(path: str, colors: List[str], name: str, spc: str = '    ') -> None:
+    with open(path, 'r+') as f:
+        raw = f.read()
+        nraw = re.sub(
+            fr'(# {name}_COLORS_START).+?(\s+# {name}_COLORS_END)',
+            r'\1' + f'\n{spc}' + f'\n{spc}'.join(map(lambda x: f'{x!r},', sorted(colors))) + r'\2',
+            raw, flags=re.DOTALL | re.MULTILINE)
+        if nraw != raw:
+            f.seek(0)
+            f.truncate()
+            f.write(nraw)
 
 
 def main() -> None:
     from kitty.options.definition import definition
     write_output('kitty', definition)
+    nullable_colors = []
+    all_colors = []
+    for opt in definition.iter_all_options():
+        if callable(opt.parser_func):
+            if opt.parser_func.__name__ in ('to_color_or_none', 'cursor_text_color'):
+                nullable_colors.append(opt.name)
+                all_colors.append(opt.name)
+            elif opt.parser_func.__name__ in ('to_color', 'titlebar_color', 'macos_titlebar_color'):
+                all_colors.append(opt.name)
+    patch_color_list('kitty/rc/set_colors.py', nullable_colors, 'NULLABLE')
+    patch_color_list('kittens/themes/collection.py', all_colors, 'ALL', ' ' * 8)
+
     from kittens.diff.options.definition import definition as kd
     write_output('kittens.diff', kd)
+    from kittens.ssh.options.definition import definition as sd
+    write_output('kittens.ssh', sd)
 
 
 if __name__ == '__main__':

gen-key-constants.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 import string
@@ -239,13 +238,13 @@ def patch_file(path: str, what: str, text: str, start_marker: str = '/* ', end_m
             end = raw.index(end_q)
         except ValueError:
             raise SystemExit(f'Failed to find "{end_q}" in {path}')
-        raw = raw[:start] + start_q + '\n' + text + '\n' + raw[end:]
+        raw = f'{raw[:start]}{start_q}\n{text}\n{raw[end:]}'
         f.seek(0)
         f.truncate(0)
         f.write(raw)
 
 
-def serialize_dict(x: dict) -> str:
+def serialize_dict(x: Dict[Any, Any]) -> str:
     return pformat(x, indent=4).replace('{', '{\n ', 1)
 
 
@@ -349,7 +348,7 @@ def generate_legacy_text_key_maps() -> None:
     patch_file('kitty_tests/keys.py', 'legacy letter tests', '\n'.join(tests), start_marker='# ', end_marker='')
 
 
-def chunks(lst: List, n: int) -> Any:
+def chunks(lst: List[Any], n: int) -> Any:
     """Yield successive n-sized chunks from lst."""
     for i in range(0, len(lst), n):
         yield lst[i:i + n]
@@ -369,7 +368,7 @@ def generate_ctrl_mapping() -> None:
         val = str(ctrl_mapping[k])
         items.append(val)
         if k in "\\'":
-            k = '\\' + k
+            k = f'\\{k}'
         mi.append(f"        case '{k}': return {val};")
 
     for line_items in chunks(items, 6):

gen-wcwidth.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2017, Kovid Goyal <kovid at kovidgoyal.net>
 
 import os
@@ -50,10 +49,25 @@ class_maps: Dict[str, Set[int]] = {}
 all_symbols: Set[int] = set()
 name_map: Dict[int, str] = {}
 word_search_map: DefaultDict[str, Set[int]] = defaultdict(set)
-zwj = 0x200d
+soft_hyphen = 0xad
 flag_codepoints = frozenset(range(0x1F1E6, 0x1F1E6 + 26))
-marks = set(emoji_skin_tone_modifiers) | {zwj} | flag_codepoints
+# See https://github.com/harfbuzz/harfbuzz/issues/169
+marks = set(emoji_skin_tone_modifiers) | flag_codepoints
 not_assigned = set(range(0, sys.maxunicode))
+property_maps: Dict[str, Set[int]] = defaultdict(set)
+
+
+def parse_prop_list() -> None:
+    global marks
+    for line in get_data('ucd/PropList.txt'):
+        if line.startswith('#'):
+            continue
+        cp_or_range, rest = line.split(';', 1)
+        chars = parse_range_spec(cp_or_range.strip())
+        name = rest.strip().split()[0]
+        property_maps[name] |= chars
+    # see https://www.unicode.org/faq/unsup_char.html#3
+    marks |= property_maps['Other_Default_Ignorable_Code_Point']
 
 
 def parse_ucd() -> None:
@@ -97,6 +111,12 @@ def parse_ucd() -> None:
                 marks.add(codepoint)
             elif category.startswith('S'):
                 all_symbols.add(codepoint)
+            elif category == 'Cf':
+                # we add Cf to marks as it contains things like tags and zero
+                # width chars. Not sure if *all* of Cf should be treated as
+                # combining chars, might need to add individual exceptions in
+                # the future.
+                marks.add(codepoint)
 
     with open('nerd-fonts-glyphs.txt') as f:
         for line in f:
@@ -213,7 +233,7 @@ def parse_eaw() -> None:
         if eaw == 'A':
             ambiguous |= chars
             seen |= chars
-        elif eaw == 'W' or eaw == 'F':
+        elif eaw in ('W', 'F'):
             doublewidth |= chars
             seen |= chars
     doublewidth |= set(range(0x3400, 0x4DBF + 1)) - seen
@@ -234,15 +254,15 @@ def get_ranges(items: List[int]) -> Generator[Union[int, Tuple[int, int]], None,
             yield a, b
 
 
-def write_case(spec: Union[Tuple, int], p: Callable) -> None:
+def write_case(spec: Union[Tuple[int, ...], int], p: Callable[..., None]) -> None:
     if isinstance(spec, tuple):
         p('\t\tcase 0x{:x} ... 0x{:x}:'.format(*spec))
     else:
-        p('\t\tcase 0x{:x}:'.format(spec))
+        p(f'\t\tcase 0x{spec:x}:')
 
 
 @contextmanager
-def create_header(path: str, include_data_types: bool = True) -> Generator[Callable, None, None]:
+def create_header(path: str, include_data_types: bool = True) -> Generator[Callable[..., None], None, None]:
     with open(path, 'w') as f:
         p = partial(print, file=f)
         p('// unicode data, built from the unicode standard on:', date.today())
@@ -282,7 +302,7 @@ def gen_emoji() -> None:
 
 def category_test(
     name: str,
-    p: Callable,
+    p: Callable[..., None],
     classes: Iterable[str],
     comment: str,
     use_static: bool = False,
@@ -312,7 +332,7 @@ def category_test(
     p('\treturn false;\n}\n')
 
 
-def codepoint_to_mark_map(p: Callable, mark_map: List[int]) -> Dict[int, int]:
+def codepoint_to_mark_map(p: Callable[..., None], mark_map: List[int]) -> Dict[int, int]:
     p('\tswitch(c) { // {{{')
     rmap = {c: m for m, c in enumerate(mark_map)}
     for spec in get_ranges(mark_map):
@@ -336,10 +356,10 @@ def classes_to_regex(classes: Iterable[str], exclude: str = '') -> Iterable[str]
 
     def as_string(codepoint: int) -> str:
         if codepoint < 256:
-            return r'\x{:02x}'.format(codepoint)
+            return fr'\x{codepoint:02x}'
         if codepoint <= 0xffff:
-            return r'\u{:04x}'.format(codepoint)
-        return r'\U{:08x}'.format(codepoint)
+            return fr'\u{codepoint:04x}'
+        return fr'\U{codepoint:08x}'
 
     for spec in get_ranges(list(chars)):
         if isinstance(spec, tuple):
@@ -354,16 +374,21 @@ def gen_ucd() -> None:
         p('#include "unicode-data.h"')
         category_test(
                 'is_combining_char', p,
-                {c for c in class_maps if c.startswith('M')},
-                'M category (marks)',
-                # See https://github.com/harfbuzz/harfbuzz/issues/169
-                extra_chars=emoji_skin_tone_modifiers | {zwj},
+                (),
+                'Combining and default ignored characters',
+                extra_chars=marks,
                 least_check_return='false'
         )
         category_test(
-            'is_ignored_char', p, 'Cc Cf Cs'.split(),
+            'is_ignored_char', p, 'Cc Cs'.split(),
             'Control characters and non-characters',
-            extra_chars=non_characters, exclude={zwj},
+            extra_chars=non_characters,
+            ascii_range='false'
+        )
+        category_test(
+            'is_non_rendered_char', p, 'Cc Cs Cf'.split(),
+            'Other_Default_Ignorable_Code_Point and soft hyphen',
+            extra_chars=property_maps['Other_Default_Ignorable_Code_Point'] | set(range(0xfe00, 0xfe0f + 1)),
             ascii_range='false'
         )
         category_test('is_word_char', p, {c for c in class_maps if c[0] in 'LN'}, 'L and N categories')
@@ -378,17 +403,22 @@ def gen_ucd() -> None:
         p('combining_type mark_for_codepoint(char_type c) {')
         rmap = codepoint_to_mark_map(p, mark_map)
         p('}\n')
-        with open('kitty/unicode-data.h') as f:
-            unicode_data = f.read()
-        m = re.search(r'^#define VS15 (\d+)', unicode_data, re.M)
-        if m is not None:
-            expected = int(m.group(1))
-        if rmap[0xfe0e] != expected:
-            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]
-            ))
+        with open('kitty/unicode-data.h', 'r+') as f:
+            raw = f.read()
+            f.seek(0)
+            raw, num = re.subn(
+                r'^// START_KNOWN_MARKS.+?^// END_KNOWN_MARKS',
+                '// START_KNOWN_MARKS\nstatic const combining_type '
+                f'VS15 = {rmap[0xfe0e]}, VS16 = {rmap[0xfe0f]};'
+                '\n// END_KNOWN_MARKS', raw, flags=re.MULTILINE | re.DOTALL)
+            if not num:
+                raise SystemExit('Faile dto patch mark definitions in unicode-data.h')
+            f.truncate()
+            f.write(raw)
+
     with open('kittens/hints/url_regex.py', 'w') as f:
-        f.write("url_delimiters = '{}'  # noqa".format(''.join(classes_to_regex(cz, exclude='\n'))))
+        f.write('# generated by gen-wcwidth.py, do not edit\n\n')
+        f.write("url_delimiters = '{}'  # noqa".format(''.join(classes_to_regex(cz, exclude='\n\r'))))
 
 
 def gen_names() -> None:
@@ -495,7 +525,7 @@ def gen_names() -> None:
 def gen_wcwidth() -> None:
     seen: Set[int] = set()
 
-    def add(p: Callable, comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int) -> None:
+    def add(p: Callable[..., None], comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int) -> None:
         chars = chars_ - seen
         seen.update(chars)
         p(f'\t\t// {comment} ({len(chars)} codepoints)' + ' {{' '{')
@@ -536,6 +566,7 @@ def gen_wcwidth() -> None:
 
 
 parse_ucd()
+parse_prop_list()
 parse_emoji()
 parse_eaw()
 gen_ucd()

glfw/backend_utils.c

@@ -91,7 +91,7 @@ compare_timers(const void *a_, const void *b_) {
     return (a->trigger_at > b->trigger_at) ? 1 : (a->trigger_at < b->trigger_at) ? -1 : 0;
 }
 
-static inline void
+static void
 update_timers(EventLoopData *eld) {
     if (eld->timers_count > 1) qsort(eld->timers, eld->timers_count, sizeof(eld->timers[0]), compare_timers);
 }
@@ -164,7 +164,7 @@ prepareForPoll(EventLoopData *eld, monotonic_t timeout) {
     return timeout;
 }
 
-static inline struct timespec
+static struct timespec
 calc_time(monotonic_t nsec) {
     struct timespec result;
     result.tv_sec  = nsec / (1000LL * 1000LL * 1000LL);
@@ -271,7 +271,7 @@ wakeupEventLoop(EventLoopData *eld) {
 }
 
 #ifndef HAS_EVENT_FD
-static inline void
+static void
 closeFds(int *fds, size_t count) {
     while(count--) {
         if (*fds > 0) {
@@ -375,7 +375,7 @@ GLFWAPI char* utf_8_strndup(const char* source, size_t max_length) {
 int createAnonymousFile(off_t size) {
     int ret, fd = -1, shm_anon = 0;
 #ifdef HAS_MEMFD_CREATE
-    fd = memfd_create("glfw-shared", MFD_CLOEXEC | MFD_ALLOW_SEALING);
+    fd = glfw_memfd_create("glfw-shared", MFD_CLOEXEC | MFD_ALLOW_SEALING);
     if (fd < 0) return -1;
     // We can add this seal before calling posix_fallocate(), as the file
     // is currently zero-sized anyway.

glfw/cocoa_init.m

@@ -264,6 +264,8 @@ display_reconfigured(CGDirectDisplayID display UNUSED, CGDisplayChangeSummaryFla
     }
 }
 
+static NSDictionary<NSString*,NSNumber*> *global_shortcuts = nil;
+
 @interface GLFWHelper : NSObject
 @end
 
@@ -280,6 +282,16 @@ display_reconfigured(CGDirectDisplayID display UNUSED, CGDisplayChangeSummaryFla
     (void)object;
 }
 
+// watch for settings change and rebuild global_shortcuts using key/value observing on NSUserDefaults
+- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
+{
+    (void)keyPath; (void)object; (void)change; (void)context;
+    if (global_shortcuts != nil) {
+        [global_shortcuts release];
+        global_shortcuts = nil;
+    }
+}
+
 @end // GLFWHelper
 
 // Delegate for application related notifications {{{
@@ -346,32 +358,49 @@ static GLFWapplicationwillfinishlaunchingfun finish_launching_callback = NULL;
         finish_launching_callback();
 }
 
-- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename {
-    (void)theApplication;
-    if (!filename || !_glfw.ns.file_open_callback) return NO;
-    const char *path = NULL;
+- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename {
+    (void)sender;
+    if (!filename || !_glfw.ns.url_open_callback) return NO;
+    const char *url = NULL;
     @try {
-        path = [[NSFileManager defaultManager] fileSystemRepresentationWithPath: filename];
+        url = [[[NSURL fileURLWithPath:filename] absoluteString] UTF8String];
     } @catch(NSException *exc) {
         NSLog(@"Converting openFile filename: %@ failed with error: %@", filename, exc.reason);
         return NO;
     }
-    if (!path) return NO;
-    return _glfw.ns.file_open_callback(path);
+    if (!url) return NO;
+    return _glfw.ns.url_open_callback(url);
 }
 
 - (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames {
     (void)sender;
-    if (!_glfw.ns.file_open_callback || !filenames) return;
+    if (!_glfw.ns.url_open_callback || !filenames) return;
     for (id x in filenames) {
         NSString *filename = x;
-        const char *path = NULL;
+        const char *url = NULL;
         @try {
-            path = [[NSFileManager defaultManager] fileSystemRepresentationWithPath: filename];
+            url = [[[NSURL fileURLWithPath:filename] absoluteString] UTF8String];
         } @catch(NSException *exc) {
             NSLog(@"Converting openFiles filename: %@ failed with error: %@", filename, exc.reason);
         }
-        if (path) _glfw.ns.file_open_callback(path);
+        if (url) _glfw.ns.url_open_callback(url);
+    }
+}
+
+// Remove openFile and openFiles when the minimum supported macOS version is 10.13
+- (void)application:(NSApplication *)sender openURLs:(NSArray<NSURL *> *)urls
+{
+    (void)sender;
+    if (!_glfw.ns.url_open_callback || !urls) return;
+    for (id x in urls) {
+        NSURL *ns_url = x;
+        const char *url = NULL;
+        @try {
+            url = [[ns_url absoluteString] UTF8String];
+        } @catch(NSException *exc) {
+            NSLog(@"Converting openURLs url: %@ failed with error: %@", ns_url, exc.reason);
+        }
+        if (url) _glfw.ns.url_open_callback(url);
     }
 }
 
@@ -379,7 +408,6 @@ static GLFWapplicationwillfinishlaunchingfun finish_launching_callback = NULL;
 {
     (void)notification;
     [NSApp stop:nil];
-    if (_glfw.ns.file_open_callback) _glfw.ns.file_open_callback(":cocoa::application launched::");
 
     CGDisplayRegisterReconfigurationCallback(display_reconfigured, NULL);
     _glfwCocoaPostEmptyEvent();
@@ -453,22 +481,293 @@ void* _glfwLoadLocalVulkanLoaderNS(void)
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
 
-static inline bool
-is_ctrl_tab(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    if (
-            (modifierFlags == NSEventModifierFlagControl &&
-                [event.charactersIgnoringModifiers isEqualToString:@"\t"]) ||
-            (modifierFlags == (NSEventModifierFlagControl | NSEventModifierFlagShift) &&
-                [event.charactersIgnoringModifiers isEqualToString:@"\x19"])
-       ) return true;
-    return false;
+/**
+ * Apple Symbolic HotKeys Ids
+ * To find this symbolic hot keys indices do:
+ * 1. open Terminal
+ * 2. restore defaults in System Preferences > Keyboard > Shortcuts
+ * 3. defaults read com.apple.symbolichotkeys > current.txt
+ * 4. enable/disable given symbolic hot key in System Preferences > Keyboard > Shortcuts
+ * 5. defaults read com.apple.symbolichotkeys | diff -C 5 current.txt -
+ * 6. restore defaults in System Preferences > Keyboard > Shortcuts
+ */
+typedef enum AppleShortcutNames {
+    // launchpad & dock
+    kSHKTurnDockHidingOnOrOff                   = 52,   // Opt, Cmd, D
+    kSHKShowLaunchpad                           = 160,  //
+
+    // display
+    kSHKDecreaseDisplayBrightness1              = 53,   // F14 (Fn)
+    kSHKDecreaseDisplayBrightness2              = 55,   // F14 (Fn, Ctrl)
+    kSHKIncreaseDisplayBrightness1              = 54,   // F15 (Fn)
+    kSHKIncreaseDisplayBrightness2              = 56,   // F15 (Fn, Ctrl)
+
+    // mission control
+    kSHKMissionControl                          = 32,   // Ctrl, Arrow Up
+    kSHKShowNotificationCenter                  = 163,  //
+    kSHKTurnDoNotDisturbOnOrOff                 = 175,  //
+    kSHKApplicationWindows                      = 33,   // Ctrl, Arrow Down
+    kSHKShowDesktop                             = 36,   // F11
+    kSHKMoveLeftASpace                          = 79,   // Ctrl, Arrow Left
+    kSHKMoveRightASpace                         = 81,   // Ctrl, Arrow Right
+    kSHKSwitchToDesktop1                        = 118,  // Ctrl, 1
+    kSHKSwitchToDesktop2                        = 119,  // Ctrl, 2
+    kSHKSwitchToDesktop3                        = 120,  // Ctrl, 3
+    kSHKSwitchToDesktop4                        = 121,  // Ctrl, 4
+    kSHKQuickNote                               = 190,  // Fn, Q
+
+    // keyboard
+    kSHKChangeTheWayTabMovesFocus               = 13,   // Ctrl, F7
+    kSHKTurnKeyboardAccessOnOrOff               = 12,   // Ctrl, F1
+    kSHKMoveFocusToTheMenuBar                   = 7,    // Ctrl, F2
+    kSHKMoveFocusToTheDock                      = 8,    // Ctrl, F3
+    kSHKMoveFocusToActiveOrNextWindow           = 9,    // Ctrl, F4
+    kSHKMoveFocusToTheWindowToolbar             = 10,   // Ctrl, F5
+    kSHKMoveFocusToTheFloatingWindow            = 11,   // Ctrl, F6
+    kSHKMoveFocusToNextWindow                   = 27,   // Cmd, `
+    kSHKMoveFocusToStatusMenus                  = 57,   // Ctrl, F8
+
+    // input sources
+    kSHKSelectThePreviousInputSource            = 60,   // Ctrl, Space bar
+    kSHKSelectNextSourceInInputMenu             = 61,   // Ctrl, Opt, Space bar
+
+    // screenshots
+    kSHKSavePictureOfScreenAsAFile              = 28,   // Shift, Cmd, 3
+    kSHKCopyPictureOfScreenToTheClipboard       = 29,   // Ctrl, Shift, Cmd, 3
+    kSHKSavePictureOfSelectedAreaAsAFile        = 30,   // Shift, Cmd, 4
+    kSHKCopyPictureOfSelectedAreaToTheClipboard = 31,   // Ctrl, Shift, Cmd, 4
+    kSHKScreenshotAndRecordingOptions           = 184,  // Shift, Cmd, 5
+
+    // spotlight
+    kSHKShowSpotlightSearch                     = 64,   // Cmd, Space bar
+    kSHKShowFinderSearchWindow                  = 65,   // Opt, Cmd, Space bar
+
+    // accessibility
+    kSHKTurnZoomOnOrOff                         = 15,   // Opt, Cmd, 8
+    kSHKTurnImageSmoothingOnOrOff               = 23,   // Opt, Cmd, Backslash "\"
+    kSHKZoomOut                                 = 19,   // Opt, Cmd, -
+    kSHKZoomIn                                  = 17,   // Opt, Cmd, =
+    kSHKTurnFocusFollowingOnOrOff               = 179,  //
+
+    kSHKIncreaseContrast                        = 25,   // Ctrl, Opt, Cmd, .
+    kSHKDecreaseContrast                        = 26,   // Ctrl, Opt, Cmd, ,
+
+    kSHKInvertColors                            = 21,   // Ctrl, Opt, Cmd, 8
+    kSHKTurnVoiceOverOnOrOff                    = 59,   // Cmd, F5
+    kSHKShowAccessibilityControls               = 162,  // Opt, Cmd, F5
+
+    // app shortcuts
+    kSHKShowHelpMenu                            = 98,   // Shift, Cmd, /
+
+    // deprecated (Not shown on macOS Monterey)
+    kSHKMoveFocusToTheWindowDrawer              = 51,   // Opt, Cmd, `
+    kSHKShowDashboard                           = 62,   // F12
+    kSHKLookUpInDictionary                      = 70,   // Shift, Cmd, E
+    kSHKHideAndShowFrontRow                     = 73,   // Cmd, Esc
+    kSHKActivateSpaces                          = 75,   // F8
+
+    // unknown
+    kSHKUnknown                                 = 0,    //
+} AppleShortcutNames;
+
+static bool
+is_shiftable_shortcut(int scv) {
+    return scv == kSHKMoveFocusToActiveOrNextWindow || scv == kSHKMoveFocusToNextWindow;
 }
 
-static inline bool
-is_cmd_period(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    if (modifierFlags != NSEventModifierFlagCommand) return false;
-    if ([event.charactersIgnoringModifiers isEqualToString:@"."]) return true;
-    return false;
+#define USEFUL_MODS(x) (x & (NSEventModifierFlagShift | NSEventModifierFlagOption | NSEventModifierFlagCommand | NSEventModifierFlagControl))
+
+static void
+build_global_shortcuts_lookup(void) {
+    // dump these in a terminal with: defaults read com.apple.symbolichotkeys
+    NSMutableDictionary<NSString*, NSNumber*> *temp = [NSMutableDictionary dictionaryWithCapacity:128];  // will be autoreleased
+    NSMutableSet<NSNumber*> *temp_configured = [NSMutableSet setWithCapacity:128];  // will be autoreleased
+    NSMutableSet<NSNumber*> *temp_missing_value = [NSMutableSet setWithCapacity:128];  // will be autoreleased
+    NSDictionary *apple_settings = [[NSUserDefaults standardUserDefaults] persistentDomainForName:@"com.apple.symbolichotkeys"];
+    if (apple_settings) {
+        NSDictionary<NSString*, id> *symbolic_hotkeys = [apple_settings objectForKey:@"AppleSymbolicHotKeys"];
+        if (symbolic_hotkeys) {
+            for (NSString *key in symbolic_hotkeys) {
+                id obj = symbolic_hotkeys[key];
+                if (![key isKindOfClass:[NSString class]] || ![obj isKindOfClass:[NSDictionary class]]) continue;
+                NSInteger sc = [key integerValue];
+                NSDictionary *sc_value = obj;
+                id enabled = [sc_value objectForKey:@"enabled"];
+                if (!enabled || ![enabled isKindOfClass:[NSNumber class]]) continue;
+                [temp_configured addObject:@(sc)];
+                if (![enabled boolValue]) continue;
+                id v = [sc_value objectForKey:@"value"];
+                if (!v || ![v isKindOfClass:[NSDictionary class]]) {
+                    if ([enabled boolValue]) [temp_missing_value addObject:@(sc)];
+                    continue;
+                }
+                NSDictionary *value = v;
+                id t = [value objectForKey:@"type"];
+                if (!t || ![t isKindOfClass:[NSString class]] || ![t isEqualToString:@"standard"]) continue;
+                id p = [value objectForKey:@"parameters"];
+                if (!p || ![p isKindOfClass:[NSArray class]] || [(NSArray*)p count] < 2) continue;
+                NSArray<NSNumber*> *parameters = p;
+                NSInteger ch = [parameters[0] isKindOfClass:[NSNumber class]] ? [parameters[0] integerValue] : 0xffff;
+                NSInteger vk = [parameters[1] isKindOfClass:[NSNumber class]] ? [parameters[1] integerValue] : 0xffff;
+                NSEventModifierFlags mods = ([parameters count] > 2 && [parameters[2] isKindOfClass:[NSNumber class]]) ? [parameters[2] unsignedIntegerValue] : 0;
+                mods = USEFUL_MODS(mods);
+                static char buf[64];
+#define S(x, k) snprintf(buf, sizeof(buf) - 1, #x":%lx:%ld", (unsigned long)mods, (long)k)
+                if (ch == 0xffff) { if (vk == 0xffff) continue; S(v, vk); } else S(c, ch);
+                temp[@(buf)] = @(sc);
+                // the move to next window shortcuts also respond to the same shortcut + shift
+                if (is_shiftable_shortcut([key intValue]) && !(mods & NSEventModifierFlagShift)) {
+                    mods |= NSEventModifierFlagShift;
+                    if (ch == 0xffff) S(v, vk); else S(c, ch);
+                    temp[@(buf)] = @(sc);
+                }
+#undef S
+            }
+        }
+    }
+
+    // Add global shortcut definitions when the default enabled shortcut is not defined,
+    // or when the default enabled shortcut is not disabled and is missing a value.
+    // Here are the shortcuts that are enabled by default in the standard ANSI (US) layout.
+    // macOS provides separate configurations for some languages or keyboards.
+    // In general, the rules here will not take effect.
+    static char buf[64];
+#define S(i, t, m, k) if ([temp_configured member:@(i)] == nil || [temp_missing_value member:@(i)] != nil) { \
+        snprintf(buf, sizeof(buf) - 1, #t":%lx:%ld", (unsigned long)m, (long)k); \
+        temp[@(buf)] = @(i); \
+    }
+
+    // launchpad & dock
+    S(kSHKTurnDockHidingOnOrOff, c, (NSEventModifierFlagOption | NSEventModifierFlagCommand), 'd'); // Opt, Cmd, D
+    // mission control
+    S(kSHKMissionControl, v, NSEventModifierFlagControl, 126); // Ctrl, Arrow Up
+    S(kSHKApplicationWindows, v, NSEventModifierFlagControl, 125); // Ctrl, Arrow Down
+    // keyboard
+    S(kSHKMoveFocusToTheMenuBar, v, NSEventModifierFlagControl, 120); // Ctrl, F2
+    S(kSHKMoveFocusToTheDock, v, NSEventModifierFlagControl, 99); // Ctrl, F3
+    S(kSHKMoveFocusToActiveOrNextWindow, v, NSEventModifierFlagControl, 118); // Ctrl, F4
+    S(kSHKMoveFocusToActiveOrNextWindow, v, (NSEventModifierFlagShift | NSEventModifierFlagControl), 118); // Shift, Ctrl, F4
+    S(kSHKMoveFocusToNextWindow, c, NSEventModifierFlagCommand, 96); // Cmd, `
+    S(kSHKMoveFocusToNextWindow, c, (NSEventModifierFlagShift | NSEventModifierFlagCommand), 96); // Shift, Cmd, `
+    S(kSHKMoveFocusToStatusMenus, v, NSEventModifierFlagControl, 100); // Ctrl, F8
+    // input sources
+    S(kSHKSelectThePreviousInputSource, c, NSEventModifierFlagControl, 32); // Ctrl, Space bar
+    S(kSHKSelectNextSourceInInputMenu, c, (NSEventModifierFlagControl | NSEventModifierFlagOption), 32); // Ctrl, Opt, Space bar
+    // spotlight
+    S(kSHKShowSpotlightSearch, c, NSEventModifierFlagCommand, 32); // Cmd, Space bar
+    S(kSHKShowFinderSearchWindow, c, (NSEventModifierFlagOption | NSEventModifierFlagCommand), 32); // Opt, Cmd, Space bar
+
+#undef S
+    global_shortcuts = [[NSDictionary dictionaryWithDictionary:temp] retain];
+    /* NSLog(@"global_shortcuts: %@", global_shortcuts); */
+}
+
+static int
+is_active_apple_global_shortcut(NSEvent *event) {
+    if (global_shortcuts == nil) build_global_shortcuts_lookup();
+    NSEventModifierFlags modifierFlags = USEFUL_MODS([event modifierFlags]);
+    static char lookup_key[64];
+#define LOOKUP(t, k) \
+    snprintf(lookup_key, sizeof(lookup_key) - 1, #t":%lx:%ld", (unsigned long)modifierFlags, (long)k); \
+    NSNumber *sc = global_shortcuts[@(lookup_key)]; \
+    if (sc != nil) return [sc intValue]; \
+
+    if ([event.charactersIgnoringModifiers length] == 1) {
+        if (modifierFlags & NSEventModifierFlagShift) {
+            const uint32_t ch_without_shift = vk_to_unicode_key_with_current_layout([event keyCode]);
+            if (ch_without_shift < GLFW_FKEY_FIRST || ch_without_shift > GLFW_FKEY_LAST) {
+                LOOKUP(c, ch_without_shift);
+            }
+        }
+        const unichar ch = [event.charactersIgnoringModifiers characterAtIndex:0];
+        LOOKUP(c, ch);
+    }
+    unsigned short vk = [event keyCode];
+    if (vk != 0xffff) {
+        LOOKUP(v, vk);
+    }
+#undef LOOKUP
+    return kSHKUnknown;
+}
+
+static bool
+is_useful_apple_global_shortcut(int sc) {
+    switch(sc) {
+        // launchpad & dock
+        case kSHKTurnDockHidingOnOrOff:                   // Opt, Cmd, D
+        case kSHKShowLaunchpad:                           //
+
+        // display
+        case kSHKDecreaseDisplayBrightness1:              // F14 (Fn)
+        case kSHKDecreaseDisplayBrightness2:              // F14 (Fn, Ctrl)
+        case kSHKIncreaseDisplayBrightness1:              // F15 (Fn)
+        case kSHKIncreaseDisplayBrightness2:              // F14 (Fn, Ctrl)
+
+        // mission control
+        case kSHKMissionControl:                          // Ctrl, Arrow Up
+        case kSHKShowNotificationCenter:                  //
+        case kSHKTurnDoNotDisturbOnOrOff:                 //
+        case kSHKApplicationWindows:                      // Ctrl, Arrow Down
+        case kSHKShowDesktop:                             // F11
+        case kSHKMoveLeftASpace:                          // Ctrl, Arrow Left
+        case kSHKMoveRightASpace:                         // Ctrl, Arrow Right
+        case kSHKSwitchToDesktop1:                        // Ctrl, 1
+        case kSHKSwitchToDesktop2:                        // Ctrl, 2
+        case kSHKSwitchToDesktop3:                        // Ctrl, 3
+        case kSHKSwitchToDesktop4:                        // Ctrl, 4
+        case kSHKQuickNote:                               // Fn, Q
+
+        // keyboard
+        /* case kSHKChangeTheWayTabMovesFocus:               // Ctrl, F7 */
+        /* case kSHKTurnKeyboardAccessOnOrOff:               // Ctrl, F1 */
+        case kSHKMoveFocusToTheMenuBar:                   // Ctrl, F2
+        case kSHKMoveFocusToTheDock:                      // Ctrl, F3
+        case kSHKMoveFocusToActiveOrNextWindow:           // Ctrl, F4
+        /* case kSHKMoveFocusToTheWindowToolbar:             // Ctrl, F5 */
+        /* case kSHKMoveFocusToTheFloatingWindow:            // Ctrl, F6 */
+        case kSHKMoveFocusToNextWindow:                   // Cmd, `
+        case kSHKMoveFocusToStatusMenus:                  // Ctrl, F8
+
+        // input sources
+        case kSHKSelectThePreviousInputSource:            // Ctrl, Space bar
+        case kSHKSelectNextSourceInInputMenu:             // Ctrl, Opt, Space bar
+
+        // screenshots
+        /* case kSHKSavePictureOfScreenAsAFile:              // Shift, Cmd, 3 */
+        /* case kSHKCopyPictureOfScreenToTheClipboard:       // Ctrl, Shift, Cmd, 3 */
+        /* case kSHKSavePictureOfSelectedAreaAsAFile:        // Shift, Cmd, 4 */
+        /* case kSHKCopyPictureOfSelectedAreaToTheClipboard: // Ctrl, Shift, Cmd, 4 */
+        /* case kSHKScreenshotAndRecordingOptions:           // Shift, Cmd, 5 */
+
+        // spotlight
+        case kSHKShowSpotlightSearch:                     // Cmd, Space bar
+        case kSHKShowFinderSearchWindow:                  // Opt, Cmd, Space bar
+
+        // accessibility
+        /* case kSHKTurnZoomOnOrOff:                         // Opt, Cmd, 8 */
+        /* case kSHKTurnImageSmoothingOnOrOff:               // Opt, Cmd, Backslash "\" */
+        /* case kSHKZoomOut:                                 // Opt, Cmd, - */
+        /* case kSHKZoomIn:                                  // Opt, Cmd, = */
+        /* case kSHKTurnFocusFollowingOnOrOff:               // */
+        /* case kSHKIncreaseContrast:                        // Ctrl, Opt, Cmd, . */
+        /* case kSHKDecreaseContrast:                        // Ctrl, Opt, Cmd, , */
+        /* case kSHKInvertColors:                            // Ctrl, Opt, Cmd, 8 */
+        /* case kSHKTurnVoiceOverOnOrOff:                    // Cmd, F5 */
+        /* case kSHKShowAccessibilityControls:               // Opt, Cmd, F5 */
+
+        // app shortcuts
+        /* case kSHKShowHelpMenu:                            // Shift, Cmd, / */
+
+        // deprecated (Not shown on macOS Monterey)
+        /* case kSHKMoveFocusToTheWindowDrawer:              // Opt, Cmd, ` */
+        /* case kSHKShowDashboard:                           // F12 */
+        /* case kSHKLookUpInDictionary:                      // Shift, Cmd, E */
+        /* case kSHKHideAndShowFrontRow:                     // Cmd, Esc */
+        /* case kSHKActivateSpaces:                          // F8 */
+            return true;
+        default:
+            return false;
+    }
 }
 
 GLFWAPI GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback) {
@@ -507,33 +806,76 @@ int _glfwPlatformInit(void)
     }
 
     [NSApp setDelegate:_glfw.ns.delegate];
+    static struct {
+        unsigned short virtual_key_code;
+        NSEventModifierFlags input_source_switch_modifiers;
+        NSTimeInterval timestamp;
+    } last_keydown_shortcut_event;
+    last_keydown_shortcut_event.virtual_key_code = 0xffff;
+    last_keydown_shortcut_event.input_source_switch_modifiers = 0;
 
     NSEvent* (^keydown_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
     {
-        NSEventModifierFlags modifierFlags = [event modifierFlags] & NSEventModifierFlagDeviceIndependentFlagsMask;
-        if (is_ctrl_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
-            // Cocoa swallows Ctrl+Tab to cycle between views
-            [[NSApp keyWindow].contentView keyDown:event];
+        debug_key("---------------- key down -------------------\n");
+        debug_key("%s\n", [[event description] UTF8String]);
+        if (!_glfw.ignoreOSKeyboardProcessing) {
+            // first check if there is a global menu bar shortcut
+            if ([[NSApp mainMenu] performKeyEquivalent:event]) {
+                debug_key("keyDown triggerred global menu bar action ignoring\n");
+                last_keydown_shortcut_event.virtual_key_code = [event keyCode];
+                last_keydown_shortcut_event.input_source_switch_modifiers = 0;
+                last_keydown_shortcut_event.timestamp = [event timestamp];
+                return nil;
+            }
+            // now check if there is a useful apple shortcut
+            int global_shortcut = is_active_apple_global_shortcut(event);
+            if (is_useful_apple_global_shortcut(global_shortcut)) {
+                debug_key("keyDown triggerred global macOS shortcut ignoring\n");
+                last_keydown_shortcut_event.virtual_key_code = [event keyCode];
+                // record the modifier keys if switching to the next input source
+                last_keydown_shortcut_event.input_source_switch_modifiers = (global_shortcut == kSHKSelectNextSourceInInputMenu) ? USEFUL_MODS([event modifierFlags]) : 0;
+                last_keydown_shortcut_event.timestamp = [event timestamp];
+                return event;
+            }
         }
-
-        return event;
+        last_keydown_shortcut_event.virtual_key_code = 0xffff;
+        NSWindow *kw = [NSApp keyWindow];
+        if (kw && kw.contentView) [kw.contentView keyDown:event];
+        else debug_key("keyDown ignored as no keyWindow present\n");
+        return nil;
     };
 
     NSEvent* (^keyup_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
     {
-        NSEventModifierFlags modifierFlags = [event modifierFlags] & NSEventModifierFlagDeviceIndependentFlagsMask;
-        if (modifierFlags & NSEventModifierFlagCommand) {
-            // From http://cocoadev.com/index.pl?GameKeyboardHandlingAlmost
-            // This works around an AppKit bug, where key up events while holding
-            // down the command key don't get sent to the key window.
-            [[NSApp keyWindow] sendEvent:event];
-        }
-        if (is_ctrl_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
-            // Cocoa swallows Ctrl+Tab to cycle between views
-            [[NSApp keyWindow].contentView keyUp:event];
+        debug_key("----------------- key up --------------------\n");
+        debug_key("%s\n", [[event description] UTF8String]);
+        if (last_keydown_shortcut_event.virtual_key_code != 0xffff && last_keydown_shortcut_event.virtual_key_code == [event keyCode]) {
+            // ignore as the corresponding key down event triggered a menu bar or macOS shortcut
+            last_keydown_shortcut_event.virtual_key_code = 0xffff;
+            debug_key("keyUp ignored as corresponds to previous keyDown that trigerred a shortcut\n");
+            return nil;
         }
+        NSWindow *kw = [NSApp keyWindow];
+        if (kw && kw.contentView) [kw.contentView keyUp:event];
+        else debug_key("keyUp ignored as no keyWindow present\n");
+        return nil;
+    };
 
-        return event;
+    NSEvent* (^flags_changed_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
+    {
+        debug_key("-------------- flags changed -----------------\n");
+        debug_key("%s\n", [[event description] UTF8String]);
+        last_keydown_shortcut_event.virtual_key_code = 0xffff;
+        // switching to the next input source is only confirmed when all modifier keys are released
+        if (last_keydown_shortcut_event.input_source_switch_modifiers) {
+            if (!([event modifierFlags] & last_keydown_shortcut_event.input_source_switch_modifiers))
+                last_keydown_shortcut_event.input_source_switch_modifiers = 0;
+            return event;
+        }
+        NSWindow *kw = [NSApp keyWindow];
+        if (kw && kw.contentView) [kw.contentView flagsChanged:event];
+        else debug_key("flagsChanged ignored as no keyWindow present\n");
+        return nil;
     };
 
     _glfw.ns.keyUpMonitor =
@@ -542,6 +884,9 @@ int _glfwPlatformInit(void)
     _glfw.ns.keyDownMonitor =
         [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskKeyDown
                                               handler:keydown_block];
+    _glfw.ns.flagsChangedMonitor =
+        [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskFlagsChanged
+                                              handler:flags_changed_block];
 
     if (_glfw.hints.init.ns.chdir)
         changeToResourcesDirectory();
@@ -554,6 +899,13 @@ int _glfwPlatformInit(void)
     };
     [[NSUserDefaults standardUserDefaults] registerDefaults:defaults];
 
+    NSUserDefaults *apple_settings = [[NSUserDefaults alloc] initWithSuiteName:@"com.apple.symbolichotkeys"];
+    [apple_settings addObserver:_glfw.ns.helper
+                     forKeyPath:@"AppleSymbolicHotKeys"
+                        options:NSKeyValueObservingOptionNew
+                        context:NULL];
+    _glfw.ns.appleSettings = apple_settings;
+
     [[NSNotificationCenter defaultCenter]
         addObserver:_glfw.ns.helper
            selector:@selector(selectedKeyboardInputSourceChanged:)
@@ -609,6 +961,8 @@ void _glfwPlatformTerminate(void)
                     object:nil];
         [[NSNotificationCenter defaultCenter]
             removeObserver:_glfw.ns.helper];
+        if (_glfw.ns.appleSettings)
+            [_glfw.ns.appleSettings removeObserver:_glfw.ns.helper forKeyPath:@"AppleSymbolicHotKeys"];
         [_glfw.ns.helper release];
         _glfw.ns.helper = nil;
     }
@@ -617,10 +971,18 @@ void _glfwPlatformTerminate(void)
         [NSEvent removeMonitor:_glfw.ns.keyUpMonitor];
     if (_glfw.ns.keyDownMonitor)
         [NSEvent removeMonitor:_glfw.ns.keyDownMonitor];
+    if (_glfw.ns.flagsChangedMonitor)
+        [NSEvent removeMonitor:_glfw.ns.flagsChangedMonitor];
+
+    if (_glfw.ns.appleSettings != nil) {
+        [_glfw.ns.appleSettings release];
+        _glfw.ns.appleSettings = nil;
+    }
 
     free(_glfw.ns.clipboardString);
 
     _glfwTerminateNSGL();
+    if (global_shortcuts != nil) { [global_shortcuts release]; global_shortcuts = nil; }
 
     } // autoreleasepool
 }
@@ -703,7 +1065,7 @@ typedef struct {
 static Timer timers[128] = {{0}};
 static size_t num_timers = 0;
 
-static inline void
+static void
 remove_timer_at(size_t idx) {
     if (idx < num_timers) {
         Timer *t = timers + idx;