feature/context-menu ee1887b: Improve :type of defcustom 'context-menu-functions' and add documentation.

[Juri Linkov]

branch: feature/context-menu
commit ee1887bf54e7091a382ad24691ce0f482c61d7ea
Author: Juri Linkov <juri@linkov.net>
Commit: Juri Linkov <juri@linkov.net>

    Improve :type of defcustom 'context-menu-functions' and add documentation.
    
    * doc/emacs/frames.texi (Menu Mouse Clicks): Describe context-menu-mode
    and context-menu-functions instead of suggesting global-set-key.
    (Menu Bars): Mention context-menu-mode and context-menu-functions.
    
    * etc/NEWS: Add context-menu-mode and context-menu-functions.
    
    * lisp/mouse.el (context-menu-functions): Use :type with 
repeat/function-item.
    (context-menu-minor, context-menu-undo, context-menu-region)
    (context-menu-ffap): Improve docstrings displayed for function-item in
    defcustom of context-menu-functions.
---
 doc/emacs/frames.texi | 25 +++++++++++--------------
 etc/NEWS              | 11 ++++++++++-
 lisp/mouse.el         | 22 +++++++++++++---------
 3 files changed, 34 insertions(+), 24 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 70615f6..e03fb95 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -366,20 +366,15 @@ This menu is for changing the default face within the 
window's buffer.
 @xref{Text Scale}.
 @end table
 
+@cindex context menu
+@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 menu
-instead of running the @code{mouse-save-then-kill} command, rebind
-@kbd{mouse-3} by adding the following line to your init file
-(@pxref{Init Rebinding}):
-
-@smallexample
-(global-set-key [mouse-3]
-  '(menu-item "Menu Bar" ignore
-    :filter (lambda (_)
-              (if (zerop (or (frame-parameter nil 'menu-bar-lines) 0))
-                  (mouse-menu-bar-map)
-                (mouse-menu-major-mode-map)))))
-@end smallexample
+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}.
 
 @node Mode Line Mouse
 @section Mode Line Mouse Commands
@@ -1217,7 +1212,9 @@ the use of menu bars at startup, customize the variable
 terminals, where this makes one additional line available for text.
 If the menu bar is off, you can still pop up a menu of its contents
 with @kbd{C-mouse-3} on a display which supports pop-up menus.
-@xref{Menu Mouse Clicks}.
+Or you can enable @code{context-menu-mode} and customize the variable
+@code{context-menu-functions} to pop up a context menu with
+@kbd{mouse-3}.  @xref{Menu Mouse Clicks}.
 
   @xref{Menu Bar}, for information on how to invoke commands with the
 menu bar.  @xref{X Resources}, for how to customize the menu bar
diff --git a/etc/NEWS b/etc/NEWS
index 49396c3..4ca2623 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -346,8 +346,17 @@ onto 'file-name-history'.
 +++
 ** A prefix arg now causes 'delete-other-frames' to only iconify frames.
 
+** Menus
+
++++
+*** New mode 'context-menu-mode' for a context menu bound to 'mouse-3'.
+When this mode is enabled, clicking 'down-mouse-3' anywhere in the buffer
+pops up a context menu whose contents depends on surrounding context
+near the mouse click.  You can customize the order of the default submenus
+in the context menu by customizing the user option 'context-menu-functions'.
+
 +++
-** The "Edit => Clear" menu item now obeys a rectangular region.
+*** The "Edit => Clear" menu item now obeys a rectangular region.
 
 +++
 ** New command 'execute-extended-command-for-buffer'.
diff --git a/lisp/mouse.el b/lisp/mouse.el
index 60c4f4b..49191e3 100644
--- a/lisp/mouse.el
+++ b/lisp/mouse.el
@@ -286,14 +286,15 @@ not it is actually displayed."
   "List of functions that produce the contents of the context menu.
 Each function receives the menu as its argument and should return
 the same menu with changes such as added new menu items."
-  :type 'hook
-  :options '(context-menu-undo
-             context-menu-region
-             context-menu-global
-             context-menu-local
-             context-menu-minor
-             context-menu-vc
-             context-menu-ffap)
+  :type '(repeat
+          (choice (function-item context-menu-undo)
+                  (function-item context-menu-region)
+                  (function-item context-menu-global)
+                  (function-item context-menu-local)
+                  (function-item context-menu-minor)
+                  (function-item context-menu-vc)
+                  (function-item context-menu-ffap)
+                  (function :tag "Custom function")))
   :version "28.1")
 
 (defcustom context-menu-filter-function nil
@@ -337,7 +338,7 @@ the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-minor (menu)
-  "Minor mode submenus."
+  "Minor modes submenus."
   (run-hooks 'activate-menubar-hook 'menu-bar-update-hook)
   (define-key-after menu [separator-minor] menu-bar-separator)
   (dolist (mode (minor-mode-key-binding [menu-bar]))
@@ -357,6 +358,7 @@ the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-undo (menu)
+  "Undo menu."
   (when (cddr menu)
     (define-key-after menu [separator-undo] menu-bar-separator))
   (define-key-after menu [undo]
@@ -375,6 +377,7 @@ the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-region (menu)
+  "Region commands menu."
   (when (cddr menu)
     (define-key-after menu [separator-region] menu-bar-separator))
   (define-key-after menu [cut]
@@ -424,6 +427,7 @@ the same menu with changes such as added new menu items."
   menu)
 
 (defun context-menu-ffap (menu)
+  "File at point menu."
   (save-excursion
     (mouse-set-point last-input-event)
     (when (ffap-guess-file-name-at-point)