From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Kelly Dean Newsgroups: gmane.emacs.devel Subject: [Old patch] Unify fn and var help to make learning elisp a little easier Date: Tue, 20 Jan 2015 23:06:51 +0000 Message-ID: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1421795311 7523 80.91.229.3 (20 Jan 2015 23:08:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 20 Jan 2015 23:08:31 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jan 21 00:08:27 2015 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1YDhuL-0007Nl-Jz for ged-emacs-devel@m.gmane.org; Wed, 21 Jan 2015 00:08:25 +0100 Original-Received: from localhost ([::1]:45912 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YDhuK-0008KX-RA for ged-emacs-devel@m.gmane.org; Tue, 20 Jan 2015 18:08:24 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34826) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YDhu5-0008KO-Sm for emacs-devel@gnu.org; Tue, 20 Jan 2015 18:08:11 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YDhu2-0004te-Cg for emacs-devel@gnu.org; Tue, 20 Jan 2015 18:08:09 -0500 Original-Received: from relay3-d.mail.gandi.net ([2001:4b98:c:538::195]:52648) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YDhu2-0004pe-2p for emacs-devel@gnu.org; Tue, 20 Jan 2015 18:08:06 -0500 Original-Received: from mfilter2-d.gandi.net (mfilter2-d.gandi.net [217.70.178.140]) by relay3-d.mail.gandi.net (Postfix) with ESMTP id A24FDA80AB for ; Wed, 21 Jan 2015 00:08:01 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mfilter2-d.gandi.net Original-Received: from relay3-d.mail.gandi.net ([217.70.183.195]) by mfilter2-d.gandi.net (mfilter2-d.gandi.net [10.0.15.180]) (amavisd-new, port 10024) with ESMTP id KA2sTje6QGek for ; Wed, 21 Jan 2015 00:08:00 +0100 (CET) X-Originating-IP: 66.220.3.179 Original-Received: from localhost (gm179.geneticmail.com [66.220.3.179]) (Authenticated sender: kelly@prtime.org) by relay3-d.mail.gandi.net (Postfix) with ESMTPSA id CB5D4A80BE for ; Wed, 21 Jan 2015 00:07:58 +0100 (CET) X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4b98:c:538::195 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:181492 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable I originally proposed this a couple years ago: https://lists.gnu.org/archive/html/emacs-devel/2012-12/msg00165.html At the time, my patch was declined due to a paperwork issue. However, the= FSF now has a disclaimer on file for me, so that issue has been solved. I've been using this patch since the time I wrote it, and find it handy. = I rarely use =C2=ABC-h v=C2=BB or =C2=ABC-h f=C2=BB anymore. If other people might find it useful too, I propose installing it in Emac= s. Stefan and Drew suggested maybe using a different keybinding than =C2=AB= C-h o=C2=BB, though. (I'll have to re-train my muscle memory, but that's = ok.) The remaining lowercase options for =C2=ABC-h=C2=BB are [juxyz]. Of = those, I would vote for x. A copy of my original patch is attached below. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=descfunorvar.patch --- emacs-24.2/lisp/help-fns.el +++ emacs-24.2/lisp/help-fns.el @@ -897,6 +897,37 @@ ;;;###autoload +(defun describe-function-or-variable (symbol &optional buffer frame) + "Display the full documentation of the function or variable SYMBOL. +If SYMBOL is a variable and 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-or-f (variable-at-point)) + (found (symbolp v-or-f)) + (v-or-f (if found v-or-f (function-called-at-point))) + (found (or found v-or-f)) + (enable-recursive-minibuffers t) + val) + (setq val (completing-read (if found + (format + "Describe function or variable (default %s): " v-or-f) + "Describe function or variable: ") + obarray + (lambda (vv) + (or (fboundp vv) + (get vv 'variable-documentation) + (and (boundp vv) (not (keywordp vv))))) + t nil nil + (if found (symbol-name v-or-f)))) + (list (if (equal val "") + v-or-f (intern val))))) + (if (not (symbolp symbol)) (message "You didn't specify a function or variable") + (unless (buffer-live-p buffer) (setq buffer (current-buffer))) + (unless (frame-live-p frame) (setq frame (selected-frame))) + (help-xref-interned symbol buffer frame))) + +;;;###autoload (defun describe-syntax (&optional buffer) "Describe the syntax specifications in the syntax table of BUFFER. The descriptions are inserted in a help buffer, which is then displayed. --- emacs-24.2/lisp/help-mode.el +++ emacs-24.2/lisp/help-mode.el @@ -627,10 +627,13 @@ ;; Additional functions for (re-)creating types of help buffers. -(defun help-xref-interned (symbol) + +;;;###autoload +(defun help-xref-interned (symbol &optional buffer frame) "Follow a hyperlink which appeared to be an arbitrary interned SYMBOL. Both variable, function and face documentation are extracted into a single -help buffer." +help buffer. If SYMBOL is a variable, include buffer-local value for optional +BUFFER or FRAME." (with-current-buffer (help-buffer) ;; Push the previous item on the stack before clobbering the output buffer. (help-setup-xref nil nil) @@ -646,7 +649,7 @@ (get symbol 'variable-documentation)) ;; Don't record the current entry in the stack. (setq help-xref-stack-item nil) - (describe-variable symbol)))) + (describe-variable symbol buffer frame)))) (cond (sdoc ;; We now have a help buffer on the variable. --- emacs-24.2/lisp/help.el +++ emacs-24.2/lisp/help.el @@ -90,6 +90,7 @@ (define-key map "k" 'describe-key) (define-key map "l" 'view-lossage) (define-key map "m" 'describe-mode) + (define-key map "o" 'describe-function-or-variable) (define-key map "n" 'view-emacs-news) (define-key map "p" 'finder-by-keyword) (define-key map "P" 'describe-package) @@ -215,6 +216,7 @@ m Display documentation of current minor modes and current major mode, including their special commands. n Display news of recent Emacs changes. +o SYMBOL Display the given function or variable's documentation and value. p TOPIC Find packages matching a given topic keyword. r Display the Emacs manual in Info mode. s Display contents of current syntax table, plus explanations. --=-=-=--