Re: Improved help from minibuffer prompts

[Juanma Barranquero <lektu@mi.madritel.es>]

On 19 Apr 2004 13:50:58 +0200, storm@cua.dk (Kim F. Storm) wrote:

> Here is another idea, enhancing on Richard's idea:
> 
> Show the full doc string, but highlight occurrences of the upper case
> PARAM name in the doc string -- then the user will be able to quickly
> locate the relevant information and focus on that...

Related to that, here's a (proof-of-concept) patch that sets the face
`font-lock-variable-name-face' for all uses of the arguments of a
function in a `describe-function' *Help* buffer.

I say proof-of-concept because I've not provided a way to make it
optional, I've hard-coded the face used, etc. Still, it works
beautifully.

The auxiliary function help-highlight-arguments is designed in such a
way that it can be pased a nil WORDS argument (and then it highlights
all arguments of the function), or a list of desired arguments to
highlight, so it can be of help if highlighting info for an argument is
desired (which was discused in this thread).

Opinions?

                                                           /L/e/k/t/u


Index: help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.40
diff -u -2 -r1.40 help-fns.el
--- help-fns.el	29 Apr 2004 18:46:13 -0000	1.40
+++ help-fns.el	29 Apr 2004 23:39:08 -0000
@@ -131,4 +131,25 @@
 ;; Functions
 
+(defun help-highlight-arguments (fun &rest words)
+  (save-excursion
+    (goto-char (point-min))
+    (let* ((case-fold-search nil)
+           (next (and (not words)
+                      (re-search-forward (concat "(" (symbol-name fun)) nil t))))
+      ;; Make a list of all arguments
+      (while next
+        (when (re-search-forward " \\([^ &\)\.]+\\)" nil t)
+          (setq words (cons (match-string 1) words)))
+        (setq next (not (search-forward ")" (1+ (point)) t))))
+      ;; Highlight all found arguments anywhere in the *Help* buffer
+      (while words
+        (let* ((word (car words))
+               (solo (concat "\\<" word "\\>"))
+               (high (propertize word 'face 'font-lock-variable-name-face)))
+          (setq words (cdr words))
+          (goto-char (point-min))
+          (while (re-search-forward solo nil t)
+            (replace-match high nil t)))))))
+
 ;;;###autoload
 (defun describe-function (function)
@@ -156,4 +177,6 @@
 	(print-help-return-message)
 	(with-current-buffer standard-output
+          ;; highlight argument names
+          (help-highlight-arguments function)
 	  ;; Return the text we displayed.
 	  (buffer-string))))))