[PATCH] Unify fn and var help to make learning elisp a little easier

[PATCH] Unify fn and var help to make learning elisp a little easier

[Kelly Dean]

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

A new user will often not remember whether a symbol he has in mind is a function or variable, so he doesn't know whether to use C-h f or C-h v to get help for it. For example do I use mark or (mark)? C-h v mark TAB TAB, it's not there, C-g C-h f mark TAB TAB, there it is. Later I'm looking for mark-active and try C-h f first, and again have to cancel and switch. Also, when a symbol is used as both a function and a variable, a new user would want to know about this, but he's not going to find out by using C-h f or C-h v unless he manually tries both every time he looks up something new, which is inconvenient.
A help command which provides completion on both functions and variables, and if a symbol is used as both, shows the help pages for both, solves both problems. The attached patch is a simple union of describe-function and describe-variable to do this. It triggers bug# 13105, but I sent a fix for that.

BTW am I supposed to send little things like this to emacs-devel, or to bug-gnu-emacs, or just post on the wiki? It isn't a bug, but some of the docs say the bug list is also for new features and patches so they can be tracked by bug number, but they also say if a patch needs discussion then it should go to the devel list. Maybe it's superfluous, not worth cluttering Emacs with it.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: descfunorvar.patch --]
[-- Type: text/x-diff; name="descfunorvar.patch", Size: 3385 bytes --]

--- 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 @@
 
 \f
 ;; 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.

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Stefan Monnier]

> A new user will often not remember whether a symbol he has in mind
> is a function or variable, so he doesn't know whether to use C-h f or C-h
> v to get help for it.

A command that gives you help on "any symbol" would make a lot of
sense, yes.
Actually, there is already a function for that, called
`help-xref-interned', so all we need is to give it a nicer name
(e.g. describe-symbol), and an `interactive' spec which
provides completion.

> BTW am I supposed to send little things like this to emacs-devel, or to
> bug-gnu-emacs, or just post on the wiki?

Either is fine.


        Stefan

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Kelly Dean]

> Actually, there is already a function for that, called
> `help-xref-interned', so all we need is to give it a nicer
> name
> (e.g. describe-symbol), and an `interactive' spec which
> provides completion.
That's what my patch does.

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[chad]

On 07 Dec 2012, at 10:12, Kelly Dean <kellydeanch@yahoo.com> wrote:

>> Actually, there is already a function for that, called
>> `help-xref-interned', so all we need is to give it a nicer
>> name
>> (e.g. describe-symbol), and an `interactive' spec which
>> provides completion.
> That's what my patch does.

FWIW, when faced with a similar issue long ago, I did something like
this:

	;; add apropos to Help
	(define-key help-map "A" 'apropos)

Actually, I rebind `a' to apropos and bind `A' to apropos-command, but
I doubt Emacs wants that change by default. Neither of these gets
completion, if that's important to you. At the time, I liked the word list
well enough that I didn't miss completion, but that was before things
like ido, icomplete, and anything/company/helm/etc were so common.

Hope that helps,
~Chad

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Stefan Monnier]

>> Actually, there is already a function for that, called
>> `help-xref-interned', so all we need is to give it a nicer name
>> (e.g. describe-symbol), and an `interactive' spec which
>> provides completion.
> That's what my patch does.

Duh, sorry!  Your patch is a lot better than "a simple union of
describe-function and describe-variable to do this".  I was fooled by
your humility.

The patch looks pretty good, actually.  I'm not completely sure we want
to use "C-h o" for its binding, tho I don't see any obvious reasons
not to.

But now we have the reverse problem that this goes beyond the "tiny
change" limit, so we'd need you to sign some copyright paperwork before
we can accept it.  Would you be willing to do that?


        Stefan

RE: [PATCH] Unify fn and var help to make learning elisp a littleeasier

[Drew Adams]

> I'm not completely sure we want to use "C-h o" for its
>  binding, tho I don't see any obvious reasons not to.

FWIW, I bind `C-h o' to `describe-option' (in help-fns+.el):

(defun describe-option (variable &optional buffer)
  "Describe an Emacs user variable (option).
Same as using a prefix arg with `describe-variable'."
  (interactive
   (let ((symb  (or (and (fboundp 'symbol-nearest-point)
                         (symbol-nearest-point))
                    (and (symbolp (variable-at-point))
                         (variable-at-point))))
         (enable-recursive-minibuffers  t))
     (list (intern
            (completing-read
             "Describe user option: "
             obarray 'user-variable-p t nil nil
             (and symb  (symbol-name symb)) t)))))
  (describe-variable variable buffer t))

FWIW2, I also have a command `describe-option-of-type', which I bind
to `C-h C-o':

,----
| describe-option-of-type is an interactive compiled Lisp function in
| `help-fns+.el'.
| 
| It is bound to help C-o, menu-bar help-menu describe
| describe-option-of-type.
| 
| (describe-option-of-type TYPE OPTION)
| 
| Describe an Emacs user OPTION (variable) of a given `defcustom' TYPE.
| A prefix argument determines the type-checking behavior:
|  - None:         OPTION is defined with TYPE or a subtype of TYPE.
|  - Plain `C-u':  OPTION is defined with TYPE or a subtype of TYPE,
|                  or its current value is compatible with TYPE.
|  - Negative:     OPTION is defined with TYPE (exact match).
|  - Non-negative: OPTION is defined with TYPE (exact match),
|                  or its current value is compatible with TYPE.
| 
| If TYPE is nil (default value) then *all* `defcustom' variables are
| potential candidates.  That is different from using `describe-option',
| because `describe-option' includes user-variable candidates not
| defined with `defcustom' (with `*'-prefixed doc strings).
`----

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Kelly Dean]

> I'm not completely sure we want
> to use "C-h o" for its binding, tho I don't see any obvious
> reasons not to.
Since Drew's describe-option uses o, the remaining lowercase options are juxyz. Of those, I vote for x.

> But now we have the reverse problem that this goes beyond
> the "tiny
> change" limit, so we'd need you to sign some copyright
> paperwork before
> we can accept it.  Would you be willing to do that?
I disclaim copyright on it. It's in the public domain, except for whatever the FSF already has copyright on, which I think is most of it, since it's mostly copied from describe-function and describe-variable.

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Dmitry Gutov]

Stefan,

Could you comment on this offer to put the code into public domain?
Is this possible and/or acceptable for Emacs?

Kelly Dean <kellydeanch@yahoo.com> writes:
>> I'm not completely sure we want
>> to use "C-h o" for its binding, tho I don't see any obvious
>> reasons not to.
> Since Drew's describe-option uses o, the remaining lowercase options are juxyz. Of those, I vote for x.
>
>> But now we have the reverse problem that this goes beyond
>> the "tiny
>> change" limit, so we'd need you to sign some copyright
>> paperwork before
>> we can accept it.  Would you be willing to do that?
> I disclaim copyright on it. It's in the public domain, except for whatever the
> FSF already has copyright on, which I think is most of it, since it's mostly
> copied from describe-function and describe-variable.

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Glenn Morris]

Dmitry Gutov wrote:

> Could you comment on this offer to put the code into public domain?
> Is this possible and/or acceptable for Emacs?

Not Stefan, but I'm afraid simply stating "this is in the public domain"
is not enough. We require a disclaimer to be filed with FSF records via
their standard process. It's a simple procedure that is really not a lot
of work (I think it can be done entirely electronically if in the USA).
It's no less work than completing a copyright assignment, though, so if
that is the only motivation then it is better to do an assignment. In
fact it is more work, because it has to be done for every change,
whereas an assignment is normally a one-time thing for "past and future
changes".

So if the only objection to doing an assignment was a practical one,
then I hope you will reconsider. It's really easy to do. If it's an
objection on principal then I am afraid we cannot use your
contributions.

For more details, http://www.gnu.org/licenses/why-assign.html.
gnu-misc-discuss is probably the place to discuss it.

Re: [PATCH] Unify fn and var help to make learning elisp a little easier

[Stefan Monnier]

> Could you comment on this offer to put the code into public domain?
> Is this possible and/or acceptable for Emacs?

No, it's not sufficient.  I've contacted the author privately to get his
copyright paperwork.


        Stefan