Docs: Improve the documentations

Add more text roles and links. Fix typos. Adjust the default shortcut order in overview. Notes on the impact of kitty-open.desktop on the default open apps. Document KITTY_DEVELOP_FROM in glossary. Add Python type hints to the watcher example. Mention clone-in-kitty in launch --copy-env. Fix remote control ls example does not work, by escaping the backslash.
2022-04-30 16:55:04 +08:00 · 2022-04-30 16:55:04 +08:00 · 13303416b8
commit 13303416b8
parent b9fd039668
27 changed files with 585 additions and 530 deletions
--- a/docs/basic.rst
+++ b/docs/basic.rst
@ -1,12 +1,13 @@
 Tabs and Windows
 -------------------
-|kitty| is capable of running multiple programs organized into tabs and
+|kitty| is capable of running multiple programs organized into tabs and windows.
-windows. The top level of organization is the *Tab*. Each tab consists
+The top level of organization is the :term:`OS window <os_window>`. Each OS
-of one or more *windows*. The windows can be arranged in multiple
+window consists of one or :term:`tabs <tab>`. Each tab consists of one or more
-different layouts, like windows are organized in a tiling window
+:term:`kitty windows <window>`. The kitty windows can be arranged in multiple
-manager. The keyboard controls (which are all customizable) for tabs and
+different :term:`layouts <layout>`, like windows are organized in a tiling
-windows are:
+window manager. The keyboard controls (which are :ref:`all customizable
 <conf-kitty-shortcuts>`) for tabs and windows are:
 Scrolling
 ~~~~~~~~~~~~~~
@ -64,8 +65,9 @@ Focus specific window       :sc:`first_window`, :sc:`second_window` ... :sc:`ten
                            (clockwise from the top-left)
 ========================    =======================
-Additionally, you can define shortcuts in :file:`kitty.conf` to focus neighboring
+Additionally, you can define shortcuts in :file:`kitty.conf` to focus
-windows and move windows around (similar to window movement in vim)::
+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
@ -77,20 +79,20 @@ 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 (starting from
+: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 ``nth_os_window``. Only positive
+To switch to the nth OS window, you can define :ac:`nth_os_window`. Only
-numbers are accepted, starting from one.
+positive numbers are accepted, starting from one.
 .. _detach_window:
-You can define shortcuts to detach the current window and
+You can define shortcuts to detach the current window and move it to another tab
-move it to another tab or another OS window::
+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
@ -106,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
+Finally, you can define a shortcut to close all windows in a tab other than the
-the currently active window::
+currently active window::
    map f9 close_other_windows_in_tab
@ -124,18 +126,18 @@ 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 maximized                    :sc:`toggle_maximized`
-Input unicode character             :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
+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)
 Pass current selection to program   :sc:`pass_selection_to_program`
 Edit |kitty| config file            :sc:`edit_config_file` (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`
--- a/docs/binary.rst
+++ b/docs/binary.rst
@ -21,7 +21,7 @@ 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 ``PATH`` create a symlink in :file:`~/.local/bin` or
+   to add it to your :envvar:`PATH`, create a symlink in :file:`~/.local/bin` or
   :file:`/usr/bin` or wherever.
@ -30,11 +30,12 @@ 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
+<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
+the :file:`.dmg` and install as normal. If you are on Linux, download the
-and extract it into a directory. The |kitty| executable will be in the
+tarball and extract it into a directory. The |kitty| executable will be in the
 :file:`bin` sub-directory.
 Desktop integration on Linux
 --------------------------------
@ -57,9 +58,19 @@ particular desktop, but it should work for most major desktop environments.
    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
--- a/docs/build.rst
+++ b/docs/build.rst
@ -7,21 +7,21 @@ Build from source
 .. highlight:: sh
-|kitty| is designed to run from source, for easy hack-ability. Make sure
+|kitty| is designed to run from source, for easy hack-ability. Make sure the
-the following dependencies are installed first.
+following dependencies are installed first.
 .. note::
-   If you just want to test the latest changes to kitty you dont need to build
+   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
+   If you are making small changes only to the Python parts of kitty, there is
-   build kitty at all, instead, assuming you have installed the official kitty
+   no need to build kitty at all, instead, assuming you have installed the
-   binaries, you can simply set the KITTY_DEVELOP_FROM enviroment variable to
+   official kitty binaries, you can simply set the :envvar:`KITTY_DEVELOP_FROM`
-   point to the directory into which you have checked out the kitty source
+   enviroment variable to point to the directory into which you have checked out
-   code. kitty will then load its python code from there. You should use a
+   the kitty source code. kitty will then load its Python code from there. You
-   version of the source that matches the binary version as closely as
+   should use a version of the source that matches the binary version as closely
-   possible, since the two are tightly coupled.
+   as possible, since the two are tightly coupled.
 Dependencies
@ -46,7 +46,9 @@ 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 following packages, if they are not already installed by your distro:
+* 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``
@ -77,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
+If that works, you can create a symlink to the launcher in :file:`~/bin` or some
-some other directory on your PATH so that you can run |kitty| using
+other directory on your PATH so that you can run |kitty| using just ``kitty``.
 just ``kitty``.
 Building kitty.app on macOS from source
@ -90,25 +91,24 @@ 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
+Python and the other dependencies. So if you ever un-install/upgrade those
-you might have to rebuild the app.
+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
-   `bypy framework <https://github.com/kovidgoyal/bypy>`_ however, that is
+   `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.
+   Apple disallows certain functionality, such as notifications for unsigned
-   If you need this functionality, you can try signing the built kitty.app with
+   applications. If you need this functionality, you can try signing the built
-   a self signed certificate, see for example, `here
+   :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>`_.
+   <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,
+   If you are facing issues with ``linker`` while building, try with a ``brew``
-   try with a ``brew`` installed python instead, see :iss:`289`
+   installed Python instead, see :iss:`289` for more discussion.
   for more discussion.
 Build and run from source with Nix
@ -116,13 +116,14 @@ 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.
 Debug builds
@ -132,7 +133,8 @@ 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::
+This includes debug info in the binary for better traces. To build with address
 sanitizer, use::
    make asan
@ -144,46 +146,45 @@ 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|
+This will install |kitty| into the directory :file:`linux-package`. You can run
-with :file:`linux-package/bin/kitty`.  All the files needed to run kitty will be in
+|kitty| with :file:`linux-package/bin/kitty`. All the files needed to run kitty
-:file:`linux-package/lib/kitty`. The terminfo file will be installed into
+will be in :file:`linux-package/lib/kitty`. The terminfo file will be installed
-:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install
+into :file:`linux-package/share/terminfo`. Simply copy these files into
-|kitty|. In other words, :file:`linux-package` is the staging area into which |kitty| is
+:file:`/usr` to install |kitty|. In other words, :file:`linux-package` is the
-installed. You can choose a different staging area, by passing the ``--prefix``
+staging area into which |kitty| is installed. You can choose a different staging
-argument to :file:`setup.py`.
+area, by passing the ``--prefix`` argument to :file:`setup.py`.
 You should probably split |kitty| into three packages:
 :code:`kitty-terminfo`
-    installs the terminfo file
+    Installs the terminfo file
 :code:`kitty-shell-integration`
-    installs the shell integration scripts (the contents of the
+    Installs the shell integration scripts (the contents of the
-    shell-integration directory in the kitty source code, probably to
+    shell-integration directory in the kitty source code), probably to
    :file:`/usr/share/kitty/shell-integration`
 :code:`kitty`
-    installs the main program
+    Installs the main program
-This allows users to install the terminfo and shell integration files on
+This allows users to install the terminfo and shell integration files on servers
-servers into which they ssh, without needing to install all of |kitty|.
+into which they ssh, without needing to install all of |kitty|.
 .. note::
-   You need a couple of extra dependencies to build linux-package.
+   You need a couple of extra dependencies to build linux-package. :file:`tic`
-   :file:`tic` to compile terminfo files, usually found in the
+   to compile terminfo files, usually found in the development package of
-   development package of :file:`ncurses`. Also, if you are building from
+   :file:`ncurses`. Also, if you are building from a git checkout instead of the
-   a git checkout instead of the released source code tarball, you will
+   released source code tarball, you will need to install the dependencies from
-   need to install the dependencies from ``docs/requirements.txt`` to
+   :file:`docs/requirements.txt` to build the kitty documentation. They can be
-   build the kitty documentation. They can be installed most easily with
+   installed most easily with ``python -m pip -r docs/requirements.txt``.
   ``python -m pip -r docs/requirements.txt``.
 This applies to creating packages for |kitty| for macOS package managers such as
 Homebrew or MacPorts as well.
--- a/docs/color-stack.rst
+++ b/docs/color-stack.rst
@ -2,25 +2,25 @@ 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
+set the default foreground, background, selection and cursor colors and the ANSI
-ANSI color table. This allows for various performance optimizations when
+color table. This allows for various performance optimizations when drawing the
-drawing the screen. The problem is that if the user previously used the escape
+screen. The problem is that if the user previously used the escape codes to
-codes to change these colors herself, then running the full screen application
+change these colors themselves, then running the full screen application will
-will lose her changes even after it exits. To avoid this, kitty introduces a
+lose those changes even after it exits. To avoid this, kitty introduces a new
-new pair of *OSC* escape codes to push and pop the current color values from a
+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
+These escape codes save/restore the colors, default background, default
-background, default foreground, selection background, selection foreground and
+foreground, selection background, selection foreground and cursor color and the
-cursor color and the 256 colors of the ANSI color table.
+256 colors of the ANSI color table.
-.. note:: In July 2020, after several years, XTerm copied this protocol
+.. 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
+   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.
--- a/docs/conf.rst
+++ b/docs/conf.rst
@ -3,9 +3,8 @@ kitty.conf
 .. highlight:: conf
-|kitty| is highly customizable, everything from keyboard shortcuts, to
+|kitty| is highly customizable, everything from keyboard shortcuts, to rendering
-rendering frames-per-second. See below for an overview of all customization
+frames-per-second. See below for an overview of all customization possibilities.
 possibilities.
 You can open the config file within kitty by pressing :sc:`edit_config_file`
 (:kbd:`⌘+,` on macOS). A :file:`kitty.conf` with commented default
@ -23,8 +22,8 @@ You can also display the current configuration by pressing :sc:`debug_config`
 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
+character. This works only if the ``#`` character is the first character in the
-in the line.
+line.
 .. _include:
@ -44,7 +43,7 @@ from environment variables. For example::
 .. note:: Syntax highlighting for :file:`kitty.conf` in vim is available via
-   `vim-kitty <https://github.com/fladson/vim-kitty>`_.
+   `vim-kitty <https://github.com/fladson/vim-kitty>`__.
 .. include:: /generated/conf-kitty.rst
@ -55,17 +54,17 @@ Sample kitty.conf
 .. only:: html
-    You can download a sample :file:`kitty.conf` file with all default settings and
+    You can download a sample :file:`kitty.conf` file with all default settings
-    comments describing each setting by clicking: :download:`sample kitty.conf
+    and comments describing each setting by clicking: :download:`sample
-    </generated/conf/kitty.conf>`.
+    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
+   :sc:`edit_config_file` shortcut in kitty. This will generate a config file
-   file with full documentation and all settings commented out. If you
+   with full documentation and all settings commented out. If you have a
-   have a pre-existing kitty.conf, then that will be used instead, delete
+   pre-existing :file:`kitty.conf`, then that will be used instead, delete it to
-   it to see the sample file.
+   see the sample file.
 All mappable actions
--- a/docs/deccara.rst
+++ b/docs/deccara.rst
@ -3,19 +3,18 @@ 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
+<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
+(bce)* capability. See :iss:`this discussion <160#issuecomment-346470545>`
-:iss:`this discussion <160#issuecomment-346470545>`
+and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`__
 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
+For example, to set the background color to blue in a rectangular region of the
-rectangular region of the screen from (3, 4) to (10, 11), you use::
+screen from (3, 4) to (10, 11), you use::
    <ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x
--- a/docs/desktop-notifications.rst
+++ b/docs/desktop-notifications.rst
@ -5,21 +5,20 @@ 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
+notifications. It is easy to use from shell scripts and fully extensible to show
-show title and body.  Clicking on the notification can optionally focus the
+title and body. Clicking on the notification can optionally focus the window it
-window it came from, and/or send an escape code back to the application running
+came from, and/or send an escape code back to the application running in that
-in that window.
+window.
-The design of the escape code is partially based on the discussion in
+The design of the escape code is partially based on the discussion in the
-the defunct
+defunct `terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`__
 `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:`<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
@ -45,28 +44,27 @@ 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
+``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and can only take the
-can only take the values ``0`` and ``1``. A value of ``0`` means the
+values ``0`` and ``1``. A value of ``0`` means the notification is not yet done
-notification is not yet done and the terminal emulator should hold off
+and the terminal emulator should hold off displaying it. A value of ``1`` means
-displaying it. A value of ``1`` means the notification is done, and should be
+the notification is done, and should be displayed. You can specify the title or
-displayed. You can specify the title or body multiple times and the terminal
+body multiple times and the terminal emulator will concatenate them, thereby
-emulator will concatenate them, thereby allowing arbitrarily long text
+allowing arbitrarily long text (terminal emulators are free to impose a sensible
-(terminal emulators are free to impose a sensible limit to avoid
+limit to avoid Denial-of-Service attacks).
 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
+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.
+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
+was activated. This is controlled by the ``a`` key which takes a comma separated
-separated set of values, ``report`` and ``focus``. The value ``focus`` means
+set of values, ``report`` and ``focus``. The value ``focus`` means focus the
-focus the window from which the notification was issued and is the default.
+window from which the notification was issued and is the default. ``report``
-``report`` means send an escape code back to the application. The format of the
+means send an escape code back to the application. The format of the returned
-returned escape code is::
+escape code is::
    <OSC> 99 ; i=identifier ; <terminator>
@ -87,9 +85,9 @@ 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
+   the notification, however, given that some platforms, such as legacy versions
-   allow displaying custom icons on a notification, at all, it was decided to
+   of macOS, don't allow displaying custom images on a notification, it was
-   leave it out of the spec for the time being.
+   decided to leave it out of the spec for the time being.
   Similarly, features such as scheduled notifications could be added in future
   revisions.
@ -107,7 +105,7 @@ Key      Value                 Default    Description
 ``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,
+``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
@ -118,5 +116,6 @@ Key      Value                 Default    Description
 .. note::
-   |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
+   |kitty| also supports the `legacy OSC 9 protocol developed by iTerm2
-   desktop notifications.
+   <https://iterm2.com/documentation-escape-codes.html>`__ for desktop
   notifications.
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@ -67,8 +67,9 @@ Variables that influence kitty behavior
 .. envvar:: VISUAL
-   The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
+   The terminal based text editor (such as :program:`vi` or :program:`nano`)
-   instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
+   kitty uses, when, for instance, opening :file:`kitty.conf` in response to
   :sc:`edit_config_file`.
 .. envvar:: EDITOR
@ -101,6 +102,11 @@ Variables that influence kitty behavior
   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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--- a/docs/integrations.rst
+++ b/docs/integrations.rst
@ -4,8 +4,8 @@ Integrations with other tools
 ================================
 kitty provides extremely powerful interfaces such as :doc:`remote-control` and
-:doc:`kittens/custom` and :doc:`kittens/icat`
+:doc:`kittens/custom` and :doc:`kittens/icat` that allow it to be integrated
-that allow it to be integrated with other tools seamlessly.
+with other tools seamlessly.
 Image and document viewers
@ -30,19 +30,22 @@ Display markdown files nicely formatted with images in the terminal
 `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:
@ -61,8 +64,8 @@ View images in the terminal, similar to kitty's icat.
 `nb <https://github.com/xwmx/nb>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-command line and local web note-taking, bookmarking, archiving, and
+Command line and local web note-taking, bookmarking, archiving, and knowledge
-knowledge base application that uses kitty's graphics protocol for images.
+base application that uses kitty's graphics protocol for images.
 .. _tool_w3m:
@ -75,9 +78,9 @@ images.
 `timg <https://github.com/hzeller/timg>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A terminal image and video viewer, that displays static and animated
+A terminal image and video viewer, that displays static and animated images or
-images or plays videos. Fast multi-threaded loading, JPEG exif rotation,
+plays videos. Fast multi-threaded loading, JPEG exif rotation, grid view and
-grid view and connecting to the webcam make it a versatile terminal utility.
+connecting to the webcam make it a versatile terminal utility.
 System and data visualisation tools
@ -87,7 +90,8 @@ System and data visualisation tools
 `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:
@ -105,16 +109,16 @@ Show images from Julia directly in kitty
 `euporie <https://github.com/joouha/euporie>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A text-based user interface for running and editing Jupyter notebooks,
+A text-based user interface for running and editing Jupyter notebooks, powered
-powered by kitty's graphics protocol for displaying plots
+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
+A graphing and data visualization tool that can be made to display its output in
-output in kitty with the following bash snippet:
+kitty with the following bash snippet:
 .. code-block:: sh
@ -171,26 +175,28 @@ 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
+|kitty| can be integrated into many different terminal based text editors to add
-such a split windows, previews, REPLs etc.
+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:
@ -202,7 +208,7 @@ Allows easily running tests in a terminal window
 `hologram.nvim <https://github.com/edluffy/hologram.nvim>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Terminal image viewer for nvim
+Terminal image viewer for Neovim
 Scrollback manipulation
@ -228,21 +234,21 @@ Miscellaneous
 `kitty-smart-tab <https://github.com/yurikhan/kitty-smart-tab>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-use keys to either control tabs or pass them onto running applications if
+Use keys to either control tabs or pass them onto running applications if no
-no tabs are present
+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
+Use keys to either scroll or pass them onto running applications if no
-no scrollback buffer is present
+scrollback buffer is present
 .. 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:
--- a/docs/kittens/hints.rst
+++ b/docs/kittens/hints.rst
@ -52,7 +52,7 @@ 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
--- a/docs/kittens/query_terminal.rst
+++ b/docs/kittens/query_terminal.rst
@ -5,7 +5,7 @@ This kitten is used to query |kitty| from terminal programs about version, value
 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
+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
--- a/docs/kittens/ssh.rst
+++ b/docs/kittens/ssh.rst
@ -124,7 +124,7 @@ 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
+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
--- a/docs/kittens_intro.rst
+++ b/docs/kittens_intro.rst
@ -20,8 +20,8 @@ Extend with 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
+its advanced features. These programs are called kittens. They are used both to
-to add features to |kitty| itself and to create useful standalone programs.
+add features to |kitty| itself and to create useful standalone programs.
 Some prominent kittens:
 :doc:`icat <kittens/icat>`
@ -33,7 +33,7 @@ Some prominent kittens:
    images
-:doc:`Unicode Input <kittens/unicode_input>`
+:doc:`Unicode input <kittens/unicode_input>`
    Easily input arbitrary Unicode characters in |kitty| by name or hex code.
@ -48,29 +48,31 @@ Some prominent kittens:
 :doc:`Transfer files <kittens/transfer>`
-    Transfer files and directories seamlessly and easily from remote machines over your existing
+    Transfer files and directories seamlessly and easily from remote machines
-    SSH sessions with a simple command.
+    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.
+    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
+    Type in one :term:`kitty window <window>` and have it broadcast to all (or a
-    other :term:`kitty windows <window>`.
+    subset) of other :term:`kitty windows <window>`.
 :doc:`SSH <kittens/ssh>`
-    SSH with automatic shell integration, connection re-use for low latency and easy cloning
+    SSH with automatic :ref:`shell integration <shell_integration>`, connection
-    of local shell and editor configuration to the remote machine.
+    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
+    Draw a GPU accelerated dock panel on your desktop showing the output from an
-    from an arbitrary terminal program.
+    arbitrary terminal program.
 :doc:`Clipboard <kittens/clipboard>`
--- a/docs/launch.rst
+++ b/docs/launch.rst
@ -5,22 +5,21 @@ The :command:`launch` command
 |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.
+in new windows/tabs. It can be mapped to user defined shortcuts in
-It is very powerful and allows sending the contents of
+:file:`kitty.conf`. It is very powerful and allows sending the contents of the
-the current window to the launched program, as well as many other options.
+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
+To run a different program simply pass the command line as arguments to launch::
 launch::
    map f1 launch vim path/to/some/file
-To open a new window with the same working directory as the currently
+To open a new window with the same working directory as the currently active
-active window::
+window::
    map f1 launch --cwd=current
@ -30,9 +29,10 @@ 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
@ -46,16 +46,16 @@ There are many more powerful options, refer to the complete list below.
        map f1 launch_tab vim
        map f2 launch_tab emacs
-    The :kbd:`F1` key will now open vim in a new tab with the current windows
+    The :kbd:`F1` key will now open :program:`vim` in a new tab with the current
-    working directory
+    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, :envvar:`KITTY_PIPE_DATA` whose
+piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA`
-contents are::
+whose contents are::
   KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
@ -73,33 +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
+    Replaced by the number of lines in STDIN. Only present when passing some
-    data to STDIN
+    data to STDIN.
 ``@input-line-number``
-    replaced the number of lines a pager should scroll to match the current
+    Replaced the number of lines a pager should scroll to match the current
-    scroll position in kitty. See :opt:`scrollback_pager` for details
+    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.
+    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.
+    Replaced by the last line on screen. Can be used for pager positioning.
 For example::
@ -112,44 +112,51 @@ For example::
 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):
+    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
+the ``Window`` object the action is occurring on. The ``data`` object is a dict
-a dict that contains event dependent data. Some useful methods and attributes
+that contains event dependent data. Some useful methods and attributes for the
-for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
+``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
+in the window and ``window.id`` is the internal kitty ``id`` of the window.
 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
+it is searched for in the system-wide :envvar:`PATH` environment variable. Note
-this **may not** be the value of ``PATH`` inside a shell, as shell startup scripts
+that this **may not** be the value of :envvar:`PATH` inside a shell, as shell
-often change the value of this variable. If it is not found there, then a
+startup scripts often change the value of this variable. If it is not found
-system specific list of default paths is searched. If it is still not found,
+there, then a system specific list of default paths is searched. If it is still
-then your shell is run and the value of ``PATH`` inside the shell is used.
+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
--- a/docs/layouts.rst
+++ b/docs/layouts.rst
@ -10,7 +10,8 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
    :align: center
    :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
@ -18,21 +19,22 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
    :align: center
    :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,
+There are many different layouts available. They are all enabled by default, you
-you can switch layouts using :sc:`next_layout`. To control which layouts
+can switch layouts using :ac:`next_layout` (:sc:`next_layout` by default). To
-are available use :opt:`enabled_layouts`, the first listed layout becomes
+control which layouts are available use :opt:`enabled_layouts`, the first listed
-the default. Individual layouts and how to use them are described below.
+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
+This is the simplest layout. It displays a single window using all available
-space, other windows are hidden behind it. It has no options::
+space, other windows are hidden behind it. This layout has no options::
    enabled_layouts stack
@ -40,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
+``mirrored`` option when set to ``true`` will cause the full-height windows to
-on the left side of the screen instead of the right. The syntax
+be on the right side of the screen instead of the left. The syntax
-for the options is shown below::
+for the options is::
    enabled_layouts tall:bias=50;full_size=1;mirrored=false
@ -65,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
@ -75,14 +77,13 @@ windows, for example::
 The Fat Layout
 ----------------
-Displays one (or optionally more) full width windows on the top half of the
+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.
+screen. Remaining windows are tiled horizontally on the bottom half of the
-There are options to control how the screen is split vertically ``bias``
+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
+full-width windows there are ``full_size`` (a positive integer). The
-``mirrored`` option when set to ``true`` will cause the narrow windows to be
+``mirrored`` option when set to ``true`` will cause the full-width windows to be
-on the top of the screen instead of the bottom. The syntax for the options is
+on the bottom of the screen instead of the top. The syntax for the options is::
 shown below::
    enabled_layouts fat:bias=50;full_size=1;mirrored=false
@ -100,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
@ -132,20 +138,20 @@ define a few extra key bindings in :file:`kitty.conf`::
    # 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
+    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
+    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
+    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
+    map f7 layout_action rotate
    # Move the active window in the indicated direction
    map shift+up move_window up
@ -164,11 +170,11 @@ 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 when a ``--location`` is not
+are placed into vertical or horizontal splits when a :option:`--location <launch
-specified. A value of ``horizontal`` (same as ``--location=vsplit``)
+--location>` is not specified. A value of ``horizontal`` (same as
-means when a new split is created the two windows will be placed side by side
+``--location=vsplit``) means when a new split is created the two windows will be
-and a value of ``vertical`` (same as ``--location=hsplit``) means the two
+placed side by side and a value of ``vertical`` (same as ``--location=hsplit``)
-windows will be placed one on top of the other. By default::
+means the two windows will be placed one on top of the other. By default::
    enabled_layouts splits:split_axis=horizontal
@ -193,7 +199,7 @@ windows will be placed one on top of the other. 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
@ -213,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
@ -239,14 +245,14 @@ 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
+instructions. In a given window layout only some operations may be possible for
-for a particular window. For example, in the Tall layout you can make the first
+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
@ -256,22 +262,21 @@ action, for example::
   # 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*
-Some layouts take options to control their behavior. For example, the ``fat``
+and *Tall* layouts accept the ``bias`` and ``full_size`` options to control
-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
-how the available space is split up.
+<enabled_layouts>` use::
 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
+instead of ``50%`` of available width. ``bias`` can be any number between ``10``
-and 90.
+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!
--- a/docs/marks.rst
+++ b/docs/marks.rst
@ -53,21 +53,20 @@ If you want to create markers dynamically rather than pre-defining them in
    map f1 create_marker
    map f2 remove_marker
-Then pressing :kbd:`F1` will allow you to enter the marker definition and set
+Then pressing :kbd:`F1` will allow you to enter the marker definition and set it
-it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
+and pressing :kbd:`F2` will remove the marker. :ac:`create_marker` accepts the
-the same syntax as ``toggle_marker`` above. Note that while creating markers,
+same syntax as :ac:`toggle_marker` above. Note that while creating markers, the
-the prompt has history so you can easily re-use previous marker expressions.
+prompt has history so you can easily re-use previous marker expressions.
-You can also use the facilities for :doc:`remote-control` to dynamically
+You can also use the facilities for :doc:`remote-control` to dynamically add or
-add/remove markers.
+remove markers.
 Scrolling to marks
 --------------------
-kitty has an action :ac:`scroll_to_mark` to scroll to the next line that
+kitty has a :ac:`scroll_to_mark` action to scroll to the next line that contains
-contains a mark. You can use it by mapping it to some shortcut in
+a mark. You can use it by mapping it to some shortcut in :file:`kitty.conf`::
 :file:`kitty.conf`::
    map ctrl+p scroll_to_mark prev
    map ctrl+n scroll_to_mark next
@ -92,8 +91,8 @@ The syntax of the :ac:`toggle_marker` action is::
 Here :code:`marker-type` is one of:
-* :code:`text` - simple substring matching
+* :code:`text` - Simple substring matching
-* :code:`itext` - case-insensitive 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`.
@ -104,8 +103,8 @@ 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
+:file:`mymarker.py` and in it create a :code:`marker` function. This function
-function receives the text of the line as input and must yield three numbers,
+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:
--- a/docs/overview.rst
+++ b/docs/overview.rst
@ -4,23 +4,22 @@ Overview
 Design philosophy
 -------------------
-|kitty| is designed for power keyboard users. To that end all its controls
+|kitty| is designed for power keyboard users. To that end all its controls work
-work with the keyboard (although it fully supports mouse interactions as
+with the keyboard (although it fully supports mouse interactions as well). Its
-well). Its configuration is a simple, human editable, single file for
+configuration is a simple, human editable, single file for easy reproducibility
-easy reproducibility (I like to store configuration in source control).
+(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
+written in a mix of C (for performance sensitive parts) and Python (for easy
-easy hackability of the UI). It does not depend on any large and complex
+hackability of the UI). It does not depend on any large and complex UI toolkit,
-UI toolkit, using only OpenGL for rendering everything.
+using only OpenGL for rendering everything.
-Finally, |kitty| is designed from the ground up to support all modern
+Finally, |kitty| is designed from the ground up to support all modern terminal
-terminal features, such as unicode, true color, bold/italic fonts, text
+features, such as Unicode, true color, bold/italic fonts, text formatting, etc.
-formatting, etc. It even extends existing text formatting escape codes,
+It even extends existing text formatting escape codes, to add support for
-to add support for features not available elsewhere, such as colored and
+features not available elsewhere, such as colored and styled (curly) underlines.
-styled (curly) underlines. One of the design goals of |kitty| is to be
+One of the design goals of |kitty| is to be easily extensible so that new
-easily extensible so that new features can be added in the future with
+features can be added in the future with relatively little effort.
 relatively little effort.
 .. include:: basic.rst
@ -28,10 +27,10 @@ relatively little effort.
 Configuring kitty
 -------------------
-|kitty| is highly configurable, everything from keyboard shortcuts to
+|kitty| is highly configurable, everything from keyboard shortcuts to painting
-painting frames-per-second. Press :sc:`edit_config_file` in kitty
+frames-per-second. Press :sc:`edit_config_file` in kitty to open its fully
-to open its fully commented sample config file in your text editor.
+commented sample config file in your text editor. For details see the
-For details see the :doc:`configuration docs <conf>`.
+:doc:`configuration docs <conf>`.
 .. toctree::
   :hidden:
@ -51,17 +50,26 @@ windows automatically, resizing and moving them as needed. You can create a new
 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
+* **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
+
 * **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
+
 * **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
+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.
@ -79,9 +87,9 @@ 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
+: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 images
+: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
@ -101,9 +109,9 @@ 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
+change window layout, get text from one window and send text to another, etc.
-from one window and send text to another, etc, etc. The possibilities are
+The possibilities are endless. See the :doc:`tutorial <remote-control>` to get
-endless. See the :doc:`tutorial <remote-control>` to get started.
+started.
 .. toctree::
   :hidden:
@ -117,10 +125,9 @@ Startup Sessions
 ------------------
 You can control the :term:`tabs <tab>`, :term:`kitty window <window>` layout,
-working directory, startup programs,
+working directory, startup programs, etc. by creating a *session* file and using
-etc. by creating a "session" file and using the :option:`kitty --session`
+the :option:`kitty --session` command line flag or the :opt:`startup_session`
-command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
+option in :file:`kitty.conf`. For example:
 For example:
 .. code-block:: session
@ -130,28 +137,28 @@ For example:
    cd ~
    # Create a window and run the specified command in it
    launch zsh
-    # Create a window with some environment variables set and run
+    # Create a window with some environment variables set and run vim in it
    # 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
+    # Create a new tab
-    # name which will be displayed in the tab bar, if omitted, the
+    # The part after new_tab is the optional tab title which will be displayed in
-    # title of the active window will be used instead)
+    # 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
+    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 80x25 cells (if specifed before new_os_window will apply to first OS window)
+    # Set new window size to 80x24 cells
-    os_window_size 80c 25c
+    os_window_size 80c 24c
-    # set the --class for the new OS window
+    # Set the --class for the new OS window
    os_window_class mywindow
    launch sh
    # Make the current window the active (focused) window
@ -159,8 +166,8 @@ For example:
    launch emacs
 .. note::
-    The :doc:`launch <launch>` command when used in a session file
+    The :doc:`launch <launch>` command when used in a session file cannot create
-    cannot create new OS windows, or tabs.
+    new OS windows, or tabs.
 Creating tabs/windows
@ -182,25 +189,25 @@ 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
+* 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
+* 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
+* Selecting text automatically copies it to the primary clipboard (on platforms
  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
+* You can middle click to paste from the primary clipboard (on platforms with a
-  of the clicked on command in a pager (requires :ref:`shell_integration`)
+  primary clipboard).
-* You can select text with kitty even when a terminal program has grabbed
+* You can right click while holding :kbd:`Ctrl+Shift` to open the output of the
-  the mouse by holding down the :kbd:`shift` key
+  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,
+You can also customize what happens when clicking on :term:`hyperlinks` in
-having it open files in your editor, download remote files, open things
+kitty, having it open files in your editor, download remote files, open things
 in your browser, etc.
 For details, see :doc:`here <open_actions>`.
@ -214,12 +221,11 @@ Font control
 -----------------
 |kitty| has extremely flexible and powerful font selection features. You can
-specify individual families for the regular, bold, italic and bold+italic
+specify individual families for the regular, bold, italic and bold+italic fonts.
-fonts. You can even specify specific font families for specific ranges of
+You can even specify specific font families for specific ranges of Unicode
-unicode characters. This allows precise control over text rendering. It can
+characters. This allows precise control over text rendering. It can comein handy
-come in handy for applications like powerline, without the need to use patched
+for applications like powerline, without the need to use patched fonts. See the
-fonts. See the various font related configuration directives in
+various font related configuration directives in :ref:`conf-kitty-fonts`.
 :ref:`conf-kitty-fonts`.
 .. _scrollback:
@ -229,28 +235,28 @@ 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
+|kitty| has an extra, neat feature. Sometimes you need to explore the scrollback
-scrollback buffer in more detail, maybe search for some text or refer to it
+buffer in more detail, maybe search for some text or refer to it side-by-side
-side-by-side while typing in a follow-up command. |kitty| allows you to do this
+while typing in a follow-up command. |kitty| allows you to do this by pressing
-by pressing the :sc:`show_scrollback` key-combination, which will open the
+the :sc:`show_scrollback` shortcut, which will open the scrollback buffer in
-scrollback buffer in your favorite pager program (which is ``less`` by default).
+your favorite pager program (which is :program:`less` by default). Colors and
-Colors and text formatting are preserved. You can explore the scrollback buffer
+text formatting are preserved. You can explore the scrollback buffer comfortably
-comfortably within the pager.
+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`,
+arbitrary, command running in a new :term:`window`, :term:`tab` or
-for example::
+: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`
+Would open the scrollback buffer in a new :term:`window` when you press the
-key. See :sc:`show_scrollback <show_scrollback>` for details.
+:kbd:`F1` key. See :sc:`show_scrollback <show_scrollback>` for details.
-If you want to use it with an editor such as vim to get more powerful features,
+If you want to use it with an editor such as :program:`vim` to get more powerful
-you can see tips for doing so, in :iss:`this thread <719>`.
+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
+If you wish to store very large amounts of scrollback to view using the piping
-:sc:`show_scrollback <show_scrollback>` features, you can use the
+or :sc:`show_scrollback <show_scrollback>` features, you can use the
 :opt:`scrollback_pager_history_size` option.
@ -258,8 +264,8 @@ 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.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
-<https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
+<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.
@ -274,17 +280,16 @@ See :doc:`shell-integration` for details.
 Multiple copy/paste buffers
 -----------------------------
-In addition to being able to copy/paste from the system clipboard, in |kitty| you
+In addition to being able to copy/paste from the system clipboard, in |kitty|
-can also setup an arbitrary number of copy paste buffers. To do so, simply add
+you can also setup an arbitrary number of copy paste buffers. To do so, simply
-something like the following to your :file:`kitty.conf`::
+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
+names are arbitrary strings, so you can define as many such buffers as you need.
 need.
 Marks
--- a/docs/performance.rst
+++ b/docs/performance.rst
@ -2,30 +2,31 @@ 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
+and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to
-an optimum balance for these. To that end it keeps a cache of each rendered
+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
+glyph in video RAM so that font rendering is not a bottleneck. Interaction with
-with child programs takes place in a separate thread from rendering, to improve
+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`
+There are two config options you can tune to adjust the performance,
-and :opt:`input_delay`. These control the artificial delays introduced into the
+:opt:`repaint_delay` and :opt:`input_delay`. These control the artificial delays
-render loop to reduce CPU usage. See :ref:`conf-kitty-performance` for details.
+introduced into the render loop to reduce CPU usage. See
-See also the :opt:`sync_to_monitor` option to further decrease latency at the cost
+:ref:`conf-kitty-performance` for details. See also the :opt:`sync_to_monitor`
-of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
+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
+You can generate detailed per-function performance data using
-<https://github.com/gperftools/gperftools>`_. Build |kitty| with `make
+`gperftools <https://github.com/gperftools/gperftools>`__. Build |kitty| with
-profile`. Run kitty and perform the task you want to analyse, for example,
+``make profile``. Run kitty and perform the task you want to analyse, for
-scrolling a large file with `less`. After you quit, function call statistics
+example, scrolling a large file with :program:`less`. After you quit, function
-will be printed to `stdout` and you can use tools like *kcachegrind* for more
+call statistics will be printed to STDOUT and you can use tools like
-detailed analysis.
+*KCachegrind* for more detailed analysis.
-Here are some CPU usage numbers for the task of scrolling a file continuously
+Here are some CPU usage numbers for the task of scrolling a file continuously in
-in less.  The CPU usage is for the terminal process and X together and is
+:program:`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
+measured using :program:`htop`. The measurements are taken at the same font and
-size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU
+window size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz``
-with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
+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
+    Some people have asked why kitty does not perform better than terminal XXX
-    the test of sinking large amounts of data, such as catting a large text
+    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
+    file. The answer is because this is not a goal for kitty. kitty deliberately
-    deliberately throttles input parsing and output rendering to minimize
+    throttles input parsing and output rendering to minimize resource usage
-    resource usage while still being able to sink output faster than any real
+    while still being able to sink output faster than any real world program can
-    world program can produce it. Reducing CPU usage, and hence battery drain
+    produce it. Reducing CPU usage, and hence battery drain while achieving
-    while achieving instant response times and smooth scrolling to a human eye
+    instant response times and smooth scrolling to a human eye is a far more
-    is a far more important goal.
+    important goal.
--- a/docs/protocol-extensions.rst
+++ b/docs/protocol-extensions.rst
@ -1,23 +1,24 @@
 Terminal protocol extensions
 ===================================
-|kitty| has extensions to the legacy terminal protocol, to enable advanced features.
+|kitty| has extensions to the legacy terminal protocol, to enable advanced
-These are typically in the form of new or re-purposed escape codes. While these
+features. These are typically in the form of new or re-purposed escape codes.
-extensions are currently |kitty| specific, it would be nice to get some of them
+While these extensions are currently |kitty| specific, it would be nice to get
-adopted more broadly, to push the state of terminal emulators forward.
+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
+while filling in some gaps in the existing xterm protocol. In particular, one of
-of the goals of this specification is explicitly not to "re-imagine" the tty.
+the goals of this specification is explicitly not to "re-imagine" the TTY. The
-The tty should remain what it is -- a device for efficiently processing text
+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
+possible amount of extra functionality into the terminal program itself. This is
-is to make it as easy to implement these protocol extensions as possible,
+to make it as easy to implement these protocol extensions as possible, thereby
-thereby hopefully encouraging their widespread adoption.
+hopefully encouraging their widespread adoption.
-If you wish to discuss these extensions, propose additions/changes to them
+If you wish to discuss these extensions, propose additions or changes to them,
-please do so by opening issues in the `GitHub
+please do so by opening issues in the `GitHub bug tracker
-<https://github.com/kovidgoyal/kitty/issues>`_ bug tracker.
+<https://github.com/kovidgoyal/kitty/issues>`__.
 .. toctree::
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@ -9,9 +9,9 @@ Quickstart
   binary
   build
-Pre-built binaries of |kitty| are available for both macOS and Linux.
+Pre-built binaries of |kitty| are available for both macOS and Linux. See the
-See the :doc:`binary install instructions </binary>`. You can also
+:doc:`binary install instructions </binary>`. You can also :doc:`build from
-:doc:`build from source </build>`.
+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.
@ -25,4 +25,4 @@ and Linux.
 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`.
+For a tour of kitty's design and features, see the :doc:`overview`.
--- a/docs/rc_protocol.rst
+++ b/docs/rc_protocol.rst
@ -16,25 +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
+The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are
-standalone client, use the kitty version that you are developing against. Using
+developing a standalone client, use the kitty version that you are developing
-a version greater than the version of the kitty instance you are talking to,
+against. Using a version greater than the version of the kitty instance you are
-will cause a failure.
+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 optional payload is a JSON object that is specific to the actual command
-The fields in the object for every command are documented below.
+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
+the ``@ ls`` command from the shell using only shell tools.
-as::
+
 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
--- a/docs/shell-integration.rst
+++ b/docs/shell-integration.rst
@ -4,8 +4,8 @@ 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.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
-<https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
+<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.
@ -22,7 +22,7 @@ Features
 * 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
+* 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
@ -30,7 +30,8 @@ Features
 * 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
+* :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.
@ -45,7 +46,7 @@ Configuration
 ---------------
 Shell integration is controlled by the :opt:`shell_integration` option. By
-default, all shell integration is enabled. Individual features can be turned
+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:
@ -63,19 +64,20 @@ no-rc
    variable when kitty runs the shell.
 no-cursor
-    Turn off changing of the text cursor to a bar when editing text.
+    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
+    Note that for the fish shell kitty relies on fish's native title setting
-    setting functionality instead.
+    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
+    machines using the :doc:`ssh kitten <kittens/ssh>` automatically with the
-    working directory as the current window.
+    same working directory as the current window.
-    Note that for the ``fish`` shell this will not disable its built-in current
+    Note that for the fish shell this will not disable its built-in current
    working directory reporting.
 no-prompt-mark
@ -84,8 +86,8 @@ no-prompt-mark
 no-complete
    Turn off completion for the kitty command.
-    Note that for the ``fish`` shell this does not take effect, since fish
+    Note that for the fish shell this does not take effect, since fish already
-    already comes with a kitty completion script.
+    comes with a kitty completion script.
 More ways to browse command output
@ -137,9 +139,9 @@ How it works
 -----------------
 At startup, kitty detects if the shell you have configured (either system wide
-or in kitty.conf) is a supported shell. If so, kitty injects some shell specific
+or the :opt:`shell` option in :file:`kitty.conf`) is a supported shell. If so,
-code into the shell, to enable shell integration. How it does so varies for
+kitty injects some shell specific code into the shell, to enable shell
-different shells.
+integration. How it does so varies for different shells.
 .. tab:: zsh
--- a/docs/underlines.rst
+++ b/docs/underlines.rst
@ -1,24 +1,25 @@
 Colored and styled underlines
 ================================
-|kitty| supports colored and styled (wavy) underlines. This is of particular
+|kitty| supports colored and styled (wavy) underlines. This is of particular use
-use in terminal editors such as vim and emacs to display red, wavy underlines
+in terminal based text editors such as :program:`vim` and :program:`emacs` to
-under mis-spelled words and/or syntax errors. This is done by re-purposing some
+display red, wavy underlines under mis-spelled words and/or syntax errors. This
-SGR escape codes that are not used in modern terminals (`CSI codes
+is done by re-purposing some SGR escape codes that are not used in modern
-<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`_)
+terminals (`CSI codes <https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`__)
 To set the underline style::
-    <ESC>[4:0m  # this is no underline
+    <ESC>[4:0m  # no underline
-    <ESC>[4:1m  # this is a straight underline
+    <ESC>[4:1m  # straight underline
-    <ESC>[4:2m  # this is a double underline
+    <ESC>[4:2m  # double underline
-    <ESC>[4:3m  # this is a curly underline
+    <ESC>[4:3m  # curly underline
-    <ESC>[4:4m  # this is a dotted underline
+    <ESC>[4:4m  # dotted underline
-    <ESC>[4:5m  # this is a dashed underline
+    <ESC>[4:5m  # dashed underline
-    <ESC>[4m    # this is a straight underline (for backwards compat)
+    <ESC>[4m    # straight underline (for backwards compat)
-    <ESC>[24m   # this is no 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)::
+To set the underline color (this is reserved and as far as I can tell not
 actually used for anything)::
    <ESC>[58...m
@ -29,8 +30,8 @@ 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
+The underline color must remain the same under reverse video, if it has a color,
-color, if not, it should follow the foreground color.
+if not, it should follow the foreground color.
-To detect support for this feature in a terminal emulator, query the terminfo database
+To detect support for this feature in a terminal emulator, query the terminfo
-for the ``Su`` boolean capability.
+database for the ``Su`` boolean capability.
--- a/docs/unscroll.rst
+++ b/docs/unscroll.rst
@ -4,10 +4,10 @@ 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
+<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The ``SD``
-``SD`` escape code normally causes the text on screen to scroll down by the
+escape code normally causes the text on screen to scroll down by the specified
-specified number of lines, with empty lines appearing at the top of the screen.
+number of lines, with empty lines appearing at the top of the screen. This
-This extension allows the new lines to be filled in from the scrollback buffer
+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
@ -22,17 +22,17 @@ 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/>`_
+<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>`_.
+<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>`_
+* `mintty <https://github.com/mintty/mintty/releases/tag/3.5.2>`__
--- a/kitty/launch.py
+++ b/kitty/launch.py
@ -36,51 +36,51 @@ def options_spec() -> str:
    return '''
 --window-title --title
 The title to set for the new window. By default, title is controlled by the
-child process. The special value :code:`current` will copy the title from the currently
+child process. The special value :code:`current` will copy the title from the
-active window.
+currently active window.
 --tab-title
 The title for the new tab if launching in a new tab. By default, the title
 of the active window in the tab is used as the tab title. The special value
-:code:`current` will copy the title form the title of the currently active tab.
+:code:`current` will copy the title from the title of the currently active tab.
 --type
 type=choices
 default=window
 choices=window,tab,os-window,overlay,background,clipboard,primary
-Where to launch the child process, in a new kitty window in the current tab,
+Where to launch the child process, in a new kitty :code:`window` in the current
-a new tab, or a new OS window or an overlay over the current window.
+tab, a new :code:`tab`, or a new :code:`os-window` or an :code:`overlay` over
-Note that if the current window already has an overlay, then it will
+the current window. Note that if the current window already has an overlay, then
-open a new window. The value of background means the process will be
+it will open a new window. The value of :code:`background` means the process
-run in the background. The values clipboard and primary are meant
+will be run in the background. The values :code:`clipboard` and :code:`primary`
-to work with :option:`launch --stdin-source` to copy data to the system
+are meant to work with :option:`--stdin-source <launch --stdin-source>` to copy
-clipboard or primary selection.
+data to the system clipboard or primary selection.
 --keep-focus --dont-take-focus
 type=bool-set
-Keep the focus on the currently active window instead of switching
+Keep the focus on the currently active window instead of switching to the newly
-to the newly opened window.
+opened window.
 --cwd
 The working directory for the newly launched child. Use the special value
 :code:`current` to use the working directory of the currently active window.
-The special value :code:`last_reported` uses the last working directory
+The special value :code:`last_reported` uses the last working directory reported
-reported by the shell (needs :ref:`shell_integration` to work). The special
+by the shell (needs :ref:`shell_integration` to work). The special value
-value :code:`oldest` works like :code:`current` but uses the working directory
+:code:`oldest` works like :code:`current` but uses the working directory of the
-of the oldest foreground process associated with the currently active window
+oldest foreground process associated with the currently active window rather
-rather than the newest foreground process.
+than the newest foreground process.
 --env
 type=list
 Environment variables to set in the child process. Can be specified multiple
-times to set different environment variables.  Syntax: :code:`name=value`.
+times to set different environment variables. Syntax: :code:`name=value`. Using
-Using :code:`name=` will set to empty string and just :code:`name` will
+:code:`name=` will set to empty string and just :code:`name` will remove the
-remove the environment variable.
+environment variable.
 --hold
@ -102,121 +102,129 @@ currently active window.
 --copy-env
 type=bool-set
-Copy the environment variables from the currently active window into the
+Copy the environment variables from the currently active window into the newly
-newly launched child process. Note that most shells only set environment
+launched child process. Note that most shells only set environment variables for
-variables for child processes, so this will only copy the environment
+child processes, so this will only copy the environment variables that the shell
-variables that the shell process itself has not the environment variables
+process itself has, not the environment variables child processes inside the
-child processes inside the shell see. To copy that enviroment, use the
+shell see. To copy that enviroment, use the kitty remote control feature with
-kitty remote control feature with :code:`kitty @launch --copy-env`.
+:option:`kitty @ launch --copy-env`, and the :ref:`clone-in-kitty <clone_shell>`
 feature can also be used.
 --location
 type=choices
 default=default
 choices=first,after,before,neighbor,last,vsplit,hsplit,split,default
-Where to place the newly created window when it is added to a tab which
+Where to place the newly created window when it is added to a tab which already
-already has existing windows in it. :code:`after` and :code:`before` place the new
+has existing windows in it. :code:`after` and :code:`before` place the new
-window before or after the active window. :code:`neighbor` is a synonym for :code:`after`.
+window before or after the active window. :code:`neighbor` is a synonym for
-Also applies to creating a new tab, where the value of :code:`after`
+:code:`after`. Also applies to creating a new tab, where the value of
-will cause the new tab to be placed next to the current tab instead of at the end.
+:code:`after` will cause the new tab to be placed next to the current tab
-The values of :code:`vsplit`, :code:`hsplit` and :code:`split` are only used by the
+instead of at the end. The values of :code:`vsplit`, :code:`hsplit` and
-:code:`splits` layout and control if the new window is placed in a vertical,
+:code:`split` are only used by the :code:`splits` layout and control if the new
-horizontal or automatic split with the currently active window. The default is
+window is placed in a vertical, horizontal or automatic split with the currently
-to place the window in a layout dependent manner, typically, after the
+active window. The default is to place the window in a layout dependent manner,
-currently active window.
+typically, after the currently active window.
 --allow-remote-control
 type=bool-set
-Programs running in this window can control kitty (if remote control is
+Programs running in this window can control kitty (even if remote control is not
-enabled). Note that any program with the right level of permissions can still
+enabled in :file:`kitty.conf`). Note that any program with the right level of
-write to the pipes of any other program on the same computer and therefore can
+permissions can still write to the pipes of any other program on the same
-control kitty. It can, however, be useful to block programs running on other
+computer and therefore can control kitty. It can, however, be useful to block
-computers (for example, over ssh) or as other users.
+programs running on other computers (for example, over SSH) or as other users.
 --stdin-source
 type=choices
 default=none
 choices=none,@selection,@screen,@screen_scrollback,@alternate,@alternate_scrollback,@first_cmd_output_on_screen,@last_cmd_output,@last_visited_cmd_output
-Pass the screen contents as :code:`STDIN` to the child process. :code:`@selection` is
+Pass the screen contents as :file:`STDIN` to the child process.
-the currently selected text. :code:`@screen` is the contents of the currently active
+:code:`@selection` is the currently selected text. :code:`@screen` is the
-window. :code:`@screen_scrollback` is the same as :code:`@screen`, but includes the
+contents of the currently active window. :code:`@screen_scrollback` is the same
-scrollback buffer as well. :code:`@alternate` is the secondary screen of the current
+as :code:`@screen`, but includes the scrollback buffer as well.
-active window. For example if you run a full screen terminal application, the
+:code:`@alternate` is the secondary screen of the current active window. For
-secondary screen will be the screen you return to when quitting the application.
+example if you run a full screen terminal application, the secondary screen will
-:code:`@first_cmd_output_on_screen` is the output from the first command run in the shell on screen,
+be the screen you return to when quitting the application.
-:code:`@last_cmd_output` is the output from the last command run in the shell,
+:code:`@first_cmd_output_on_screen` is the output from the first command run in
-:code:`@last_visited_cmd_output` is the first output below the last scrolled position via
+the shell on screen, :code:`@last_cmd_output` is the output from the last
-scroll_to_prompt, this three needs :ref:`shell_integration` to work.
+command run in the shell, :code:`@last_visited_cmd_output` is the first output
 below the last scrolled position via :ac:`scroll_to_prompt`, this three needs
 :ref:`shell integration <shell_integration>` to work.
 --stdin-add-formatting
 type=bool-set
-When using :option:`launch --stdin-source` add formatting escape codes, without this
+When using :option:`--stdin-source <launch --stdin-source>` add formatting
-only plain text will be sent.
+escape codes, without this only plain text will be sent.
 --stdin-add-line-wrap-markers
 type=bool-set
-When using :option:`launch --stdin-source` add a carriage return at every line wrap
+When using :option:`--stdin-source <launch --stdin-source>` add a carriage
-location (where long lines are wrapped at screen edges). This is useful if you
+return at every line wrap location (where long lines are wrapped at screen
-want to pipe to program that wants to duplicate the screen layout of the
+edges). This is useful if you want to pipe to program that wants to duplicate
-screen.
+the screen layout of the screen.
 --marker
 Create a marker that highlights text in the newly created window. The syntax is
-the same as for the :code:`toggle_marker` map action (see :doc:`/marks`).
+the same as for the :ac:`toggle_marker` action (see :doc:`/marks`).
 --os-window-class
-Set the WM_CLASS property on X11 and the application id property on Wayland for
+Set the *WM_CLASS* property on X11 and the application id property on Wayland
-the newly created OS Window when using :option:`launch --type`=os-window.
+for the newly created OS window when using :option:`--type=os-window
-Defaults to whatever is used by the parent kitty process, which in turn
+<launch --type>`. Defaults to whatever is used by the parent kitty process,
-defaults to :code:`kitty`.
+which in turn defaults to :code:`kitty`.
 --os-window-name
-Set the WM_NAME property on X11 for the newly created OS Window when using
+Set the *WM_NAME* property on X11 for the newly created OS Window when using
-:option:`launch --type`=os-window. Defaults to :option:`launch --os-window-class`.
+:option:`--type=os-window <launch --type>`. Defaults to
 :option:`--os-window-class <launch --os-window-class>`.
 --os-window-title
 Set the title for the newly created OS window. This title will override any
-titles set by programs running in kitty. The special value :code:`current`
+titles set by programs running in kitty. The special value :code:`current` will
-will use the title of the current OS Window, if any.
+use the title of the current OS window, if any.
 --logo
-Path to a PNG image to use as the logo for the newly created window. See :opt:`window_logo_path`.
+Path to a PNG image to use as the logo for the newly created window. See
 :opt:`window_logo_path`.
 --logo-position
-The position for the window logo. Only takes effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
+The position for the window logo. Only takes effect if :option:`--logo` is
 specified. See :opt:`window_logo_position`.
 --logo-alpha
 type=float
 default=-1
-The amount the window logo should be faded into the background.
+The amount the window logo should be faded into the background. Only takes
-Only takes effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
+effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
 --color
 type=list
-Change colors in the newly launched window. You can either specify a path to a .conf
+Change colors in the newly launched window. You can either specify a path to a
-file with the same syntax as kitty.conf to read the colors from, or specify them
+:file:`.conf` file with the same syntax as :file:`kitty.conf` to read the colors
-individually, for example: ``--color background=white`` ``--color foreground=red``
+from, or specify them individually, for example: ``--color background=white``
 ``--color foreground=red``
 --watcher -w
 type=list
-Path to a python file. Appropriately named functions in this file will be called
+Path to a Python file. Appropriately named functions in this file will be called
-for various events, such as when the window is resized, focused or closed. See the section
+for various events, such as when the window is resized, focused or closed. See
-on watchers in the launch command documentation: :ref:`watchers`. Relative paths are
+the section on watchers in the launch command documentation: :ref:`watchers`.
-resolved relative to the kitty config directory. Global watchers for all windows can be
+Relative paths are resolved relative to the :ref:`kitty config directory
-specified with :opt:`watcher`.
+<confloc>`. Global watchers for all windows can be specified with
 :opt:`watcher` in :file:`kitty.conf`.
 '''
--- a/kitty/modes.h
+++ b/kitty/modes.h
@ -58,7 +58,7 @@
 // National Replacement Character Set Mode
 #define DECNRCM (42 << 5)
-// Xterm mouse protocol
+// xterm mouse protocol
 #define MOUSE_BUTTON_TRACKING (1000 << 5)
 #define MOUSE_MOTION_TRACKING  (1002 << 5)
 #define MOUSE_MOVE_TRACKING (1003 << 5)
--- a/kitty/parser.c
+++ b/kitty/parser.c
@ -1001,7 +1001,7 @@ dispatch_csi(Screen *screen, PyObject DUMP_UNUSED *dump_callback) {
        case 'm':
            if (start_modifier == '>' && !end_modifier) {
                REPORT_ERROR(
-                    "The application is trying to use XTerm's modifyOtherKeys."
+                    "The application is trying to use xterm's modifyOtherKeys."
                    " This is superseded by the kitty keyboard protocol: https://sw.kovidgoyal.net/kitty/keyboard-protocol/"
                    " the application should be updated to use that"
                );