|PATCH| describe-minor-mode and describe-minor-mode-from-indicator

[Masatake YAMATO <jet@gyve.org>]

Dear, Stefan Monnier

(I found your name on the MAINTAINERS file as a developer 
who has interests on minor-mode/major-mode infrastructure.
So I've put your name to To: field of this mail.)

I've created a prototype of describe-minor-mode.

Background: Few days ago, I found a strange string
on mode-line: "doe". I wonder what is "doe". However,
I cannot find a way to know what is doe. M-x describe-mode
tells me nothing about doe. Finally I have to do 
"grep doe emacs/lisp/*.el".

What I did: 
I think we need something help
functions for minor mode. I wrote 3 things:

1. M-x describe-minor-mode
   The user of describe-minor-mode can give its argument
   with completion. The completion table is built from the
   name of minor modes activated on the current buffer.

2. M-x describe-minor-mode-from-indicator
   Almost the same as describe-minor-mode but the user 
   can pass an indicator instead of minor mode name to
   get help. I could not implment completion.
   (You will be not satisfied with "without completion".)

3. I added "Describe `MinorMode'" menu item to "Minor Modes" 
   popup menu. The user can get help about a minor mode with mouse-3.

I believe these functions helps beginner of Emacs. In other word
the user might be confused with strange minor mode strings. 

Regards,
Masatake YAMATO

Index: help.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help.el,v
retrieving revision 1.255
diff -u -r1.255 help.el
--- help.el	13 Jan 2003 08:04:46 -0000	1.255
+++ help.el	18 Jan 2003 08:19:27 -0000
@@ -611,6 +611,20 @@
 	  (setq minor-modes (cdr minor-modes))))
       (print-help-return-message))))
 
+(defun describe-minor-mode (minor-mode)
+  "Display documentation of a minor mode given as MINOR-MODE."
+  (interactive (list (intern (completing-read 
+			      "Minor mode: "
+			      (delete nil (mapcar
+					   (function (lambda (x)
+						       (if (eval (car x))
+							   (list (symbol-name (car x))))))
+					   minor-mode-alist))))))
+  (if (fboundp minor-mode)
+      (describe-function minor-mode)
+    (describe-variable minor-mode)))
+
+
 \f
 ;;; Automatic resizing of temporary buffers.
 
Index: bindings.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/bindings.el,v
retrieving revision 1.112
diff -u -r1.112 bindings.el
--- bindings.el	21 Dec 2002 20:19:37 -0000	1.112
+++ bindings.el	18 Jan 2003 08:19:28 -0000
@@ -376,6 +376,14 @@
   "Return the value of symbol VAR if it is bound, else nil."
   `(and (boundp (quote ,var)) ,var))
 
+
+(define-key mode-line-mode-menu [describe-minor-mode]
+  `(menu-item ,'(format "Describe `%s'" 
+			(substring mode-line-mode-menu-grab-mode-indicator 1))
+	      (lambda () (interactive) (describe-minor-mode-from-indicator))
+	      :visible (and mode-line-mode-menu-grab-mode-indicator
+			    (string= " " (substring mode-line-mode-menu-grab-mode-indicator 0 1)))))
+
 (define-key mode-line-mode-menu [overwrite-mode]
   `(menu-item ,(purecopy "Overwrite (Ovwrt)") overwrite-mode
 	      :button (:toggle . overwrite-mode)))
@@ -413,9 +421,49 @@
   `(menu-item ,(purecopy "Abbrev (Abbrev)") abbrev-mode
 	      :button (:toggle . abbrev-mode)))
 
+(defun get-mode-indicator-from-event (event)
+  (car (nth 4 (car (cdr event)))))
+(defvar mode-line-mode-menu-grab-mode-indicator nil)
+
 (defun mode-line-mode-menu (event)
   (interactive "@e")
+  (setq mode-line-mode-menu-grab-mode-indicator (get-mode-indicator-from-event event))
   (x-popup-menu event mode-line-mode-menu))
+
+(defun describe-minor-mode-from-indicator (&optional indicator)
+  "Display documentation of a minor mode specified by INDICATOR."
+  (interactive "sIndicator: ")
+  (unless indicator
+    (setq indicator mode-line-mode-menu-grab-mode-indicator))
+  (let ((minor-mode (lookup-minor-mode-from-indicator indicator)))
+    (if minor-mode
+	(describe-minor-mode minor-mode)
+      (message "Cannot find minor mode for `%s'" indicator))))
+
+(defun lookup-minor-mode-from-indicator (indicator)
+  "Return a minor mode symbol from its indicator on the modeline."
+  (if (and (< 0 (length indicator)) 
+	   (not (string= " " (substring indicator 0 1))))
+      (setq indicator (concat " " indicator)))
+  (let ((minor-modes minor-mode-alist)
+	result)
+    (while minor-modes
+      (let* ((minor-mode (car (car minor-modes)))
+	     (anindicator (car (cdr (car minor-modes)))))
+	(while (and anindicator (symbolp anindicator)
+		    (boundp anindicator)
+		    (not (eq anindicator (symbol-value anindicator))))
+	  (setq anindicator (symbol-value anindicator)))
+	(if (and (consp anindicator) 
+		 (keywordp (car anindicator))
+		 (eq :eval (car anindicator)))
+	    (setq anindicator (eval (cadr anindicator))))
+	(if (and (stringp anindicator) 
+		 (string= anindicator indicator))
+	    (setq result minor-mode
+		  minor-modes nil)
+	  (setq minor-modes (cdr minor-modes)))))
+    result))
 
 ;; Add menu of buffer operations to the buffer identification part
 ;; of the mode line.or header line.