Docs: Improve ssh kitten documentation

Add more text roles.
Put the env example at the end.
The alias syntax of fish and bash requires quotation marks.
Document `SSH_ASKPASS` in the glossary.

docs/glossary.rst

@@ -84,6 +84,12 @@ 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:: SSH_ASKPASS
+
+   Specify the program for SSH to ask for passwords. When this is set, :doc:`ssh
+   kitten </kittens/ssh>` will use this environment variable by default. See
+   :opt:`askpass <kitten-ssh.askpass>` for details.
+
 .. envvar:: KITTY_CLONE_SOURCE_CODE
 
    Set this to some shell code that will be executed in the cloned window with

docs/kittens/ssh.rst

@@ -15,28 +15,27 @@ Truly convenient SSH
    Automatic shell integration, file transfer and reuse of connections
 
 The ssh kitten allows you to login easily to remote hosts, and automatically
-setup the environment there to be as comfortable as your local shell. You
+setup the environment there to be as comfortable as your local shell. You can
-can specify environment variables to set on the remote host and
+specify environment variables to set on the remote host and files to copy there,
-files to copy there, making your remote experience just like your
+making your remote experience just like your local shell. Additionally, it
-local shell. Additionally, it automatically sets up :ref:`shell_integration` on
+automatically sets up :ref:`shell_integration` on the remote host and copies the
-the remote host and copies the kitty terminfo database there.
+kitty terminfo database there.
 
 The ssh kitten is a thin wrapper around the traditional `ssh <https://man.openbsd.org/ssh>`__
 command line program and supports all the same options and arguments and configuration.
-In interactive usage scenarios it is a drop in replacement for ``ssh``. To try it
+In interactive usage scenarios it is a drop in replacement for :program:`ssh`.
-out, simply run:
+To try it out, simply run:
 
 .. code-block:: sh
 
     kitty +kitten ssh some-hostname-to-connect-to
 
-You should end up at a shell prompt on the remote host, with shell
+You should end up at a shell prompt on the remote host, with shell integration
-integration enabled. If you like it you can add an alias to it in your shell's
+enabled. If you like it you can add an alias to it in your shell's rc files:
-rc files:
 
 .. code-block:: sh
 
-    alias s=kitty +kitten ssh
+    alias s="kitty +kitten ssh"
 
 So now you can just type ``s hostname`` to connect.
 
@@ -44,13 +43,12 @@ If you define a mapping in :file:`kitty.conf` such as::
 
     map f1 new_window_with_cwd
 
-Then, pressing :kbd:`F1` will open a new window automatically logged
+Then, pressing :kbd:`F1` will open a new window automatically logged into the
-into the same host using the ssh kitten, at the same directory.
+same host using the ssh kitten, at the same directory.
 
-The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf`
+The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf` file
-file where you can specify environment variables to set on the remote host
+where you can specify environment variables to set on the remote host and files
-and files to copy from the local to the remote host. Let's see a
+to copy from the local to the remote host. Let's see a quick example:
-quick example:
 
 .. code-block:: conf
 
@@ -80,8 +78,9 @@ Additionally, you can pass config options on the command line:
 
 The :code:`--kitten` argument can be specified multiple times, with directives
 from :file:`ssh.conf`. These are merged with :file:`ssh.conf` as if they were
-appended to the end of that file. They apply only to the host being SSHed to
+appended to the end of that file. They apply only to the host being SSHed to by
-by this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are ignored.
+this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are
+ignored.
 
 .. warning::
 
@@ -98,8 +97,8 @@ A real world example
 Suppose you often SSH into a production server, and you would like to setup
 your shell and editor there using your custom settings. However, other people
 could SSH in as well and you don't want to clobber their settings. Here is how
-this could be achieved using the ssh kitten with zsh and vim as the shell and
+this could be achieved using the ssh kitten with :program:`zsh` and
-editor, respectively:
+:program:`vim` as the shell and editor, respectively:
 
 .. code-block:: conf
 
@@ -125,23 +124,24 @@ How it works
 The ssh kitten works by having SSH transmit and execute a POSIX sh (or
 :opt:`optionally <kitten-ssh.interpreter>` Python) bootstrap script on the
 remote host using an :opt:`interpreter <kitten-ssh.interpreter>`. This script
-reads setup data over the tty device, which kitty sends as a base64 encoded
+reads setup data over the TTY device, which kitty sends as a base64 encoded
 compressed tarball. The script extracts it and places the :opt:`files <kitten-ssh.copy>`
 and sets the :opt:`environment variables <kitten-ssh.env>` before finally
 launching the :opt:`login shell <kitten-ssh.login_shell>` with :opt:`shell
 integration <kitten-ssh.shell_integration>` enabled. The data is requested by
 the kitten over the TTY with a random one time password. kitty reads the request
 and if the password matches a password pre-stored in shared memory on the
-localhost by the kitten, the transmission is allowed. If your OpenSSH version is
+localhost by the kitten, the transmission is allowed. If your local
->= 8.4 then the data is transmitted instantly without any roundtrip delay.
+`OpenSSH <https://www.openssh.com/>`__ version is >= 8.4 then the data is
+transmitted instantly without any roundtrip delay.
 
 .. note::
 
-   When connecting to BSD hosts, it is possible the bootstrap script will
+   When connecting to BSD hosts, it is possible the bootstrap script will fail
-   fail or run slowly, because the default shells are crippled in various ways.
+   or run slowly, because the default shells are crippled in various ways.
    Your best bet is to install Python on the remote, make sure the login shell
-   is something POSIX sh compliant, and use :code:`python` as the :opt:`interpreter
+   is something POSIX sh compliant, and use :code:`python` as the
-   <kitten-ssh.interpreter>` in :file:`ssh.conf`.
+   :opt:`interpreter <kitten-ssh.interpreter>` in :file:`ssh.conf`.
 
 .. include:: /generated/conf-kitten-ssh.rst
 

kittens/ssh/options/definition.py

@@ -24,26 +24,26 @@ opt = definition.add_option
 agr('bootstrap', 'Host bootstrap configuration')  # {{{
 
 opt('hostname', '*', option_type='hostname', long_text='''
-The hostname that the following options apply to. A glob pattern to match multiple
+The hostname that the following options apply to. A glob pattern to match
-hosts can be used. Multiple hostnames can also be specified separated by spaces.
+multiple hosts can be used. Multiple hostnames can also be specified, separated
-The hostname can include an optional username in the form :code:`user@host`.
+by spaces. The hostname can include an optional username in the form
-When not specified options apply to all hosts, until the
+:code:`user@host`. When not specified options apply to all hosts, until the
-first hostname specification is found. Note that matching of hostname is done against
+first hostname specification is found. Note that matching of hostname is done
-the name you specify on the command line to connect to the remote host.
+against the name you specify on the command line to connect to the remote host.
-If you wish to include the same basic configuration for many
+If you wish to include the same basic configuration for many different hosts,
-different hosts, you can do so with the :ref:`include <include>` directive.
+you can do so with the :ref:`include <include>` directive.
 ''')
 
 opt('interpreter', 'sh', long_text='''
-The interpreter to use on the remote host. Must be either a POSIX complaint shell
+The interpreter to use on the remote host. Must be either a POSIX complaint
-or a python executable. If the default sh is not available or broken, using
+shell or a :program:`python` executable. If the default :program:`sh` is not
-an alternate interpreter can be useful.
+available or broken, using an alternate interpreter can be useful.
 ''')
 
 opt('remote_dir', '.local/share/kitty-ssh-kitten', option_type='relative_dir', long_text='''
-The location on the remote host where the files needed for this kitten
+The location on the remote host where the files needed for this kitten are
-are installed. The location is relative to the HOME directory. Absolute paths or paths
+installed. The location is relative to the HOME directory. Absolute paths or
-that resolve to a location outside the HOME are not allowed.
+paths that resolve to a location outside the HOME are not allowed.
 ''')
 
 opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
@@ -51,8 +51,7 @@ opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
 
     copy .vimrc .zshrc .config/some-dir
 
-If a file should be copied to some other destination on the remote host,
+Use :code:`--dest` to copy a file to some other destination on the remote host::
-use :code:`--dest`::
 
     copy --dest some-other-name some-file
 
@@ -79,51 +78,54 @@ integration on a per-host basis.
 ''')
 
 opt('login_shell', '', long_text='''
-The login shell to execute on the remote host. By default, the remote user account's
+The login shell to execute on the remote host. By default, the remote user
-login shell is used.
+account's login shell is used.
 ''')
 
 opt('+env', '', option_type='env', add_to_default=False, long_text='''
-Specify environment variables to set on the remote host. Note that
+Specify the environment variables to be set on the remote host. Using the
-environment variables can refer to each other, so if you use::
+name with an equal sign (e.g. :code:`env VAR=`) will set it to the empty string.
-
+Specifying only the name (e.g. :code:`env VAR`) will remove the variable from
-    env MYVAR1=a
+the remote shell environment. The special value :code:`_kitty_copy_env_var_`
-    env MYVAR2=$MYVAR1/$HOME/b
-
-The value of MYVAR2 will be :code:`a/<path to home directory>/b`. Using
-:code:`VAR=` will set it to the empty string and using just :code:`VAR`
-will delete the variable from the child process' environment. The definitions
-are processed alphabetically. The special value :code:`_kitty_copy_env_var_`
 will cause the value of the variable to be copied from the local environment.
+The definitions are processed alphabetically. Note that environment variables
+are expanded recursively, for example::
+
+    env VAR1=a
+    env VAR2=${HOME}/${VAR1}/b
+
+The value of :code:`VAR2` will be :code:`<path to home directory>/a/b`.
 ''')
 
 opt('cwd', '', long_text='''
-The working directory on the remote host to change to. Env vars in this
+The working directory on the remote host to change to. Environment variables in
-value are expanded. The default is empty so no changing is done, which
+this value are expanded. The default is empty so no changing is done, which
-usually means the home directory is used.
+usually means the HOME directory is used.
 ''')
 
 opt('color_scheme', '', long_text='''
-Specify a color scheme to use when connecting to the remote host.  If the
+Specify a color scheme to use when connecting to the remote host. If this option
-color_scheme ends with :code:`.conf` it is assumed to be the name of a config
+ends with :code:`.conf`, it is assumed to be the name of a config file to load
-file to load from the kitty config directory, otherwise it is assumed to be the
+from the kitty config directory, otherwise it is assumed to be the name of a
-name of a color theme to load via the themes kitten. Note that only colors
+color theme to load via the :doc:`themes kitten </kittens/themes>`. Note that
-applying to the text/background are changed, other config settings in the .conf
+only colors applying to the text/background are changed, other config settings
-files/themes are ignored.
+in the .conf files/themes are ignored.
 ''')
 
 opt('remote_kitty', 'if-needed', choices=('if-needed', 'no', 'yes'), long_text='''
-Make kitty available on the remote server. Useful to run kittens such as the
+Make :program:`kitty` available on the remote host. Useful to run kittens such
-icat kitten to display images or the transfer file kitten to transfer files.
+as the :doc:`icat kitten </kittens/icat>` to display images or the
-Only works if the remote server has an architecture for which pre-compiled
+:doc:`transfer file kitten </kittens/transfer>` to transfer files. Only works if
-kitty binaries are available. Note that kitty is not actually copied to the
+the remote host has an architecture for which :link:`pre-compiled kitty binaries
-remote server, instead a small bootstrap script is copied which will download
+<https://github.com/kovidgoyal/kitty/releases>` are available. Note that kitty
-and run kitty when kitty is first executed on the remote server. A value of
+is not actually copied to the remote host, instead a small bootstrap script is
-:code:`if-needed` means kitty is installed only if not already present in the
+copied which will download and run kitty when kitty is first executed on the
-system-wide PATH. A value of :code:`yes` means that kitty is installed even if
+remote host. A value of :code:`if-needed` means kitty is installed only if not
-already present, and the installed kitty takes precedence. Finally, :code:`no`
+already present in the system-wide PATH. A value of :code:`yes` means that kitty
-means no kitty is installed on the remote machine. The installed kitty
+is installed even if already present, and the installed kitty takes precedence.
-can be updated by running: :code:`kitty +update-kitty` on the remote machine.
+Finally, :code:`no` means no kitty is installed on the remote host. The
+installed kitty can be updated by running: :code:`kitty +update-kitty` on the
+remote host.
 ''')
 egr()  # }}}
 
@@ -131,20 +133,21 @@ agr('ssh', 'SSH configuration')  # {{{
 
 opt('share_connections', 'yes', option_type='to_bool', long_text='''
 Within a single kitty instance, all connections to a particular server can be
-shared. This reduces startup latency for subsequent connections and means that you have
+shared. This reduces startup latency for subsequent connections and means that
-to enter the password only once. Under the hood, it uses SSH ControlMasters and
+you have to enter the password only once. Under the hood, it uses SSH
-these are automatically cleaned up by kitty when it quits.
+ControlMasters and these are automatically cleaned up by kitty when it quits.
 ''')
 
 opt('askpass', 'unless-set', choices=('unless-set', 'ssh', 'native'), long_text='''
 Control the program SSH uses to ask for passwords or confirmation of host keys
-etc. The default is to use kitty's native askpass, unless the SSH_ASKPASS
+etc. The default is to use kitty's native :program:`askpass`, unless the
-environment variable is set. Set it to :code:`ssh` to not interfere with the
+:envvar:`SSH_ASKPASS` environment variable is set. Set this option to
-normal ssh askpass mechanism at all, which typically means that ssh will prompt
+:code:`ssh` to not interfere with the normal ssh askpass mechanism at all, which
-at the terminal. Set it to :code:`native` to always use kitty's native,
+typically means that ssh will prompt at the terminal. Set it to :code:`native`
-built-in askpass implementation. Note that not using the kitty askpass implementation
+to always use kitty's native, built-in askpass implementation. Note that not
-means that SSH might need to use the terminal before the connection is established
+using the kitty askpass implementation means that SSH might need to use the
-so the kitten cannot use the terminal to send data without an extra roundtrip,
+terminal before the connection is established, so the kitten cannot use the
-adding to initial connection latency.
+terminal to send data without an extra roundtrip, adding to initial connection
+latency.
 ''')
 egr()  # }}}