From a7ef1de5ace3b288bd659cae526dec638f90726e Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
Date: Fri, 18 Oct 2024 11:22:52 +0200
Subject: [PATCH] Explain tty-color-mode frame parameter more.

* doc/emacs/cmdargs.texi (Colors X): Explain that tty color
support is dynamic.
* doc/lispref/frames.texi (Font and Color Parameters): Explain
that 'tty-color-mode' can be changed on the fly.
* doc/misc/efaq.texi (Colors on a TTY): Explain how to disable
'tty-color-mode', either at startup or dynamically.

(cherry picked from commit 2c640e63a8a6ea9f2fbbb55ff44d7a8a0ec0f4b4)
---
 doc/emacs/cmdargs.texi  |  6 +++++-
 doc/lispref/frames.texi |  2 +-
 doc/misc/efaq.texi      | 15 +++++++++++++++
 3 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index ba4b45d272b..9b72b883628 100644
--- a/doc/emacs/cmdargs.texi
+++ b/doc/emacs/cmdargs.texi
@@ -1027,7 +1027,11 @@ there is no mode that supports @var{num} colors, Emacs acts as if
 @var{num} were 0, i.e., it uses the terminal's default color support
 mode.
 @end table
-If @var{mode} is omitted, it defaults to @var{ansi8}.
+If @var{mode} is omitted, it defaults to @var{ansi8}.  This support is
+dynamic: the current mode is available via the @code{tty-color-mode}
+frame parameter, and it can be changed by modifying that frame parameter.
+This means you can also specify the initial value via
+@code{default-frame-alist} instead of the command-line option.
 @end table
 
   For example, to use a coral mouse cursor and a slate blue text cursor,
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 0d3b9e0c33d..a01894897cf 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2447,7 +2447,7 @@ off color support.
 
 If the parameter's value is a symbol, it specifies a number through
 the value of @code{tty-color-mode-alist}, and the associated number is
-used instead.
+used instead.  This parameter supports dynamic changes.
 
 @vindex screen-gamma@r{, a frame parameter}
 @item screen-gamma
diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index 3554ef80bd0..cf9bce79039 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1870,6 +1870,21 @@ think that your terminal supports colors, but Emacs won't use them,
 check the @code{termcap} entry for your display type for color-related
 capabilities.
 
+If by contrast you wish to @emph{disable} tty color support, either
+start emacs with the @samp{--color=no} command-line option, or ensure
+that the frame parameter @code{tty-color-mode} is @code{no}, e.g. by
+putting the following in your init file:
+
+@lisp
+(push '(tty-color-mode . no) default-frame-alist)
+@end lisp
+
+To disable tty color support in the @emph{current} frame you can run:
+
+@lisp
+(set-frame-parameter nil 'tty-color-mode 'no)
+@end lisp
+
 The command @kbd{M-x list-colors-display} pops up a window which
 exhibits all the colors Emacs knows about on the current display.
 
-- 
2.39.5