From 1411269187cdb4f8751ff0548fd6173404ebc727 Mon Sep 17 00:00:00 2001 From: pagedown Date: Tue, 28 Jun 2022 11:52:20 +0800 Subject: [PATCH] Docs: Improve documentation for remote commands Use text roles in the document to apply the style in the cli output. Add more links. Unify the text roles. Use code blocks instead of quote blocks. Use '+' to connect the shortcut key names. --- kitty/launch.py | 12 ++++++------ kitty/rc/base.py | 6 +++--- kitty/rc/close_tab.py | 2 +- kitty/rc/launch.py | 4 ++-- kitty/rc/new_window.py | 2 +- kitty/rc/scroll_window.py | 2 +- kitty/rc/send_text.py | 2 +- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/kitty/launch.py b/kitty/launch.py index f2c3ef2eb..d0033870e 100644 --- a/kitty/launch.py +++ b/kitty/launch.py @@ -181,15 +181,15 @@ the same as for the :ac:`toggle_marker` action (see :doc:`/marks`). --os-window-class -Set the *WM_CLASS* property on X11 and the application id property on Wayland -for the newly created OS window when using :option:`--type=os-window +Set the :italic:`WM_CLASS` property on X11 and the application id property on +Wayland for the newly created OS window when using :option:`--type=os-window `. Defaults to whatever is used by the parent kitty process, which in turn defaults to :code:`kitty`. --os-window-name -Set the *WM_NAME* property on X11 for the newly created OS Window when using -:option:`--type=os-window `. Defaults to +Set the :italic:`WM_NAME` property on X11 for the newly created OS Window when +using :option:`--type=os-window `. Defaults to :option:`--os-window-class `. @@ -220,8 +220,8 @@ effect if :option:`--logo` is specified. See :opt:`window_logo_position`. type=list Change colors in the newly launched window. You can either specify a path to a :file:`.conf` file with the same syntax as :file:`kitty.conf` to read the colors -from, or specify them individually, for example: ``--color background=white`` -``--color foreground=red`` +from, or specify them individually, for example: :code:`--color background=white +--color foreground=red`. --watcher -w diff --git a/kitty/rc/base.py b/kitty/rc/base.py index 9d5c81979..baac8af24 100644 --- a/kitty/rc/base.py +++ b/kitty/rc/base.py @@ -87,7 +87,7 @@ For numeric fields: :code:`id`, :code:`pid`, :code:`num` and :code:`recent`, the 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). +is the same as the order in which the windows are reported by the :ref:`kitty @ ls ` command). The window id of the current window is available as the :envvar:`KITTY_WINDOW_ID` environment variable. @@ -95,7 +95,7 @@ The field :code:`recent` refers to recently active windows in the currently acti 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`. +or a name and value, for example, :code:`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`. @@ -128,7 +128,7 @@ The :code:`recent` number matches recently active tabs in the currently active O 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 +or a name and value, for example, :code:`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: diff --git a/kitty/rc/close_tab.py b/kitty/rc/close_tab.py index 279330685..8902120b2 100644 --- a/kitty/rc/close_tab.py +++ b/kitty/rc/close_tab.py @@ -24,7 +24,7 @@ class CloseTab(RemoteCommand): 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: +tabs in the currently focused OS window, use:: kitty @ close-tab --match "not state:focused and state:parent_focused" ''' diff --git a/kitty/rc/launch.py b/kitty/rc/launch.py index 6449aadc2..d19da9cd2 100644 --- a/kitty/rc/launch.py +++ b/kitty/rc/launch.py @@ -51,8 +51,8 @@ class Launch(RemoteCommand): desc = ( 'Prints out the id of the newly opened window. Any command line arguments' ' are assumed to be the command line used to run in the new window, if none' - ' are provided, the default shell is run. For example:' - ' :code:`kitty @ launch --title=Email mutt`.' + ' are provided, the default shell is run. For example:\n' + ':code:`kitty @ launch --title=Email mutt`' ) options_spec = MATCH_TAB_OPTION + '\n\n' + '''\ --no-response diff --git a/kitty/rc/new_window.py b/kitty/rc/new_window.py index 31d99c750..3b614a863 100644 --- a/kitty/rc/new_window.py +++ b/kitty/rc/new_window.py @@ -28,7 +28,7 @@ class NewWindow(RemoteCommand): short_desc = 'Open new window' desc = ( - 'DEPRECATED: Use the launch command instead.\n\n' + 'DEPRECATED: Use the :ref:`launch ` command instead.\n\n' 'Open a new window in the specified tab. If you use the :option:`kitty @ new-window --match` option' ' the first matching tab is used. Otherwise the currently active tab is used.' ' Prints out the id of the newly opened window' diff --git a/kitty/rc/scroll_window.py b/kitty/rc/scroll_window.py index 1fd20a98e..ccfa547ed 100644 --- a/kitty/rc/scroll_window.py +++ b/kitty/rc/scroll_window.py @@ -27,7 +27,7 @@ class ScrollWindow(RemoteCommand): desc = ( '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-`' + ' argument of the form :italic:`[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.' ) diff --git a/kitty/rc/send_text.py b/kitty/rc/send_text.py index 6aa8aea13..88407bc13 100644 --- a/kitty/rc/send_text.py +++ b/kitty/rc/send_text.py @@ -93,7 +93,7 @@ Do not send text to the active window, even if it is one of the matched 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 :kbd:`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