; Describe problems with 'screen' and COLORTERM variable

* etc/PROBLEMS: Describe the issue with 'screen' and
COLORTERM=truecolor.  (Bug#62237)

1 files changed, 27 insertions, 0 deletions

diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 69c42e9bed0..3c75e81b8b9 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -2293,6 +2293,33 @@ recommended way of turning on Font-lock is by typing "M-x
 global-font-lock-mode RET" or by customizing the variable
 'global-font-lock-mode'.
 
+** Colors are not available or messed up on TTY frames inside 'screen'.
+
+This can happen if you have COLORTERM=truecolor defined in the
+environment when Emacs starts, but your version of 'screen' doesn't
+actually support 24-bit true colors.
+
+The COLORTERM environment variable is supposed to be set to the value
+"truecolor" only if the terminal used by Emacs actually supports true
+color.  Emacs does not have any means of verifying that this support
+is available, it takes the fact that the variable is defined to this
+value as an indication that true color support is, in fact, available,
+and uses color setting commands that COLORTERM=truecolor presumes,
+bypassing the usual Terminfo capabilities related to colors.
+
+Some text-mode terminals, such as GNOME Terminal, are known to set
+this environment variable, supposedly to announce their own support
+for true color; however the setting is then inherited by any other
+terminal emulators started from such a terminal, even though those
+other terminal emulators might not themselves support true color using
+the same commands as Emacs uses when it sees COLORTERM=truecolor.
+
+The solution is to either upgrade to a newer version of 'screen'
+(version 5.x or later reportedly supports true color), or to unset the
+COLORTERM variable before starting 'screen', and let Emacs use the
+color support provided by the terminal emulator as defined in the
+Terminfo database.
+
 ** Unexpected characters inserted into the buffer when you start Emacs.
 See e.g. <URL:https://debbugs.gnu.org/11129>