Docs: Improve the FAQ

Add more text roles and links.
Document `PATH` in the glossary.

docs/faq.rst

@@ -27,14 +27,15 @@ turned off for specific symbols using :opt:`narrow_symbols`.
 Using a color theme with a background color does not work well in vim?
 -----------------------------------------------------------------------
 
-First make sure you have not changed the TERM environment variable, it should
+First make sure you have not changed the :envvar:`TERM` environment variable, it
-be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file
+should be ``xterm-kitty``. vim uses *background color erase* even if the
-does not contain the ``bce`` capability. This is a bug in vim. You can work around
+terminfo file does not contain the ``bce`` capability. This is a bug in vim. You
-it by adding the following to your vimrc::
+can work around it by adding the following to your vimrc::
 
     let &t_ut=''
 
-See :doc:`here <deccara>` for why |kitty| does not support background color erase.
+See :doc:`here <deccara>` for why |kitty| does not support background color
+erase.
 
 
 I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
@@ -47,26 +48,26 @@ terminfo files to the server::
     kitty +kitten ssh myserver
 
 This :doc:`ssh kitten <kittens/ssh>` takes all the same command line arguments
-as ssh, you can alias it to something small in your shell's rc files to avoid
+as :program:`ssh`, you can alias it to something small in your shell's rc files
-having to type it each time::
+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
+If the ssh kitten fails, use the following one-liner instead (it is slower as it
-is slower as it needs to ssh into the server twice, but will work with most
+needs to ssh into the server twice, but will work with most servers)::
-servers)::
 
     infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
 
-If you are behind a proxy (like Balabit) that prevents this, or ``tic`` comes
+If you are behind a proxy (like Balabit) that prevents this, or :program:`tic`
-with macOS that does not support reading from STDIN, you must redirect the 1st
+comes with macOS that does not support reading from STDIN, you must redirect the
-command to a file, copy that to the server and run ``tic`` manually.  If you
+first command to a file, copy that to the server and run :program:`tic`
-connect to a server, embedded or Android system that doesn't have ``tic``, copy over
+manually. If you connect to a server, embedded or Android system that doesn't
-your local file terminfo to the other system as :file:`~/.terminfo/x/xterm-kitty`.
+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
-have ssh do this automatically, if possible, when connecting to a server, so that
+have :program:`ssh` do this automatically, if possible, when connecting to a
-all terminals work transparently.
+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
@@ -84,9 +85,9 @@ command to apply your change (on the server)::
 Keys such as arrow keys, backspace, delete, home/end, etc. do not work when using su or sudo?
 -------------------------------------------------------------------------------------------------
 
-Make sure the TERM environment variable, is ``xterm-kitty``.  And either the
+Make sure the :envvar:`TERM` environment variable, is ``xterm-kitty``.  And
-TERMINFO environment variable points to a directory containing :file:`x/xterm-kitty`
+either the :envvar:`TERMINFO` environment variable points to a directory
-or that file is under :file:`~/.terminfo/x/`.
+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/`::
 
@@ -94,18 +95,19 @@ For macOS, you may also need to put that file under :file:`~/.terminfo/78/`::
     ln -snf ../x/xterm-kitty ~/.terminfo/78/xterm-kitty
     tic -x -o ~/.terminfo "$KITTY_INSTALLATION_DIR/terminfo/kitty.terminfo"
 
-Note that ``sudo`` might remove TERMINFO.  Then setting it at the shell prompt can
+Note that :program:`sudo` might remove :envvar:`TERMINFO`. Then setting it at
-be too late, because command line editing may not be reinitialized.  In that case
+the shell prompt can be too late, because command line editing may not be
-you can either ask ``sudo`` to set it or if that is not supported, insert an ``env``
+reinitialized. In that case you can either ask :program:`sudo` to set it or if
-command before starting the shell, or, if not possible, after sudo start another
+that is not supported, insert an :program:`env` command before starting the
-Shell providing the right terminfo path::
+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 sudo to preserve TERMINFO by running ``sudo
+You can configure :program:`sudo` to preserve :envvar:`TERMINFO` by running
-visudo`` and adding the following line::
+``sudo visudo`` and adding the following line::
 
     Defaults env_keep += "TERM TERMINFO"
 
@@ -129,15 +131,15 @@ You can also define keyboard shortcuts to set colors, for example::
 
     map f1 set_colors --configured /path/to/some/config/file/colors.conf
 
-Or you can enable :doc:`remote control <remote-control>` for |kitty| and use :ref:`at_set-colors`.
+Or you can enable :doc:`remote control <remote-control>` for |kitty| and use
-The shortcut mapping technique has the same syntax as the remote control
+:ref:`at_set-colors`. The shortcut mapping technique has the same syntax as the
-command, for details, see :ref:`at_set-colors`.
+remote control command, for details, see :ref:`at_set-colors`.
 
 To change colors when SSHing into a remote host, use the :opt:`color_scheme
 <kitten-ssh.color_scheme>` setting for the :doc:`ssh kitten <kittens/ssh>`.
 
 Additionally, You can use the
-`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`_
+`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`__
 to set colors. Examples of using OSC escape codes to set colors::
 
     Change the default foreground color:
@@ -154,7 +156,7 @@ to set colors. Examples of using OSC escape codes to set colors::
     printf '\x1b]4;n;green\x1b\\'
 
 You can use various syntaxes/names for color specifications in the above
-examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`_
+examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`__
 for full details.
 
 If a ``?`` is given rather than a color specification, kitty will respond
@@ -167,14 +169,15 @@ How do I specify command line options for kitty on macOS?
 Apple does not want you to use command line options with GUI applications. To
 workaround that limitation, |kitty| will read command line options from the file
 :file:`<kitty config dir>/macos-launch-services-cmdline` when it is launched
-from the GUI, i.e. by clicking the |kitty| application icon or using ``open -a kitty``.
+from the GUI, i.e. by clicking the |kitty| application icon or using
-Note that this file is *only read* when running via the GUI.
+``open -a kitty``. Note that this file is *only read* when running via the GUI.
 
-You can, of course, also run |kitty| from a terminal with command line options, using:
+You can, of course, also run |kitty| from a terminal with command line options,
-:file:`/Applications/kitty.app/Contents/MacOS/kitty`.
+using: :file:`/Applications/kitty.app/Contents/MacOS/kitty`.
+
+And within |kitty| itself, you can always run |kitty| using just ``kitty`` as it
+cleverly adds itself to the :envvar:`PATH`.
 
-And within |kitty| itself, you can always run |kitty| using just `kitty` as it
-cleverly adds itself to the ``PATH``.
 
 I catted a binary file and now kitty is hung?
 -----------------------------------------------
@@ -182,10 +185,10 @@ I catted a binary file and now kitty is hung?
 **Never** output unknown binary data directly into a terminal.
 
 Terminals have a single channel for both data and control. Certain bytes
-are control codes. Some of these control codes are of arbitrary length, so
+are control codes. Some of these control codes are of arbitrary length, so if
-if the binary data you output into the terminal happens to contain the starting
+the binary data you output into the terminal happens to contain the starting
-sequence for one of these control codes, the terminal will hang waiting for
+sequence for one of these control codes, the terminal will hang waiting for the
-the closing sequence. Press :kbd:`ctrl+shift+delete` to reset the terminal.
+closing sequence. Press :sc:`reset_terminal` to reset the terminal.
 
 If you do want to cat unknown data, use ``cat -v``.
 
@@ -193,30 +196,34 @@ If you do want to cat unknown data, use ``cat -v``.
 kitty is not able to use my favorite font?
 ---------------------------------------------
 
-|kitty| achieves its stellar performance by caching alpha masks of each
+|kitty| achieves its stellar performance by caching alpha masks of each rendered
-rendered character on the GPU, and rendering them all in parallel. This means
+character on the GPU, and rendering them all in parallel. This means it is a
-it is a strictly character cell based display. As such it can use only
+strictly character cell based display. As such it can use only monospace fonts,
-monospace fonts, since every cell in the grid has to be the same size.
+since every cell in the grid has to be the same size. Furthermore, it needs
-Furthermore, it needs fonts to be freely resizable, so it does not support
+fonts to be freely resizable, so it does not support bitmapped fonts.
-bitmapped fonts.
 
 .. note::
-   If you are trying to use a font patched with NERD font symbols, dont do that
+   If you are trying to use a font patched with `Nerd Fonts
-   as patching destroys fonts. There is no need, simply install the standalone
+   <https://nerdfonts.com/>`__ symbols, don't do that as patching destroys
-   NERD font (the file :file:`NerdFontsSymbolsOnly.zip` from the `NERD font
+   fonts. There is no need, simply install the standalone ``Symbols Nerd Font``
-   releases page <https://github.com/ryanoasis/nerd-fonts/releases>`__). kitty
+   (the file :file:`NerdFontsSymbolsOnly.zip` from the `Nerd Fonts releases page
-   should pick up symbols from it automatically, and you can tell it to do so
+   <https://github.com/ryanoasis/nerd-fonts/releases>`__). kitty should pick up
-   explicitly in case it doesnt with the :opt:`symbol_map` directive::
+   symbols from it automatically, and you can tell it to do so explicitly in
+   case it doesn't with the :opt:`symbol_map` directive::
 
         symbol_map U+23FB-U+23FE,U+2665,U+26A1,U+2B58,U+E000-U+E00A,U+E0A0-U+E0A3,U+E0B0-U+E0C8,U+E0CA,U+E0CC-U+E0D2,U+E0D4,U+E200-U+E2A9,U+E300-U+E3E3,U+E5FA-U+E62F,U+E700-U+E7C5,U+F000-U+F2E0,U+F300-U+F31C,U+F400-U+F4A9,U+F500-U+F8FF Symbols Nerd Font
 
+   Those Unicode symbols beyond the ``E000-F8FF`` Unicode private use area are
+   not included.
+
 If your font is not listed in ``kitty +list-fonts`` it means that it is not
-monospace or is a bitmapped font. On Linux you can list all monospace fonts with::
+monospace or is a bitmapped font. On Linux you can list all monospace fonts
+with::
 
     fc-list : family spacing outline scalable | grep -e spacing=100 -e spacing=90 | grep -e outline=True | grep -e scalable=True
 
-Note that the spacing property is calculated by fontconfig based on actual
+Note that the spacing property is calculated by fontconfig based on actual glyph
-glyph widths in the font. If for some reason fontconfig concludes your favorite
+widths in the font. If for some reason fontconfig concludes your favorite
 monospace font does not have ``spacing=100`` you can override it by using the
 following :file:`~/.config/fontconfig/fonts.conf`::
 
@@ -278,7 +285,7 @@ homepage:
 
 On macOS you can change the icon by following the steps:
 
-#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+i`
+#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+I`
 #. Drag :file:`kitty.icns` onto the application icon in the kitty info pane
 #. Delete the icon cache and restart Dock::
 
@@ -301,7 +308,7 @@ the :sc:`send_text <send_text>` you can use the ``show_key`` kitten. Run::
 Then press the key you want to emulate. Note that this kitten will only show
 keys that actually reach the terminal program, in particular, keys mapped to
 actions in kitty will not be shown. To check those first map them to
-:code:`no_op`.
+:ac:`no_op`.
 
 How do I open a new window or tab with the same working directory as the current window?
 --------------------------------------------------------------------------------------------
@@ -328,8 +335,8 @@ variables which kitty will now inherit.
 You need to make sure that the environment variables you define in your shell's
 rc files are either also defined system wide or via the :opt:`env` directive in
 :file:`kitty.conf`. Common environment variables that cause issues are those
-related to localization, such as ``LANG, LC_*`` and loading of configuration
+related to localization, such as :envvar:`LANG`, ``LC_*`` and loading of
-files such as ``XDG_*, KITTY_CONFIG_DIRECTORY``.
+configuration files such as ``XDG_*``, :envvar:`KITTY_CONFIG_DIRECTORY`.
 
 To see the environment variables that kitty sees, you can add the following
 mapping to :file:`kitty.conf`::
@@ -346,40 +353,42 @@ sorts of places where they may or may not work.
 I am using tmux and have a problem
 --------------------------------------
 
-First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`, do
+First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`,
-not use them, if at all possible. kitty contains features that do all of what
+do not use them, if at all possible. kitty contains features that do all of what
 tmux does, but better, with the exception of remote persistence (:iss:`391`).
 If you still want to use tmux, read on.
 
 Image display will not work, see `tmux issue
-<https://github.com/tmux/tmux/issues/1391>`_.
+<https://github.com/tmux/tmux/issues/1391>`__.
 
-Using ancient versions of tmux such as 1.8 will
+Using ancient versions of tmux such as 1.8 will cause gibberish on screen when
-cause gibberish on screen when pressing keys (:iss:`3541`).
+pressing keys (:iss:`3541`).
 
-If you are using tmux with multiple terminals or you start it under one
+If you are using tmux with multiple terminals or you start it under one terminal
-terminal and then switch to another and these terminals have different TERM
+and then switch to another and these terminals have different :envvar:`TERM`
-variables, tmux will break. You will need to restart it as tmux does not
+variables, tmux will break. You will need to restart it as tmux does not support
-support multiple terminfo definitions.
+multiple terminfo definitions.
 
 If you use any of the advanced features that kitty has innovated, such as
-styled underlines, desktop notifications, extended keyboard support, etc.
+:doc:`styled underlines </underlines>`, :doc:`desktop notifications
-they may or may not work, depending on the whims of tmux's maintainer, your
+</desktop-notifications>`, :doc:`extended keyboard support
-version of tmux, etc.
+</keyboard-protocol>`, etc. they may or may not work, depending on the whims of
+tmux's maintainer, your version of tmux, etc.
 
 
 I opened and closed a lot of windows/tabs and top shows kitty's memory usage is very high?
 -------------------------------------------------------------------------------------------
 
-``top`` is not a good way to measure process memory usage. That is because on
+:program:`top` is not a good way to measure process memory usage. That is
-modern systems, when allocating memory to a process, the C library functions
+because on modern systems, when allocating memory to a process, the C library
-will typically allocate memory in large blocks, and give the process chunks of
+functions will typically allocate memory in large blocks, and give the process
-these blocks. When the process frees a chunk, the C library will not
+chunks of these blocks. When the process frees a chunk, the C library will not
 necessarily release the underlying block back to the OS. So even though the
-application has released the memory, ``top`` will still claim the process is
+application has released the memory, :program:`top` will still claim the process
-using it.
+is using it.
 
-To check for memory leaks, instead use a tool like ``valgrind``. Run::
+To check for memory leaks, instead use a tool like `Valgrind
+<https://valgrind.org/>`__. Run::
 
     PYTHONMALLOC=malloc valgrind --tool=massif kitty
 
@@ -392,18 +401,19 @@ that window, maybe run yes or find again. Then quit kitty and run::
 You will see the allocations graph goes up when you opened the windows, then
 goes back down when you closed them, indicating there were no memory leaks.
 
-For those interested, you can get a similar profile out of ``valgrind`` as you get
+For those interested, you can get a similar profile out of :program:`valgrind`
-with ``top`` by adding ``--pages-as-heap=yes`` then you will see that memory
+as you get with :program:`top` by adding ``--pages-as-heap=yes`` then you will
-allocated in malloc is not freed in free. This can be further refined if you
+see that memory allocated in malloc is not freed in free. This can be further
-use `glibc`` as your C library by setting the environment variable
+refined if you use ``glibc`` as your C library by setting the environment
-``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free memory
+variable ``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free
-allocated in sizes of more than 64 bytes. With this set, memory usage will
+memory allocated in sizes of more than 64 bytes. With this set, memory usage
-climb high, then fall when closing windows, but not fall all the way back. The
+will climb high, then fall when closing windows, but not fall all the way back.
-remaining used memory can be investigated using valgrind again, and it will
+The remaining used memory can be investigated using valgrind again, and it will
 come from arenas in the GPU drivers and the per thread arenas glibc's malloc
-maintains. These too allocate memory in large blocks and dont release it back
+maintains. These too allocate memory in large blocks and don't release it back
 to the OS immediately.
 
+
 Why does kitty sometimes start slowly on my Linux system?
 -------------------------------------------------------------------------------------------
 
@@ -427,4 +437,4 @@ The correct command will depend on your situation and hardware.
 :file:`libEGL_mesa.so` and ignore :file:`libEGL_nvidia.so` also available on the
 system, which will wake the NVIDIA card during device enumeration.
 ``MESA_LOADER_DRIVER_OVERRIDE`` also assures that Mesa won't offer any NVIDIA
-card during enumeration, and will instead just use `/lib/dri/radeonsi_dri.so`.
+card during enumeration, and will instead just use :file:`radeonsi_dri.so`.

docs/glossary.rst

@@ -109,6 +109,10 @@ Variables that kitty sets when running child programs
    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:: PATH
+
+   kitty prepends itself to the PATH of its own environment to ensure the
+   functions calling :program:`kitty` will work properly.
 
 .. envvar:: KITTY_WINDOW_ID