path: root/README.terminfo.rst
diff options
Diffstat (limited to 'README.terminfo.rst')
1 files changed, 77 insertions, 0 deletions
diff --git a/README.terminfo.rst b/README.terminfo.rst
new file mode 100644
index 00000000000..c5f4b6db6fe
--- /dev/null
+++ b/README.terminfo.rst
@@ -0,0 +1,77 @@
+Terminfo Entries
+:Author: Sebastian J. Bronner <>
+:Date: 2019-10-30
+The Problem
+Most Linux-based distributions will have the bulk of their terminfo entries in
+the ``ncurses`` package. These live in ``/usr/share/terminfo``. There you will
+find several entries for ``st``. These, however, do not work well with current
+versions of ``st``. You need the terminfo entries supplied with ``st``.
+Specifically, I have observed the following issues when using the terminfo
+entries supplied with ``ncurses``:
+* Start ``st``.
+* Run ``tmux`` in the ``st`` window.
+* Run ``nvim`` in ``tmux``.
+ * ``tmux`` will crash immediately with the following message:
+ .. code:: console
+ [lost server]
+ %
+* Run ``w3m`` with any URL in ``tmux``.
+ * ``w3m`` will not react to any key presses (most notably the arrow keys and
+ ``q``) and must be terminated with ``killall w3m``.
+ * The command line returned where ``w3m`` was running will show all the
+ missing keypresses.
+For reference, I performed these tests using the following software versions:
+``st`` 0.8.2, ``tmux`` 2.9_a, ``neovim`` 0.4.2, and ``w3m``
+The Solution
+The ``ncurses`` package should stop shipping terminfo entries for ``st``. These
+should then be provided in ``/usr/share/terminfo`` by this (and other) ``st``
+packages. The conflicting terminfo entries are
+* ``st`` and
+* ``st-256color``.
+Additional entries that could be considered for removal from ``ncurses`` are
+* ``st-0.6``,
+* ``st-0.7``,
+* ``st-16color``,
+* ``st-direct``,
+* ``stterm`` (for distributions that rename ``st`` to ``stterm``),
+* ``stterm-16color``, and
+* ``stterm-256color``.
+This solution cannot be implemented without the cooperation of ``ncurses``
+since many distributions (including Arch Linux) do not allow for two packages
+that provide files with identical paths to be installed side-by-side.
+Therefore, I am bringing this to the attention of the ``ncurses`` team.
+The Workaround
+A somewhat painful, albeit pragmatic, workaround is as follows: A user that
+encounters issues that are due to mismatched terminfo entries, such as those
+above, can symlink the terminfo entries included in this package into her
+user-level terminfo database using the following commands:
+.. code:: shell
+ mkdir ~/.terminfo/s
+ ln -s /usr/share/st/terminfo/s/* ~/.terminfo/s