master 72e688e: Improve documentation of context menus

[Eli Zaretskii]

branch: master
commit 72e688eacdb5fa8c4f1bc52bdcb304201ce8d2f3
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    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.
---
 doc/emacs/frames.texi  | 17 ++++++++++++-----
 doc/lispref/modes.texi | 16 ++++++++++++++++
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 5b15e62..d582d24 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 d9caeab..951f30f 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -471,6 +471,22 @@ 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
 variable @code{imenu-generic-expression}, for the two variables