KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: Improve clone-in-kitty documentation and fix LANG descriptions

Browse Source 
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.
This commit is contained in:
pagedown 2022-04-24 17:18:31 +08:00
parent cf2a20e4ea
commit ecb60b313e
No known key found for this signature in database
GPG Key ID: E921CF18AC8FF6EB
2 changed files with 32 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
docs/glossary.rst
View File

@ -45,6 +45,7 @@ Environment variables
------------------------ ------------------------
Variables that influence kitty behavior Variables that influence kitty behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. envvar:: KITTY_CONFIG_DIRECTORY .. 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 The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`. instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
.. envvar:: EDITOR .. envvar:: EDITOR
Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set. 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 is possible for the autodiscovery to fail; the default Wayland XKB mappings
are used in this case. See :pull:`3943` for details. 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 <clone_shell>` 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 <clone_shell>` is used.
Variables that kitty sets when running child programs Variables that kitty sets when running child programs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. envvar:: LANG .. envvar:: LANG
This is set only on macOS, and only if the country and language from the This is only set on macOS. If the country and language from the macOS user
macOS user settings form a valid locale. settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
.. envvar:: KITTY_WINDOW_ID .. envvar:: KITTY_WINDOW_ID
@ -137,7 +148,7 @@ Variables that kitty sets when running child programs
Set when the :doc:`remote control <remote-control>` facility is enabled and Set when the :doc:`remote control <remote-control>` facility is enabled and
the a socket is used for control via :option:`kitty --listen-on` or :opt:`listen_on`. 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. issuing remote control commands.
@ -158,7 +169,7 @@ Variables that kitty sets when running child programs
.. envvar:: KITTY_COMMON_OPTS .. envvar:: KITTY_COMMON_OPTS
Set with the values of some common kitty options when running 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 .. envvar:: KITTY_SHELL_INTEGRATION

29
docs/shell-integration.rst
View File

@ -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 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 .. 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 environment variables and the current working directory copied. This even
works over SSH when using :doc:`kittens/ssh`. 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 <launch>` command, so you can open a new tab instead or a new OS :doc:`launch <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 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 make sense when cloning are ignored. Most prominently, the following options are
are ignored: :option:`launch --allow-remote-control`, :option:`launch ignored: :option:`--allow-remote-control <launch --allow-remote-control>`,
--copy-cmdline`, :option:`launch --copy-env`, :option:`launch --stdin-source`, :option:`--copy-cmdline <launch --copy-cmdline>`, :option:`--copy-env <launch
:option:`launch --marker` and :option:`launch --watcher`. --copy-env>`, :option:`--stdin-source <launch --stdin-source>`,
:option:`--marker <launch --marker>` and :option:`--watcher <launch --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 cloned window using environment variables. It will automatically clone virtual
environments created by the python venv module or conda. In addition, setting the environments created by the :link:`Python venv module
env var :file:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause <https://docs.python.org/3/library/venv.html>` or :link:`Conda
that file to be sourced in the cloned window. Similarly, setting <https://conda.io/>`. In addition, setting the
:file:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that code to be env var :envvar:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that
run in the cloned window with :code:`eval`. This can be controlled by 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`. :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 state (mainly CWD and env vars) and this state is transmitted to kitty and
restored by the shell integration scripts in the cloned window. restored by the shell integration scripts in the cloned window.