From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: help-fns.el patch for commands to describe options and commands Date: Fri, 19 Oct 2007 12:06:42 -0700 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_NextPart_000_0071_01C81248.8302C040" X-Trace: ger.gmane.org 1192820879 27142 80.91.229.12 (19 Oct 2007 19:07:59 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 19 Oct 2007 19:07:59 +0000 (UTC) To: "Emacs-Devel" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Oct 19 21:07:59 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1IixCP-0003bl-4R for ged-emacs-devel@m.gmane.org; Fri, 19 Oct 2007 21:07:58 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IixCG-0001r4-VM for ged-emacs-devel@m.gmane.org; Fri, 19 Oct 2007 15:07:49 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1IixCC-0001mc-Lx for emacs-devel@gnu.org; Fri, 19 Oct 2007 15:07:44 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1IixCA-0001hL-GA for emacs-devel@gnu.org; Fri, 19 Oct 2007 15:07:44 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1IixCA-0001gx-BS for emacs-devel@gnu.org; Fri, 19 Oct 2007 15:07:42 -0400 Original-Received: from agminet01.oracle.com ([141.146.126.228]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1IixC9-00070y-Nn for emacs-devel@gnu.org; Fri, 19 Oct 2007 15:07:42 -0400 Original-Received: from agmgw1.us.oracle.com (agmgw1.us.oracle.com [152.68.180.212]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l9JJ7dFf018417 for ; Fri, 19 Oct 2007 14:07:39 -0500 Original-Received: from acsmt350.oracle.com (acsmt350.oracle.com [141.146.40.150]) by agmgw1.us.oracle.com (Switch-3.2.0/Switch-3.2.0) with ESMTP id l9I8gKr8013502 for ; Fri, 19 Oct 2007 13:07:38 -0600 Original-Received: from dhcp-amer-csvpn-gw1-141-144-64-153.vpn.oracle.com by acsmt351.oracle.com with ESMTP id 3306310951192820799; Fri, 19 Oct 2007 12:06:39 -0700 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal X-MIMEOLE: Produced By Microsoft MimeOLE V6.00.2900.3198 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:81245 Archived-At: This is a multi-part message in MIME format. ------=_NextPart_000_0071_01C81248.8302C040 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit 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.) ------=_NextPart_000_0071_01C81248.8302C040 Content-Type: application/octet-stream; name="help-fns-2007-10-19.patch" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="help-fns-2007-10-19.patch" *** help-fns-CVS-2007-10-19.el Fri Oct 19 10:38:10 2007=0A= --- help-fns-patched-2007-10-19.el Fri Oct 19 11:39:10 2007=0A= ***************=0A= *** 38,45 ****=0A= ;; Functions=0A= =0A= ;;;###autoload=0A= ! (defun describe-function (function)=0A= ! "Display the full documentation of FUNCTION (a symbol)."=0A= (interactive=0A= (let ((fn (function-called-at-point))=0A= (enable-recursive-minibuffers t)=0A= --- 38,48 ----=0A= ;; Functions=0A= =0A= ;;;###autoload=0A= ! (defun describe-function (function &optional commandp)=0A= ! "Display the full documentation of FUNCTION (a symbol).=0A= ! FUNCTION names an Emacs Lisp function, possibly a user command.=0A= ! With a prefix arg, candidates are commands (interactive functions).=0A= ! Returns the description that was displayed, as a string."=0A= (interactive=0A= (let ((fn (function-called-at-point))=0A= (enable-recursive-minibuffers t)=0A= ***************=0A= *** 47,58 ****=0A= (setq val (completing-read (if fn=0A= (format "Describe function (default %s): " fn)=0A= "Describe function: ")=0A= ! obarray 'fboundp t nil nil=0A= ! (and fn (symbol-name fn))))=0A= ! (list (if (equal val "")=0A= ! fn (intern val)))))=0A= (if (null function)=0A= (message "You didn't specify a function")=0A= (help-setup-xref (list #'describe-function function) = (interactive-p))=0A= (save-excursion=0A= (with-output-to-temp-buffer (help-buffer)=0A= --- 50,63 ----=0A= (setq val (completing-read (if fn=0A= (format "Describe function (default %s): " fn)=0A= "Describe function: ")=0A= ! obarray (if current-prefix-arg 'commandp 'fboundp)=0A= ! t nil nil (and fn (symbol-name fn))))=0A= ! (list (if (equal val "") fn (intern val))=0A= ! current-prefix-arg)))=0A= (if (null function)=0A= (message "You didn't specify a function")=0A= + (unless (or (not commandp) (commandp function))=0A= + (error "Not a defined Emacs command (interactive function): = `%s'" function))=0A= (help-setup-xref (list #'describe-function function) = (interactive-p))=0A= (save-excursion=0A= (with-output-to-temp-buffer (help-buffer)=0A= ***************=0A= *** 66,71 ****=0A= --- 71,92 ----=0A= ;; Return the text we displayed.=0A= (buffer-string))))))=0A= =0A= + ;;;###autoload=0A= + (defun describe-command (function)=0A= + "Describe an Emacs command (interactive function).=0A= + Same as using a prefix argument with command `describe-function'."=0A= + (interactive=0A= + (let ((fn (function-called-at-point))=0A= + (enable-recursive-minibuffers t)=0A= + val)=0A= + (setq val (completing-read (if fn=0A= + (format "Describe command (default %s): " fn)=0A= + "Describe command: ")=0A= + obarray 'commandp t nil nil=0A= + (and fn (symbol-name fn))))=0A= + (list (if (equal val "") fn (intern val)))))=0A= + (describe-function function t))=0A= + =0A= (defun help-split-fundoc (docstring def)=0A= "Split a function DOCSTRING into the actual doc and the usage info.=0A= Return (USAGE . DOC) or nil if there's no usage info.=0A= ***************=0A= *** 457,467 ****=0A= 0))=0A= =0A= ;;;###autoload=0A= ! (defun describe-variable (variable &optional buffer frame)=0A= "Display the full documentation of VARIABLE (a symbol).=0A= ! Returns the documentation as a string, also.=0A= If VARIABLE has a buffer-local value in BUFFER or FRAME=0A= ! \(default to the current buffer and current frame),=0A= it is displayed along with the global value."=0A= (interactive=0A= (let ((v (variable-at-point))=0A= --- 478,490 ----=0A= 0))=0A= =0A= ;;;###autoload=0A= ! (defun describe-variable (variable &optional buffer frame optionp)=0A= "Display the full documentation of VARIABLE (a symbol).=0A= ! VARIABLE names an Emacs Lisp variable, possibly a user option.=0A= ! With a prefix argument, candidates are user variables (options) only.=0A= ! Returns the documentation as a string.=0A= If VARIABLE has a buffer-local value in BUFFER or FRAME=0A= ! \(default to the current buffer and current frame), then=0A= it is displayed along with the global value."=0A= (interactive=0A= (let ((v (variable-at-point))=0A= ***************=0A= *** 472,488 ****=0A= "Describe variable (default %s): " v)=0A= "Describe variable: ")=0A= obarray=0A= ! '(lambda (vv)=0A= ! (or (boundp vv)=0A= ! (get vv 'variable-documentation)))=0A= t nil nil=0A= (if (symbolp v) (symbol-name v))))=0A= ! (list (if (equal val "")=0A= ! v (intern val)))))=0A= (unless (buffer-live-p buffer) (setq buffer (current-buffer)))=0A= (unless (frame-live-p frame) (setq frame (selected-frame)))=0A= (if (not (symbolp variable))=0A= (message "You did not specify a variable")=0A= (save-excursion=0A= (let ((valvoid (not (with-current-buffer buffer (boundp = variable))))=0A= val val-start-pos locus)=0A= --- 495,516 ----=0A= "Describe variable (default %s): " v)=0A= "Describe variable: ")=0A= obarray=0A= ! (if current-prefix-arg=0A= ! (lambda (vv) (user-variable-p vv))=0A= ! (lambda (vv)=0A= ! (or (boundp vv) (get vv = 'variable-documentation))))=0A= t nil nil=0A= (if (symbolp v) (symbol-name v))))=0A= ! (list (if (equal val "") v (intern val))=0A= ! nil=0A= ! nil=0A= ! current-prefix-arg)))=0A= (unless (buffer-live-p buffer) (setq buffer (current-buffer)))=0A= (unless (frame-live-p frame) (setq frame (selected-frame)))=0A= (if (not (symbolp variable))=0A= (message "You did not specify a variable")=0A= + (unless (or (not optionp) (user-variable-p variable))=0A= + (error "Not a defined Emacs user option: `%s'" variable))=0A= (save-excursion=0A= (let ((valvoid (not (with-current-buffer buffer (boundp = variable))))=0A= val val-start-pos locus)=0A= ***************=0A= *** 662,667 ****=0A= --- 690,713 ----=0A= ;; Return the text we displayed.=0A= (buffer-string))))))))=0A= =0A= + ;;;###autoload=0A= + (defun describe-option (variable &optional buffer frame)=0A= + "Describe an Emacs user variable (option).=0A= + Same as using a prefix argument with command `describe-variable'."=0A= + (interactive=0A= + (let ((v (variable-at-point))=0A= + (enable-recursive-minibuffers t)=0A= + val)=0A= + (setq val (completing-read (if (symbolp v)=0A= + (format "Describe option (default %s): " v)=0A= + "Describe option: ")=0A= + obarray 'user-variable-p t nil nil=0A= + (if (symbolp v) (symbol-name v))))=0A= + (list (if (equal val "") v (intern val))=0A= + nil=0A= + nil=0A= + current-prefix-arg)))=0A= + (describe-variable variable buffer frame t))=0A= =0A= ;;;###autoload=0A= (defun describe-syntax (&optional buffer)=0A= =0A= Diff finished. Fri Oct 19 12:02:43 2007=0A= ------=_NextPart_000_0071_01C81248.8302C040 Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Emacs-devel mailing list Emacs-devel@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-devel ------=_NextPart_000_0071_01C81248.8302C040--