Docs: Categorize the ssh kitten configuration options and minor tweaks

docs/kittens/ssh.rst

@@ -31,7 +31,7 @@ rc files:
 
     alias s=kitty +kitten ssh
 
-So you can now type just ``s hostname`` to connect.
+So now you can just type ``s hostname`` to connect.
 
 If you define a mapping in :file:`kitty.conf` such as::
 
@@ -76,11 +76,11 @@ 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
 by this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are ignored.
 
-.. note::
+.. warning::
 
-   Because of limitations of the design of SSH, any typing you do before the
+   Due to the limitations in the design of SSH, any typing you do before the
-   shell prompt appears may be lost. So ideally dont start typing till you see
+   shell prompt appears may be lost. So ideally don't start typing till you see
-   the shell prompt 😇.
+   the shell prompt. 😇
 
 
 .. _real_world_ssh_kitten_config:
@@ -121,12 +121,12 @@ remote server using an :opt:`interpreter <kitten-ssh.interpreter>`. This script
 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 shell
+launching the :opt:`login shell <kitten-ssh.login_shell>` with :opt:`shell
-integration enabled. The data is requested by the kitten over the TTY with a
+integration <kitten-ssh.shell_integration>` enabled. The data is requested by
-random one time password. kitty reads the request and if the password matches
+the kitten over the TTY with a random one time password. kitty reads the request
-a password pre-stored in shared memory on the localhost by the kitten, the
+and if the password matches a password pre-stored in shared memory on the
-transmission is allowed. If your OpenSSH version is >= 8.4 then the data is
+localhost by the kitten, the transmission is allowed. If your OpenSSH version is
-transmitted instantly without any roundtrip delay.
+>= 8.4 then the data is transmitted instantly without any roundtrip delay.
 
 .. note::
 

kittens/ssh/copy.py

@@ -35,9 +35,10 @@ variables and ~ are not expanded.
 
 --exclude
 type=list
-A glob pattern. Files whose names would match this pattern after transfer
+A glob pattern. Files with names matching this pattern are excluded from being
-are excluded from being transferred. Useful when adding directories. Can
+transferred. Useful when adding directories. Can
-be specified multiple times, if any of the patterns match the file will be excluded.
+be specified multiple times, if any of the patterns match the file will be
+excluded.
 '''
 
 

kittens/ssh/options/definition.py

@@ -21,11 +21,10 @@ agr = definition.add_group
 egr = definition.end_group
 opt = definition.add_option
 
-agr('host', 'Host environment')  # {{{
+agr('bootstrap', 'Host bootstrap configuration')  # {{{
 
-opt('hostname', '*', option_type='hostname',
+opt('hostname', '*', option_type='hostname', long_text='''
-    long_text='''
+The hostname that the following options apply to. A glob pattern to match multiple
-The hostname the following options apply to. A glob pattern to match multiple
 hosts can be used. Multiple hostnames can also be specified separated by spaces.
 The hostname can include an optional username in the form :code:`user@host`.
 When not specified options apply to all hosts, until the
@@ -35,6 +34,18 @@ If you wish to include the same basic configuration for many
 different hosts, 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
+or a python executable. If the default sh is not 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 computer where the files needed for this kitten
+are installed. The location is relative to the HOME directory. Absolute paths or paths
+that resolve to a location outside the HOME are not allowed.
+''')
+
 opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
 {copy_message} For example::
 
@@ -56,6 +67,21 @@ Files can be excluded when copying with :code:`--exclude`::
 Files whose remote name matches the exclude pattern will not be copied.
 For more details, see :ref:`ssh_copy_command`.
 ''')
+egr()  # }}}
+
+agr('shell', 'Login shell environment')  # {{{
+
+opt('shell_integration', 'inherited', long_text='''
+Control the shell integration on the remote host. See :ref:`shell_integration`
+for details on how this setting works. The special value :code:`inherited` means
+use the setting from :file:`kitty.conf`. This setting is useful for overriding
+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
+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
@@ -71,42 +97,22 @@ are processed alphabetically. The special value :code:`_kitty_copy_env_var_`
 will cause the value of the variable to be copied from the local machine.
 ''')
 
-
 opt('cwd', '', long_text='''
 The working directory on the remote host to change to. Env vars in this
 value are expanded. The default is empty so no changing is done, which
 usually means the home directory is used.
 ''')
+egr()  # }}}
 
-opt('share_connections', 'y', option_type='to_bool', long_text='''
+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
 to enter the password only once. Under the hood, it uses SSH ControlMasters and
 these are automatically cleaned up by kitty when it quits.
 ''')
 
-opt('interpreter', 'sh', long_text='''
-The interpreter to use on the remote host. Must be either a POSIX complaint shell
-or a python executable. If the default sh is not 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 computer where the files needed for this kitten
-are installed. The location is relative to the HOME directory. Absolute paths or paths
-that resolve to a location outside the HOME are not allowed.
-''')
-
-opt('shell_integration', 'inherited', long_text='''
-Control the shell integration on the remote host. See :ref:`shell_integration`
-for details on how this setting works. The special value :code:`inherited` means
-use the setting from :file:`kitty.conf`. This setting is useful for overriding
-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
-login shell is used.''')
-
 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