diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 32b8f7c1c..c0979d9a7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -76,7 +76,7 @@ jobs:
python-version: 3.8
- name: Install build-only deps
- run: pip install flake8 mypy types-requests types-docutils sphinx
+ run: pip install -r docs/requirements.txt flake8 mypy types-requests types-docutils
- name: Run pyflakes
run: python -m flake8 --count .
diff --git a/Makefile b/Makefile
index 1db9b9ba7..a82f987af 100644
--- a/Makefile
+++ b/Makefile
@@ -44,3 +44,7 @@ website:
./publish.py --only website
docs: man html
+
+
+develop-docs:
+ $(MAKE) -C docs develop-docs
diff --git a/docs/Makefile b/docs/Makefile
index 5f857fa19..f47d6b089 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -18,3 +18,7 @@ help:
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+develop-docs:
+ sphinx-autobuild --ignore "/home/kovid/work/kitty/docs/generated/*" --watch ../kitty --watch ../kittens -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index d1678db8e..95c4150e2 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -5,118 +5,11 @@
* Distributed under terms of the MIT license.
*/
-.float-left-img {
- float: left;
- margin-right: 1em;
- margin-bottom: 1em;
-}
-
-.float-right-img { float: right; margin-left: 1em; margin-bottom: 1em }
-
-.half-with-img { max-width: 50% }
-
-.fit-img { max-width: 95% }
-
-div.body {
- min-width: 200px;
-}
-
-pre {
- white-space: pre-wrap;
-}
-
-pre.pre {
- white-space: pre;
-}
-
-a[href], input[type="submit"] { cursor: pointer; }
-
-img[style] {
- /* Used for :scale: images to have them render properly but still popup when clicked */
- width: auto !important;
- height: auto !important;
-}
-
-a {
- text-decoration: none !important;
- border-bottom: none !important;
-}
-
-body div.document {
- margin-top: 1ex;
+.sidebar-logo {
+ max-height: 128px;
}
.major-features li {
- margin-top: 0.75ex;
margin-bottom: 0.75ex;
-}
-
-.support-form input[type=submit] {
- border-radius: 6px;
- box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
- background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100);
- border: 1px solid rgb(255, 170, 34);
- display: inline-block;
- color: rgb(51, 51, 51);
- font-family: Arial;
- font-size: 15px;
- font-weight: bold;
- padding: 6px 24px;
- text-decoration: none;
- text-shadow: rgb(255, 238, 102) 0px 1px 0px;
-}
-
-.support-form input[type=submit]:hover {
- background: linear-gradient(rgb(255, 171, 35) 5%, rgb(255, 236, 100) 100%) rgb(255, 171, 35);
-}
-
-.support-form input[type=submit]:focus {
- outline: 0;
-}
-
-
-div.sphinxsidebar {
- font-size: inherit;
- line-height: inherit;
- max-height: 100%;
- overflow-y: auto;
-}
-
-#sidebartoc li {
margin-top: 0.75ex;
- margin-bottom: 0.75ex;
-}
-
-#sidebartoc ul {
- list-style: none !important;
-}
-
-#sidebartoc a[href]:hover {
- color: red;
-}
-
-
-.green {
- color: green;
-}
-
-.cyan {
- color: blue;
-}
-
-.env {
- font-style: italic;
-}
-
-.italic {
- font-style: italic;
-}
-
-.bold {
- font-weight: bold;
-}
-
-.title {
- font-size: larger;
- font-weight: bold
}
diff --git a/docs/_templates/base.html b/docs/_templates/base.html
new file mode 100644
index 000000000..b9ca3170f
--- /dev/null
+++ b/docs/_templates/base.html
@@ -0,0 +1,19 @@
+{% extends "!base.html" %}
+{% block extrahead %}
+ {{ super() }}
+ {%- if analytics_id %}
+
+ {% endif -%}
+{% endblock %}
diff --git a/docs/_templates/localtoc.html b/docs/_templates/localtoc.html
deleted file mode 100644
index 655bdb7c4..000000000
--- a/docs/_templates/localtoc.html
+++ /dev/null
@@ -1,6 +0,0 @@
-{%- if display_toc %}
-
-
-{%- endif %}
diff --git a/docs/_templates/searchbox.html b/docs/_templates/searchbox.html
deleted file mode 100644
index c707c04c5..000000000
--- a/docs/_templates/searchbox.html
+++ /dev/null
@@ -1,22 +0,0 @@
-{#
- basic/searchbox.html
- ~~~~~~~~~~~~~~~~~~~~
-
- Sphinx sidebar template: quick search box.
-
- :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
- :license: BSD, see LICENSE for details.
-#}
-{%- if pagename != "search" and builder != "singlehtml" %}
-
-
-{%- endif %}
diff --git a/docs/_templates/support.html b/docs/_templates/support.html
deleted file mode 100644
index 43338c62c..000000000
--- a/docs/_templates/support.html
+++ /dev/null
@@ -1,7 +0,0 @@
-{% if pagename != "support" %}
-
-
-
-{% endif %}
diff --git a/docs/actions.rst b/docs/actions.rst
index 3430296c9..98e476824 100644
--- a/docs/actions.rst
+++ b/docs/actions.rst
@@ -1,15 +1,9 @@
-:tocdepth: 2
-
Mappable actions
-===================
+==================
.. highlight:: conf
The actions described below can be mapped to any key press or mouse action
using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`.
-.. contents::
- :local:
- :depth: 1
-
.. include:: /generated/actions.rst
diff --git a/docs/binary.rst b/docs/binary.rst
index 723c37de8..49b60a405 100644
--- a/docs/binary.rst
+++ b/docs/binary.rst
@@ -1,6 +1,9 @@
-kitty - Binary install
+Install kitty
========================
+Binary install
+----------------
+
.. |ins| replace:: curl -L :literal:`https://sw.kovidgoyal.net/kitty/installer.sh` | sh /dev/stdin
.. highlight:: sh
diff --git a/docs/build.rst b/docs/build.rst
index 93e7ad175..85afb96f8 100644
--- a/docs/build.rst
+++ b/docs/build.rst
@@ -1,5 +1,5 @@
-Building kitty from source
-==============================
+Build from source
+==================
.. image:: https://github.com/kovidgoyal/kitty/workflows/CI/badge.svg
:alt: Build status
@@ -78,8 +78,8 @@ 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
- `_ however, that is designed to
- run on Linux and is not for the faint of heart.
+ `bypy framework `_ however, that is
+ designed to run on Linux and is not for the faint of heart.
.. note::
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 21bb21e65..7d5539b7e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -37,6 +37,8 @@ To update |kitty|, :doc:`follow the instructions `.
- Wayland: Fix :opt:`initial_window_width/height ` specified
in cells not working on High DPI screens (:iss:`3834`)
+- A new theme for the kitty website with support for dark mode.
+
0.21.2 [2021-06-28]
----------------------
@@ -1716,8 +1718,7 @@ To update |kitty|, :doc:`follow the instructions `.
using standard keyboards) via `IBus
`_ (:iss:`469`)
-- Implement completion for the kitty command in bash and zsh. See
- :ref:`completion`.
+- Implement completion for the kitty command in bash and zsh
- Render the text under the cursor in a fixed color, configurable via
the option :opt:`cursor_text_color` (:iss:`126`)
diff --git a/docs/clipboard.rst b/docs/clipboard.rst
new file mode 100644
index 000000000..1396f55d4
--- /dev/null
+++ b/docs/clipboard.rst
@@ -0,0 +1,29 @@
+Pasting to clipboard
+=======================
+
+|kitty| implements the OSC 52 escape code protocol to get/set the clipboard
+contents (controlled via the :opt:`clipboard_control` setting). There is one
+difference in kitty's implementation compared to some other terminal emulators.
+|kitty| allows sending arbitrary amounts of text to the clipboard. It does so
+by modifying the protocol slightly. Successive OSC 52 escape codes to set the
+clipboard will concatenate, so::
+
+ ]52;c;\
+ ]52;c;\
+
+will result in the clipboard having the contents ``payload1 + payload2``. To
+send a new string to the clipboard send an OSC 52 sequence with an invalid payload
+first, for example::
+
+ ]52;c;!\
+
+Here ``!`` is not valid base64 encoded text, so it clears the clipboard.
+Further, since it is invalid, it should be ignored by terminal emulators
+that do not support this extension, thereby making it safe to use, simply
+always send it before starting a new OSC 52 paste, even if you aren't chunking
+up large pastes, that way kitty won't concatenate your paste, and it will have
+no ill-effects in other terminal emulators.
+
+In case you're using software that can't be easily adapted to this
+protocol extension, it can be disabled by specifying ``no-append`` to the
+:opt:`clipboard_control` setting.
diff --git a/docs/color-stack.rst b/docs/color-stack.rst
new file mode 100644
index 000000000..c3f8f7fa1
--- /dev/null
+++ b/docs/color-stack.rst
@@ -0,0 +1,26 @@
+Saving and restoring colors
+==============================
+
+It is often useful for a full screen application with its own color themes to
+set the default foreground, background, selection and cursor colors and the
+ANSI color table. This allows for various performance optimizations when
+drawing the screen. The problem is that if the user previously used the escape
+codes to change these colors herself, then running the full screen application
+will lose her changes even after it exits. To avoid this, kitty introduces a
+new pair of *OSC* escape codes to push and pop the current color values from a
+stack::
+
+ ]30001\ # push onto stack
+ ]30101\ # pop from stack
+
+These escape codes save/restore the colors, default
+background, default foreground, selection background, selection foreground and
+cursor color and the 256 colors of the ANSI color table.
+
+.. note:: In July 2020, after several years, XTerm copied this protocol
+ extension, without acknowledgement, and using incompatible escape codes
+ (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not
+ just the dynamic colors but the entire ANSI color table. In the interests of
+ promoting interoperability, kitty added support for XTerm's escape codes as
+ well, and changed this extension to also save/restore the entire ANSI color
+ table.
diff --git a/docs/conf.py b/docs/conf.py
index 916469027..9dd7a2f95 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -22,7 +22,6 @@
Comment, Keyword, Literal, Name, Number, String, Whitespace
)
from sphinx import addnodes, version_info # type: ignore
-from sphinx.environment.adapters.toctree import TocTree # type: ignore
from sphinx.util.logging import getLogger # type: ignore
kitty_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -60,8 +59,14 @@
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
+ 'sphinx_copybutton',
+ 'sphinx_inline_tabs',
+ "sphinxext.opengraph",
]
+# URL for OpenGraph tags
+ogp_site_url = 'https://sw.kovidgoyal.net/kitty/'
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -85,13 +90,10 @@
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [
- '_build', 'Thumbs.db', '.DS_Store',
+ '_build', 'Thumbs.db', '.DS_Store', 'basic.rst',
'generated/cli-*.rst', 'generated/conf-*.rst', 'generated/actions.rst'
]
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
rst_prolog = '''
.. |kitty| replace:: *kitty*
.. |version| replace:: VERSION
@@ -111,32 +113,23 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'alabaster'
+html_theme = 'furo'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
-html_theme_options = {
- 'logo': 'kitty.png',
- 'show_powered_by': False,
- 'fixed_sidebar': True,
- 'sidebar_collapse': True,
- 'github_button': False,
- 'github_banner': True,
- 'github_user': 'kovidgoyal',
- 'github_repo': 'kitty',
- # increase contrast of link color with text color
- 'link': '#00587d',
- 'link_hover': 'green',
+html_theme_options: Dict[str, Any] = {
+ 'sidebar_hide_name': True,
+ 'navigation_with_keys': True,
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static', '../logo/kitty.png']
-html_favicon = '../logo/kitty.png'
+html_static_path = ['_static']
+html_favicon = html_logo = '../logo/kitty.svg'
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
@@ -146,16 +139,8 @@
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
-html_sidebars = {
- '**': [
- 'about.html',
- 'support.html',
- 'searchbox.html',
- 'localtoc.html',
- 'relations.html',
- ]
-}
html_show_sourcelink = False
+html_show_sphinx = False
# -- Options for manual page output ------------------------------------------
@@ -220,28 +205,6 @@ def commit_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, o
# }}}
-# Sidebar ToC {{{
-def create_toc(app: Any, pagename: str) -> Optional[Any]:
- tt = TocTree(app.env)
- toctree = tt.get_toc_for(pagename, app.builder)
- if toctree is not None:
- subtree = toctree[toctree.first_child_matching_class(nodes.list_item)]
- bl = subtree.first_child_matching_class(nodes.bullet_list)
- if bl is None:
- return None # Empty ToC
- subtree = subtree[bl]
- # for li in subtree.traverse(nodes.list_item):
- # modify_li(li)
- # subtree['ids'] = [ID]
- return app.builder.render_partial(subtree)['fragment']
-
-
-def add_html_context(app: Any, pagename: str, templatename: str, context: Any, *args: Any) -> None:
- if 'toc' in context:
- context['toc'] = create_toc(app, pagename) or context['toc']
-# }}}
-
-
# CLI docs {{{
def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
from kitty.cli import option_spec_as_rst
@@ -519,6 +482,10 @@ def generate_default_config(definition: Definition, name: str) -> None:
# }}}
+def add_html_context(app: Any, pagename: str, templatename: str, context: Any, *args: Any) -> None:
+ context['analytics_id'] = app.config.analytics_id
+
+
def setup(app: Any) -> None:
os.makedirs('generated/conf', exist_ok=True)
from kittens.runner import all_kitten_names
@@ -526,10 +493,11 @@ def setup(app: Any) -> None:
write_cli_docs(kn)
write_remote_control_protocol_docs()
write_conf_docs(app, kn)
+ app.add_config_value('analytics_id', '', 'env')
+ app.connect('html-page-context', add_html_context)
app.add_css_file('custom.css')
app.add_lexer('session', SessionLexer() if version_info[0] < 3 else SessionLexer)
app.add_role('link', link_role)
app.add_role('iss', partial(num_role, 'issues'))
app.add_role('pull', partial(num_role, 'pull'))
app.add_role('commit', commit_role)
- app.connect('html-page-context', add_html_context)
diff --git a/docs/conf.rst b/docs/conf.rst
index 6dfb3cd6f..17fce5922 100644
--- a/docs/conf.rst
+++ b/docs/conf.rst
@@ -1,6 +1,4 @@
-:tocdepth: 2
-
-Configuring kitty
+Configure kitty
===============================
.. highlight:: conf
@@ -42,7 +40,7 @@ expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if
Sample kitty.conf
-^^^^^^^^^^^^^^^^^^^^^
+--------------------
.. only:: html
@@ -57,3 +55,14 @@ Sample kitty.conf
file with full documentation and all settings commented out. If you
have a pre-existing kitty.conf, then that will be used instead, delete
it to see the sample file.
+
+
+All mappable actions
+------------------------
+
+See the :doc:`list of all the things you can make kitty can do `.
+
+.. toctree::
+ :hidden:
+
+ actions
diff --git a/docs/deccara.rst b/docs/deccara.rst
new file mode 100644
index 000000000..04da22958
--- /dev/null
+++ b/docs/deccara.rst
@@ -0,0 +1,21 @@
+Setting text styles/colors in arbitrary regions of the screen
+------------------------------------------------------------------
+
+There already exists an escape code to set *some* text attributes in arbitrary
+regions of the screen, `DECCARA
+`_. However, it is limited to
+only a few attributes. |kitty| extends this to work with *all* SGR attributes.
+So, for example, this can be used to set the background color in an arbitrary
+region of the screen.
+
+The motivation for this extension is the various problems with the existing
+solution for erasing to background color, namely the *background color erase
+(bce)* capability. See
+`this discussion `_
+and `this FAQ `_
+for a summary of problems with *bce*.
+
+For example, to set the background color to blue in a
+rectangular region of the screen from (3, 4) to (10, 11), you use::
+
+ [2*x[4;3;11;10;44$r[*x
diff --git a/docs/desktop-notifications.rst b/docs/desktop-notifications.rst
new file mode 100644
index 000000000..4eb3f7fa3
--- /dev/null
+++ b/docs/desktop-notifications.rst
@@ -0,0 +1,122 @@
+.. _desktop_notifications:
+
+
+Desktop notifications
+=======================
+
+|kitty| implements an extensible escape code (OSC 99) to show desktop
+notifications. It is easy to use from shell scripts and fully extensible to
+show title and body. Clicking on the notification can optionally focus the
+window it came from, and/or send an escape code back to the application running
+in that window.
+
+The design of the escape code is partially based on the discussion in
+the defunct
+`terminal-wg `_
+
+The escape code has the form::
+
+ 99 ; metadata ; payload
+
+Here ```` is :code:`]` and ```` is
+:code:``. The metadata is a section of colon separated
+:code:`key=value` pairs. Every key must be a single character from the set
+:code:`a-zA-Z` and every value must be a word consisting of characters from
+the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
+interpreted based on the metadata section. The two semi-colons *must* always be
+present even when no metadata is present.
+
+Before going into details, lets see how one can display a simple, single line
+notification from a shell script::
+
+ printf '\x1b]99;;Hello world\x1b\\'
+
+To show a message with a title and a body::
+
+ printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
+ printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\'
+
+The most important key in the metadata is the ``p`` key, it controls how the
+payload is interpreted. A value of ``title`` means the payload is setting the
+title for the notification. A value of ``body`` means it is setting the body,
+and so on, see the table below for full details.
+
+The design of the escape code is fundamentally chunked, this is because
+different terminal emulators have different limits on how large a single escape
+code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
+key is the *notification id* which can be any string containing the characters
+``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
+can only take the values ``0`` and ``1``. A value of ``0`` means the
+notification is not yet done and the terminal emulator should hold off
+displaying it. A value of ``1`` means the notification is done, and should be
+displayed. You can specify the title or body multiple times and the terminal
+emulator will concatenate them, thereby allowing arbitrarily long text
+(terminal emulators are free to impose a sensible limit to avoid
+Denial-of-Service attacks).
+
+Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
+text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
+which case there must be an ``e=1`` key in the metadata to indicate the payload
+is base64 encoded.
+
+When the user clicks the notification, a couple of things can happen, the
+terminal emulator can focus the window from which the notification came, and/or
+it can send back an escape code to the application indicating the notification
+was activated. This is controlled by the ``a`` key which takes a comma
+separated set of values, ``report`` and ``focus``. The value ``focus`` means
+focus the window from which the notification was issued and is the default.
+``report`` means send an escape code back to the application. The format of the
+returned escape code is::
+
+ 99 ; i=identifier ;
+
+The value of ``identifier`` comes from the ``i`` key in the escape code sent by
+the application. If the application sends no identifier, then the terminal
+*must* use ``i=0``. Actions can be preceded by a negative sign to turn them
+off, so for example if you do not want any action, turn off the default
+``focus`` action with::
+
+ a=-focus
+
+Complete specification of all the metadata keys is in the table below. If a
+terminal emulator encounters a key in the metadata it does not understand,
+the key *must* be ignored, to allow for future extensibility of this escape
+code. Similarly if values for known keys are unknown, the terminal emulator
+*should* either ignore the entire escape code or perform a best guess effort
+to display it based on what it does understand.
+
+.. note::
+ It is possible to extend this escape code to allow specifying an icon for
+ the notification, however, given that some platforms, such as macOS, dont
+ allow displaying custom icons on a notification, at all, it was decided to
+ leave it out of the spec for the time being.
+
+ Similarly, features such as scheduled notifications could be added in future
+ revisions.
+
+
+======= ==================== ========= =================
+Key Value Default Description
+======= ==================== ========= =================
+``a`` Comma separated list ``focus`` What action to perform when the
+ of ``report``, notification is clicked
+ ``focus``, with
+ optional leading
+ ``-``
+
+``d`` ``0`` or ``1`` ``1`` Indicates if the notification is
+ complete or not.
+
+``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is base64 encoded UTF-8,
+ otherwise it is plain UTF-8 text with no C0 control codes in it
+
+``i`` ``[a-zA-Z0-9-_+.]`` ``0`` Identifier for the notification
+
+``p`` One of ``title`` or ``title`` Whether the payload is the notification title or body. If a
+ ``body``. notification has no title, the body will be used as title.
+======= ==================== ========= =================
+
+
+.. note::
+ |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
+ desktop notifications.
diff --git a/docs/faq.rst b/docs/faq.rst
index 3f2ee90ec..0fb09a902 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -3,9 +3,6 @@ Frequently Asked Questions
.. highlight:: sh
-.. contents::
- :local:
-
Some special symbols are rendered small/truncated in kitty?
-----------------------------------------------------------
@@ -36,7 +33,7 @@ it by adding the following to your vimrc::
let &t_ut=''
-See :ref:`here ` for why |kitty| does not support background color erase.
+See :doc:`here ` for why |kitty| does not support background color erase.
I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
@@ -54,8 +51,6 @@ type it each time::
alias ssh="kitty +kitten ssh"
-Remember to also setup :ref:`completion`.
-
If for some reason that does not work (typically because the server is using a
non POSIX compliant shell as ``/bin/sh``), you can try using it with ``python``
instead::
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 5961aecc1..0b7c76ecd 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1,3 +1,5 @@
+:orphan:
+
Glossary
=========
diff --git a/docs/graphics-protocol.rst b/docs/graphics-protocol.rst
index 444eacc5e..211d21d55 100644
--- a/docs/graphics-protocol.rst
+++ b/docs/graphics-protocol.rst
@@ -1,18 +1,16 @@
-:tocdepth: 3
-
The terminal graphics protocol
-==================================
+=================================
The goal of this specification is to create a flexible and performant protocol
that allows the program running in the terminal, hereafter called the *client*,
to render arbitrary pixel (raster) graphics to the screen of the terminal
-emulator. The major design goals are
+emulator. The major design goals are:
- * Should not require terminal emulators to understand image formats.
- * Should allow specifying graphics to be drawn at individual pixel positions.
- * The graphics should integrate with the text, in particular it should be possible to draw graphics
- below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
- * Should use optimizations when the client is running on the same computer as the terminal emulator.
+* Should not require terminal emulators to understand image formats.
+* Should allow specifying graphics to be drawn at individual pixel positions.
+* The graphics should integrate with the text, in particular it should be possible to draw graphics
+ below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
+* Should use optimizations when the client is running on the same computer as the terminal emulator.
For some discussion regarding the design choices, see `#33
`_.
@@ -30,23 +28,19 @@ alpha-blending and text over graphics.
Some programs and libraries that use the kitty graphics protocol:
- * `termpdf.py `_ - a terminal PDF/DJVU/CBR viewer
- * `ranger `_ - a terminal file manager, with
- image previews, see this `PR `_
- * :doc:`kitty-diff ` - a side-by-side terminal diff program with support for images
- * `pixcat `_ - a third party CLI and python library that wraps the graphics protocol
- * `neofetch `_ - A command line system
- information tool
- * `viu `_ - a terminal image viewer
- * `glkitty `_ - C library to draw OpenGL shaders in the terminal with a glgears demo
- * `ctx.graphics `_ - Library for drawing graphics
- * `timg `_ - a terminal image and video viewer
- * `notcurses `_ - C library for terminal graphics with bindings for C++, Rust and Python
- * `rasterm `_ - Go library to display images in the the terminal
-
-
-.. contents::
- :local:
+* `termpdf.py `_ - a terminal PDF/DJVU/CBR viewer
+* `ranger `_ - a terminal file manager, with
+ image previews, see this `PR `_
+* :doc:`kitty-diff ` - a side-by-side terminal diff program with support for images
+* `pixcat `_ - a third party CLI and python library that wraps the graphics protocol
+* `neofetch `_ - A command line system
+ information tool
+* `viu `_ - a terminal image viewer
+* `glkitty `_ - C library to draw OpenGL shaders in the terminal with a glgears demo
+* `ctx.graphics `_ - Library for drawing graphics
+* `timg `_ - a terminal image and video viewer
+* `notcurses `_ - C library for terminal graphics with bindings for C++, Rust and Python
+* `rasterm `_ - Go library to display images in the the terminal
Getting the window size
diff --git a/docs/index.rst b/docs/index.rst
index 50bd9e69e..de977cd80 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,426 +1,66 @@
-:tocdepth: 2
-
-==========================================================
-kitty - the fast, featureful, GPU based terminal emulator
+kitty
==========================================================
-.. container:: major-features
+*The fast, feature-rich, GPU based terminal emulator*
- * Offloads rendering to the GPU for :doc:`lower system load ` and
- buttery smooth scrolling. Uses threaded rendering to minimize input latency.
+.. toctree::
+ :hidden:
- * Supports all modern terminal features: :doc:`graphics (images)
- `, unicode, `true-color
- `_,
- OpenType ligatures, mouse protocol, :doc:`hyperlinks `,
- focus tracking, `bracketed paste `_
- and several :doc:`new terminal protocol extensions
- `.
+ quickstart
+ overview
+ faq
+ support
+ performance
+ changelog
+ integrations
+ protocol-extensions
- * Supports tiling multiple terminal :term:`windows ` side by side in different
- :ref:`layouts ` without needing to use an extra program like tmux
- * Can be :doc:`controlled from scripts or the shell prompt `,
- even over SSH.
+.. tab:: Fast
- * Has a framework for :ref:`kittens`, small terminal programs that can be used to
- extend |kitty|'s functionality. For example, they are used for
- :doc:`Unicode input `, :doc:`Hints ` and
- :doc:`Side-by-side diff `.
+ * Offloads rendering to the GPU for :doc:`lower system load `
+ * Uses threaded rendering for absolutely minimal latency
+ * Performance tradeoffs can be :ref:`tuned `
- * Supports :ref:`startup sessions ` which allow you to specify
- the :term:`window`/:term:`tab` layout, working directories and programs to run on startup.
+.. tab:: Capable
- * Cross-platform: |kitty| works on Linux and macOS, but because it uses only
- OpenGL for rendering, it should be trivial to port to other Unix-like platforms.
+ * Graphics, with :doc:`images and animations `
+ * Ligatures and emoji, with :opt:`per glyph font substitution `
+ * Hyperlinks, with :doc:`configurable actions `
- * Allows you to open :ref:`the scrollback buffer ` in a
- separate :term:`overlay window ` using arbitrary programs of
- your choice. This is useful for browsing the history comfortably in a
- pager or editor.
+.. tab:: Scriptable
- * Has :ref:`multiple copy/paste buffers `, like vim.
+ * Control from :doc:`scripts or the shell `
+ * Extend with :ref:`kittens ` using the Python language
+ * Use :ref:`startup sessions ` to specify working environments
+
+.. tab:: Composable
+
+ * Programmble tabs, :ref:`splits ` and multiple :doc:`layouts ` to manage windows
+ * Browse the :ref:`entire history ` or the output from the last command comfortably in pagers and editors
+ * Edit or download :doc:`remote files ` in an existin SSH session
+
+.. tab:: Cross-platform
+
+ * Linux
+ * macOS
+ * Various BSDs
+
+.. tab:: Innovative
+
+ Pioneered various extensions to move the entire terminal ecosystem forward
+
+ * :doc:`graphics-protocol`
+ * :doc:`keyboard-protocol`
+ * Lots more in :doc:`protocol-extensions`
.. figure:: screenshots/screenshot.png
:alt: Screenshot, showing three programs in the 'Tall' layout
:align: center
- :scale: 100%
+ :width: 100%
Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
-
-.. contents::
- :local:
- :depth: 1
-
-
-.. _quickstart:
-
-Quickstart
---------------
-
-Pre-built binaries of |kitty| are available for both macOS and Linux.
-See the :doc:`binary install instructions `. You can also
-:doc:`build from source `.
-
-Additionally, you can use your favorite package manager to install the |kitty|
-package, but note that some Linux distribution packages are woefully outdated.
-|kitty| is available in a vast number of package repositories for macOS
-and Linux.
-
-.. image:: https://repology.org/badge/tiny-repos/kitty.svg
- :target: https://repology.org/project/kitty/versions
- :alt: Number of repositories kitty is available in
-
-See :doc:`Configuring kitty ` for help on configuring |kitty| and
-:doc:`Invocation ` for the command line arguments |kitty| supports.
-
-
-Design philosophy
--------------------
-
-|kitty| is designed for power keyboard users. To that end all its controls
-work with the keyboard (although it fully supports mouse interactions as
-well). Its configuration is a simple, human editable, single file for
-easy reproducibility (I like to store configuration in source control).
-
-The code in |kitty| is designed to be simple, modular and hackable. It is
-written in a mix of C (for performance sensitive parts) and Python (for
-easy hackability of the UI). It does not depend on any large and complex
-UI toolkit, using only OpenGL for rendering everything.
-
-Finally, |kitty| is designed from the ground up to support all modern
-terminal features, such as unicode, true color, bold/italic fonts, text
-formatting, etc. It even extends existing text formatting escape codes,
-to add support for features not available elsewhere, such as colored and
-styled (curly) underlines. One of the design goals of |kitty| is to be
-easily extensible so that new features can be added in the future with
-relatively little effort.
-
-.. include:: basic.rst
-
-.. _layouts:
-
-Layouts
-----------
-
-A :term:`layout` is an arrangement of multiple :term:`kitty windows `
-inside a top-level :term:`OS window `. You can create a new
-:term:`window` using the :sc:`new_window` key combination.
-
-Currently, there are seven layouts available:
-
-* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom
-* **Grid** -- All windows are shown in a grid
-* **Horizontal** -- All windows are shown side-by-side
-* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits
-* **Stack** -- Only a single maximized window is shown at a time
-* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right
-* **Vertical** -- All windows are shown one below the other
-
-By default, all layouts are enabled and you can switch between layouts using
-the :sc:`next_layout` key combination. You can also create shortcuts to select
-particular layouts, and choose which layouts you want to enable/disable, see
-:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in
-:opt:`enabled_layouts` becomes the default layout.
-
-For more details on the layouts and how to use them see :doc:`layouts`.
-
-.. _kittens:
-
-Kittens
-------------------
-
-|kitty| has a framework for easily creating terminal programs that make use of
-its advanced features. These programs are called kittens. They are used both
-to add features to |kitty| itself and to create useful standalone programs.
-Some prominent kittens:
-
-:doc:`icat `
- Display images in the terminal
-
-
-:doc:`diff `
- A fast, side-by-side diff for the terminal with syntax highlighting and
- images
-
-
-:doc:`Unicode Input `
- Easily input arbitrary unicode characters in |kitty| by name or hex code.
-
-
-:doc:`Hints `
- Select and open/paste/insert arbitrary text snippets such as URLs,
- filenames, words, lines, etc. from the terminal screen.
-
-
-:doc:`Remote file `
- Edit, open, or download remote files over SSH easily, by simply clicking on
- the filename.
-
-
-:doc:`Hyperlinked grep `
- Search your files using `ripgrep `_
- and open the results directly in your favorite editor in the terminal,
- at the line containing the search result, simply by clicking on the result you want.
-
-
-:doc:`Broadcast `
- Type in one :term:`kitty window ` and have it broadcast to all (or a subset) of
- other :term:`kitty windows `.
-
-
-:doc:`Panel `
- Draw a GPU accelerated dock panel on your desktop showing the output
- from an arbitrary terminal program.
-
-
-:doc:`Clipboard `
- Copy/paste to the clipboard from shell scripts, even over SSH.
-
-You can also :doc:`Learn to create your own kittens `.
-
-
-Configuring kitty
--------------------
-
-|kitty| is highly configurable, everything from keyboard shortcuts to
-painting frames-per-second. Press :sc:`edit_config_file` in kitty
-to open its fully commented sample config file in your text editor.
-For details see the :doc:`configuration docs `.
-
-
-Remote control
-------------------
-
-|kitty| has a very powerful system that allows you to control it from the
-:doc:`shell prompt, even over SSH `. You can change colors,
-fonts, open new :term:`windows `, :term:`tabs `, set their titles,
-change window layout, get text
-from one window and send text to another, etc, etc. The possibilities are
-endless. See the :doc:`tutorial ` to get started.
-
-.. _sessions:
-
-Startup Sessions
-------------------
-
-You can control the :term:`tabs `, `:term:`kitty window ` layout,
-working directory, startup programs,
-etc. by creating a "session" file and using the :option:`kitty --session`
-command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
-For example:
-
-.. code-block:: session
-
- # Set the layout for the current tab
- layout tall
- # Set the working directory for windows in the current tab
- cd ~
- # Create a window and run the specified command in it
- launch zsh
- # Create a window with some environment variables set and run
- # vim in it
- launch --env FOO=BAR vim
- # Set the title for the next window
- launch --title "Chat with x" irssi --profile x
-
- # Create a new tab (the part after new_tab is the optional tab
- # name which will be displayed in the tab bar, if omitted, the
- # title of the active window will be used instead)
- new_tab my tab
- cd ~/somewhere
- # Set the layouts allowed in this tab
- enabled_layouts tall, stack
- # Set the current layout
- layout stack
- launch zsh
-
- # Create a new OS window
- new_os_window
- # set new window size to 80x25 cells
- os_window_size 80c 25c
- # set the --class for the new OS window
- os_window_class mywindow
- launch sh
- # Make the current window the active (focused) window
- focus
- launch emacs
-
-.. note::
- The :doc:`launch ` command when used in a session file
- cannot create new OS windows, or tabs.
-
-
-Mouse features
--------------------
-
-* You can click on a URL to open it in a browser.
-* You can double click to select a word and then drag to select more words.
-* You can triple click to select a line and then drag to select more lines.
-* You can triple click while holding :kbd:`ctrl+alt` to select from clicked
- point to end of line.
-* You can right click to extend a previous selection.
-* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in
- columns.
-* Selecting text automatically copies it to the primary clipboard (on
- platforms with a primary clipboard).
-* You can middle click to paste from the primary clipboard (on platforms
- with a primary clipboard).
-* You can select text with kitty even when a terminal program has grabbed
- the mouse by holding down the :kbd:`shift` key.
-
-All these actions can be customized in :file:`kitty.conf` as described
-:ref:`here `.
-
-
-Font control
------------------
-
-|kitty| has extremely flexible and powerful font selection features. You can
-specify individual families for the regular, bold, italic and bold+italic
-fonts. You can even specify specific font families for specific ranges of
-unicode characters. This allows precise control over text rendering. It can
-come in handy for applications like powerline, without the need to use patched
-fonts. See the various font related configuration directives in
-:ref:`conf-kitty-fonts`.
-
-
-.. _scrollback:
-
-The scrollback buffer
------------------------
-
-|kitty| supports scrolling back to view history, just like most terminals. You
-can use either keyboard shortcuts or the mouse scroll wheel to do so. However,
-|kitty| has an extra, neat feature. Sometimes you need to explore the
-scrollback buffer in more detail, maybe search for some text or refer to it
-side-by-side while typing in a follow-up command. |kitty| allows you to do this
-by pressing the :sc:`show_scrollback` key-combination, which will open the
-scrollback buffer in your favorite pager program (which is ``less`` by default).
-Colors and text formatting are preserved. You can explore the scrollback buffer
-comfortably within the pager.
-
-Additionally, you can pipe the contents of the scrollback buffer to an
-arbitrary, command running in a new :term:`window`, :term:`tab` or :term:`overlay`,
-for example::
-
- map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
-
-Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1`
-key. See :sc:`show_scrollback` for details.
-
-If you want to use it with an editor such as vim to get more powerful features,
-you can see tips for doing so, in
-`this thread `_.
-
-If you wish to store very large amounts of scrollback to view using the piping or
-:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size`
-option.
-
-.. _cpbuf:
-
-Multiple copy/paste buffers
------------------------------
-
-In addition to being able to copy/paste from the system clipboard, in |kitty| you
-can also setup an arbitrary number of copy paste buffers. To do so, simply add
-something like the following to your :file:`kitty.conf`::
-
- map f1 copy_to_buffer a
- map f2 paste_from_buffer a
-
-This will allow you to press :kbd:`F1` to copy the current selection to an
-internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
-names are arbitrary strings, so you can define as many such buffers as you
-need.
-
-Marks
--------------
-
-kitty has the ability to mark text on the screen based on regular expressions.
-This can be useful to highlight words or phrases when browsing output from long
-running programs or similar. To learn how this feature works, see :doc:`marks`.
-
-
-Frequently Asked Questions
----------------------------------
-
-The list of Frequently Asked Questions (*FAQ*) is :doc:`available here `.
-
-
-Cool integrations for kitty with other CLI tools
---------------------------------------------------
-
-kitty provides extremely powerful interfaces such as :doc:`remote-control` and
-:doc:`kittens/custom` and :doc:`kittens/icat`
-that allow it to be integrated with other tools seamlessly. For a list of such
-user created integrations, see: :doc:`integrations`.
-
-.. _completion:
-
-Completion for kitty
----------------------------------
-
-|kitty| comes with completion for the ``kitty`` command for popular shells.
-
-
-bash
-~~~~~~~~
-
-Add the following to your :file:`~/.bashrc`
-
-.. code-block:: sh
-
- source <(kitty + complete setup bash)
-
-Older versions of bash (for example, v3.2) do not support
-process substitution with the source command, in which
-case you can try an alternative:
-
-.. code-block:: sh
-
- source /dev/stdin <<<"$(kitty + complete setup bash)"
-
-
-zsh
-~~~~~~~~~
-
-Add the following to your :file:`~/.zshrc`
-
-.. code-block:: sh
-
- autoload -Uz compinit
- compinit
- # Completion for kitty
- kitty + complete setup zsh | source /dev/stdin
-
-The important thing above is to make sure the call to |kitty| to load the zsh
-completions happens after the call to :file:`compinit`.
-
-
-fish
-~~~~~~~~
-
-For versions of fish earlier than 3.0.0, add the following to your
-:file:`~/.config/fish/config.fish`. Later versions source completions by default.
-
-.. code-block:: sh
-
- kitty + complete setup fish | source
-
-
-Changelog
-------------------
-
-See :doc:`changelog`.
-
-.. toctree::
- :hidden:
- :glob:
-
- *
- kittens/*
- generated/rc
+To get started see :doc:`quickstart`.
diff --git a/docs/invocation.rst b/docs/invocation.rst
index bdb7da92d..cacbcf380 100644
--- a/docs/invocation.rst
+++ b/docs/invocation.rst
@@ -1,3 +1,5 @@
+:orphan:
+
The kitty command line interface
====================================
diff --git a/docs/keyboard-protocol.rst b/docs/keyboard-protocol.rst
index 7aae1ba7a..e884fafea 100644
--- a/docs/keyboard-protocol.rst
+++ b/docs/keyboard-protocol.rst
@@ -1,5 +1,5 @@
-A protocol for comprehensive keyboard handling in terminals
-=================================================================
+Comprehensive keyboard handling in terminals
+==============================================
There are various problems with the current state of keyboard handling in
terminals. They include:
diff --git a/docs/kittens/diff.rst b/docs/kittens/diff.rst
index 6356ba115..25a99dbc2 100644
--- a/docs/kittens/diff.rst
+++ b/docs/kittens/diff.rst
@@ -1,6 +1,8 @@
-kitty-diff - A fast side-by-side diff tool with syntax highlighting and images
+kitty-diff
================================================================================
+*A fast side-by-side diff tool with syntax highlighting and images*
+
.. highlight:: sh
Major Features
@@ -21,13 +23,10 @@ Major Features
.. figure:: ../screenshots/diff.png
:alt: Screenshot, showing a sample diff
:align: center
- :scale: 100%
+ :width: 100%
Screenshot, showing a sample diff
-.. contents::
- :local:
-
Installation
---------------
@@ -121,8 +120,8 @@ Why does this work only in kitty?
The diff kitten makes use of various features that are :doc:`kitty only
`, such as the :doc:`kitty graphics protocol
-`, the :ref:`extended keyboard protocol
-`, etc. It also leverages terminal program
+`, the :doc:`extended keyboard protocol
+`, etc. It also leverages terminal program
infrastructure I created for all of kitty's other kittens to reduce the amount
of code needed (the entire implementation is under 2000 lines of code).
diff --git a/docs/kittens/hints.rst b/docs/kittens/hints.rst
index 9b552ca89..6982bf679 100644
--- a/docs/kittens/hints.rst
+++ b/docs/kittens/hints.rst
@@ -9,7 +9,7 @@ browser.
.. figure:: ../screenshots/hints_mode.png
:alt: URL hints mode
:align: center
- :scale: 100%
+ :width: 100%
URL hints mode
diff --git a/docs/kittens/hyperlinked_grep.rst b/docs/kittens/hyperlinked_grep.rst
index 16bfccb09..3ea78e670 100644
--- a/docs/kittens/hyperlinked_grep.rst
+++ b/docs/kittens/hyperlinked_grep.rst
@@ -58,7 +58,7 @@ Then, for example, for ZSH, add the following to :file:`.zshrc`::
compdef _rg hg
To learn more about kitty's powerful framework for customizing URL click
-actions, :doc:`see here <../open_actions>`.
+actions, :doc:`see here `.
Hopefully, someday this functionality will make it into some `upstream grep
`_
diff --git a/docs/kittens/icat.rst b/docs/kittens/icat.rst
index f14d708e9..3c2be662d 100644
--- a/docs/kittens/icat.rst
+++ b/docs/kittens/icat.rst
@@ -1,6 +1,8 @@
-icat - Display images in the terminal
+icat
========================================
+*Display images in the terminal*
+
The ``icat`` kitten can be used to display arbitrary images in the |kitty|
terminal. Using it is as simple as::
diff --git a/docs/kittens/panel.rst b/docs/kittens/panel.rst
index 13e0d1084..af62affd3 100644
--- a/docs/kittens/panel.rst
+++ b/docs/kittens/panel.rst
@@ -14,7 +14,7 @@ using terminal programs instead of GUI toolkits.
.. figure:: ../screenshots/panel.png
:alt: Screenshot, showing a sample panel
:align: center
- :scale: 100%
+ :width: 100%
Screenshot, showing a sample panel
diff --git a/docs/kittens/remote_file.rst b/docs/kittens/remote_file.rst
index 1cae3479e..3c661a3a6 100644
--- a/docs/kittens/remote_file.rst
+++ b/docs/kittens/remote_file.rst
@@ -11,7 +11,7 @@ Then hold down :kbd:`ctrl+shift` and click the name of the file.
.. figure:: ../screenshots/remote_file.png
:alt: Remote file actions
:align: center
- :scale: 100%
+ :width: 100%
Remote file actions
diff --git a/docs/kittens/unicode-input.rst b/docs/kittens/unicode-input.rst
index 1a91b68b3..9195607e8 100644
--- a/docs/kittens/unicode-input.rst
+++ b/docs/kittens/unicode-input.rst
@@ -7,7 +7,7 @@ Press :sc:`input_unicode_character` to start the unicode input widget, shown bel
.. figure:: ../screenshots/unicode.png
:alt: A screenshot of the unicode input widget
:align: center
- :scale: 100%
+ :width: 100%
A screenshot of the unicode input widget
diff --git a/docs/kittens_intro.rst b/docs/kittens_intro.rst
new file mode 100644
index 000000000..567a4700a
--- /dev/null
+++ b/docs/kittens_intro.rst
@@ -0,0 +1,66 @@
+.. _kittens:
+
+Extend kitty
+================
+
+.. toctree::
+ :hidden:
+ :glob:
+
+ kittens/icat
+ kittens/diff
+ kittens/unicode-input
+ kittens/hints
+ kittens/remote_file
+ kittens/hyperlinked_grep
+ kittens/custom
+ kittens/*
+
+|kitty| has a framework for easily creating terminal programs that make use of
+its advanced features. These programs are called kittens. They are used both
+to add features to |kitty| itself and to create useful standalone programs.
+Some prominent kittens:
+
+:doc:`icat `
+ Display images in the terminal
+
+
+:doc:`diff `
+ A fast, side-by-side diff for the terminal with syntax highlighting and
+ images
+
+
+:doc:`Unicode Input `
+ Easily input arbitrary unicode characters in |kitty| by name or hex code.
+
+
+:doc:`Hints `
+ Select and open/paste/insert arbitrary text snippets such as URLs,
+ filenames, words, lines, etc. from the terminal screen.
+
+
+:doc:`Remote file `
+ Edit, open, or download remote files over SSH easily, by simply clicking on
+ the filename.
+
+
+:doc:`Hyperlinked grep `
+ Search your files using `ripgrep `_
+ and open the results directly in your favorite editor in the terminal,
+ at the line containing the search result, simply by clicking on the result you want.
+
+
+:doc:`Broadcast `
+ Type in one :term:`kitty window ` and have it broadcast to all (or a subset) of
+ other :term:`kitty windows `.
+
+
+:doc:`Panel `
+ Draw a GPU accelerated dock panel on your desktop showing the output
+ from an arbitrary terminal program.
+
+
+:doc:`Clipboard `
+ Copy/paste to the clipboard from shell scripts, even over SSH.
+
+You can also :doc:`Learn to create your own kittens `.
diff --git a/docs/launch.rst b/docs/launch.rst
index f1a583d5a..6888407d6 100644
--- a/docs/launch.rst
+++ b/docs/launch.rst
@@ -1,4 +1,4 @@
-Launching programs in new windows/tabs
+Launching new tabs/windows
========================================
.. program:: launch
diff --git a/docs/layouts.rst b/docs/layouts.rst
index aeb510407..dcd165d8b 100644
--- a/docs/layouts.rst
+++ b/docs/layouts.rst
@@ -1,5 +1,5 @@
-Layouts
-============
+Arrange windows
+===================
kitty has the ability to define its own windows that can be tiled next to each
other in arbitrary arrangements, based on *Layouts*, see below for examples:
@@ -8,7 +8,7 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
.. figure:: screenshots/screenshot.png
:alt: Screenshot, showing three programs in the 'Tall' layout
:align: center
- :scale: 100%
+ :width: 100%
Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
@@ -16,7 +16,7 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
.. figure:: screenshots/splits.png
:alt: Screenshot, showing windows in the 'Splits' layout
:align: center
- :scale: 100%
+ :width: 100%
Screenshot, showing windows with arbitrary arrangement in the 'Splits'
layout
diff --git a/docs/marks.rst b/docs/marks.rst
index 15c75366e..4c699ce64 100644
--- a/docs/marks.rst
+++ b/docs/marks.rst
@@ -1,5 +1,5 @@
-Marks
-=================
+Mark text on screen
+========================
kitty has the ability to mark text on the screen based on regular expressions.
diff --git a/docs/open_actions.rst b/docs/open_actions.rst
index 70b20588a..79a4f37f9 100644
--- a/docs/open_actions.rst
+++ b/docs/open_actions.rst
@@ -1,10 +1,11 @@
-Customizing the actions taken when clicking on links
+Scripting the mouse click
======================================================
-|kitty| has support for `terminal hyperlinks `_. These
+|kitty| has support for `terminal hyperlinks
+`_. These
are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
-``mdcat``, etc. You can customize exactly what happens when clicking on these hyperlinks
-in |kitty|.
+``mdcat``, etc. You can customize exactly what happens when clicking on these
+hyperlinks in |kitty|.
You can tell kitty to take arbitrarily many, complex actions
when a link is clicked. Let us illustrate with some examples, first. Create
diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644
index 000000000..de43d81ef
--- /dev/null
+++ b/docs/overview.rst
@@ -0,0 +1,287 @@
+Overview
+==============
+
+Design philosophy
+-------------------
+
+|kitty| is designed for power keyboard users. To that end all its controls
+work with the keyboard (although it fully supports mouse interactions as
+well). Its configuration is a simple, human editable, single file for
+easy reproducibility (I like to store configuration in source control).
+
+The code in |kitty| is designed to be simple, modular and hackable. It is
+written in a mix of C (for performance sensitive parts) and Python (for
+easy hackability of the UI). It does not depend on any large and complex
+UI toolkit, using only OpenGL for rendering everything.
+
+Finally, |kitty| is designed from the ground up to support all modern
+terminal features, such as unicode, true color, bold/italic fonts, text
+formatting, etc. It even extends existing text formatting escape codes,
+to add support for features not available elsewhere, such as colored and
+styled (curly) underlines. One of the design goals of |kitty| is to be
+easily extensible so that new features can be added in the future with
+relatively little effort.
+
+.. include:: basic.rst
+
+
+Configuring kitty
+-------------------
+
+|kitty| is highly configurable, everything from keyboard shortcuts to
+painting frames-per-second. Press :sc:`edit_config_file` in kitty
+to open its fully commented sample config file in your text editor.
+For details see the :doc:`configuration docs `.
+
+.. toctree::
+ :hidden:
+
+ conf
+
+
+.. _layouts:
+
+Layouts
+----------
+
+A :term:`layout` is an arrangement of multiple :term:`kitty windows `
+inside a top-level :term:`OS window `. The layout manages all its
+windows automatically, resizing and moving them as needed. You can create a new
+:term:`window` using the :sc:`new_window` key combination.
+
+Currently, there are seven layouts available:
+
+* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom
+* **Grid** -- All windows are shown in a grid
+* **Horizontal** -- All windows are shown side-by-side
+* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits
+* **Stack** -- Only a single maximized window is shown at a time
+* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right
+* **Vertical** -- All windows are shown one below the other
+
+By default, all layouts are enabled and you can switch between layouts using
+the :sc:`next_layout` key combination. You can also create shortcuts to select
+particular layouts, and choose which layouts you want to enable/disable, see
+:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in
+:opt:`enabled_layouts` becomes the default layout.
+
+For more details on the layouts and how to use them see :doc:`the documentation
+`.
+
+.. toctree::
+ :hidden:
+
+ layouts
+
+Extending kitty
+------------------
+
+kitty has a powerful framework for scripting. You can create small terminal
+programs called :doc:`kittens `. These can used to add features
+to kitty, for example, :doc:`editing remote files ` or
+:doc:`inputting unicode characters `. They can also be
+used to create programs that leverage kitty's powerful features, for example,
+:doc:`viewing images ` or :doc:`diffing files with images
+`.
+
+You can :doc:`create your own kittens to scratch your own itches
+`.
+
+For a list of all the builtin kittens, :ref:`see here `.
+
+.. toctree::
+ :hidden:
+
+ kittens_intro
+
+
+Remote control
+------------------
+
+|kitty| has a very powerful system that allows you to control it from the
+:doc:`shell prompt, even over SSH `. You can change colors,
+fonts, open new :term:`windows `, :term:`tabs `, set their titles,
+change window layout, get text
+from one window and send text to another, etc, etc. The possibilities are
+endless. See the :doc:`tutorial ` to get started.
+
+.. toctree::
+ :hidden:
+
+ remote-control
+
+
+.. _sessions:
+
+Startup Sessions
+------------------
+
+You can control the :term:`tabs `, `:term:`kitty window ` layout,
+working directory, startup programs,
+etc. by creating a "session" file and using the :option:`kitty --session`
+command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
+For example:
+
+.. code-block:: session
+
+ # Set the layout for the current tab
+ layout tall
+ # Set the working directory for windows in the current tab
+ cd ~
+ # Create a window and run the specified command in it
+ launch zsh
+ # Create a window with some environment variables set and run
+ # vim in it
+ launch --env FOO=BAR vim
+ # Set the title for the next window
+ launch --title "Chat with x" irssi --profile x
+
+ # Create a new tab (the part after new_tab is the optional tab
+ # name which will be displayed in the tab bar, if omitted, the
+ # title of the active window will be used instead)
+ new_tab my tab
+ cd ~/somewhere
+ # Set the layouts allowed in this tab
+ enabled_layouts tall, stack
+ # Set the current layout
+ layout stack
+ launch zsh
+
+ # Create a new OS window
+ new_os_window
+ # set new window size to 80x25 cells
+ os_window_size 80c 25c
+ # set the --class for the new OS window
+ os_window_class mywindow
+ launch sh
+ # Make the current window the active (focused) window
+ focus
+ launch emacs
+
+.. note::
+ The :doc:`launch ` command when used in a session file
+ cannot create new OS windows, or tabs.
+
+
+Launching new tabs/windows
+-------------------------------
+
+kitty can be told to run arbitrary programs in new :term:`tabs `,
+:term:`windows ` or :term:`overlays ` at a keypress.
+To learn how to do this, see :doc:`here `.
+
+.. toctree::
+ :hidden:
+
+ launch
+
+
+Mouse features
+-------------------
+
+* You can click on a URL to open it in a browser.
+* You can double click to select a word and then drag to select more words.
+* You can triple click to select a line and then drag to select more lines.
+* You can triple click while holding :kbd:`ctrl+alt` to select from clicked
+ point to end of line.
+* You can right click to extend a previous selection.
+* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in
+ columns.
+* Selecting text automatically copies it to the primary clipboard (on
+ platforms with a primary clipboard).
+* You can middle click to paste from the primary clipboard (on platforms
+ with a primary clipboard).
+* You can 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 `.
+
+
+Scripting the mouse click
+---------------------------
+
+You can customize what happens when clicking on hyperlinks in kitty,
+having it open files in your editor, download remote files, open things
+in your browser, etc.
+
+For details, see :doc:`here `.
+
+.. toctree::
+ :hidden:
+
+ open_actions
+
+Font control
+-----------------
+
+|kitty| has extremely flexible and powerful font selection features. You can
+specify individual families for the regular, bold, italic and bold+italic
+fonts. You can even specify specific font families for specific ranges of
+unicode characters. This allows precise control over text rendering. It can
+come in handy for applications like powerline, without the need to use patched
+fonts. See the various font related configuration directives in
+:ref:`conf-kitty-fonts`.
+
+
+.. _scrollback:
+
+The scrollback buffer
+-----------------------
+
+|kitty| supports scrolling back to view history, just like most terminals. You
+can use either keyboard shortcuts or the mouse scroll wheel to do so. However,
+|kitty| has an extra, neat feature. Sometimes you need to explore the
+scrollback buffer in more detail, maybe search for some text or refer to it
+side-by-side while typing in a follow-up command. |kitty| allows you to do this
+by pressing the :sc:`show_scrollback` key-combination, which will open the
+scrollback buffer in your favorite pager program (which is ``less`` by default).
+Colors and text formatting are preserved. You can explore the scrollback buffer
+comfortably within the pager.
+
+Additionally, you can pipe the contents of the scrollback buffer to an
+arbitrary, command running in a new :term:`window`, :term:`tab` or :term:`overlay`,
+for example::
+
+ map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
+
+Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1`
+key. See :sc:`show_scrollback` for details.
+
+If you want to use it with an editor such as vim to get more powerful features,
+you can see tips for doing so, in
+`this thread `_.
+
+If you wish to store very large amounts of scrollback to view using the piping or
+:sc:`show_scrollback` features, you can use the :opt:`scrollback_pager_history_size`
+option.
+
+.. _cpbuf:
+
+Multiple copy/paste buffers
+-----------------------------
+
+In addition to being able to copy/paste from the system clipboard, in |kitty| you
+can also setup an arbitrary number of copy paste buffers. To do so, simply add
+something like the following to your :file:`kitty.conf`::
+
+ map f1 copy_to_buffer a
+ map f2 paste_from_buffer a
+
+This will allow you to press :kbd:`F1` to copy the current selection to an
+internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
+names are arbitrary strings, so you can define as many such buffers as you
+need.
+
+
+Marks
+-------------
+
+kitty has the ability to mark text on the screen based on regular expressions.
+This can be useful to highlight words or phrases when browsing output from long
+running programs or similar. To learn how this feature works, see :doc:`marks`.
+
+.. toctree::
+ :hidden:
+
+ marks
diff --git a/docs/performance.rst b/docs/performance.rst
index 8516d369d..8d2e0d9eb 100644
--- a/docs/performance.rst
+++ b/docs/performance.rst
@@ -1,4 +1,4 @@
-|kitty| Performance
+Performance
===================
The main goals for |kitty| performance are user perceived latency while typing
diff --git a/docs/pipe.rst b/docs/pipe.rst
index 8f1289cd8..8afd47a97 100644
--- a/docs/pipe.rst
+++ b/docs/pipe.rst
@@ -1,3 +1,5 @@
+:orphan:
+
Working with the screen and history buffer contents
======================================================
diff --git a/docs/protocol-extensions.rst b/docs/protocol-extensions.rst
index 2d4e477b5..bc5f2bfca 100644
--- a/docs/protocol-extensions.rst
+++ b/docs/protocol-extensions.rst
@@ -1,7 +1,7 @@
-Extensions to the xterm protocol
+Terminal protocol extensions
===================================
-|kitty| has a few extensions to the xterm protocol, to enable advanced features.
+|kitty| has extensions to the legacy terminal protocol, to enable advanced features.
These are typically in the form of new or re-purposed escape codes. While these
extensions are currently |kitty| specific, it would be nice to get some of them
adopted more broadly, to push the state of terminal emulators forward.
@@ -19,301 +19,15 @@ If you wish to discuss these extensions, propose additions/changes to them
please do so by opening issues in the `GitHub
`_ bug tracker.
-.. contents::
- :local:
-Colored and styled underlines
--------------------------------
-
-|kitty| supports colored and styled (wavy) underlines. This is of particular
-use in terminal editors such as vim and emacs to display red, wavy underlines
-under mis-spelled words and/or syntax errors. This is done by re-purposing some
-SGR escape codes that are not used in modern terminals (`CSI codes
-`_)
-
-To set the underline style::
-
- [4:0m # this is no underline
- [4:1m # this is a straight underline
- [4:2m # this is a double underline
- [4:3m # this is a curly underline
- [4:4m # this is a dotted underline (not implemented in kitty)
- [4:5m # this is a dashed underline (not implemented in kitty)
- [4m # this is a straight underline (for backwards compat)
- [24m # this is no underline (for backwards compat)
-
-To set the underline color (this is reserved and as far as I can tell not actually used for anything)::
-
- [58...m
-
-This works exactly like the codes ``38, 48`` that are used to set foreground and
-background color respectively.
-
-To reset the underline color (also previously reserved and unused)::
-
- [59m
-
-The underline color must remain the same under reverse video, if it has a
-color, if not, it should follow the foreground color.
-
-To detect support for this feature in a terminal emulator, query the terminfo database
-for the ``Su`` boolean capability.
-
-Graphics rendering
----------------------
-
-See :doc:`/graphics-protocol` for a description
-of this protocol to enable drawing of arbitrary raster images in the terminal.
-
-
-.. _extended-key-protocol:
-
-Keyboard handling
--------------------
-
-kitty has a :doc:`keyboard protocol ` for reporting key
-presses to terminal applications that solves all key handling issues in
-terminal applications.
-
-.. _ext_styles:
-
-Setting text styles/colors in arbitrary regions of the screen
-------------------------------------------------------------------
-
-There already exists an escape code to set *some* text attributes in arbitrary
-regions of the screen, `DECCARA
-`_. However, it is limited to
-only a few attributes. |kitty| extends this to work with *all* SGR attributes.
-So, for example, this can be used to set the background color in an arbitrary
-region of the screen.
-
-The motivation for this extension is the various problems with the existing
-solution for erasing to background color, namely the *background color erase
-(bce)* capability. See
-`this discussion `_
-and `this FAQ `_
-for a summary of problems with *bce*.
-
-For example, to set the background color to blue in a
-rectangular region of the screen from (3, 4) to (10, 11), you use::
-
- [2*x[4;3;11;10;44$r[*x
-
-
-Saving and restoring colors
----------------------------------------------------------------------------------
-
-It is often useful for a full screen application with its own color themes to
-set the default foreground, background, selection and cursor colors and the
-ANSI color table. This allows for various performance optimizations when
-drawing the screen. The problem is that if the user previously used the escape
-codes to change these colors herself, then running the full screen application
-will lose her changes even after it exits. To avoid this, kitty introduces a
-new pair of *OSC* escape codes to push and pop the current color values from a
-stack::
-
- ]30001\ # push onto stack
- ]30101\ # pop from stack
-
-These escape codes save/restore the colors, default
-background, default foreground, selection background, selection foreground and
-cursor color and the 256 colors of the ANSI color table.
-
-.. note:: In July 2020, after several years, XTerm copied this protocol
- extension, without acknowledgement, and using incompatible escape codes
- (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not
- just the dynamic colors but the entire ANSI color table. In the interests of
- promoting interoperability, kitty added support for XTerm's escape codes as
- well, and changed this extension to also save/restore the entire ANSI color
- table.
-
-
-Pasting to clipboard
-----------------------
-
-|kitty| implements the OSC 52 escape code protocol to get/set the clipboard
-contents (controlled via the :opt:`clipboard_control` setting). There is one
-difference in kitty's implementation compared to some other terminal emulators.
-|kitty| allows sending arbitrary amounts of text to the clipboard. It does so
-by modifying the protocol slightly. Successive OSC 52 escape codes to set the
-clipboard will concatenate, so::
-
- ]52;c;\
- ]52;c;\
-
-will result in the clipboard having the contents ``payload1 + payload2``. To
-send a new string to the clipboard send an OSC 52 sequence with an invalid payload
-first, for example::
-
- ]52;c;!\
-
-Here ``!`` is not valid base64 encoded text, so it clears the clipboard.
-Further, since it is invalid, it should be ignored by terminal emulators
-that do not support this extension, thereby making it safe to use, simply
-always send it before starting a new OSC 52 paste, even if you aren't chunking
-up large pastes, that way kitty won't concatenate your paste, and it will have
-no ill-effects in other terminal emulators.
-
-In case you're using software that can't be easily adapted to this
-protocol extension, it can be disabled by specifying ``no-append`` to the
-:opt:`clipboard_control` setting.
-
-
-.. _unscroll:
-
-Unscrolling the screen
------------------------
-
-This is a small extension to the `SD (Pan up) escape code
-`_ from the VT-420 terminal. The
-``SD`` escape code normally causes the text on screen to scroll down by the
-specified number of lines, with empty lines appearing at the top of the screen.
-This extension allows the new lines to be filled in from the scrollback buffer
-instead of being blank.
-
-The motivation for this is that many modern shells will show completions in a
-block of lines under the cursor, this causes some of the on-screen text to be
-lost even after the completion is completed, because it has scrolled off
-screen. This escape code allows that text to be restored.
-
-If the scrollback buffer is empty or there is no scrollback buffer, such as for
-the alternate screen, then the newly inserted lines must be empty, just as with
-the original ``SD`` escape code. The maximum number of lines that can be
-scrolled down is implementation defined, but must be at least one screen worth.
-
-The syntax of the escape code is identical to that of ``SD`` except that it has
-a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
-`_
-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
-`_.
-
-.. versionadded:: 0.20.2
-
-
-.. _desktop_notifications:
-
-
-Desktop notifications
----------------------------------
-
-|kitty| implements an extensible escape code (OSC 99) to show desktop
-notifications. It is easy to use from shell scripts and fully extensible to
-show title and body. Clicking on the notification can optionally focus the
-window it came from, and/or send an escape code back to the application running
-in that window.
-
-The design of the escape code is partially based on the discussion in
-the defunct
-`terminal-wg `_
-
-The escape code has the form::
-
- 99 ; metadata ; payload
-
-Here ```` is :code:`]` and ```` is
-:code:``. The metadata is a section of colon separated
-:code:`key=value` pairs. Every key must be a single character from the set
-:code:`a-zA-Z` and every value must be a word consisting of characters from
-the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
-interpreted based on the metadata section. The two semi-colons *must* always be
-present even when no metadata is present.
-
-Before going into details, lets see how one can display a simple, single line
-notification from a shell script::
-
- printf '\x1b]99;;Hello world\x1b\\'
-
-To show a message with a title and a body::
-
- printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
- printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\'
-
-The most important key in the metadata is the ``p`` key, it controls how the
-payload is interpreted. A value of ``title`` means the payload is setting the
-title for the notification. A value of ``body`` means it is setting the body,
-and so on, see the table below for full details.
-
-The design of the escape code is fundamentally chunked, this is because
-different terminal emulators have different limits on how large a single escape
-code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
-key is the *notification id* which can be any string containing the characters
-``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
-can only take the values ``0`` and ``1``. A value of ``0`` means the
-notification is not yet done and the terminal emulator should hold off
-displaying it. A value of ``1`` means the notification is done, and should be
-displayed. You can specify the title or body multiple times and the terminal
-emulator will concatenate them, thereby allowing arbitrarily long text
-(terminal emulators are free to impose a sensible limit to avoid
-Denial-of-Service attacks).
-
-Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
-text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
-which case there must be an ``e=1`` key in the metadata to indicate the payload
-is base64 encoded.
-
-When the user clicks the notification, a couple of things can happen, the
-terminal emulator can focus the window from which the notification came, and/or
-it can send back an escape code to the application indicating the notification
-was activated. This is controlled by the ``a`` key which takes a comma
-separated set of values, ``report`` and ``focus``. The value ``focus`` means
-focus the window from which the notification was issued and is the default.
-``report`` means send an escape code back to the application. The format of the
-returned escape code is::
-
- 99 ; i=identifier ;
-
-The value of ``identifier`` comes from the ``i`` key in the escape code sent by
-the application. If the application sends no identifier, then the terminal
-*must* use ``i=0``. Actions can be preceded by a negative sign to turn them
-off, so for example if you do not want any action, turn off the default
-``focus`` action with::
-
- a=-focus
-
-Complete specification of all the metadata keys is in the table below. If a
-terminal emulator encounters a key in the metadata it does not understand,
-the key *must* be ignored, to allow for future extensibility of this escape
-code. Similarly if values for known keys are unknown, the terminal emulator
-*should* either ignore the entire escape code or perform a best guess effort
-to display it based on what it does understand.
-
-.. note::
- It is possible to extend this escape code to allow specifying an icon for
- the notification, however, given that some platforms, such as macOS, dont
- allow displaying custom icons on a notification, at all, it was decided to
- leave it out of the spec for the time being.
-
- Similarly, features such as scheduled notifications could be added in future
- revisions.
-
-
-======= ==================== ========= =================
-Key Value Default Description
-======= ==================== ========= =================
-``a`` Comma separated list ``focus`` What action to perform when the
- of ``report``, notification is clicked
- ``focus``, with
- optional leading
- ``-``
-
-``d`` ``0`` or ``1`` ``1`` Indicates if the notification is
- complete or not.
-
-``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is base64 encoded UTF-8,
- otherwise it is plain UTF-8 text with no C0 control codes in it
-
-``i`` ``[a-zA-Z0-9-_+.]`` ``0`` Identifier for the notification
-
-``p`` One of ``title`` or ``title`` Whether the payload is the notification title or body. If a
- ``body``. notification has no title, the body will be used as title.
-======= ==================== ========= =================
-
-
-.. note::
- |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
- desktop notifications.
+.. toctree::
+ :maxdepth: 1
+
+ underlines
+ graphics-protocol
+ keyboard-protocol
+ desktop-notifications
+ unscroll
+ clipboard
+ color-stack
+ deccara
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
new file mode 100644
index 000000000..7df450812
--- /dev/null
+++ b/docs/quickstart.rst
@@ -0,0 +1,28 @@
+.. _quickstart:
+
+Quickstart
+===========
+
+.. toctree::
+ :hidden:
+
+ binary
+ build
+
+Pre-built binaries of |kitty| are available for both macOS and Linux.
+See the :doc:`binary install instructions `. You can also
+:doc:`build from source `.
+
+Additionally, you can use your favorite package manager to install the |kitty|
+package, but note that some Linux distribution packages are woefully outdated.
+|kitty| is available in a vast number of package repositories for macOS
+and Linux.
+
+.. image:: https://repology.org/badge/tiny-repos/kitty.svg
+ :target: https://repology.org/project/kitty/versions
+ :alt: Number of repositories kitty is available in
+
+See :doc:`Configuring kitty ` for help on configuring |kitty| and
+:doc:`Invocation ` for the command line arguments |kitty| supports.
+
+For a tour of kitty's design and features, see the :doc:`/overview`.
diff --git a/docs/rc_protocol.rst b/docs/rc_protocol.rst
index ea34df4fb..95ad2b29e 100644
--- a/docs/rc_protocol.rst
+++ b/docs/rc_protocol.rst
@@ -1,5 +1,5 @@
-Documentation for the kitty remote control protocol
-======================================================
+The kitty remote control protocol
+==================================
The kitty remote control protocol is a simple protocol that involves sending
data to kitty in the form of JSON. Any individual command of kitty has the
@@ -37,5 +37,4 @@ 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 .
-
.. include:: generated/rc.rst
diff --git a/docs/remote-control.rst b/docs/remote-control.rst
index 81e57d213..cca38976c 100644
--- a/docs/remote-control.rst
+++ b/docs/remote-control.rst
@@ -1,6 +1,4 @@
-:tocdepth: 2
-
-Controlling kitty from scripts or the shell
+Control kitty from scripts
==============================================
.. highlight:: sh
@@ -174,10 +172,15 @@ Now press, F1 and start typing, what you type will be sent to all windows,
live, as you type it.
-Documentation for the remote control protocol
+The remote control protocol
-----------------------------------------------
If you wish to develop your own client to talk to |kitty|, you
-can use the :doc:`rc_protocol`.
+can use the :doc:`protocol specification `.
+
+.. toctree::
+ :hidden:
+
+ rc_protocol
.. include:: generated/cli-kitty-at.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 000000000..5a57e5492
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,5 @@
+sphinx
+furo
+sphinx-copybutton
+sphinxext-opengraph
+sphinx-inline-tabs
diff --git a/docs/underlines.rst b/docs/underlines.rst
new file mode 100644
index 000000000..de63eaae2
--- /dev/null
+++ b/docs/underlines.rst
@@ -0,0 +1,36 @@
+Colored and styled underlines
+================================
+
+|kitty| supports colored and styled (wavy) underlines. This is of particular
+use in terminal editors such as vim and emacs to display red, wavy underlines
+under mis-spelled words and/or syntax errors. This is done by re-purposing some
+SGR escape codes that are not used in modern terminals (`CSI codes
+`_)
+
+To set the underline style::
+
+ [4:0m # this is no underline
+ [4:1m # this is a straight underline
+ [4:2m # this is a double underline
+ [4:3m # this is a curly underline
+ [4:4m # this is a dotted underline (not implemented in kitty)
+ [4:5m # this is a dashed underline (not implemented in kitty)
+ [4m # this is a straight underline (for backwards compat)
+ [24m # this is no underline (for backwards compat)
+
+To set the underline color (this is reserved and as far as I can tell not actually used for anything)::
+
+ [58...m
+
+This works exactly like the codes ``38, 48`` that are used to set foreground and
+background color respectively.
+
+To reset the underline color (also previously reserved and unused)::
+
+ [59m
+
+The underline color must remain the same under reverse video, if it has a
+color, if not, it should follow the foreground color.
+
+To detect support for this feature in a terminal emulator, query the terminfo database
+for the ``Su`` boolean capability.
diff --git a/docs/unscroll.rst b/docs/unscroll.rst
new file mode 100644
index 000000000..bd05071db
--- /dev/null
+++ b/docs/unscroll.rst
@@ -0,0 +1,34 @@
+.. _unscroll:
+
+Unscrolling the screen
+========================
+
+This is a small extension to the `SD (Pan up) escape code
+`_ from the VT-420 terminal. The
+``SD`` escape code normally causes the text on screen to scroll down by the
+specified number of lines, with empty lines appearing at the top of the screen.
+This extension allows the new lines to be filled in from the scrollback buffer
+instead of being blank.
+
+The motivation for this is that many modern shells will show completions in a
+block of lines under the cursor, this causes some of the on-screen text to be
+lost even after the completion is completed, because it has scrolled off
+screen. This escape code allows that text to be restored.
+
+If the scrollback buffer is empty or there is no scrollback buffer, such as for
+the alternate screen, then the newly inserted lines must be empty, just as with
+the original ``SD`` escape code. The maximum number of lines that can be
+scrolled down is implementation defined, but must be at least one screen worth.
+
+The syntax of the escape code is identical to that of ``SD`` except that it has
+a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
+`_
+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
+`_.
+
+.. versionadded:: 0.20.2
diff --git a/kitty/actions.py b/kitty/actions.py
index 70289e1ba..374985063 100644
--- a/kitty/actions.py
+++ b/kitty/actions.py
@@ -91,17 +91,13 @@ def as_rst() -> str:
a(title)
a('-' * len(title))
a('')
- a('.. contents::')
- a(' :local:')
- a(' :depth: 1')
- a('')
for action in allg[group]:
a('')
a(f'.. _action-{action.name}:')
a('')
a(action.name)
- a('^' * len(action.name))
+ a('+' * len(action.name))
a('')
a(action.short_help)
a('')
diff --git a/kitty/conf/types.py b/kitty/conf/types.py
index db7331ce5..60ee7f3c6 100644
--- a/kitty/conf/types.py
+++ b/kitty/conf/types.py
@@ -428,7 +428,7 @@ def as_rst(self, conf_name: str, shortcut_slugs: Dict[str, Tuple[str, str]], kit
a(f'.. _conf-{conf_name}-{self.name}:')
a('')
a(self.title)
- heading_level = '+' if level > 1 else '^'
+ heading_level = '+' if level > 1 else '-'
a(heading_level * (len(self.title) + 20))
a('')
if self.start_text:
diff --git a/publish.py b/publish.py
index 5dbd27a3c..6e07dc098 100755
--- a/publish.py
+++ b/publish.py
@@ -63,7 +63,7 @@ def run_man(args: Any) -> None:
def run_html(args: Any) -> None:
- call('make FAIL_WARN=-W "OPTS=-D html_theme_options.analytics_id=UA-20736318-2" dirhtml', cwd=docs_dir)
+ call('make FAIL_WARN=-W "OPTS=-D analytics_id=UA-20736318-2" dirhtml', cwd=docs_dir)
add_old_redirects('docs/_build/dirhtml')