Re-organize the terminfo FAQ entries into a single one

docs/faq.rst

@@ -92,79 +92,51 @@ These settings must be placed **before** setting the ``colorscheme``. It is
 also important that the value of the vim ``term`` variable is not changed
 after these settings.
 
-I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
+I get errors about the terminal being unknown or opening the terminal failing or functional keys like arrow keys don't work?
------------------------------------------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------------------------------------------------------
 
-This happens because the |kitty| terminfo files are not available on the server.
+These issues all have the same root cause: the kitty terminfo files not being
-You can ssh in using the following command which will automatically copy the
+available. The most common way this happens is SSHing into a computer that does
-terminfo files to the server::
+not have the kitty terminfo files. The simplest fix for that is running::
 
     kitty +kitten ssh myserver
 
+It will automatically copy over the terminfo files and also magically enable
+:doc:`shell integration </shell-integration>` on the remote machine.
+
 This :doc:`ssh kitten <kittens/ssh>` takes all the same command line arguments
 as :program:`ssh`, you can alias it to something small in your shell's rc files
 to avoid having to type it each time::
 
     alias s="kitty +kitten ssh"
 
-If the ssh kitten fails, use the following one-liner instead (it is slower as it
+If this does not work, see :ref:`manual_terminfo_copy` for alternative ways to
-needs to ssh into the server twice, but will work with most servers)::
+get the kitty terminfo files onto a remote computer.
 
-    infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
+The next most common reason for this is if you are running commands as root
+using :program:`sudo` or :program:`su`. These programs often filter the
+:envvar:`TERMINFO` environment variable which is what points to the kitty
+terminfo files.
 
-If you are behind a proxy (like Balabit) that prevents this, or :program:`tic`
+First, make sure the :envvar:`TERM` is set to ``xterm-kitty`` in the sudo
-comes with macOS that does not support reading from STDIN, you must redirect the
+environment. By default, it should be automatically copied over.
-first command to a file, copy that to the server and run :program:`tic`
-manually. If you connect to a server, embedded or Android system that doesn't
-have :program:`tic`, copy over your local file terminfo to the other system as
-:file:`~/.terminfo/x/xterm-kitty`.
 
-Really, the correct solution for this is to convince the OpenSSH maintainers to
+If you are using a well maintained Linux distribution, it will have a
-have :program:`ssh` do this automatically, if possible, when connecting to a
+``kitty-terminfo`` package that you can simply install to make the kitty
-server, so that all terminals work transparently.
+terminfo files available system-wide. Then the problem will no longer occur.
 
-If the server is running FreeBSD, or another system that relies on termcap
+Alternately, you can configure :program:`sudo` to preserve :envvar:`TERMINFO`
-rather than terminfo, you will need to convert the terminfo file on your local
+by running ``sudo visudo`` and adding the following line::
-machine by running (on local machine with |kitty|)::
-
-    infocmp -CrT0 xterm-kitty
-
-The output of this command is the termcap description, which should be appended
-to :file:`/usr/share/misc/termcap` on the remote server. Then run the following
-command to apply your change (on the server)::
-
-    cap_mkdb /usr/share/misc/termcap
-
-
-Keys such as arrow keys, backspace, delete, home/end, etc. do not work when using su or sudo?
--------------------------------------------------------------------------------------------------
-
-Make sure the :envvar:`TERM` environment variable, is ``xterm-kitty``.  And
-either the :envvar:`TERMINFO` environment variable points to a directory
-containing :file:`x/xterm-kitty` or that file is under :file:`~/.terminfo/x/`.
-
-For macOS, you may also need to put that file under :file:`~/.terminfo/78/`::
-
-    mkdir -p ~/.terminfo/{78,x}
-    ln -snf ../x/xterm-kitty ~/.terminfo/78/xterm-kitty
-    tic -x -o ~/.terminfo "$KITTY_INSTALLATION_DIR/terminfo/kitty.terminfo"
-
-Note that :program:`sudo` might remove :envvar:`TERMINFO`. Then setting it at
-the shell prompt can be too late, because command line editing may not be
-reinitialized. In that case you can either ask :program:`sudo` to set it or if
-that is not supported, insert an :program:`env` command before starting the
-shell, or, if not possible, after sudo start another shell providing the right
-terminfo path::
-
-    sudo … TERMINFO=$HOME/.terminfo bash -i
-    sudo … env TERMINFO=$HOME/.terminfo bash -i
-    TERMINFO=/home/ORIGINALUSER/.terminfo exec bash -i
-
-You can configure :program:`sudo` to preserve :envvar:`TERMINFO` by running
-``sudo visudo`` and adding the following line::
 
     Defaults env_keep += "TERM TERMINFO"
 
+If none of these are suitable for you, you can run sudo as follows::
+
+    sudo TERMINFO="$TERMINFO" -s -H
+
+This will start a new root shell with the correct :envvar:`TERMINFO` value from your
+current environment copied over.
+
 If you have double width characters in your prompt, you may also need to
 explicitly set a UTF-8 locale, like::
 

docs/kittens/ssh.rst

@@ -162,3 +162,42 @@ The copy command
 --------------------
 
 .. include:: /generated/ssh-copy.rst
+
+
+.. _manual_terminfo_copy:
+
+Copying terminfo files manually
+-------------------------------------
+
+Sometimes, the ssh kitten can fail, or maybe you dont like to use it. In such
+cases, the terminfo files can be copied over manually to a server with the
+following one liner::
+
+    infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
+
+If you are behind a proxy (like Balabit) that prevents this, or you are SSHing
+into macOS where the :program:`tic` does not support reading from :file:`STDIN`,
+you must redirect the first command to a file, copy that to the server and run :program:`tic`
+manually. If you connect to a server, embedded, or Android system that doesn't
+have :program:`tic`, copy over your local file terminfo to the other system as
+:file:`~/.terminfo/x/xterm-kitty`.
+
+If the server is running a relatively modern Linux distribution and you have
+root access to it, you could simply install the ``kitty-terminfo`` package on
+the server to make the terminfo files available.
+
+Really, the correct solution for this is to convince the OpenSSH maintainers to
+have :program:`ssh` do this automatically, if possible, when connecting to a
+server, so that all terminals work transparently.
+
+If the server is running FreeBSD, or another system that relies on termcap
+rather than terminfo, you will need to convert the terminfo file on your local
+machine by running (on local machine with |kitty|)::
+
+    infocmp -CrT0 xterm-kitty
+
+The output of this command is the termcap description, which should be appended
+to :file:`/usr/share/misc/termcap` on the remote server. Then run the following
+command to apply your change (on the server)::
+
+    cap_mkdb /usr/share/misc/termcap