From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 21 Aug 2021 08:49:56 +0000 (+0300)
Subject: Improve documentation of context menus
X-Git-Tag: emacs-28.0.90~1397
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=72e688eacdb5fa8c4f1bc52bdcb304201ce8d2f3;p=emacs.git

Improve documentation of context menus

* doc/lispref/modes.texi (Major Mode Conventions): Add conventions
of setting menu-bar menus and context menus for a major mode.
* doc/emacs/frames.texi (Menu Mouse Clicks): Fix description of
context menu functionality.
---

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 5b15e6290d0..d582d24e766 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -370,11 +370,18 @@ This menu is for changing the default face within the window's buffer.
 @findex context-menu-mode
 @vindex context-menu-functions
 @kindex Down-mouse-3
-  Some graphical applications use @kbd{mouse-3} for a mode-specific
-menu.  If you prefer @kbd{mouse-3} in Emacs to bring up such a context
-menu instead of running the @code{mouse-save-then-kill} command,
-enable @code{context-menu-mode} and customize the variable
-@code{context-menu-functions}.
+  Many GUI applications use @kbd{mouse-3} to display @dfn{context
+menus}: menus that provide access to various pertinent settings and
+actions for the location and context of the mouse click.  If you
+prefer this in Emacs over the default function of @kbd{mouse-3}, which
+is bound to the @code{mouse-save-then-kill} command (@pxref{Mouse
+Commands}), you can enable the minor mode @code{context-menu-mode}.
+Then Emacs will show context menus when you click @kbd{mouse-3}.  The
+exact contents of these context menus depends on the current major
+mode and the buffer contents around the place where you click the
+mouse.  To customize the contents of the context menu, you can use the
+variable @code{context-menu-functions} (@pxref{Major Mode
+Conventions,,, elisp, The Emacs Lisp Reference Manual}).
 
 @node Mode Line Mouse
 @section Mode Line Mouse Commands
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d9caeab3bc3..951f30fc6ff 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -470,6 +470,22 @@ setting up a buffer-local value for the variable
 Each face that the mode defines should, if possible, inherit from an
 existing Emacs face.  @xref{Basic Faces}, and @ref{Faces for Font Lock}.
 
+@item
+Consider adding a mode-specific menu to the menu bar.  This should
+preferably include the most important menu-specific settings and
+commands that will allow users discovering the main features quickly
+and efficiently.
+
+@item
+@cindex context menus, for a major mode
+@vindex context-menu-functions
+Consider adding mode-specific context menus for the mode, to be used
+if and when users activate the @code{context-menu-mode} (@pxref{Menu
+Mouse Clicks,,, emacs, The Emacs Manual}).  To this end, define a
+mode-specific function which builds one or more menus depending on the
+location of the @kbd{mouse-3} click in the buffer, and then add that
+function to the buffer-local value of @code{context-menu-functions}.
+
 @item
 The mode should specify how Imenu should find the definitions or
 sections of a buffer, by setting up a buffer-local value for the