From 17632dea3cd77e0fdceb0a2745013cd24bdb8f12 Mon Sep 17 00:00:00 2001 From: pagedown Date: Fri, 29 Apr 2022 01:31:11 +0800 Subject: [PATCH] Docs: Improve remote control command documentation Improve the --match option description. Add more text roles and links. Fix typos. --- docs/remote-control.rst | 135 +++++++++++++++-------------- kitty/rc/base.py | 74 ++++++++-------- kitty/rc/close_tab.py | 9 +- kitty/rc/close_window.py | 4 +- kitty/rc/create_marker.py | 2 +- kitty/rc/detach_tab.py | 10 +-- kitty/rc/detach_window.py | 10 +-- kitty/rc/disable_ligatures.py | 4 +- kitty/rc/env.py | 6 +- kitty/rc/get_colors.py | 2 +- kitty/rc/get_text.py | 18 ++-- kitty/rc/goto_layout.py | 4 +- kitty/rc/kitten.py | 8 +- kitty/rc/last_used_layout.py | 2 +- kitty/rc/ls.py | 4 +- kitty/rc/new_window.py | 6 +- kitty/rc/remove_marker.py | 2 +- kitty/rc/resize_os_window.py | 8 +- kitty/rc/resize_window.py | 12 +-- kitty/rc/scroll_window.py | 10 +-- kitty/rc/select_window.py | 10 +-- kitty/rc/send_text.py | 6 +- kitty/rc/set_background_image.py | 6 +- kitty/rc/set_background_opacity.py | 8 +- kitty/rc/set_colors.py | 4 +- kitty/rc/set_enabled_layouts.py | 8 +- kitty/rc/set_font_size.py | 2 +- kitty/rc/set_spacing.py | 20 ++--- kitty/rc/set_tab_color.py | 4 +- kitty/rc/set_tab_title.py | 2 +- kitty/rc/set_window_logo.py | 8 +- kitty/rc/set_window_title.py | 7 +- kitty/rc/signal_child.py | 12 +-- 33 files changed, 220 insertions(+), 207 deletions(-) diff --git a/docs/remote-control.rst b/docs/remote-control.rst index f3cd566f0..377d3185d 100644 --- a/docs/remote-control.rst +++ b/docs/remote-control.rst @@ -4,9 +4,12 @@ Control kitty from scripts .. highlight:: sh |kitty| can be controlled from scripts or the shell prompt. You can open new -windows, send arbitrary text input to any window, name windows and tabs, etc. +windows, send arbitrary text input to any window, change the title of windows +and tabs, etc. + Let's walk through a few examples of controlling |kitty|. + Tutorial ------------ @@ -21,43 +24,44 @@ Now, in the new |kitty| window, enter the command:: kitty @ launch --title Output --keep-focus cat -This will open a new window, running the ``cat`` program that will appear next -to the current window. +This will open a new window, running the :program:`cat` program that will appear +next to the current window. Let's send some text to this new window:: kitty @ send-text --match cmdline:cat Hello, World -This will make ``Hello, World`` show up in the window running the ``cat`` program. -The :option:`kitty @ send-text --match` option is very powerful, it allows selecting windows by their -titles, the command line of the program running in the window, the working -directory of the program running in the window, etc. See ``kitty @ send-text ---help`` for details. +This will make ``Hello, World`` show up in the window running the :program:`cat` +program. The :option:`kitty @ send-text --match` option is very powerful, it +allows selecting windows by their titles, the command line of the program +running in the window, the working directory of the program running in the +window, etc. See :ref:`kitty @ send-text --help ` for details. More usefully, you can pipe the output of a command running in one window to another window, for example:: - ls | kitty @ send-text --match title:Output --stdin + ls | kitty @ send-text --match title:^Output --stdin -This will show the output of ls in the output window instead of the current -window. You can use this technique to, for example, show the output of running -``make`` in your editor in a different window. The possibilities are endless. +This will show the output of :program:`ls` in the output window instead of the +current window. You can use this technique to, for example, show the output of +running :program:`make` in your editor in a different window. The possibilities +are endless. You can even have things you type show up in a different window. Run:: - kitty @ send-text --match title:Output --stdin + kitty @ send-text --match title:^Output --stdin And type some text, it will show up in the output window, instead of the current -window. Type ``Ctrl+D`` when you are ready to stop. +window. Type :kbd:`Ctrl+D` when you are ready to stop. Now, let's open a new tab:: kitty @ launch --type=tab --tab-title "My Tab" --keep-focus bash This will open a new tab running the bash shell with the title "My Tab". -We can change the title of the tab with:: +We can change the title of the tab to "New Title" with:: - kitty @ set-tab-title --match title:My New Title + kitty @ set-tab-title --match title:^My New Title Let's change the title of the current tab:: @@ -65,79 +69,83 @@ Let's change the title of the current tab:: Now lets switch to the newly opened tab:: - kitty @ focus-tab --match title:New + kitty @ focus-tab --match title:^New Similarly, to focus the previously opened output window (which will also switch back to the old tab, automatically):: - kitty @ focus-window --match title:Output + kitty @ focus-window --match title:^Output You can get a listing of available tabs and windows, by running:: kitty @ ls This outputs a tree of data in JSON format. The top level of the tree is all -operating system kitty windows. Each OS window has an id and a list of tabs. -Each tab has its own id, a title and a list of windows. Each window has an id, -title, current working directory, process id (PID) and command-line of the -process running in the window. You can use this information with :option:`kitty @ focus-window --match` -to control individual windows. +:term:`OS windows `. Each OS window has an id and a list of +:term:`tabs `. Each tab has its own id, a title and a list of :term:`kitty +windows `. Each window has an id, title, current working directory, +process id (PID) and command-line of the process running in the window. You can +use this information with :option:`kitty @ focus-window --match` to control +individual windows. -As you can see, it is very easy to control |kitty| using the -``kitty @`` messaging system. This tutorial touches only the -surface of what is possible. See ``kitty @ --help`` for more details. +As you can see, it is very easy to control |kitty| using the ``kitty @`` +messaging system. This tutorial touches only the surface of what is possible. +See ``kitty @ --help`` for more details. -Note that in the example's above, ``kitty @`` messaging works only when run inside a |kitty| window, -not anywhere. But, within a |kitty| window it even works over SSH. If you want to control -|kitty| from programs/scripts not running inside a |kitty| window, you have to implement a couple of -extra steps. First start |kitty| as:: +Note that in the example's above, ``kitty @`` messaging works only when run +inside a |kitty| window, not anywhere. But, within a |kitty| window it even +works over SSH. If you want to control |kitty| from programs/scripts not running +inside a |kitty| window, you have to implement a couple of extra steps. First +start |kitty| as:: kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty -The :option:`kitty --listen-on` option tells |kitty| to listen for control messages at the -specified path. See ``kitty --help`` for details. Now you can control this -instance of |kitty| using the :option:`kitty @ --to` command line argument to ``kitty @``. For example:: +The :option:`kitty --listen-on` option tells |kitty| to listen for control +messages at the specified UNIX-domain socket. See ``kitty --help`` for details. +Now you can control this instance of |kitty| using the :option:`kitty @ --to` +command line argument to ``kitty @``. For example:: kitty @ --to unix:/tmp/mykitty ls -Note that if all you want to do is run a single |kitty| "daemon" and have subsequent -|kitty| invocations appear as new top-level windows, you can use the simpler :option:`kitty --single-instance` -option, see ``kitty --help`` for that. +Note that if all you want to do is run a single |kitty| "daemon" and have +subsequent |kitty| invocations appear as new top-level windows, you can use the +simpler :option:`kitty --single-instance` option, see ``kitty --help`` for that. + The builtin kitty shell -------------------------- -You can explore the |kitty| command language more easily using the builtin |kitty| -shell. Run ``kitty @`` with no arguments and you will be dropped into the |kitty| -shell with completion for |kitty| command names and options. +You can explore the |kitty| command language more easily using the builtin +|kitty| shell. Run ``kitty @`` with no arguments and you will be dropped into +the |kitty| shell with completion for |kitty| command names and options. You can even open the |kitty| shell inside a running |kitty| using a simple keyboard shortcut (:sc:`kitty_shell` by default). .. note:: This has the added advantage that you don't need to use - ``allow_remote_control`` to make it work. + :opt:`allow_remote_control` to make it work. Allowing only some windows to control kitty ---------------------------------------------- -If you do not want to allow all programs running in |kitty| to control it, you can selectively -enable remote control for only some |kitty| windows. Simply create a shortcut -such as:: +If you do not want to allow all programs running in |kitty| to control it, you +can selectively enable remote control for only some |kitty| windows. Simply +create a shortcut such as:: map ctrl+k launch --allow-remote-control some_program Then programs running in windows created with that shortcut can use ``kitty @`` to control kitty. Note that any program with the right level of permissions can -still write to the pipes of any other program on the same computer and -therefore can control |kitty|. It can, however, be useful to block programs -running on other computers (for example, over ssh) or as other users. +still write to the pipes of any other program on the same computer and therefore +can control |kitty|. It can, however, be useful to block programs running on +other computers (for example, over SSH) or as other users. -.. note:: You dont need ``allow_remote_control`` to make this work as it is +.. note:: You don't need :opt:`allow_remote_control` to make this work as it is limited to only programs running in that specific window. Be careful with what programs you run in such windows, since they can effectively control - kitty, as if you were running with ``allow_remote_control`` turned on. + kitty, as if you were running with :opt:`allow_remote_control` turned on. .. _rc_mapping: @@ -148,15 +156,15 @@ Mapping key presses to remote control commands If you wish to trigger a remote control command easily with just a keypress, you can map it in :file:`kitty.conf`. For example:: - map F1 remote_control set-spacing margin=30 + map f1 remote_control set-spacing margin=30 -Then pressing the :kbd:`F1` key will set the active window margins to 30. -The syntax for what follows :code:`remote_control` is exactly the same +Then pressing the :kbd:`F1` key will set the active window margins to +:code:`30`. The syntax for what follows :ac:`remote_control` is exactly the same as the syntax for what follows :code:`kitty @` above. -.. note:: You do not need ``allow_remote_control`` to use these mappings, - as they are not actual remote programs, but are simply a way to resuse - the remote control infrastructure via keybings. +.. note:: You do not need :opt:`allow_remote_control` to use these mappings, + as they are not actual remote programs, but are simply a way to resuse the + remote control infrastructure via keybings. Broadcasting what you type to all kitty windows @@ -166,17 +174,17 @@ As a simple illustration of the power of remote control, lets have what we type sent to all open kitty windows. To do that define the following mapping in :file:`kitty.conf`:: - map F1 launch --allow-remote-control kitty +kitten broadcast + map f1 launch --allow-remote-control kitty +kitten broadcast -Now press, F1 and start typing, what you type will be sent to all windows, +Now press :kbd:`F1` and start typing, what you type will be sent to all windows, live, as you type it. The remote control protocol ----------------------------------------------- -If you wish to develop your own client to talk to |kitty|, you -can use the :doc:`protocol specification `. +If you wish to develop your own client to talk to |kitty|, you can use the +:doc:`remote control protocol specification `. .. _search_syntax: @@ -184,12 +192,13 @@ can use the :doc:`protocol specification `. Matching windows and tabs ---------------------------- -Many remote control operations operate on windows or tabs. To select these, -the :code:`--match` option is often used. This allows matching using various +Many remote control operations operate on windows or tabs. To select these, the +:code:`--match` option is often used. This allows matching using various sophisticated criteria such as title, ids, cmdlines, etc. These criteria are -expressions of the form :code:`field:query`. Where field is the field against -which to match and query is the expression to match. They can be further -combined using Boolean operators, best illustrated with some examples:: +expressions of the form :code:`field:query`. Where :italic:`field` is the field +against which to match and :italic:`query` is the expression to match. They can +be further combined using Boolean operators, best illustrated with some +examples:: title:"My special window" or id:43 title:bash and env:USER=kovid diff --git a/kitty/rc/base.py b/kitty/rc/base.py index d8f772a27..0b9fd5ee5 100644 --- a/kitty/rc/base.py +++ b/kitty/rc/base.py @@ -75,46 +75,50 @@ ArgsType = List[str] MATCH_WINDOW_OPTION = '''\ --match -m -The window to match. Match specifications are of the form: -:italic:`field:regexp`. Where field can be one of: -:code:`id`, :code:`title`, :code:`pid`, :code:`cwd`, :code:`cmdline`, -:code:`num`, :code:`env`, :code:`state` and :code:`recent`. -You can use the :italic:`ls` command to get a list of windows. Expressions can -be :ref:`combined using Boolean operators `. Note that for -numeric fields such as :code:`id`, :code:`pid`, :code:`recent` and :code:`num` the expression is interpreted as a number, -not a regular expression. The field :code:`num` refers to the window position in the current tab, -starting from zero and counting clockwise (this is the same as the order in which the -windows are reported by the :italic:`ls` command). The window id of the current window -is available as the KITTY_WINDOW_ID environment variable. The field :code:`recent` refers to recently -active windows in the currently active tab, with zero being the currently active window, one being the previously active -window and so on. When using the :italic:`env` field -to match on environment variables you can specify only the environment variable name or a name -and value, for example, :italic:`env:MY_ENV_VAR=2`. The field :code:`state` matches -on the state of the window. Supported states are: +The window to match. Match specifications are of the form: :italic:`field:query`. +Where :italic:`field` can be one of: :code:`id`, :code:`title`, :code:`pid`, :code:`cwd`, :code:`cmdline`, :code:`num`, +:code:`env`, :code:`state` and :code:`recent`. +:italic:`query` is the expression to match. Expressions can be either a number or a regular expression, and can be +:ref:`combined using Boolean operators `. +Note that for numeric fields: :code:`id`, :code:`pid`, :code:`num` and :code:`recent`, the expression is interpreted as +a number, not a regular expression. +The field :code:`num` refers to the window position in the current tab, starting from zero and counting clockwise (this +is the same as the order in which the windows are reported by the :italic:`ls` command). +The window id of the current window is available as the :envvar:`KITTY_WINDOW_ID` environment variable. +The field :code:`recent` refers to recently active windows in the currently active tab, with zero being the currently +active window, one being the previously active window and so on. +When using the :code:`env` field to match on environment variables, you can specify only the environment variable name +or a name and value, for example, :italic:`env:MY_ENV_VAR=2`. +The field :code:`state` matches on the state of the window. Supported states are: :code:`active`, :code:`focused`, :code:`needs_attention`, :code:`parent_active` and :code:`parent_focused`. -Active windows are windows that are the active window in their parent tab. There is only one focused window -and it is the window to which keyboard events are delivered. +Active windows are the windows that are active in their parent tab. There is only one focused window and it is the +window to which keyboard events are delivered. +Note that you can use the :ref:`kitty @ ls ` command to get a list of windows. ''' MATCH_TAB_OPTION = '''\ --match -m -The tab to match. Match specifications are of the form: -:italic:`field:regexp`. Where field can be one of: -:code:`id`, :code:`index`, :code:`title`, :code:`window_id`, -:code:`window_title`, :code:`pid`, :code:`cwd`, :code:`env`, :code:`cmdline` and :code:`recent`. -You can use the :italic:`ls` command to get a list of tabs. Expressions can -be :ref:`combined using Boolean operators `. Note that for -numeric fields such as :code:`id`, :code:`recent`, :code:`index` or :code:`pid` the expression -is interpreted as a number, not a regular expression. When using :code:`title` or :code:`id`, first a matching tab is -looked for and if not found a matching window is looked for, and the tab -for that window is used. You can also use :code:`window_id` and :code:`window_title` to match -the tab that contains the window with the specified id or title. The :code:`index` number -is used to match the nth tab in the currently active OS window. The :code:`recent` number -matches recently active tabs in the currently active OS window, with zero being the currently -active tab, one the previously active tab and so on. The field :code:`state` matches -on the state of the tab. Supported states are: +The tab to match. Match specifications are of the form: :italic:`field:query`. +Where :italic:`field` can be one of: :code:`id`, :code:`index`, :code:`title`, :code:`window_id`, :code:`window_title`, +:code:`pid`, :code:`cwd`, :code:`cmdline` :code:`env`, :code:`state` and :code:`recent`. +:italic:`query` is the expression to match. Expressions can be either a number or a regular expression, and can be +:ref:`combined using Boolean operators `. +Note that for numeric fields: :code:`id`, :code:`index`, :code:`window_id`, :code:`pid` and :code:`recent`, the +expression is interpreted as a number, not a regular expression. +When using :code:`title` or :code:`id`, first a matching tab is looked for, and if not found a matching window is looked +for, and the tab for that window is used. +You can also use :code:`window_id` and :code:`window_title` to match the tab that contains the window with the specified +id or title. +The :code:`index` number is used to match the nth tab in the currently active OS window. +The :code:`recent` number matches recently active tabs in the currently active OS window, with zero being the currently +active tab, one the previously active tab and so on. +When using the :code:`env` field to match on environment variables, you can specify only the environment variable name +or a name and value, for example, :italic:`env:MY_ENV_VAR=2`. Tabs containing any window with the specified environment +variables are matched. +The field :code:`state` matches on the state of the tab. Supported states are: :code:`active`, :code:`focused`, :code:`needs_attention`, :code:`parent_active` and :code:`parent_focused`. -Active tabs are tabs that are the active tab in their parent OS Window. There is only one focused tab +Active tabs are the tabs that are active in their parent OS window. There is only one focused tab and it is the tab to which keyboard events are delivered. +Note that you can use the :ref:`kitty @ ls ` command to get a list of tabs. ''' @@ -259,7 +263,7 @@ def command_for_name(cmd_name: str) -> RemoteCommand: try: m = import_module(f'kitty.rc.{cmd_name}') except ImportError: - raise KeyError(f'{cmd_name} is not a known kitty remote control command') + raise KeyError(f'Unknown kitty remote control command: {cmd_name}') return cast(RemoteCommand, getattr(m, cmd_name)) diff --git a/kitty/rc/close_tab.py b/kitty/rc/close_tab.py index a4bdbb4aa..279330685 100644 --- a/kitty/rc/close_tab.py +++ b/kitty/rc/close_tab.py @@ -20,17 +20,18 @@ class CloseTab(RemoteCommand): self: Boolean indicating whether to close the tab of the window the command is run in ''' - short_desc = 'Close the specified tab(s)' + short_desc = 'Close the specified tabs' desc = '''\ -Close an arbitrary set of tabs. The :code:`--match` option can be used to specify complex sets of tabs to close. For example, to close -all non-focused tabs in the currently focused OS window, use: +Close an arbitrary set of tabs. The :code:`--match` option can be used to +specify complex sets of tabs to close. For example, to close all non-focused +tabs in the currently focused OS window, use: kitty @ close-tab --match "not state:focused and state:parent_focused" ''' options_spec = MATCH_TAB_OPTION + '''\n --self type=bool-set -If specified close the tab of the window this command is run in, rather than the active tab. +Close the tab of the window this command is run in, rather than the active tab. ''' argspec = '' diff --git a/kitty/rc/close_window.py b/kitty/rc/close_window.py index a63634f15..983c4fc65 100644 --- a/kitty/rc/close_window.py +++ b/kitty/rc/close_window.py @@ -19,11 +19,11 @@ class CloseWindow(RemoteCommand): self: Boolean indicating whether to close the window the command is run in ''' - short_desc = 'Close the specified window(s)' + short_desc = 'Close the specified windows' options_spec = MATCH_WINDOW_OPTION + '''\n --self type=bool-set -If specified close the window this command is run in, rather than the active window. +Close the window this command is run in, rather than the active window. ''' argspec = '' diff --git a/kitty/rc/create_marker.py b/kitty/rc/create_marker.py index aaab8cf47..54dda8c19 100644 --- a/kitty/rc/create_marker.py +++ b/kitty/rc/create_marker.py @@ -30,7 +30,7 @@ class CreateMarker(RemoteCommand): options_spec = MATCH_WINDOW_OPTION + '''\n --self type=bool-set -If specified apply marker to the window this command is run in, rather than the active window. +Apply marker to the window this command is run in, rather than the active window. ''' argspec = 'MARKER SPECIFICATION' diff --git a/kitty/rc/detach_tab.py b/kitty/rc/detach_tab.py index 3d41799b1..2174a68ee 100644 --- a/kitty/rc/detach_tab.py +++ b/kitty/rc/detach_tab.py @@ -16,19 +16,19 @@ class DetachTab(RemoteCommand): ''' match: Which tab to detach - target_tab: Which OS Window that containing the target tab to move the detached tab to + target_tab: Which tab to move the detached tab to the OS window it is run in self: Boolean indicating whether to detach the tab the command is run in ''' - short_desc = 'Detach a tab and place it in a different/new OS Window' + short_desc = 'Detach the specified tabs and place them in a different/new OS window' desc = ( - 'Detach the specified tab and either move it into a new OS window' - ' or add it to the OS Window containing the tab specified by :option:`kitty @ detach-tab --target-tab`' + 'Detach the specified tabs and either move them into a new OS window' + ' or add them to the OS window containing the tab specified by :option:`kitty @ detach-tab --target-tab`' ) options_spec = MATCH_TAB_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--target-tab -t') + '''\n --self type=bool-set -If specified detach the tab this command is run in, rather than the active tab. +Detach the tab this command is run in, rather than the active tab. ''' argspec = '' diff --git a/kitty/rc/detach_window.py b/kitty/rc/detach_window.py index 64d02774a..97c99b6e3 100644 --- a/kitty/rc/detach_window.py +++ b/kitty/rc/detach_window.py @@ -21,18 +21,18 @@ class DetachWindow(RemoteCommand): self: Boolean indicating whether to detach the window the command is run in ''' - short_desc = 'Detach a window and place it in a different/new tab' + short_desc = 'Detach the specified windows and place them in a different/new tab' desc = ( - 'Detach the specified window and either move it into a new tab, a new OS window' - ' or add it to the specified tab. Use the special value :code:`new` for :option:`kitty @ detach-window --target-tab`' - ' to move to a new tab. If no target tab is specified the window is moved to a new OS window.' + 'Detach the specified windows and either move them into a new tab, a new OS window' + ' or add them to the specified tab. Use the special value :code:`new` for :option:`kitty @ detach-window --target-tab`' + ' to move to a new tab. If no target tab is specified the windows are moved to a new OS window.' ) options_spec = MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--target-tab -t') + '''Use the special value :code:`new` to move to a new tab. --self type=bool-set -If specified detach the window this command is run in, rather than the active window. +Detach the window this command is run in, rather than the active window. ''' argspec = '' diff --git a/kitty/rc/disable_ligatures.py b/kitty/rc/disable_ligatures.py index 8f05231d9..b53122ea0 100644 --- a/kitty/rc/disable_ligatures.py +++ b/kitty/rc/disable_ligatures.py @@ -24,8 +24,8 @@ class DisableLigatures(RemoteCommand): short_desc = 'Control ligature rendering' desc = ( - 'Control ligature rendering for the specified windows/tabs (defaults to active window). The STRATEGY' - ' can be one of: never, always, cursor' + 'Control ligature rendering for the specified windows/tabs (defaults to active window). The :italic:`STRATEGY`' + ' can be one of: :code:`never`, :code:`always`, :code:`cursor`.' ) options_spec = '''\ --all -a diff --git a/kitty/rc/env.py b/kitty/rc/env.py index 1b4bc52e8..d5e7503cc 100644 --- a/kitty/rc/env.py +++ b/kitty/rc/env.py @@ -12,13 +12,13 @@ from .base import ( class Env(RemoteCommand): ''' - env+: dictionary of environment variables to values. Empty values cause the variable to be deleted. + env+: Dictionary of environment variables to values. Empty values cause the variable to be removed. ''' short_desc = 'Change environment variables seen by future children' desc = ( - 'Change the environment variables seen by processing in newly launched windows.' - ' Similar to the :opt:`env` option in kitty.conf, but affects running kitty instances.' + 'Change the environment variables that will be seen in newly launched windows.' + ' Similar to the :opt:`env` option in :file:`kitty.conf`, but affects running kitty instances.' ' Empty values cause the environment variable to be removed.' ) argspec = 'env_var1=val env_var2=val ...' diff --git a/kitty/rc/get_colors.py b/kitty/rc/get_colors.py index 4bb094ac5..08fff0ede 100644 --- a/kitty/rc/get_colors.py +++ b/kitty/rc/get_colors.py @@ -26,7 +26,7 @@ class GetColors(RemoteCommand): short_desc = 'Get terminal colors' desc = ( 'Get the terminal colors for the specified window (defaults to active window).' - ' Colors will be output to stdout in the same syntax as used for kitty.conf' + ' Colors will be output to stdout in the same syntax as used for :file:`kitty.conf`.' ) options_spec = '''\ --configured -c diff --git a/kitty/rc/get_text.py b/kitty/rc/get_text.py index 47dddb24a..2ad8e6b54 100644 --- a/kitty/rc/get_text.py +++ b/kitty/rc/get_text.py @@ -23,7 +23,7 @@ class GetText(RemoteCommand): cursor: Boolean, if True send cursor position/style as ANSI codes wrap_markers: Boolean, if True add wrap markers to output clear_selection: Boolean, if True clear the selection in the matched window - self: Boolean, if True use window command was run in + self: Boolean, if True use window the command was run in ''' short_desc = 'Get text from the specified window' @@ -42,8 +42,8 @@ requires :ref:`shell_integration` to be enabled. --ansi type=bool-set -By default, only plain text is returned. If you specify this flag, the text will -include the formatting escape codes for colors/bold/italic/etc. +By default, only plain text is returned. With this flag, the text will +include the ANSI formatting escape codes for colors, bold, italic, etc. --add-cursor @@ -57,13 +57,13 @@ Add carriage returns at every line wrap location (where long lines are wrapped a screen edges). +--clear-selection +Clear the selection in the matched window, if any. + + --self type=bool-set -If specified get text from the window this command is run in, rather than the active window. - - ---clear-selection -Clear the selection in the matched window, if any +Get text from the window this command is run in, rather than the active window. ''' argspec = '' @@ -72,10 +72,10 @@ Clear the selection in the matched window, if any 'match': opts.match, 'extent': opts.extent, 'ansi': opts.ansi, - 'self': opts.self, 'cursor': opts.add_cursor, 'wrap_markers': opts.add_wrap_markers, 'clear_selection': opts.clear_selection, + 'self': opts.self, } def response_from_kitty(self, boss: Boss, window: Optional[Window], payload_get: PayloadGetType) -> ResponseType: diff --git a/kitty/rc/goto_layout.py b/kitty/rc/goto_layout.py index df9bbc6e3..21fc691cd 100644 --- a/kitty/rc/goto_layout.py +++ b/kitty/rc/goto_layout.py @@ -26,8 +26,8 @@ class GotoLayout(RemoteCommand): short_desc = 'Set the window layout' desc = ( - 'Set the window layout in the specified tab (or the active tab if not specified).' - ' You can use special match value :italic:`all` to set the layout in all tabs.' + 'Set the window layout in the specified tabs (or the active tab if not specified).' + ' You can use special match value :code:`all` to set the layout in all tabs.' ) options_spec = MATCH_TAB_OPTION argspec = 'LAYOUT_NAME' diff --git a/kitty/rc/kitten.py b/kitty/rc/kitten.py index f7ed3cd0c..ae857977c 100644 --- a/kitty/rc/kitten.py +++ b/kitty/rc/kitten.py @@ -22,11 +22,11 @@ class Kitten(RemoteCommand): short_desc = 'Run a kitten' desc = ( - 'Run a kitten over the specified window (active window by default).' + 'Run a kitten over the specified windows (active window by default).' ' The :italic:`kitten_name` can be either the name of a builtin kitten' - ' or the path to a python file containing a custom kitten. If a relative path' - ' is used it is searched for in the kitty config directory. If the kitten is a' - ' no_ui kitten and its handle response method returns a string or boolean, this' + ' or the path to a Python file containing a custom kitten. If a relative path' + ' is used it is searched for in the :ref:`kitty config directory `. If the kitten is a' + ' :italic:`no_ui` kitten and its handle response method returns a string or boolean, this' ' is printed out to stdout.' ) options_spec = MATCH_WINDOW_OPTION diff --git a/kitty/rc/last_used_layout.py b/kitty/rc/last_used_layout.py index d9ddb45f9..c7fa637e8 100644 --- a/kitty/rc/last_used_layout.py +++ b/kitty/rc/last_used_layout.py @@ -21,7 +21,7 @@ class LastUsedLayout(RemoteCommand): short_desc = 'Switch to the last used layout' desc = ( - 'Switch to the last used window layout in the specified tab (or the active tab if not specified).' + 'Switch to the last used window layout in the specified tabs (or the active tab if not specified).' ) options_spec = '''\ --all -a diff --git a/kitty/rc/ls.py b/kitty/rc/ls.py index 8ede5d0c4..da0819ba9 100644 --- a/kitty/rc/ls.py +++ b/kitty/rc/ls.py @@ -17,7 +17,7 @@ if TYPE_CHECKING: class LS(RemoteCommand): ''' - all_env_vars: Whether to send all environment variables for ever window rather than just differing ones + all_env_vars: Whether to send all environment variables for every window rather than just differing ones ''' short_desc = 'List all tabs/windows' @@ -33,7 +33,7 @@ class LS(RemoteCommand): options_spec = '''\ --all-env-vars type=bool-set -Show all environment variables in output not just differing ones. +Show all environment variables in output, not just differing ones. ''' argspec = '' diff --git a/kitty/rc/new_window.py b/kitty/rc/new_window.py index 1f2b26e31..2448750dc 100644 --- a/kitty/rc/new_window.py +++ b/kitty/rc/new_window.py @@ -50,7 +50,7 @@ the working directory for the kitty process you are talking to is. --keep-focus --dont-take-focus type=bool-set -Keep the current window focused instead of switching to the newly opened window +Keep the current window focused instead of switching to the newly opened window. --window-type @@ -61,11 +61,11 @@ What kind of window to open. A kitty window or a top-level OS window. --new-tab type=bool-set -Open a new tab +Open a new tab. --tab-title -When using :option:`kitty @ new-window --new-tab` set the title of the tab. +Set the title of the tab, when open a new tab. --no-response diff --git a/kitty/rc/remove_marker.py b/kitty/rc/remove_marker.py index 0915c7110..b60042cc7 100644 --- a/kitty/rc/remove_marker.py +++ b/kitty/rc/remove_marker.py @@ -24,7 +24,7 @@ class RemoveMarker(RemoteCommand): options_spec = MATCH_WINDOW_OPTION + '''\n --self type=bool-set -If specified apply marker to the window this command is run in, rather than the active window. +Apply marker to the window this command is run in, rather than the active window. ''' argspec = '' diff --git a/kitty/rc/resize_os_window.py b/kitty/rc/resize_os_window.py index 5ab7c7f06..7a79b9410 100644 --- a/kitty/rc/resize_os_window.py +++ b/kitty/rc/resize_os_window.py @@ -23,9 +23,9 @@ class ResizeOSWindow(RemoteCommand): height: Integer indicating desired window height ''' - short_desc = 'Resize the specified OS Window' + short_desc = 'Resize the specified OS Windows' desc = ( - 'Resize the specified OS Window.' + 'Resize the specified OS Windows.' ' Note that some window managers/environments do not allow applications to resize' ' their windows, for example, tiling window managers.' ) @@ -39,7 +39,7 @@ The action to perform. --unit default=cells choices=cells,pixels -The unit in which to interpret specified sizes +The unit in which to interpret specified sizes. --width @@ -62,7 +62,7 @@ instead of absolute sizes. --self type=bool-set -If specified resize the window this command is run in, rather than the active window. +Resize the window this command is run in, rather than the active window. --no-response diff --git a/kitty/rc/resize_window.py b/kitty/rc/resize_window.py index 12bd3b75f..e59d03db4 100644 --- a/kitty/rc/resize_window.py +++ b/kitty/rc/resize_window.py @@ -20,9 +20,9 @@ class ResizeWindow(RemoteCommand): axis: One of :code:`horizontal, vertical` or :code:`reset` ''' - short_desc = 'Resize the specified window' + short_desc = 'Resize the specified windows' desc = ( - 'Resize the specified window in the current layout.' + 'Resize the specified windows in the current layout.' ' Note that not all layouts can resize all windows in all directions.' ) options_spec = MATCH_WINDOW_OPTION + '''\n @@ -36,15 +36,15 @@ The number of cells to change the size by, can be negative to decrease the size. type=choices choices=horizontal,vertical,reset default=horizontal -The axis along which to resize. If :italic:`horizontal`, +The axis along which to resize. If :code:`horizontal`, it will make the window wider or narrower by the specified increment. -If :italic:`vertical`, it will make the window taller or shorter by the specified increment. -The special value :italic:`reset` will reset the layout to its default configuration. +If :code:`vertical`, it will make the window taller or shorter by the specified increment. +The special value :code:`reset` will reset the layout to its default configuration. --self type=bool-set -If specified resize the window this command is run in, rather than the active window. +Resize the window this command is run in, rather than the active window. ''' argspec = '' string_return_is_error = True diff --git a/kitty/rc/scroll_window.py b/kitty/rc/scroll_window.py index 5f633c932..df79d948e 100644 --- a/kitty/rc/scroll_window.py +++ b/kitty/rc/scroll_window.py @@ -23,12 +23,12 @@ class ScrollWindow(RemoteCommand): match: The window to scroll ''' - short_desc = 'Scroll the specified window' + short_desc = 'Scroll the specified windows' desc = ( - 'Scroll the specified window, if no window is specified, scroll the window this command is run inside.' - ' SCROLL_AMOUNT can be either the keywords :code:`start` or :code:`end` or an' - ' argument of the form [unit][+-]. For example, 30 will scroll down 30 lines and 2p- will' - ' scroll up 2 pages. 3u will *unscroll* by 3 lines, which means that 3 lines will move from the' + 'Scroll the specified windows, if no window is specified, scroll the window this command is run inside.' + ' :italic:`SCROLL_AMOUNT` can be either the keywords :code:`start` or :code:`end` or an' + ' argument of the form [unit][+-]. For example, :code:`30` will scroll down 30 lines and :code:`2p-`' + ' will scroll up 2 pages. :code:`3u` will *unscroll* by 3 lines, which means that 3 lines will move from the' ' scrollback buffer onto the top of the screen.' ) argspec = 'SCROLL_AMOUNT' diff --git a/kitty/rc/select_window.py b/kitty/rc/select_window.py index b6be27990..df08490ea 100644 --- a/kitty/rc/select_window.py +++ b/kitty/rc/select_window.py @@ -39,23 +39,23 @@ The time in seconds to wait for the user to select a window. --self type=bool-set -If specified the tab containing the window this command is run in is used +Select window from the tab containing the window this command is run in, instead of the active tab. --title -A title that will be displayed to the user to describe what this selection is for +A title that will be displayed to the user to describe what this selection is for. --exclude-active type=bool-set -Exclude the currently active window from the list of windows to pick +Exclude the currently active window from the list of windows to pick. --reactivate-prev-tab type=bool-set -When the selection is finished, the tab in the same os window that was activated -before the selection will be reactivated. The last activated os window will also +When the selection is finished, the tab in the same OS window that was activated +before the selection will be reactivated. The last activated OS window will also be refocused. ''' is_asynchronous = True diff --git a/kitty/rc/send_text.py b/kitty/rc/send_text.py index fde434aa5..0cdc00099 100644 --- a/kitty/rc/send_text.py +++ b/kitty/rc/send_text.py @@ -74,8 +74,8 @@ class SendText(RemoteCommand): short_desc = 'Send arbitrary text to specified windows' desc = ( 'Send arbitrary text to specified windows. The text follows Python' - ' escaping rules. So you can use escapes like :italic:`\\x1b` to send control codes' - ' and :italic:`\\u21fa` to send unicode characters. If you use the :option:`kitty @ send-text --match` option' + ' escaping rules. So you can use escapes like :code:`\\x1b` to send control codes' + ' and :code:`\\u21fa` to send unicode characters. If you use the :option:`kitty @ send-text --match` option' ' the text will be sent to all matched windows. By default, text is sent to' ' only the currently active window.' ) @@ -88,7 +88,7 @@ Match all windows. --stdin type=bool-set Read the text to be sent from :italic:`stdin`. Note that in this case the text is sent as is, -not interpreted for escapes. If stdin is a terminal, you can press Ctrl-D to end reading. +not interpreted for escapes. If stdin is a terminal, you can press :kbd:`Ctrl-D` to end reading. --from-file diff --git a/kitty/rc/set_background_image.py b/kitty/rc/set_background_image.py index 9601fbbc7..491e11f49 100644 --- a/kitty/rc/set_background_image.py +++ b/kitty/rc/set_background_image.py @@ -29,10 +29,10 @@ class SetBackgroundImage(RemoteCommand): configured: Boolean indicating if the configured value should be changed ''' - short_desc = 'Set the background_image' + short_desc = 'Set the background image' desc = ( 'Set the background image for the specified OS windows. You must specify the path to a PNG image that' - ' will be used as the background. If you specify the special value "none" then any existing image will' + ' will be used as the background. If you specify the special value :code:`none` then any existing image will' ' be removed.' ) options_spec = '''\ @@ -50,7 +50,7 @@ Change the configured background image which is used for new OS windows. --layout type=choices choices=tiled,scaled,mirror-tiled,clamped,configured -How the image should be displayed. The value of configured will use the configured value. +How the image should be displayed. A value of :code:`configured` will use the configured value. --no-response diff --git a/kitty/rc/set_background_opacity.py b/kitty/rc/set_background_opacity.py index e0d0f377d..bfc437931 100644 --- a/kitty/rc/set_background_opacity.py +++ b/kitty/rc/set_background_opacity.py @@ -23,17 +23,17 @@ class SetBackgroundOpacity(RemoteCommand): all: Boolean indicating operate on all windows ''' - short_desc = 'Set the background_opacity' + short_desc = 'Set the background opacity' desc = ( 'Set the background opacity for the specified windows. This will only work if you have turned on' ' :opt:`dynamic_background_opacity` in :file:`kitty.conf`. The background opacity affects all kitty windows in a' - ' single os_window. For example: kitty @ set-background-opacity 0.5' + ' single OS window. For example: :code:`kitty @ set-background-opacity 0.5`' ) options_spec = '''\ --all -a type=bool-set -By default, colors are only changed for the currently active window. This option will -cause colors to be changed in all windows. +By default, background opacity are only changed for the currently active window. This option will +cause background opacity to be changed in all windows. ''' + '\n\n' + MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t') argspec = 'OPACITY' diff --git a/kitty/rc/set_colors.py b/kitty/rc/set_colors.py index 55756b6cd..6faea427d 100644 --- a/kitty/rc/set_colors.py +++ b/kitty/rc/set_colors.py @@ -67,8 +67,8 @@ class SetColors(RemoteCommand): desc = ( 'Set the terminal colors for the specified windows/tabs (defaults to active window).' ' You can either specify the path to a conf file' - ' (in the same format as kitty.conf) to read the colors from or you can specify individual colors,' - ' for example: kitty @ set-colors foreground=red background=white' + ' (in the same format as :file:`kitty.conf`) to read the colors from or you can specify individual colors,' + ' for example: :code:`kitty @ set-colors foreground=red background=white`' ) options_spec = '''\ --all -a diff --git a/kitty/rc/set_enabled_layouts.py b/kitty/rc/set_enabled_layouts.py index 96679da42..2f663f090 100644 --- a/kitty/rc/set_enabled_layouts.py +++ b/kitty/rc/set_enabled_layouts.py @@ -28,11 +28,11 @@ class SetEnabledLayouts(RemoteCommand): configured: Boolean indicating whether to change the configured value ''' - short_desc = 'Set the enabled layouts in a tab' + short_desc = 'Set the enabled layouts in tabs' desc = ( - 'Set the enabled layouts in the specified tab (or the active tab if not specified).' - ' You can use special match value :italic:`all` to set the layout in all tabs. If the' - ' current layout of the tab is not included in the enabled layouts its layout is changed' + 'Set the enabled layouts in the specified tabs (or the active tab if not specified).' + ' You can use special match value :code:`all` to set the enabled layouts in all tabs. If the' + ' current layout of the tab is not included in the enabled layouts, its layout is changed' ' to the first enabled layout.' ) options_spec = MATCH_TAB_OPTION + '''\n\n diff --git a/kitty/rc/set_font_size.py b/kitty/rc/set_font_size.py index 26fa09d64..b8aec7080 100644 --- a/kitty/rc/set_font_size.py +++ b/kitty/rc/set_font_size.py @@ -25,7 +25,7 @@ class SetFontSize(RemoteCommand): ' that in kitty all sub-windows in the same OS window' ' must have the same font size. A value of zero' ' resets the font size to default. Prefixing the value' - ' with a + or - increments the font size by the specified' + ' with a :code:`+` or :code:`-` increments the font size by the specified' ' amount.' ) argspec = 'FONT_SIZE' diff --git a/kitty/rc/set_spacing.py b/kitty/rc/set_spacing.py index db1700da5..318bbae52 100644 --- a/kitty/rc/set_spacing.py +++ b/kitty/rc/set_spacing.py @@ -41,30 +41,30 @@ class SetSpacing(RemoteCommand): ''' settings+: An object mapping margins/paddings using canonical form {'margin-top': 50, 'padding-left': null} etc - match_window: Window to change colors in - match_tab: Tab to change colors in - all: Boolean indicating change colors everywhere or not - configured: Boolean indicating whether to change the configured colors. Must be True if reset is True + match_window: Window to change paddings and margins in + match_tab: Tab to change paddings and margins in + all: Boolean indicating change paddings and margins everywhere or not + configured: Boolean indicating whether to change the configured paddings and margins. Must be True if reset is True ''' - short_desc = 'Set window padding and margins' + short_desc = 'Set window paddings and margins' desc = ( - 'Set the padding and margins for the specified windows (defaults to active window).' - ' For example: margin=20 or padding-left=10 or margin-h=30. The shorthand form sets' + 'Set the paddings and margins for the specified windows (defaults to active window).' + ' For example: :code:`margin=20` or :code:`padding-left=10` or :code:`margin-h=30`. The shorthand form sets' ' all values, the :code:`*-h` and :code:`*-v` variants set horizontal and vertical values.' - ' The special value "default" resets to using the default value.' + ' The special value :code:`default` resets to using the default value.' ' If you specify a tab rather than a window, all windows in that tab are affected.' ) options_spec = '''\ --all -a type=bool-set By default, settings are only changed for the currently active window. This option will -cause colors to be changed in all windows. +cause paddings and margins to be changed in all windows. --configured -c type=bool-set -Also change the configured padding and margins (i.e. the settings kitty will use for new +Also change the configured paddings and margins (i.e. the settings kitty will use for new windows). ''' + '\n\n' + MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t') argspec = 'MARGIN_OR_PADDING ...' diff --git a/kitty/rc/set_tab_color.py b/kitty/rc/set_tab_color.py index 3c22b585a..0a98be726 100644 --- a/kitty/rc/set_tab_color.py +++ b/kitty/rc/set_tab_color.py @@ -43,7 +43,7 @@ class SetTabColor(RemoteCommand): self: Boolean indicating whether to use the tab of the window the command is run in ''' - short_desc = 'Change the color of the specified tab(s) in the tab bar' + short_desc = 'Change the color of the specified tabs in the tab bar' desc = f''' {short_desc} @@ -55,7 +55,7 @@ the keyword NONE to revert to using the default colors. options_spec = MATCH_TAB_OPTION + '''\n --self type=bool-set -If specified close the tab this command is run in, rather than the active tab. +Close the tab this command is run in, rather than the active tab. ''' argspec = 'COLORS' diff --git a/kitty/rc/set_tab_title.py b/kitty/rc/set_tab_title.py index 72d0e331b..25a76add4 100644 --- a/kitty/rc/set_tab_title.py +++ b/kitty/rc/set_tab_title.py @@ -22,7 +22,7 @@ class SetTabTitle(RemoteCommand): short_desc = 'Set the tab title' desc = ( - 'Set the title for the specified tab(s). If you use the :option:`kitty @ set-tab-title --match` option' + 'Set the title for the specified tabs. If you use the :option:`kitty @ set-tab-title --match` option' ' the title will be set for all matched tabs. By default, only the tab' ' in which the command is run is affected. If you do not specify a title, the' ' title of the currently active window in the tab is used.' diff --git a/kitty/rc/set_window_logo.py b/kitty/rc/set_window_logo.py index d05b56005..c188fa865 100644 --- a/kitty/rc/set_window_logo.py +++ b/kitty/rc/set_window_logo.py @@ -22,9 +22,9 @@ if TYPE_CHECKING: class SetWindowLogo(RemoteCommand): ''' data+: Chunk of at most 512 bytes of PNG data, base64 encoded. Must send an empty chunk to indicate end of image. \ - Or the special value - to indicate image must be removed. + Or the special value :code:`-` to indicate image must be removed. position: The logo position as a string, empty string means default - alpha: The logo alpha between 0 and 1. -1 means use default + alpha: The logo alpha between :code:`0` and :code:`1`. :code:`-1` means use default match: Which window to change the logo in self: Boolean indicating whether to act on the window the command is run in ''' @@ -32,14 +32,14 @@ class SetWindowLogo(RemoteCommand): short_desc = 'Set the window logo' desc = ( 'Set the logo image for the specified windows. You must specify the path to a PNG image that' - ' will be used as the logo. If you specify the special value "none" then any existing logo will' + ' will be used as the logo. If you specify the special value :code:`none` then any existing logo will' ' be removed.' ) options_spec = MATCH_WINDOW_OPTION + '''\n --self type=bool-set -If specified act on the window this command is run in, rather than the active window. +Act on the window this command is run in, rather than the active window. --position diff --git a/kitty/rc/set_window_title.py b/kitty/rc/set_window_title.py index 31c90d713..a5c626a6b 100644 --- a/kitty/rc/set_window_title.py +++ b/kitty/rc/set_window_title.py @@ -22,7 +22,7 @@ class SetWindowTitle(RemoteCommand): short_desc = 'Set the window title' desc = ( - 'Set the title for the specified window(s). If you use the :option:`kitty @ set-window-title --match` option' + 'Set the title for the specified windows. If you use the :option:`kitty @ set-window-title --match` option' ' the title will be set for all matched windows. By default, only the window' ' in which the command is run is affected. If you do not specify a title, the' ' last title set by the child process running in the window will be used.' @@ -30,9 +30,8 @@ class SetWindowTitle(RemoteCommand): options_spec = '''\ --temporary type=bool-set -By default, if you use :italic:`set-window-title` the title will be permanently changed -and programs running in the window will not be able to change it again. If you -want to allow other programs to change it afterwards, use this option. +By default, the title will be permanently changed and programs running in the window will not be able to change it +again. If you want to allow other programs to change it afterwards, use this option. ''' + '\n\n' + MATCH_WINDOW_OPTION argspec = '[TITLE ...]' diff --git a/kitty/rc/signal_child.py b/kitty/rc/signal_child.py index 50ccc5b73..5efa5bf28 100644 --- a/kitty/rc/signal_child.py +++ b/kitty/rc/signal_child.py @@ -15,18 +15,18 @@ if TYPE_CHECKING: class SignalChild(RemoteCommand): ''' - signals: The signals, a list of names, such as SIGTERM, SIGKILL, SIGUSR1, etc. - match: Which windows to change the title in + signals: The signals, a list of names, such as :code:`SIGTERM`, :code:`SIGKILL`, :code:`SIGUSR1`, etc. + match: Which windows to send the signals to ''' - short_desc = 'Send a signal to the foreground process in the specified window' + short_desc = 'Send a signal to the foreground process in the specified windows' desc = ( - 'Send one or more signals to the foreground process in the specified window(s).' + 'Send one or more signals to the foreground process in the specified windows.' ' If you use the :option:`kitty @ signal-child --match` option' ' the signal will be sent for all matched windows. By default, only the active' ' window is affected. If you do not specify any signals, :code:`SIGINT` is sent by default.' - ' You can also map this to a keystroke in kitty.conf, for example::\n\n' - ' map F1 signal_child SIGTERM' + ' You can also map this to a shortcut in :file:`kitty.conf`, for example::\n\n' + ' map f1 signal_child SIGTERM' ) options_spec = '''\ ''' + '\n\n' + MATCH_WINDOW_OPTION