From ecb60b313e3a2d4e11b7ba9d9e1f0d8ae84093ed Mon Sep 17 00:00:00 2001 From: pagedown Date: Sun, 24 Apr 2022 17:18:31 +0800 Subject: [PATCH] Docs: Improve clone-in-kitty documentation and fix LANG descriptions Reduce duplicate `launch`. Add links to python venv and conda. Adjust the order of env vars, `.._CODE` takes precedence over `.._PATH`. Add clone-in-kitty env vars to glossary. Correct the description of the LANG env var. --- docs/glossary.rst | 21 ++++++++++++++++----- docs/shell-integration.rst | 29 ++++++++++++++++------------- 2 files changed, 32 insertions(+), 18 deletions(-) diff --git a/docs/glossary.rst b/docs/glossary.rst index 05bd4e318..33cb2c7cd 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -45,6 +45,7 @@ Environment variables ------------------------ Variables that influence kitty behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. envvar:: KITTY_CONFIG_DIRECTORY @@ -68,7 +69,6 @@ Variables that influence kitty behavior The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`. - .. envvar:: EDITOR Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set. @@ -84,13 +84,24 @@ Variables that influence kitty behavior is possible for the autodiscovery to fail; the default Wayland XKB mappings are used in this case. See :pull:`3943` for details. +.. envvar:: KITTY_CLONE_SOURCE_CODE + + Set this to some shell code that will be executed in the cloned window with + :code:`eval` when :ref:`clone-in-kitty ` is used. + +.. envvar:: KITTY_CLONE_SOURCE_PATH + + Set this to the path of a file that will be sourced in the cloned window when + :ref:`clone-in-kitty ` is used. + Variables that kitty sets when running child programs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. envvar:: LANG - This is set only on macOS, and only if the country and language from the - macOS user settings form a valid locale. + This is only set on macOS. If the country and language from the macOS user + settings form an invalid locale, it will be set to :code:`en_US.UTF-8`. .. envvar:: KITTY_WINDOW_ID @@ -137,7 +148,7 @@ Variables that kitty sets when running child programs Set when the :doc:`remote control ` facility is enabled and the a socket is used for control via :option:`kitty --listen-on` or :opt:`listen_on`. - Contains the path to the socket. Avoids needs to use :option:`kitty @ --to` when + Contains the path to the socket. Avoid the need to use :option:`kitty @ --to` when issuing remote control commands. @@ -158,7 +169,7 @@ Variables that kitty sets when running child programs .. envvar:: KITTY_COMMON_OPTS Set with the values of some common kitty options when running - kittens, so kittens can use them without needing to load kitty.conf. + kittens, so kittens can use them without needing to load :file:`kitty.conf`. .. envvar:: KITTY_SHELL_INTEGRATION diff --git a/docs/shell-integration.rst b/docs/shell-integration.rst index 146ed3891..9b4f4afe0 100644 --- a/docs/shell-integration.rst +++ b/docs/shell-integration.rst @@ -223,7 +223,7 @@ Clone the current shell into a new window ----------------------------------------------- You can clone the current shell into a new kitty window by simply running the -:code:`clone-in-kitty` command, for example: +:command:`clone-in-kitty` command, for example: .. code-block:: sh @@ -235,24 +235,27 @@ This will open a new window running a new shell instance but with all environment variables and the current working directory copied. This even works over SSH when using :doc:`kittens/ssh`. -The :file:`clone-in-kitty` command takes almost all the same arguments as the +The :command:`clone-in-kitty` command takes almost all the same arguments as the :doc:`launch ` command, so you can open a new tab instead or a new OS window, etc. Arguments of launch that can cause code execution or that don't -make sense when cloning are ignored. Most prominently, the following options -are ignored: :option:`launch --allow-remote-control`, :option:`launch ---copy-cmdline`, :option:`launch --copy-env`, :option:`launch --stdin-source`, -:option:`launch --marker` and :option:`launch --watcher`. +make sense when cloning are ignored. Most prominently, the following options are +ignored: :option:`--allow-remote-control `, +:option:`--copy-cmdline `, :option:`--copy-env `, :option:`--stdin-source `, +:option:`--marker ` and :option:`--watcher `. -:file:`clone-in-kitty` can be configured to source arbitrary code in the +:command:`clone-in-kitty` can be configured to source arbitrary code in the cloned window using environment variables. It will automatically clone virtual -environments created by the python venv module or conda. In addition, setting the -env var :file:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause -that file to be sourced in the cloned window. Similarly, setting -:file:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that code to be -run in the cloned window with :code:`eval`. This can be controlled by +environments created by the :link:`Python venv module +` or :link:`Conda +`. In addition, setting the +env var :envvar:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that +code to be run in the cloned window with :code:`eval`. Similarly, setting +:envvar:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause that file to +be sourced in the cloned window. This can be controlled by :opt:`clone_source_strategies`. -:file:`clone-in-kitty` works by asking the shell to serialize its internal +:command:`clone-in-kitty` works by asking the shell to serialize its internal state (mainly CWD and env vars) and this state is transmitted to kitty and restored by the shell integration scripts in the cloned window.