From f145427ff5fcaf55993c2d490d5539af439518bb Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Wed, 25 Jun 2025 16:21:49 +0100
Subject: [PATCH] Improve discoverability of using dumb-emacs-ansi terminal
 type

* doc/emacs/misc.texi (Interactive Shell, Shell Options):
* lisp/comint.el (comint-terminfo-terminal): Mention setting
comint-terminfo-terminal to "dumb-emacs-ansi" when the system's
terminfo database contains a definition for that terminal type.

(cherry picked from commit d05b59c8be5f350497ca142bc94ade23c568ad15)
---
 doc/emacs/misc.texi | 20 +++++++++++++-------
 lisp/comint.el      | 10 ++++++++--
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 910df0ce696..ad47dfa49f4 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -985,6 +985,10 @@ from.  For example, if you use bash, the file sent to it is
 @file{~/.emacs_bash}.  If this file is not found, Emacs tries with
 @file{~/.emacs.d/init_@var{shellname}.sh}.
 
+  You can enable colorized output for many commands by customizing the
+variable @code{comint-terminfo-terminal} to the value
+@samp{"dumb-emacs-ansi"} (@pxref{Shell Options}).
+
   To specify a coding system for the shell, you can use the command
 @kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can
 also change the coding system for a running subshell by typing
@@ -1568,13 +1572,15 @@ underlying shell, of course.
 @vindex system-uses-terminfo
 @vindex TERM@r{, environment variable, in sub-shell}
 Comint mode sets the @env{TERM} environment variable to a safe default
-value, but this value disables some useful features.  For example,
-color is disabled in applications that use @env{TERM} to determine if
-color is supported.  Therefore, Emacs provides an option
-@code{comint-terminfo-terminal} to let you choose a terminal with more
-advanced features, as defined in your system's terminfo database.
-Emacs will use this option as the value for @env{TERM} so long as
-@code{system-uses-terminfo} is non-@code{nil}.
+value, but this disables some useful features.  For example, colorized
+output is disabled in applications that use @env{TERM} to determine
+whether color is supported.  If the terminfo database on your system
+contains a definition for the @samp{"dumb-emacs-ansi"} terminal type (as
+all recent versions of terminfo do), you can enable advanced terminal
+features, including color, by customizing the option
+@code{comint-terminfo-terminal} to @samp{"dumb-emacs-ansi"}.  Emacs will
+use @code{comint-terminfo-terminal} as the value for @env{TERM} so long
+as @code{system-uses-terminfo} is non-@code{nil}.
 
 Both @code{comint-terminfo-terminal} and @code{system-uses-terminfo}
 can be declared as connection-local variables to adjust these options
diff --git a/lisp/comint.el b/lisp/comint.el
index 7bb90d76f08..d343f1d5786 100644
--- a/lisp/comint.el
+++ b/lisp/comint.el
@@ -523,8 +523,14 @@ executed once, when the buffer is created."
   :group 'comint)
 
 (defcustom comint-terminfo-terminal "dumb"
-  "Value to use for TERM when the system uses terminfo."
-  :type 'string
+  "Value to use for TERM when the system uses terminfo.
+If the system's terminfo database contains a definition for the
+\"dumb-emacs-ansi\" terminal (as all recent versions of terminfo do),
+set this to \"dumb-emacs-ansi\" and then some terminfo-aware programs
+will send colorized output when run under Comint."
+  :type '(choice (const "dumb")
+                 (const "dumb-emacs-ansi")
+                 string)
   :group 'comint
   :version "26.1")
 
-- 
2.39.5