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

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

[Drew Adams]

[-- 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

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

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> 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.

Nice.

I've often wanted this functionality (not quite enough to overcome my
laziness I guess), and this seems like a good and seamless way to fit it
into the existing handy bindings.

Thanks,

-Miles

-- 
.Numeric stability is probably not all that important when you're guessing.

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

[Richard Stallman]

    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.

That doesn't sound very useful to me.  What is the benefit it seeks to provide?
Only to limit completion?

I won't object to installing it, but I do not want to document it in
the Emacs Manual, because it isn't worth the paper.

    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.

I don't think this is is going to be useful for newbies.  They won't
learn these commands.  If they remember anything relevant it will be
C-h f and C-h v.  C-h f works with commands just as with
noninteractive functions; C-h v works with user options just as with
other variables.

If you are saying that you think some newbies will type M-x
describe-command to look for a command, I think that will be quite
rare.  If we want to make that work, the simplest way is to alias
describe-command to describe-function.

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

[Drew Adams]

>     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.
>
> That doesn't sound very useful to me.  What is the benefit it
> seeks to provide? Only to limit completion?

Yes. When you are looking for a command, you don't want to see a zillion
non-interactive functions as candidates. This cuts down that noise
*considerably*.

Users who don't fiddle with Emacs Lisp want to know about commands more
often than non-interactive functions. Same thing for user options - they
want to know what options might be available for controlling this or that.
They don't want to see zillions of internal variable names - quel horreur !
And there are many *more* internal names than external, end-user names -
double the insult.

Give them only what they are interested in - less noise. (And "them" is also
us. Don't you sometimes want to know about a command or option?)

> I won't object to installing it, but I do not want to document it in
> the Emacs Manual, because it isn't worth the paper.

OK. Anyway, I guarantee it'll eventually be a faq on Emacs Wiki (and without
me putting it there). One way or the other, people will find it and use it
and pass the knowledge along. If they learn anything about help, this will
be it. This is a stupid-simple feature, but it should have been there all
along, IMO.

>     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.
>
> I don't think this is is going to be useful for newbies.  They won't
> learn these commands.

Reason?  Why not useful?  Why not learnable?

Will they not learn these because they are not bound to keys? How about
binding them? An end user is more interested in describing commands and
options than arbitrary functions and variables, so you could even argue that
these deserve bindings more than `describe-function' and `describe-variable'
(I don't argue that, however).

I'd rather see `C-h c' for `describe-command' and `C-h o' for
`describe-option'. I'd move `describe-key-briefly' to `C-u C-h k' (but,
then, I never use it). [No, we need not have a war over particular bindings;
I just wanted to claim that this is useful to newbies and it could warrant
bindings.]

We go to the trouble (since day 1, in fact) of providing a dedicated command
and key binding for apropos of commands (only). How is this different? By
your logic, we should remove `command-apropos' and give users just
`apropos'.

> If they remember anything relevant it will be
> C-h f and C-h v.  C-h f works with commands just as with
> noninteractive functions; C-h v works with user options just as with
> other variables.

Which is fine if you want that generality. And not fine if you have a
narrower focus.

> If you are saying that you think some newbies will type M-x
> describe-command to look for a command, I think that will be quite
> rare.  If we want to make that work, the simplest way is to alias
> describe-command to describe-function.

If someone wants to find a command, why would you give him only a way to
find all functions? By that logic, give him only one command that describes
all functions and variables, with all of their names available at once for
completion. Why help the user by distinguishing which are functions and
which are variables?

The point is to give users a tool that narrows the possibilities, that from
the beginning weeds out candidates that they know they don't want (in a
particular context). If I want to know about an option, then I don't want
the added noise of internal variable names. When the user has a focus, s?he
wants a tool that respects that focus.

The other point was that these command names say what they do, so a user
looking for something that describes commands is more likely to find
`describe-command' than `describe-function'. Try `M-x apropos describe
command' - nada. Now try `M-x apropos describe function'. OK, try `C-h a
describe function'. Repeat for `option' and `variable'.

And an absolute beginner might not even imagine that an editor command is a
"function" in Emacs. Open TextPad or (shudder) Notepad or another typical
end-user text editor. Go into the Help and search for "function". Now search
for "command". Do you see the difference in hits? Go to
http://en.wikipedia.org/wiki/Text_editor and search for "function", then
"command" - 2 hits vs 14, and those 2 are not really about functions that
are commands. But Emacs is for programmers, you say? Go to
http://en.wikipedia.org/wiki/Vi and count again: 0 hits for "function", 51
for "command". Moral: an Emacs newbie will look for commands to do things,
not functions.

Yes, your aliasing would take care of that part - but not the
noise-reduction part.

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

[Stefan Monnier]

> Yes. When you are looking for a command, you don't want to see a zillion
> non-interactive functions as candidates. This cuts down that noise
> *considerably*.

I could buy that.  But those users for whom it matters most won't know to
use the C-u prefix.  And usually the C-u prefix means something like "give
me more control", so it would make more sense to only list commands/options
and let C-u specify that we actually want to see all functions/variables.


        Stefan

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

[Drew Adams]

> > Yes. When you are looking for a command, you don't want to see a zillion
> > non-interactive functions as candidates. This cuts down that noise
> > *considerably*.
>
> I could buy that.  But those users for whom it matters most won't know to
> use the C-u prefix.  And usually the C-u prefix means something like "give
> me more control", so it would make more sense to only list
> commands/options
> and let C-u specify that we actually want to see all functions/variables.

Yes, that might make more sense, and some other commands work just that way
(but it is not "usually" the case). But the command is called
`describe-function' (or `describe-variable'), so it could be argued that it
should by default do what its name says.

There is also legacy to consider, FWIW.

`C-u' means lots of different things, depending on the command. A common
meaning is that it does something related but a bit different (and often
less common). The special meaning of wider scope is not general, but it does
apply to some other help commands, such as `apropos'. "Give me more control"
doesn't mean much to me. One could argue that restricting the scope is using
more control - or the opposite - or whatever.

The users for whom it matters most, in the sense of finding the command,
will find and use `describe-command' instead. The users for whom it matters
most for `describe-function' to have this optional behavior are probably not
newbies. I, for one, use `C-u C-h f' instead of `describe-command'. But
that's mainly because I have not bound `describe-command' to a key.

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

[Miles Bader]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Yes. When you are looking for a command, you don't want to see a zillion
>> non-interactive functions as candidates. This cuts down that noise
>> *considerably*.
>
> I could buy that.  But those users for whom it matters most won't know to
> use the C-u prefix.  And usually the C-u prefix means something like "give
> me more control", so it would make more sense to only list commands/options
> and let C-u specify that we actually want to see all functions/variables.

I dunno which way should be the default (though I favor the backward
compatible way, I guess), but please, add the functionality, because
it's _useful_ (I'm not talking about newbies, just about my own use;
probably it's useful to newbies in some form too).

I very often want to peruse the _user interface_ of a package is, and
tend to do this by using "C-h C-f prefix- ?", see what functions there
are, then type the name of one to see how it works.  Clearly this gets
tons of noise from the non-command functions, and so it would be _very_
useful to have a command-only version of C-h C-f.

-Miles

-- 
[|nurgle|]  ddt- demonic? so quake will have an evil kinda setting? one that
            will  make every christian in the world foamm at the mouth?
[iddt]      nurg, that's the goal

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

[Drew Adams]

> I dunno which way should be the default (though I favor the backward
> compatible way, I guess), but please, add the functionality, because
> it's _useful_ (I'm not talking about newbies, just about my own use;
> probably it's useful to newbies in some form too).
>
> I very often want to peruse the _user interface_ of a package is, and
> tend to do this by using "C-h C-f prefix- ?", see what functions there
> are, then type the name of one to see how it works.  Clearly this gets
> tons of noise from the non-command functions, and so it would be _very_
> useful to have a command-only version of C-h C-f.

This is off-topic, but you might also find `icicle-imenu-command' useful. It
lets you browse among command definitions. It uses the imenu regexp to find
functions, and filters the results with `commandp'. Because of this way of
defining it, it finds only currently defined commands, however, not commands
defined in a file that has not been loaded.

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

[Richard Stallman]

    I very often want to peruse the _user interface_ of a package is, and
    tend to do this by using "C-h C-f prefix- ?", see what functions there
    are, then type the name of one to see how it works.

If you, as an experienced user, find it useful, we can add it
as a feature for experienced users.

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

[William Xu]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Yes. When you are looking for a command, you don't want to see a zillion
>> non-interactive functions as candidates. This cuts down that noise
>> *considerably*.
>
> I could buy that.  But those users for whom it matters most won't know to
> use the C-u prefix.  And usually the C-u prefix means something like "give
> me more control", so it would make more sense to only list commands/options
> and let C-u specify that we actually want to see all functions/variables.

I like Drew's idea. But if i have to C-u everytime to see all
functions/variables, then it would be a great pain writing elisps..  

On the contrary, C-u is not friendly to newbies. So maybe a better
solution is to add/redefine two new bindings, `C-h c' and `C-h o' for
commands and options, respectively. [Currently `C-h c' is binded to
describe-key-briefly, which i find myself nearly never use..]

-- 
William

http://williamxu.net9.org

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

[Drew Adams]

> I like Drew's idea. But if i have to C-u everytime to see all
> functions/variables, then it would be a great pain writing elisps..  
> 
> On the contrary, C-u is not friendly to newbies. So maybe a better
> solution is to add/redefine two new bindings, `C-h c' and `C-h o' for
> commands and options, respectively. [Currently `C-h c' is binded to
> describe-key-briefly, which i find myself nearly never use..]

I think that's exactly what I suggested. Maybe we just agree?

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

[Richard Stallman]

    On the contrary, C-u is not friendly to newbies. So maybe a better
    solution is to add/redefine two new bindings, `C-h c' and `C-h o' for
    commands and options, respectively.

It is a mistake to try to help newbies by providing an even larger
number of help commands for them.  So this idea is self-defeating.

By the way, C-h c is already a help command, and a very basic one,
which we will not change.

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

[William Xu]

Richard Stallman <rms@gnu.org> writes:

>     On the contrary, C-u is not friendly to newbies. So maybe a better
>     solution is to add/redefine two new bindings, `C-h c' and `C-h o' for
>     commands and options, respectively.
>
> It is a mistake to try to help newbies by providing an even larger
> number of help commands for them.  So this idea is self-defeating.

For me, C-u is perfectly okay ! 

> By the way, C-h c is already a help command, and a very basic one,
> which we will not change.

I mentioned it in my previous post: 

,----
| [Currently `C-h c' is binded to describe-key-briefly, which i find
| myself nearly never use..]
`----

-- 
William

http://williamxu.net9.org

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

[Richard Stallman]

    > I don't think this is is going to be useful for newbies.  They won't
    > learn these commands.

    Reason?  Why not useful?  Why not learnable?

Because there are limits to how much a person can learn.  Newbies to
Emacs are overloaded already.  They see lots of commands and learn
only a few of them.  Offering them one more thing to learn won't do
any good -- they can't learn MORE.

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

[Drew Adams]

>     > I don't think this is is going to be useful for newbies.  They won't
>     > learn these commands.
>
>     Reason?  Why not useful?  Why not learnable?
>
> Because there are limits to how much a person can learn.  Newbies to
> Emacs are overloaded already.  They see lots of commands and learn
> only a few of them.  Offering them one more thing to learn won't do
> any good -- they can't learn MORE.

Knowledge is not strictly quantitative: just a bin of beans with a fixed
capacity.

Learning these can mean not needing to learn some other things right away.

Learning `C-h c' for `describe-command' is more useful to a newbie than
learning `C-h c' for `describe-key-briefly'. (And it's a better mnemonic.)

Newbies need `describe-option' more than `describe-variable', so they should
learn it first (as `C-h o'). When they later delve more into Emacs and Lisp,
they can learn `C-h v' (if there is still room in the ol' bin for one more
bean).

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

[Richard Stallman]

I don't have time to argue with you about this; I've told you my decision.