; 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)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 09093b05ad67c47a9516ba634b0b30f37fec22a4..95316afc006b0e91d6c9d2de87c5f792dd881a02 100644 (file)
--- 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 1fa6e0b5b33ef2cad65faed88223d2318f66bbab..c2451e877157715934812290d10581cd8f5d87ff 100644 (file)
--- 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 8f55af155b9df698a3862481b4257fbb374d500e..23e3dc0dfd3a3925c5277211889f23e13f2b76f0 100644 (file)
--- 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