From db7df561e991ef093343b2ea15df03a5438362b8 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 24 Apr 2025 12:32:02 +0300
Subject: [PATCH] ; Improve documentation of 'modifier-bar-mode'

* doc/emacs/custom.texi (Modifier Keys):
* doc/emacs/frames.texi (Tool Bars):
* lisp/tool-bar.el (modifier-bar-mode): Improve documentation of
'modifier-bar-mode'.

(cherry picked from commit 49ea1f64c77415a893f59e0c4f4ebef6c499541b)
---
 doc/emacs/custom.texi |  4 ++++
 doc/emacs/frames.texi | 21 ++++++++++++---------
 lisp/tool-bar.el      | 11 ++++++-----
 3 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 09093b05ad6..95316afc006 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2125,6 +2125,10 @@ You can similarly enter the Shift, Control, and Meta modifiers by
 using @kbd{C-x @@ S}, @kbd{C-x @@ c}, and @kbd{C-x @@ m}, respectively,
 although this is rarely needed.
 
+  On graphical terminals, you can enable the Modifier Bar mode, which
+allows simulating the missing modifier keys by clicking a tool-bar
+button.  @xref{Tool Bars}.
+
 @node Function Keys
 @subsection Rebinding Function Keys
 
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 1fa6e0b5b33..c2451e87715 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1346,15 +1346,18 @@ displayed by moving the mouse pointer to the top of the screen.
 @cindex displaying modifier keys in the tool bar
 @cindex mode, Modifier Bar
 @cindex Modifier Bar
-  Keyboards often lack one or more of the modifier keys that Emacs
-might want to use, making it difficult or impossible to input key
-sequences that contain them.  Emacs can optionally display a list of
-buttons that act as substitutes for modifier keys within the tool bar;
-these buttons are also referred to as the ``modifier bar''.  Clicking
-an icon within the modifier bar will cause a modifier key to be
-applied to the next keyboard event that is read.  The modifier bar is
-displayed when the global minor mode @code{modifier-bar-mode} is
-enabled; to do so, type @kbd{M-x modifier-bar-mode}.
+  Keyboards often lack one or more of the modifier keys (@pxref{Modifier
+Keys}) that Emacs users might want to use, making it difficult or
+impossible to input key sequences with these modifiers.  For example,
+many keyboards lack the Hyper and Super modifiers, and smartphones
+usually also lack Ctrl and Alt modifiers.  Emacs can optionally display
+a tool bar of buttons that can substitute the modifier keys; this
+additional tool bar is known as the @dfn{modifier bar}.  Clicking a
+button within the modifier bar will cause the modifier key shown on the
+button to be applied to the next keyboard event that Emacs reads.  The
+modifier bar is displayed when the global minor mode
+@code{modifier-bar-mode} is enabled; to do so, type @kbd{M-x
+modifier-bar-mode}.
 
 @node Tab Bars
 @section Tab Bars
diff --git a/lisp/tool-bar.el b/lisp/tool-bar.el
index 8f55af155b9..23e3dc0dfd3 100644
--- a/lisp/tool-bar.el
+++ b/lisp/tool-bar.el
@@ -532,12 +532,13 @@ decoding the current key sequence, nil otherwise."
   (not (memq modifier modifier-bar-modifier-list)))
 
 (define-minor-mode modifier-bar-mode
-  "Toggle display of the modifier bar.
+  "Toggle display of the key-modifier tool bar.
 
-When enabled, a small tool bar will be displayed next to the tool
-bar containing items bound to
-`tool-bar-event-apply-control-modifier' and its related commands,
-which see."
+When enabled, a small tool bar will be displayed in addition to the
+regular tool bar, containing buttons for key modifiers such as
+Ctrl, Shift, Alt, etc.  This is useful on terminals whose keyboard
+has no keys for these modifiers, such as smartphones and other
+devices with small keyboards."
   :init-value nil
   :global t
   :group 'tool-bar
-- 
2.39.5