From 4b70de228d663cdbbae9668e6e990b0064e72fda Mon Sep 17 00:00:00 2001
From: =?utf8?q?Rami=20Ylim=C3=A4ki?= <rami.ylimaki@vincit.fi>
Date: Tue, 13 Feb 2018 07:33:39 +0200
Subject: [PATCH] Expand direct color description in Emacs FAQ

* doc/misc/efaq.texi (Colors on a TTY): Show how to list direct
mode TERM definitions.  (Bug#30429)
---
 doc/misc/efaq.texi | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index fef9b1051b0..5392748d00f 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1490,6 +1490,7 @@ exhibits all the colors Emacs knows about on the current display.
 
 Syntax highlighting is on by default since version 22.1.
 
+@cindex direct color in terminals
 Emacs 26.1 and later support direct color mode in terminals.  If Emacs
 finds Terminfo capabilities @samp{setb24} and @samp{setf24}, 24-bit
 direct color mode is used.  The capability strings are expected to
@@ -1504,14 +1505,17 @@ $ cat terminfo-custom.src
 
 xterm-emacs|xterm with 24-bit direct color mode for Emacs,
   use=xterm-256color,
-  setb24=\E[48\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%dm,
-  setf24=\E[38\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%dm,
+  setb24=\E[48\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\
+     %d\:%p1%@{255@}%&%dm,
+  setf24=\E[38\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\
+     %d\:%p1%@{255@}%&%dm,
 
 $ tic -x -o ~/.terminfo terminfo-custom.src
 
 $ TERM=xterm-emacs emacs -nw
 @end example
 
+@cindex 24-bit direct color mode
 Emacs 27.1 and later support Terminfo capability @samp{RGB} for
 detecting 24-bit direct color mode.  Multiple standard terminal
 definitions support this capability.
@@ -1519,12 +1523,29 @@ definitions support this capability.
 @example
 $ TERM=xterm-direct infocmp | grep seta[bf]
 
-  setab=\E[%?%p1%@{8@}%<%t4%p1%d%e48\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m,
-  setaf=\E[%?%p1%@{8@}%<%t3%p1%d%e38\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m,
+  setab=\E[%?%p1%@{8@}%<%t4%p1%d%e48\:2\:\:%p1%@{65536@}%/\
+     %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m,
+  setaf=\E[%?%p1%@{8@}%<%t3%p1%d%e38\:2\:\:%p1%@{65536@}%/\
+     %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m,
 
 $ TERM=xterm-direct emacs -nw
 @end example
 
+If your terminal is incompatible with XTerm, you may have to use
+another @env{TERM} definition.  Any terminal whose name includes
+@samp{direct} should be a candidate.  The @command{toe} command can be
+used to find out which of these are installed on your system:
+
+@example
+$ toe | grep '\-direct'
+
+konsole-direct  konsole with direct-color indexing
+vte-direct      vte with direct-color indexing
+st-direct       st with direct-color indexing
+xterm-direct2   xterm with direct-color indexing (old)
+xterm-direct    xterm with direct-color indexing
+@end example
+
 Terminals with @samp{RGB} capability treat pixels #000001 - #000007 as
 indexed colors to maintain backward compatibility with applications
 that are unaware of direct color mode.  Therefore the seven darkest
-- 
2.39.2