help-fns.el patch for commands to describe options and commands

["Drew Adams" <drew.adams@oracle.com>]

[-- Attachment #1: Type: text/plain, Size: 1166 bytes --]

Attached is a patch for help-fns.el. It modifies `describe-function' and
`describe-variable', so that a prefix arg means that candidates are commands
and user options, respectively. So `C-u C-h f' shows and accepts only
commands as completion candidates, and `C-u C-h v' shows and accepts only
user options for completion.

In addition, for convenience, two new commands are defined to do the same
thing without `C-u': `describe-command' and `describe-option'. This is
especially useful for newbies, who might search for something that describes
a command or an option.

Yes, users already have `apropos-command' and `apropos-variable' (which
should be called `apropos-option'), which give info about commands and
options, and they can get to a command or option description from there. I
nevertheless think this trivial addition is helpful, and not just for
newbies.

Caveat: I patched the latest CVS help-fns.el, but I have not tested the
patch with CVS Emacs. I have only an Emacs 22.1 binary for Windows. I have
tested a similar patch for Emacs 22.1. (`describe-variable' now uses things
such as `with-selected-frame', which are not available with Emacs 22.1.)


[-- Attachment #2: help-fns-2007-10-19.patch --]
[-- Type: application/octet-stream, Size: 6743 bytes --]

*** help-fns-CVS-2007-10-19.el	Fri Oct 19 10:38:10 2007
--- help-fns-patched-2007-10-19.el	Fri Oct 19 11:39:10 2007
***************
*** 38,45 ****
  ;; Functions
  
  ;;;###autoload
! (defun describe-function (function)
!   "Display the full documentation of FUNCTION (a symbol)."
    (interactive
     (let ((fn (function-called-at-point))
  	 (enable-recursive-minibuffers t)
--- 38,48 ----
  ;; Functions
  
  ;;;###autoload
! (defun describe-function (function &optional commandp)
!   "Display the full documentation of FUNCTION (a symbol).
! FUNCTION names an Emacs Lisp function, possibly a user command.
! With a prefix arg, candidates are commands (interactive functions).
! Returns the description that was displayed, as a string."
    (interactive
     (let ((fn (function-called-at-point))
  	 (enable-recursive-minibuffers t)
***************
*** 47,58 ****
       (setq val (completing-read (if fn
  				    (format "Describe function (default %s): " fn)
  				  "Describe function: ")
! 				obarray 'fboundp t nil nil
! 				(and fn (symbol-name fn))))
!      (list (if (equal val "")
! 	       fn (intern val)))))
    (if (null function)
        (message "You didn't specify a function")
      (help-setup-xref (list #'describe-function function) (interactive-p))
      (save-excursion
        (with-output-to-temp-buffer (help-buffer)
--- 50,63 ----
       (setq val (completing-read (if fn
  				    (format "Describe function (default %s): " fn)
  				  "Describe function: ")
! 				obarray (if current-prefix-arg 'commandp 'fboundp)
!                                 t nil nil (and fn (symbol-name fn))))
!      (list (if (equal val "") fn (intern val))
!            current-prefix-arg)))
    (if (null function)
        (message "You didn't specify a function")
+     (unless (or (not commandp) (commandp function))
+       (error "Not a defined Emacs command (interactive function): `%s'" function))
      (help-setup-xref (list #'describe-function function) (interactive-p))
      (save-excursion
        (with-output-to-temp-buffer (help-buffer)
***************
*** 66,71 ****
--- 71,92 ----
  	  ;; Return the text we displayed.
  	  (buffer-string))))))
  
+ ;;;###autoload
+ (defun describe-command (function)
+   "Describe an Emacs command (interactive function).
+ Same as using a prefix argument with command `describe-function'."
+   (interactive
+    (let ((fn (function-called-at-point))
+          (enable-recursive-minibuffers t)
+          val)
+      (setq val (completing-read (if fn
+ 				    (format "Describe command (default %s): " fn)
+ 				  "Describe command: ")
+ 				obarray 'commandp t nil nil
+ 				(and fn (symbol-name fn))))
+      (list (if (equal val "") fn (intern val)))))
+   (describe-function function t))
+ 
  (defun help-split-fundoc (docstring def)
    "Split a function DOCSTRING into the actual doc and the usage info.
  Return (USAGE . DOC) or nil if there's no usage info.
***************
*** 457,467 ****
        0))
  
  ;;;###autoload
! (defun describe-variable (variable &optional buffer frame)
    "Display the full documentation of VARIABLE (a symbol).
! Returns the documentation as a string, also.
  If VARIABLE has a buffer-local value in BUFFER or FRAME
! \(default to the current buffer and current frame),
  it is displayed along with the global value."
    (interactive
     (let ((v (variable-at-point))
--- 478,490 ----
        0))
  
  ;;;###autoload
! (defun describe-variable (variable &optional buffer frame optionp)
    "Display the full documentation of VARIABLE (a symbol).
! VARIABLE names an Emacs Lisp variable, possibly a user option.
! With a prefix argument, candidates are user variables (options) only.
! Returns the documentation as a string.
  If VARIABLE has a buffer-local value in BUFFER or FRAME
! \(default to the current buffer and current frame), then
  it is displayed along with the global value."
    (interactive
     (let ((v (variable-at-point))
***************
*** 472,488 ****
  				     "Describe variable (default %s): " v)
  				  "Describe variable: ")
  				obarray
! 				'(lambda (vv)
! 				   (or (boundp vv)
! 				       (get vv 'variable-documentation)))
  				t nil nil
  				(if (symbolp v) (symbol-name v))))
!      (list (if (equal val "")
! 	       v (intern val)))))
    (unless (buffer-live-p buffer) (setq buffer (current-buffer)))
    (unless (frame-live-p frame) (setq frame (selected-frame)))
    (if (not (symbolp variable))
        (message "You did not specify a variable")
      (save-excursion
        (let ((valvoid (not (with-current-buffer buffer (boundp variable))))
  	    val val-start-pos locus)
--- 495,516 ----
  				     "Describe variable (default %s): " v)
  				  "Describe variable: ")
  				obarray
!                                 (if current-prefix-arg
!                                     (lambda (vv) (user-variable-p vv))
!                                   (lambda (vv)
!                                     (or (boundp vv) (get vv 'variable-documentation))))
  				t nil nil
  				(if (symbolp v) (symbol-name v))))
!      (list (if (equal val "") v (intern val))
!            nil
!            nil
!            current-prefix-arg)))
    (unless (buffer-live-p buffer) (setq buffer (current-buffer)))
    (unless (frame-live-p frame) (setq frame (selected-frame)))
    (if (not (symbolp variable))
        (message "You did not specify a variable")
+     (unless (or (not optionp) (user-variable-p variable))
+       (error "Not a defined Emacs user option: `%s'" variable))
      (save-excursion
        (let ((valvoid (not (with-current-buffer buffer (boundp variable))))
  	    val val-start-pos locus)
***************
*** 662,667 ****
--- 690,713 ----
  	      ;; Return the text we displayed.
  	      (buffer-string))))))))
  
+ ;;;###autoload
+ (defun describe-option (variable &optional buffer frame)
+   "Describe an Emacs user variable (option).
+ Same as using a prefix argument with command `describe-variable'."
+   (interactive
+    (let ((v (variable-at-point))
+ 	 (enable-recursive-minibuffers t)
+ 	 val)
+      (setq val (completing-read (if (symbolp v)
+ 				    (format "Describe option (default %s): " v)
+ 				  "Describe option: ")
+ 				obarray 'user-variable-p t nil nil
+ 				(if (symbolp v) (symbol-name v))))
+      (list (if (equal val "") v (intern val))
+            nil
+            nil
+            current-prefix-arg)))
+   (describe-variable variable buffer frame t))
  
  ;;;###autoload
  (defun describe-syntax (&optional buffer)

Diff finished.  Fri Oct 19 12:02:43 2007

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel