Improved help from minibuffer prompts

Improved help from minibuffer prompts

[Stefan Reichör]

Hi!

I am currently working on xtla.el (the arch interface for emacs).

In my mode the user is often asked some questions in the
minibuffer. Sometimes the questions need some more
explanations. So I decided to put the needed help in the
function's docstring.

The user can ask emacs for the documentation by hitting f1 in the
minibuffer prompt.

I think the idea could be nice for emacs as well.

Here is the relevant code from xtla.el:

(defun xtla-display-command-help (command &optional current-prompt)
  (save-excursion
    (other-window -1)
    (let ((cmd-help (when (fboundp command) 
		      (documentation command))))
      (with-current-buffer (get-buffer-create "*xtla-command-help*")
        (delete-region (point-min) (point-max))
        (insert (if cmd-help
                    (format "Help for %S:\n%s" command cmd-help)
                  (format "No help available for %S" command)))))
    (Electric-pop-up-window "*xtla-command-help*")
    (resize-temp-buffer-window)
    (other-window 1)))

(define-key minibuffer-local-map [f1] 'xtla-show-command-help)
(define-key minibuffer-local-completion-map [f1] 'xtla-show-command-help)
(define-key minibuffer-local-must-match-map [f1] 'xtla-show-command-help)

(defvar xtla-command-stack nil)
(defun xtla-minibuffer-setup ()
  (push  this-command xtla-command-stack))
(add-hook 'minibuffer-setup-hook 'xtla-minibuffer-setup)

(defun xtla-minibuffer-exit ()
  (pop xtla-command-stack))
(add-hook 'minibuffer-exit-hook 'xtla-minibuffer-exit)

(defun xtla-show-command-help ()
  (interactive)
  (xtla-display-command-help (car xtla-command-stack) 
			     (minibuffer-prompt)))


Now you can hit f1 when a minibuffer prompt is displayed and you get
the function's docstring.

I like this functionality very much - and I think it would be worth to
be added to the core emacs.

What do you think?

-- 
  Stefan.

Re: Improved help from minibuffer prompts

[Miles Bader]

Stefan Reichör <xsteve@riic.at> writes:
> Now you can hit f1 when a minibuffer prompt is displayed and you get
> the function's docstring.

It's kind of a neat idea, but F1 doesn't seem like a great
key-binding to me...

How about having the completion-help display code[*] do it:
when showing completions, if there's only a single unique completion,
show instead the help buffer.

That way, you could either hit `?' after typing the command, or e.g. hit
TAB a few times -- once to complete the command, and another time to
display help.

[*] Probably not the generic completion-help code, but some specialized
    version used when completing functions/commands -- though perhaps
    the option of doing something special for completion-help-with-only-
    one-completion could be made a general feature for users of completion.

F1 currently does normal help without a prompt in the minibuffer, which
is a bit awkward; maybe it should just do the same thing as `?' in the
minibuffer -- which combined with the above technique, would actually
make it work the same as your suggestion... :-]

-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: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Miles!

> Stefan Reichör <xsteve@riic.at> writes:
>> Now you can hit f1 when a minibuffer prompt is displayed and you get
>> the function's docstring.
>
> It's kind of a neat idea, but F1 doesn't seem like a great
> key-binding to me...

Yes, I am not sure about that also. But the f1 and the C-h bindings
point to the same keymaps AFAIK.

I think it is important to make the help easy accessible.

E.g.:
M-x find-dired <RET> gives:
Run find in directory: ~/
Hitting f1 (with my patch) gives:
  Help for find-dired:
  Run `find' and go into Dired mode on a buffer of the output.
  The command run (after changing into DIR) is
  
      find . \( ARGS \) -ls
  
  except that the variable `find-ls-option' specifies what to use
  as the final argument.

> How about having the completion-help display code[*] do it:
> when showing completions, if there's only a single unique completion,
> show instead the help buffer.
>
> That way, you could either hit `?' after typing the command, or e.g. hit
> TAB a few times -- once to complete the command, and another time to
> display help.
>
I don't think, one can use '?' for the example above.
Or do I miss something here?

> [*] Probably not the generic completion-help code, but some specialized
>     version used when completing functions/commands -- though perhaps
>     the option of doing something special for completion-help-with-only-
>     one-completion could be made a general feature for users of completion.
>
> F1 currently does normal help without a prompt in the minibuffer, which
> is a bit awkward; maybe it should just do the same thing as `?' in the
> minibuffer -- which combined with the above technique, would actually
> make it work the same as your suggestion... :-]

It would be nice to have a functionality like the one I suggested to
be built into emacs.

Stefan.

Re: Improved help from minibuffer prompts

[Miles Bader]

Stefan Reichör <xsteve@riic.at> writes:
> > How about having the completion-help display code[*] do it:
> > when showing completions, if there's only a single unique completion,
> > show instead the help buffer.
>
> I don't think, one can use '?' for the example above.
> Or do I miss something here?

Ah... you're right!  I was completely confused about what you're
suggesting.

You were describing a way of getting help _after_ a command has been
started, whereas what I described is a way of getting help _before_
doing so.

I guess both could be useful, but to address your suggestion
specifically:

It seems like a good idea to me; the main question I have is whether
having F1 (or C-h) act differently in the minibuffer is natural for most
users or not.  As the normal help-menu binding for those keys already
acts weirdly in the minibuffer -- it doesn't display the help prompt --
maybe that suggests that it's unusual to use them in the minibuffer.

-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: Improved help from minibuffer prompts

[Masatake YAMATO]

> That way, you could either hit `?' after typing the command, or e.g. hit
> TAB a few times -- once to complete the command, and another time to
> display help.

I think "Hitting tab Multiple" is good idea.
Further more it is consistent with all minibuffer-*-map.
In minibuffer-local-map, the user can get the help with tab once.

Masatake YAMATO

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Miles!

> Ah... you're right!  I was completely confused about what you're
> suggesting.
>
> You were describing a way of getting help _after_ a command has been
> started, whereas what I described is a way of getting help _before_
> doing so.
>
> I guess both could be useful, but to address your suggestion
> specifically:
>
> It seems like a good idea to me; the main question I have is whether
> having F1 (or C-h) act differently in the minibuffer is natural for most
> users or not.  As the normal help-menu binding for those keys already
> acts weirdly in the minibuffer -- it doesn't display the help prompt --
> maybe that suggests that it's unusual to use them in the minibuffer.

I have the following use for the C-h bindings from the minibuffer:
C-h b to describe the bindings

I think that binding should be still accessible.


I think of two possibilities to get the command help explained by me:
f1           ... preferred by me - easy accessible (f1 bindings are 
                 still on the C-h map available)
f1 <return>  ... One key more to type, F1 map is untouched

Stefan.

Re: Improved help from minibuffer prompts

[Miles Bader]

Stefan Reichör <xsteve@riic.at> writes:
> > It seems like a good idea to me; the main question I have is whether
> > having F1 (or C-h) act differently in the minibuffer is natural for most
> > users or not.  As the normal help-menu binding for those keys already
> > acts weirdly in the minibuffer -- it doesn't display the help prompt --
> > maybe that suggests that it's unusual to use them in the minibuffer.
> 
> I have the following use for the C-h bindings from the minibuffer:
> C-h b to describe the bindings
> 
> I think that binding should be still accessible.
> 
> I think of two possibilities to get the command help explained by me:
> f1           ... preferred by me - easy accessible (f1 bindings are 
>                  still on the C-h map available)
> f1 <return>  ... One key more to type, F1 map is untouched

I think it would be bad to have F1 and C-h be sometimes the same and
sometimes different.  `F1 RET' also doesn't seem particularly intuitive,
and since the help menu isn't displayed in the minibuffer, might be hard
for people to remember.

Here's an idea:  Use the normal binding for `describe-function' (`C-h f',
or `F1 f') and either have it directly pop up the help for the currently
executing command (i.e., don't prompt for a function name as usual), or
else prompt as usual, but set the default value for the prompt to the
function currently executing command (so that you'd typically use `C-h f
RET' to get help in the situation you describe).  Since users will probably
be used to `C-h f' to get function help in other contexts, it should be
easier to remember in the minibuffer too.

-Miles
-- 
`To alcohol!  The cause of, and solution to,
 all of life's problems' --Homer J. Simpson

Re: Improved help from minibuffer prompts

[Kim F. Storm]

> Stefan Reichör <xsteve@riic.at> writes:
> > I have the following use for the C-h bindings from the minibuffer:
> > C-h b to describe the bindings

I also use C-h k quite often.

Miles Bader <miles@lsi.nec.co.jp> writes:

> I think it would be bad to have F1 and C-h be sometimes the same and
> sometimes different.  

Agree.

> Here's an idea:  Use the normal binding for `describe-function' (`C-h f',
> or `F1 f') and either have it directly pop up the help for the currently
> executing command (i.e., don't prompt for a function name as usual), or
> else prompt as usual, but set the default value for the prompt to the
> function currently executing command (so that you'd typically use `C-h f
> RET' to get help in the situation you describe).  Since users will probably
> be used to `C-h f' to get function help in other contexts, it should be
> easier to remember in the minibuffer too.

That would be ok.

Other possibilities are:

C-h . => help at point
         This could behave differently if point is in minibuffer, as
         there is usually no specific help "at point" in there.

C-h m => mode specific help (minibuffer specific help)
         I often use this to get help specific to the current context,
         so extending this to understand "minibuffer context" seems
         logical to me.

C-h C-h => maybe we don't need the "help menu" when operating on the
         minibuffer

         
-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Kim!

> Miles Bader <miles@lsi.nec.co.jp> writes:
>
>> Here's an idea:  Use the normal binding for `describe-function' (`C-h f',
>> or `F1 f') and either have it directly pop up the help for the currently
>> executing command (i.e., don't prompt for a function name as usual), or
>> else prompt as usual, but set the default value for the prompt to the
>> function currently executing command (so that you'd typically use `C-h f
>> RET' to get help in the situation you describe).  Since users will probably
>> be used to `C-h f' to get function help in other contexts, it should be
>> easier to remember in the minibuffer too.
>
> That would be ok.
>
> Other possibilities are:
>
> C-h . => help at point
>          This could behave differently if point is in minibuffer, as
>          there is usually no specific help "at point" in there.
>
> C-h m => mode specific help (minibuffer specific help)
>          I often use this to get help specific to the current context,
>          so extending this to understand "minibuffer context" seems
>          logical to me.
>
> C-h C-h => maybe we don't need the "help menu" when operating on the
>          minibuffer

I am fine with all of these bindings.
My ranking would be:
C-h .
C-h f
C-h m
C-h C-h

What do others think?

Re: Improved help from minibuffer prompts

[Richard Stallman]

    In my mode the user is often asked some questions in the
    minibuffer. Sometimes the questions need some more
    explanations. So I decided to put the needed help in the
    function's docstring.

You didn't say which function you mean, but according to the code
it looks like the entire doc string of the command that invoked
the minibuffer is the help string you use.  I don't think
that will be very natural.

It would be more natural to have a variable which, if non-nil, has
extra help for the current minibuffer question.  The caller would bind
that variable.  What do you think of that?

Better: the caller binds minibuffer-extra-help to the string
it should use.  All entry to the minibuffer binds
minibuffer-current-extra-help to minibuffer-extra-help,
and binds minibuffer-extra-help to nil.  This way, a recursive
use of the minibuffer will not mistakenly use a string
meant for the outer minibuffer level.

Re: Improved help from minibuffer prompts

[Richard Stallman]

    It's kind of a neat idea, but F1 doesn't seem like a great
    key-binding to me...

It is the standard Help key, along with C-h.
When the minibuffer has an extra help string,
both C-h and F1 should display it.  Or whatever
the user has made into the Help key should display it.

Re: Improved help from minibuffer prompts

[Richard Stallman]

    Here's an idea:  Use the normal binding for `describe-function' (`C-h f',
    or `F1 f') and either have it directly pop up the help for the currently
    executing command (i.e., don't prompt for a function name as usual), or
    else prompt as usual, but set the default value for the prompt to the
    function currently executing command (so that you'd typically use `C-h f
    RET' to get help in the situation you describe).

Only experienced users will think of doing this.
It is not adequate for the job, which is to help novices.
It would not occur to a novice to type C-h f in the minibuffer
to get help about the command that invoked it.

Re: Improved help from minibuffer prompts

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     Here's an idea:  Use the normal binding for `describe-function' (`C-h f',
>     or `F1 f') and either have it directly pop up the help for the currently
>     executing command (i.e., don't prompt for a function name as usual), or
>     else prompt as usual, but set the default value for the prompt to the
>     function currently executing command (so that you'd typically use `C-h f
>     RET' to get help in the situation you describe).
> 
> Only experienced users will think of doing this.
> It is not adequate for the job, which is to help novices.
> It would not occur to a novice to type C-h f in the minibuffer
> to get help about the command that invoked it.

The problem with using just C-h or f1 is that it would block the
ability to use C-h b or C-h k in the minibuffer.  

I use that quite often to track down problems.

Maybe C-h C-h would be ok.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Richard!

>     In my mode the user is often asked some questions in the
>     minibuffer. Sometimes the questions need some more
>     explanations. So I decided to put the needed help in the
>     function's docstring.
>
> You didn't say which function you mean, but according to the code
> it looks like the entire doc string of the command that invoked
> the minibuffer is the help string you use.  I don't think
> that will be very natural.

I think it is convenient. Every interactive function has already a
docstring.

When I type M-x grep and get a prompt and I am not sure, what I am
asked here, I can just get the help for the function grep.

> It would be more natural to have a variable which, if non-nil, has
> extra help for the current minibuffer question.  The caller would bind
> that variable.  What do you think of that?

That is also a nice idea. I think we should use that AND we should
have a fallback solution for the docstring.

> Better: the caller binds minibuffer-extra-help to the string
> it should use.  All entry to the minibuffer binds
> minibuffer-current-extra-help to minibuffer-extra-help,
> and binds minibuffer-extra-help to nil.  This way, a recursive
> use of the minibuffer will not mistakenly use a string
> meant for the outer minibuffer level.

Not sure, if I understand that.

Consider the following function:

(defun my-defun (name)
  "Just enter a funny name."
  (interactive "sEnter a name: ")
  (message (concat "The name entered was: " name)))

Now I hit:
M-x my-defun and get the prompt "Enter a name: "
Now I hit f1 (or whatever keybinding we choose) and get the following help:

Help for my-defun:
Just enter a funny name.


Where can I bind minibuffer-extra-help?
I tried the following:

(defun my-defun (name)
  "Just enter a funny name."
  (let ((minibuffer-extra-help "Just enter a funny name."))
    (interactive "sEnter a name: ")
    (message (concat "The name entered was: " name))))

(defun my-defun (name)
  "Just enter a funny name."
  (interactive "sEnter a name: ")
  (let ((minibuffer-extra-help "Just enter a funny name."))
    (message (concat "The name entered was: " name))))

That did not work.

Any ideas?

-- 
  Stefan.

Re: Improved help from minibuffer prompts

[Matthew Mundell]

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

Stefan Reichör <xsteve@riic.at> writes:

> Hi!
> 
> I am currently working on xtla.el (the arch interface for emacs).
> 
> In my mode the user is often asked some questions in the
> minibuffer. Sometimes the questions need some more
> explanations. So I decided to put the needed help in the
> function's docstring.

Here's a function called `question' which may be of use.

It allows the responses to an interactive question to be defined,
including a help response and associated help string.  The patch
includes a change to `shell-command' to use `question', in the way
suggested for the `compile' command by Dan Jacobson (in the attached
mail).  This allows `shell-command' to start concurrent asynchronous
shell commands.

The function `may-y-or-n-p' may also be useful.

Note that `question' will need dialog popup additions to be better
analogous to yes-or-no-p.

===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/simple.el,v
retrieving revision 1.634
diff -u -r1.634 simple.el
--- lisp/simple.el	25 Mar 2004 16:01:37 -0000	1.634
+++ lisp/simple.el	15 Apr 2004 11:14:47 -0000
@@ -1227,6 +1227,62 @@
 	     '(0 . 0)))
     '(0 . 0)))
 \f
+(defvar question-history nil)
+
+(defun question (prompt &optional responses help-response)
+"Prompt with PROMPT for a response from RESPONSES.
+
+RESPONSES is an alist associating responses with returns.  Each
+member of RESPONSES is of the form (\"response\" . return).  For
+example '((\"yes\" . t) (\"no\" . n)).  The return can be
+anything except nil, which is used when searching the list.
+
+HELP-RESPONSE is a cons cell with a response as its car and a
+help string as its cdr.  If the help response is entered the
+string is displayed in the other buffer and prompting continues.
+
+If only PROMPT is given `yes-or-no-p' is called with PROMPT as
+its argument."
+  (if responses
+      (let ((options))
+	;; add alternatives to prompt
+	(let (rest (answers (if help-response
+				(append responses (list help-response))
+	
+		      responses)))
+	  (while answers
+	    (setq options
+		  (concat options
+			  (if (prog1 rest (setq rest t))
+			      (if (cdr answers)
+				  (concat ", "
+					  (car (car answers)))
+				(concat " or "
+					(car (car answers))))
+			    (car (car answers)))))
+	    (setq answers (cdr answers))))
+	(setq prompt (concat prompt "(" options ") "))
+	;; return the value associated with a prompted response
+	(cdr (let (ret rsp)
+		 (while (not
+			 (setq ret (assoc (setq rsp (read-from-minibuffer
+						     prompt nil nil nil
+						     question-history nil
+						     nil))
+					  responses)))
+		   (if (and help-response
+			    (equal rsp (car help-response)))
+		       (with-output-to-temp-buffer "*Help*"
+			 (princ (cdr help-response))
+			 (with-current-buffer standard-output
+			   (help-mode)))
+		     (ding)
+		     (discard-input)
+		     (message "Please answer %s." options)
+		     (sleep-for 2 nil)))
+		   ret)))
+    (yes-or-no-p prompt)))
+\f
 (defvar shell-command-history nil
   "History list for some commands that read shell commands.")
 
@@ -1356,9 +1412,23 @@
 		;; If will kill a process, query first.
 		(setq proc (get-buffer-process buffer))
 		(if proc
-		    (if (yes-or-no-p "A command is running.  Kill it? ")
-			(kill-process proc)
-		      (error "Shell command in progress")))
+		    (let ((res (question
+				"A command is running.  Kill it? "
+				'(("yes" . t) ("no" . no) ("r" . run))
+				'("?" . "An asynchronous command is already running in the \"*Async Shell Command*\" buffer.
+Enter
+  \"yes\"  to kill the running command, replacing it with the new one,
+  \"no\"   to quit, leaving the current command running, or
+  \"r\"    to run the new command in parallel in a uniquely-named buffer."))))
+		      (cond
+		       ((eq res 'run)
+			(setq buffer (get-buffer-create
+				      (generate-new-buffer-name
+				       (buffer-name buffer)))))
+		       ((eq res t) (kill-process proc))
+		       ((eq res 'no) (error "Shell command in progress"))
+		       ;; question-p prevents this case
+		       (t (error "Error processing response")))))
 		(with-current-buffer buffer
 		  (setq buffer-read-only nil)
 		  (erase-buffer)




[-- Attachment #2: Type: message/rfc822, Size: 3345 bytes --]

From: Dan Jacobson <jidanni@jidanni.org>
Subject: A Compilation process is running; kill it? (yes or no)
Date: Wed, 17 Mar 2004 10:13:35 +0800
Message-ID: <87vfl4jk4w.fsf@jidanni.org>

When attempting a second compilation, instead of asking
A Compilation process is running; kill it? (yes or no)
ask
A Compilation process is running;a kill it? (yes or q)
which is more telling instead of "no".  Better yet, ask
A Compilation process is running; kill it? (yes, c, q, ?)
c - launch a parallel compilation.

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

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

Re: Improved help from minibuffer prompts

[Richard Stallman]

For this feature to be useful for beginners, just C-h or just F1 should
invoke it straightaway.

This feature could perhaps offer some way to get at the usual help commands.
Perhaps the help buffer could start with this message:

    Type SPC to get rid of this message and continue.
    Type Help again to access the usual help commands.

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Matthew!

> Stefan Reichör <xsteve@riic.at> writes:
>
>> Hi!
>> 
>> I am currently working on xtla.el (the arch interface for emacs).
>> 
>> In my mode the user is often asked some questions in the
>> minibuffer. Sometimes the questions need some more
>> explanations. So I decided to put the needed help in the
>> function's docstring.
>
> Here's a function called `question' which may be of use.
>
> It allows the responses to an interactive question to be defined,
> including a help response and associated help string.  The patch
> includes a change to `shell-command' to use `question', in the way
> suggested for the `compile' command by Dan Jacobson (in the attached
> mail).  This allows `shell-command' to start concurrent asynchronous
> shell commands.
>
> The function `may-y-or-n-p' may also be useful.
>
> Note that `question' will need dialog popup additions to be better
> analogous to yes-or-no-p.

I think, that your function is useful, however as far as I can see,
it allows only a fixed given number of answers.

I think that your question function should also be added to emacs.

My proposal allows to get help at every minibuffer prompt without the
need to explicitly add the help string.

-- 
  Stefan.

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Richard!

> For this feature to be useful for beginners, just C-h or just F1 should
> invoke it straightaway.

Fine with me. (in fact: I use it that way in xtla.el at the moment)

> This feature could perhaps offer some way to get at the usual help commands.
> Perhaps the help buffer could start with this message:
>
>     Type SPC to get rid of this message and continue.
>     Type Help again to access the usual help commands.

You get the help in any minibuffer prompt. Sometimes you want to type
a SPC. I think it is usefull, if the help buffer is available during
entering a value in a minibuffer.
So I am not sure about the best way to get rid of the help
window. And if it is even necessary to get rid of it (you can always
switch to the window and kill it explicitly).

I think, that entering the usual help menu with f1 of C-h is fine.
The downside of this is, that you have to type C-h C-h k instead of
C-h k, etc.


-- 
  Stefan.

Re: Improved help from minibuffer prompts

[Kim F. Storm]

Stefan Reichör <xsteve@riic.at> writes:

> I think, that entering the usual help menu with f1 of C-h is fine.
> The downside of this is, that you have to type C-h C-h k instead of
> C-h k, etc.

If that works, then it is fine with me.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Improved help from minibuffer prompts

[Kai Grossjohann]

Stefan Reichör <xsteve@riic.at> writes:

>> This feature could perhaps offer some way to get at the usual help commands.
>> Perhaps the help buffer could start with this message:
>>
>>     Type SPC to get rid of this message and continue.
>>     Type Help again to access the usual help commands.
>
> You get the help in any minibuffer prompt. Sometimes you want to type
> a SPC.

Add a third line: Type C-q SPC to insert a space.

Kai

Re: Improved help from minibuffer prompts

[Richard Stallman]

    > You didn't say which function you mean, but according to the code
    > it looks like the entire doc string of the command that invoked
    > the minibuffer is the help string you use.  I don't think
    > that will be very natural.

    I think it is convenient. Every interactive function has already a
    docstring.

The doc string for the function is not designed to explain how to
enter a specific argument.  It is the wrong text for this job.

    When I type M-x grep and get a prompt and I am not sure, what I am
    asked here, I can just get the help for the function grep.

That might be useful, but it isn't the same idea.  The idea was to
tell the user about the argument being entered, wasn't it?

Re: Improved help from minibuffer prompts

[Richard Stallman]

    Where can I bind minibuffer-extra-help?

You'd have to bind it with `let' inside the `interactive' spec.

Re: Improved help from minibuffer prompts

[Richard Stallman]

    The problem with using just C-h or f1 is that it would block the
    ability to use C-h b or C-h k in the minibuffer.  

Yes.  You could turn it off.

    Maybe C-h C-h would be ok.

It would be ok as a way to get at describe-key.
You'd type C-h C-h k.

Re: Improved help from minibuffer prompts

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     > You didn't say which function you mean, but according to the code
>     > it looks like the entire doc string of the command that invoked
>     > the minibuffer is the help string you use.  I don't think
>     > that will be very natural.
> 
>     I think it is convenient. Every interactive function has already a
>     docstring.
> 
> The doc string for the function is not designed to explain how to
> enter a specific argument.  It is the wrong text for this job.

But it is better than no text -- so it would be nice to have a
way to specify a specific help text, but in case no such text has
been provided, just showing the function docstring would be a
reasonable fallback.

> 
>     When I type M-x grep and get a prompt and I am not sure, what I am
>     asked here, I can just get the help for the function grep.
> 
> That might be useful, but it isn't the same idea.  The idea was to
> tell the user about the argument being entered, wasn't it?

The doc string is supposed to describe the arguments, so it is more
useful than no help.

Re: Improved help from minibuffer prompts

[Richard Stallman]

    The doc string is supposed to describe the arguments, so it is more
    useful than no help.

That is true--but its description of the arguments is often not
very helpful for a situation like this.

Here is a new idea.  We can develop a convention for delimiting, in
the doc string, the help about each argument.  Then the help facility
for entering an argument could look thru the doc string for the part
that refers to the current argument.

Re: Improved help from minibuffer prompts

[Richard Stallman]

Do people think the proposed `question' function is a good idea?

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Richard!

>     The doc string is supposed to describe the arguments, so it is more
>     useful than no help.
>
> That is true--but its description of the arguments is often not
> very helpful for a situation like this.
>
> Here is a new idea.  We can develop a convention for delimiting, in
> the doc string, the help about each argument.  Then the help facility
> for entering an argument could look thru the doc string for the part
> that refers to the current argument.

That is a nice idea. Here are my thoughts:
* Often you are prompted for an argument in the minibuffer.
  - A specific help for this argument would be sometimes very nice,
    because the prompt is to short to provide all the information
  - Often you want to about the function that is actually in progress
    You want to get the "big picture". In this case the whole
    documentation would be nicer.

* The convention for delimiting the doc strings would require a
  rewrite of many docstrings.
  Many source code documentation tools solve it by putting an extra
  \param section for every parameter.

* Look at the following (randomly) choosen functions and their documentations:

--------------------------------------------------------------------------------
grep-find is an interactive autoloaded Lisp function in `grep'.
(grep-find COMMAND-ARGS)

Run grep via find, with user-specified args COMMAND-ARGS.
Collect output in a buffer.
While find runs asynchronously, you can use the C-x ` command
to find the text that grep hits refer to.

This command uses a special history list for its arguments, so you can
easily repeat a find command.

--------------------------------------------------------------------------------
find-dired is an interactive autoloaded Lisp function in `find-dired'.
(find-dired DIR ARGS)

Run `find' and go into Dired mode on a buffer of the output.
The command run (after changing into DIR) is

    find . \( ARGS \) -ls

except that the variable `find-ls-option' specifies what to use
as the final argument.
--------------------------------------------------------------------------------

Consider the find-dired example. When asked for dir or args
I would like to get the whole docstring, because it covers the things
I need to know.

I am not sure about the benefit of stripping the information down for
every argument.

-- 
  Stefan.

Re: Improved help from minibuffer prompts

[Kim F. Storm]

Stefan Reichör <xsteve@riic.at> writes:

> > Here is a new idea.  We can develop a convention for delimiting, in
> > the doc string, the help about each argument.  Then the help facility
> > for entering an argument could look thru the doc string for the part
> > that refers to the current argument.
> 
> * The convention for delimiting the doc strings would require a
>   rewrite of many docstrings.

IMO, that is a lot of work for only a minor benefit (arg specific
help vs. full doc string).

> * Look at the following (randomly) choosen functions and their documentations:

> Consider the find-dired example. When asked for dir or args
> I would like to get the whole docstring, because it covers the things
> I need to know.
> 
> I am not sure about the benefit of stripping the information down for
> every argument.

I agree.  

IMO, the full doc string is often MORE useful than getting info on one
arg, so why limit it.

Here is another idea, enhancing on Richard's idea:

Show the full doc string, but highlight occurrences of the upper case
PARAM name in the doc string -- then the user will be able to quickly
locate the relevant information and focus on that...

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

RE: Improved help from minibuffer prompts

[Drew Adams]

Nothing wrong with a new convention to delimit help for each arg.

I've thought for a while that relying on just an UPPERCASE convention for
documenting arguments and their structural parts could be improved upon
somehow. (Did someone say XML doc strings? Elisp schemas? JavaDoc keywords?
:)) A more clearly defined doc-string convention (structure, order, style)
might be a start.

However:

1) As others have pointed out, functions looking for this delimiter stuff
couldn't do anything with older doc strings that lacked it. And updating all
the doc strings of the predefined functions would be OK, but it wouldn't
affect outside, contributed packages.

2) More importantly, we should make an effort (progressively) to create doc
strings that describe arguments first in a *user-centric* fashion. Nerdier
nitty-gritty explanations can be included in a doc string (if really
necessary - rare IMO), but they should come after a high-level,
user-understandable explanation. This effort would go a long way to solving
the perceived problem.

3) *Improve the prompts* for input arguments. A good prompt goes a long way
to helping users understand. I realize that some input args are so complex
that a user may need to understand more than can be put in a prompt, but
this can sometimes be an indicator that the command UI is in fact
ill-defined.

4) Keeping in mind #2 & #3, I agree with some others that it can be useful
for a user to get to the whole doc string. Wouldn't it be sufficient to
remind a user about `C-h f' at the point of the argument "help" call? Yes,
the user would have to start the command over after reading the doc, but is
that such a bad thing?

5) Often, a prefix arg (present/absent; positive, negative, zero; other
specific values) is very important to a command's functioning. It would not
be explained by the proposed arg help; users would have to consult the doc
string to get that info anyway. If they came to rely on the proposed arg
help, thinking they were getting the whole story that way, they would miss a
lot.

6) I'm not convinced of the utility of extra help for prompted parameters at
command call. I tend to think: a) the *prompt* itself should be able to do
the job, and b) if it cannot, the user should consult the doc string with
`C-h f'.

7) In sum, I like the *solution* (delimit parts of doc strings, or otherwise
structure them), but I am not sure of the importance of the *problem* it
tries to solve. Delimiting arg help might be a good idea for other possible
uses (apropos? JavaDoc-style doc?), but I'm not sure that dynamic help on
args is really needed/helpful. But then again, I haven't tried it...

 - Drew

-----Original Message-----
From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org
[mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of
Stefan Reichor
Sent: Monday, April 19, 2004 12:52 AM
To: emacs-devel@gnu.org
Subject: Re: Improved help from minibuffer prompts
...
>     The doc string is supposed to describe the arguments, so it is more
>     useful than no help.
>
> That is true--but its description of the arguments is often not
> very helpful for a situation like this.
>
> Here is a new idea.  We can develop a convention for delimiting, in
> the doc string, the help about each argument.  Then the help facility
> for entering an argument could look thru the doc string for the part
> that refers to the current argument.

That is a nice idea. Here are my thoughts:
* Often you are prompted for an argument in the minibuffer.
  - A specific help for this argument would be sometimes very nice,
    because the prompt is to short to provide all the information
  - Often you want to about the function that is actually in progress
    You want to get the "big picture". In this case the whole
    documentation would be nicer.

* The convention for delimiting the doc strings would require a
  rewrite of many docstrings.
  Many source code documentation tools solve it by putting an extra
  \param section for every parameter.

...
Consider the find-dired example. When asked for dir or args
I would like to get the whole docstring, because it covers the things
I need to know.

I am not sure about the benefit of stripping the information down for
every argument.

Re: Improved help from minibuffer prompts

[Richard Stallman]

    Consider the find-dired example. When asked for dir or args
    I would like to get the whole docstring, because it covers the things
    I need to know.

    I am not sure about the benefit of stripping the information down for
    every argument.

We don't have to do it for every argument.  The feature could be
designed so that there is a way to specify that for a certain argument
it should show you the whole string.

The idea of showing the whole string but highlighting the info for
the specific argument might also be good.

Re: Improved help from minibuffer prompts

[Richard Stallman]

    2) More importantly, we should make an effort (progressively) to create doc
    strings that describe arguments first in a *user-centric* fashion. Nerdier
    nitty-gritty explanations can be included in a doc string (if really
    necessary - rare IMO), but they should come after a high-level,
    user-understandable explanation. This effort would go a long way to solving
    the perceived problem.

    3) *Improve the prompts* for input arguments. A good prompt goes a long way
    to helping users understand. I realize that some input args are so complex
    that a user may need to understand more than can be put in a prompt, but
    this can sometimes be an indicator that the command UI is in fact
    ill-defined.

I agree completely.  Anyone who has signed papers, please rewrite
doc strings in these ways whenever you feel you need a break
from fixing bugs.

    4) Keeping in mind #2 & #3, I agree with some others that it can be useful
    for a user to get to the whole doc string. Wouldn't it be sufficient to
    remind a user about `C-h f' at the point of the argument "help" call?

That would be very inconvenient in practical use.  We're considering
other suggestions that are much easier to use.

    5) Often, a prefix arg (present/absent; positive, negative, zero; other
    specific values) is very important to a command's functioning.

That is true.  However,...

								   It would not
    be explained by the proposed arg help;

Maybe so, but I don't follow your point.  We're talking about offering
help for how to enter a minibuffer argument.  Could you explain
precisely how the prefix arg relates to this?

					   users would have to consult the doc
    string to get that info anyway. If they came to rely on the proposed arg
    help, thinking they were getting the whole story that way, they would miss a
    lot.

So what?  We're talking about getting help for entering a minibuffer
argument.

    7) In sum, I like the *solution* (delimit parts of doc strings, or otherwise
    structure them), but I am not sure of the importance of the *problem* it
    tries to solve.

Someone saw room for improvement, but I don't want to say I am certain
it is important.  Perhaps things are good enough as they are.

RE: Improved help from minibuffer prompts

[Drew Adams]

below

-----Original Message-----
From: Richard Stallman [mailto:rms@gnu.org]
Sent: Tuesday, April 20, 2004 1:48 PM
To: Drew Adams
Cc: emacs-devel@gnu.org
Subject: Re: Improved help from minibuffer prompts

    2) More importantly, we should make an effort (progressively) to create
doc
    strings that describe arguments first in a *user-centric* fashion.
Nerdier
    nitty-gritty explanations can be included in a doc string (if really
    necessary - rare IMO), but they should come after a high-level,
    user-understandable explanation. This effort would go a long way to
solving
    the perceived problem.

    3) *Improve the prompts* for input arguments. A good prompt goes a long
way
    to helping users understand. I realize that some input args are so
complex
    that a user may need to understand more than can be put in a prompt, but
    this can sometimes be an indicator that the command UI is in fact
    ill-defined.

> I agree completely.  Anyone who has signed papers, please rewrite
> doc strings in these ways whenever you feel you need a break
> from fixing bugs.

    4) Keeping in mind #2 & #3, I agree with some others that it can be
useful
    for a user to get to the whole doc string. Wouldn't it be sufficient to
    remind a user about `C-h f' at the point of the argument "help" call?

> That would be very inconvenient in practical use.  We're considering
> other suggestions that are much easier to use.

I don't see them as
 . "much easier to use" or
 . very useful.

We're considering the benefits of a help-key when prompted for an input arg
to a command; the key would call up some help on the arg. Bringing up the
entire doc string was mentioned as one possibility.

If the doc string is not well written, then the solution is to rewrite it.

If the doc string is well written, I don't see much utility in the
arg-prompt help. If it just brings up the doc string, I suppose that's OK,
but in that case it would be sufficient for it to serve as a reminder (esp.
to newbies) that the args are described via `C-h f'.

My point here was that the key sequence that calls up help when inputting an
arg could just (generically) echo "Use `C-h f <command-name-here>' for more
information".

If you need to read the doc string to continue inputting an arg, I think you
can exit the command, read it, then execute the command again. How hard is
it to re-execute a command?

I don't see much utility in *temporarily* leaving the arg-input process to
consult the help, then continuing where you left off, inputting. That kind
of thing is OK for query-replace, but it's not very useful in this context,
IMO.

As I said, however, I have not tried the proposed help, so this is just a
prejudice. I try to imagine the new feature, and I don't see it helping.
Those who have used it apparently find it helpful.

    5) Often, a prefix arg (present/absent; positive, negative, zero; other
    specific values) is very important to a command's functioning.

> That is true.  However,...

    It would not be explained by the proposed arg help;

> Maybe so, but I don't follow your point.  We're talking about offering
> help for how to enter a minibuffer argument.  Could you explain
> precisely how the prefix arg relates to this?

    users would have to consult the doc
    string to get that info anyway. If they came to rely on the proposed arg
    help, thinking they were getting the whole story that way, they would
miss a
    lot.

> So what?  We're talking about getting help for entering a minibuffer
> argument.

My point here is that if the input-arg help does *not* include the whole doc
string, then it only goes so far toward helping you use & learn about the
command. That's OK as far as it goes, but you might get the impression that
you've learned it all, and miss out on some important functionality.

If, on the other hand, the prompt help just says `Use `C-h f' for more
information' (or if it showed you the entire doc string directly), then you
might learn more.

In sum:

1. If the arg-input help does *not* give you the whole doc string (directly
or indirectly), then:

 . It's not worth it.
 . It might lead you to miss out on important info in the doc string.

2. If the arg-input help gives you the whole doc string *directly*, then:

 . It's not worth it. A reminder about `C-h f' is as good. In fact, it's
better that folks get in the habit of using `C-h f'.

    7) In sum, I like the *solution* (delimit parts of doc strings, or
otherwise
    structure them), but I am not sure of the importance of the *problem* it
    tries to solve.

> Someone saw room for improvement, but I don't want to say I am certain
> it is important.  Perhaps things are good enough as they are.

IMO, they are. #2 and #3 at the top are key: good doc strings, good prompts
(and commands that don't require understanding complex input args).


There is still the question of the utility of (somehow) structuring doc
strings - that is, making them doc structures, not just strings. Any juice
there?


 - Drew

Re: Improved help from minibuffer prompts

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 20 Apr 2004 16:13:04 -0700
> 
> My point here was that the key sequence that calls up help when inputting an
> arg could just (generically) echo "Use `C-h f <command-name-here>' for more
> information".

That could cut it, I suppose, assuming (unrealistically) that most of
the doc strings do a job that's good enough, but I think that giving a
specific help for the argument being prompted for is still better.  It
is better because the info presented to the user is shorter and
specifically targets what the user presumably is concerned about at
the time she presses the help key: what kind of input Emacs expects.

> My point here is that if the input-arg help does *not* include the whole doc
> string, then it only goes so far toward helping you use & learn about the
> command. That's OK as far as it goes, but you might get the impression that
> you've learned it all, and miss out on some important functionality.

When I want a help on a specific argument, I don't care much about the
rest of the doc string, and don't assume I know everything about the
command after reading only about the meaning of the specific argument
in question.

In general, I think we should assume that if the user invoked a
command, she already knows pretty much about that command, i.e. she
already read its documentation at least once.  We could provide a
link to the full doc string in the text we pop up to describe the
currently prompted-for arg, in case that assumption is false, but
there's no need, IMHO, to assume that the user needs to see all that
info to begin with.

As a general rule, showing too much information when there's a high
probability that the user wants to see only its small portion is a bad
idea, IMO.  For example, don't you get annoyed by all those answering
machines installed by government organizations and large firms to
respond to their support telephone lines, which force you to hear lots
of info before you get to the point?  Many times, after hearing a lot
of info that is only tangentially related to what I'm up to frustrates
me so much that I disconnect in disguise.  Similar results could
follow if we show users too much information when they need only its
small portion.

> 1. If the arg-input help does *not* give you the whole doc string (directly
> or indirectly), then:
> 
>  . It's not worth it.
>  . It might lead you to miss out on important info in the doc string.

I can understand the second part, but I don't understand the first:
why ``not worth it''?  If I'm looking specifically for what I could
type at the current prompt, I think it's worth its text in gold.

> > Someone saw room for improvement, but I don't want to say I am certain
> > it is important.  Perhaps things are good enough as they are.
> 
> IMO, they are. #2 and #3 at the top are key: good doc strings, good prompts
> (and commands that don't require understanding complex input args).

I disagree here: there's too little real estate in the minibuffer to
show a prompt that explains the possible inputs in enough detail, at
least not in all cases.  Giving the temporarily confused help that is
focused on the specific task they are confused about is IMHO A Good
Thing.

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 19 Apr 2004 13:50:58 +0200, storm@cua.dk (Kim F. Storm) wrote:

> Here is another idea, enhancing on Richard's idea:
> 
> Show the full doc string, but highlight occurrences of the upper case
> PARAM name in the doc string -- then the user will be able to quickly
> locate the relevant information and focus on that...

Related to that, here's a (proof-of-concept) patch that sets the face
`font-lock-variable-name-face' for all uses of the arguments of a
function in a `describe-function' *Help* buffer.

I say proof-of-concept because I've not provided a way to make it
optional, I've hard-coded the face used, etc. Still, it works
beautifully.

The auxiliary function help-highlight-arguments is designed in such a
way that it can be pased a nil WORDS argument (and then it highlights
all arguments of the function), or a list of desired arguments to
highlight, so it can be of help if highlighting info for an argument is
desired (which was discused in this thread).

Opinions?

                                                           /L/e/k/t/u


Index: help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.40
diff -u -2 -r1.40 help-fns.el
--- help-fns.el	29 Apr 2004 18:46:13 -0000	1.40
+++ help-fns.el	29 Apr 2004 23:39:08 -0000
@@ -131,4 +131,25 @@
 ;; Functions
 
+(defun help-highlight-arguments (fun &rest words)
+  (save-excursion
+    (goto-char (point-min))
+    (let* ((case-fold-search nil)
+           (next (and (not words)
+                      (re-search-forward (concat "(" (symbol-name fun)) nil t))))
+      ;; Make a list of all arguments
+      (while next
+        (when (re-search-forward " \\([^ &\)\.]+\\)" nil t)
+          (setq words (cons (match-string 1) words)))
+        (setq next (not (search-forward ")" (1+ (point)) t))))
+      ;; Highlight all found arguments anywhere in the *Help* buffer
+      (while words
+        (let* ((word (car words))
+               (solo (concat "\\<" word "\\>"))
+               (high (propertize word 'face 'font-lock-variable-name-face)))
+          (setq words (cdr words))
+          (goto-char (point-min))
+          (while (re-search-forward solo nil t)
+            (replace-match high nil t)))))))
+
 ;;;###autoload
 (defun describe-function (function)
@@ -156,4 +177,6 @@
 	(print-help-return-message)
 	(with-current-buffer standard-output
+          ;; highlight argument names
+          (help-highlight-arguments function)
 	  ;; Return the text we displayed.
 	  (buffer-string))))))

Re: Improved help from minibuffer prompts

[Stefan Reichör]

Hi Juanma!

> Related to that, here's a (proof-of-concept) patch that sets the face
> `font-lock-variable-name-face' for all uses of the arguments of a
> function in a `describe-function' *Help* buffer.
>
> I say proof-of-concept because I've not provided a way to make it
> optional, I've hard-coded the face used, etc. Still, it works
> beautifully.
>
> The auxiliary function help-highlight-arguments is designed in such a
> way that it can be pased a nil WORDS argument (and then it highlights
> all arguments of the function), or a list of desired arguments to
> highlight, so it can be of help if highlighting info for an argument is
> desired (which was discused in this thread).
>
> Opinions?

I looks very good!

Stefan.

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On Fri, 30 Apr 2004 07:32:48 +0200
Stefan Reichör <xsteve@riic.at> wrote:

> I looks very good!

Great.

BTW, my implementation does not grok yet CL-style "&optional (variable
default)" arglists.  I'm working on it.  I've also added a slight
modification so

(defun test (&rest buffer)
  "Do something to one or more BUFFERs."
  ...)

will highlight BUFFER in the docstring (ignoring the plural ending, and
the same for "es").

Related to CL arglists, `help-add-fundoc-usage' uses (roughly)

  (format "%s%s%s"
	  ;; doc
          ;; whitespace
          ;; arglist doc
          )

As "%s" is equivalent to `princ', it does not quote, so an arglist like

  &optional (kind "")

shows in the docstring as

  &optional (KIND  )

(See `ebrowse-draw-file-member-info' for an example of the issue.)

Does anyone anticipate problems with the following minimal patch?

                                                                Juanma



--- help-fns.el.orig	2004-04-30 10:36:06.000000000 +0200
+++ help-fns.el	2004-04-30 10:36:26.000000000 +0200
@@ -205,5 +205,5 @@
   (if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" doc) (eq arglist t))
       doc
-    (format "%s%s%s" doc
+    (format "%s%s%S" doc
 	    (if (string-match "\n?\n\\'" doc)
 		(if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "")

Re: Improved help from minibuffer prompts

[Kim F. Storm]

Juanma Barranquero <lektu@mi.madritel.es> writes:

> On 19 Apr 2004 13:50:58 +0200, storm@cua.dk (Kim F. Storm) wrote:
> 
> > Here is another idea, enhancing on Richard's idea:
> > 
> > Show the full doc string, but highlight occurrences of the upper case
> > PARAM name in the doc string -- then the user will be able to quickly
> > locate the relevant information and focus on that...
> 
> Related to that, here's a (proof-of-concept) patch that sets the face
> `font-lock-variable-name-face' for all uses of the arguments of a
> function in a `describe-function' *Help* buffer.
> 
> I say proof-of-concept because I've not provided a way to make it
> optional, I've hard-coded the face used, etc. Still, it works
> beautifully.
> 
> The auxiliary function help-highlight-arguments is designed in such a
> way that it can be pased a nil WORDS argument (and then it highlights
> all arguments of the function), or a list of desired arguments to
> highlight, so it can be of help if highlighting info for an argument is
> desired (which was discused in this thread).
> 
> Opinions?

I have applied your patch locally; I'll use it for a while before
I'll make a judgement.  But initially, I like it.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 30 Apr 2004 12:08:47 +0200
storm@cua.dk (Kim F. Storm) wrote:

> I have applied your patch locally; I'll use it for a while before
> I'll make a judgement.

Please, try this one instead.  It's a bit less elegant because of the
support for CL-style optional arguments, but it works in all tests cases
I've tried.

> But initially, I like it.

Glad to hear.

                                                                Juanma

--- help-fns.el.orig	2004-04-30 15:31:10.000000000 +0200
+++ help-fns.el	2004-04-30 15:28:47.000000000 +0200
@@ -131,4 +131,33 @@
 ;; Functions
 
+(defun help-highlight-arguments (fun &rest args)
+  (save-excursion
+    (goto-char (point-min))
+    (let* ((case-fold-search nil)
+           (next (and (not args)
+                      (re-search-forward (concat "(" (symbol-name fun)) nil t))))
+      (save-restriction
+        (narrow-to-region (point) (re-search-forward ")\n" nil t))
+        (goto-char (point-min))
+        ;; Make a list of all arguments
+        (while next
+          (if (not (re-search-forward " \\((?\\)\\([^ &\)\.]+\\)" nil t))
+              (setq next nil)
+            (setq args (cons (match-string 2) args))
+            (unless (string= (match-string 1) "")
+              ;; A pesky CL-style optional argument with default value,
+              ;; so let's skip over it
+              (search-backward "(")
+              (goto-char (scan-sexps (point) 1))))))
+      ;; Highlight all found arguments anywhere in the *Help* buffer
+      (while args
+        (let* ((arg (car args))
+               (solo (concat "\\<\\(" arg "\\)e?s?\\>"))
+               (high (propertize arg 'face 'font-lock-variable-name-face)))
+          (setq args (cdr args))
+          (goto-char (point-min))
+          (while (re-search-forward solo nil t)
+            (replace-match high nil t nil 1)))))))
+
 ;;;###autoload
 (defun describe-function (function)
@@ -156,4 +185,6 @@
 	(print-help-return-message)
 	(with-current-buffer standard-output
+          ;; highlight argument names
+          (help-highlight-arguments function)
 	  ;; Return the text we displayed.
 	  (buffer-string))))))

Re: Improved help from minibuffer prompts

[Kim F. Storm]

Juanma Barranquero <jmbarranquero@wke.es> writes:

> On 30 Apr 2004 12:08:47 +0200
> storm@cua.dk (Kim F. Storm) wrote:
> 
> > I have applied your patch locally; I'll use it for a while before
> > I'll make a judgement.
> 
> Please, try this one instead.  It's a bit less elegant because of the
> support for CL-style optional arguments, but it works in all tests cases
> I've tried.

Try C-h f defmacro RET

(defmacro NAME ARGLIST [DOCSTRING] [DECL] BODY...)

the bracketed (optional) args are not recognized.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Improved help from minibuffer prompts

[Stefan Monnier]

> Please, try this one instead.  It's a bit less elegant because of the
> support for CL-style optional arguments, but it works in all tests cases
> I've tried.

Please try to use help-split-fundoc.

ctually you don't even need to do that because if you call your function from
describe-function-1, the usage/arglist is already available separately from
the docstring.


        Stefan

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 30 Apr 2004 11:57:41 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> > Please, try this one instead.  It's a bit less elegant because of the
> > support for CL-style optional arguments, but it works in all tests cases
> > I've tried.
> 
> Please try to use help-split-fundoc.

I initially tried that, and ended having to patch describe-function
(and/or describe-function-1), help-split-fundoc and
help-add-fundoc-usage. The result wasn't pretty.

What I'm doing now, postprocessing the *Help* buffer after most of the
describe-function machinery has already run, is way easier and has the
added benefit that it almost doesn't touch what's already that.

> ctually you don't even need to do that because if you call your function from
> describe-function-1, the usage/arglist is already available separately from
> the docstring.

Yeah, but splitting usage from arglist is not a problem currently. The
problem I talked above is parsing things like the docstring for

 (defun* test (&optional (a 1))
   "Add 1 to A."
   (1+ a))

and, as far as I can see, the only point where the existing code would
help is in help-add-fundoc-usage, which does not return a string, but a
list, so adding highlighting information to it is messy (not to mention
hackish).

So, I'm not sure what benefit would it be (but I'm perhaps
misunderstanding you). Could you please elaborate?

Thanks,

                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 30 Apr 2004 17:50:38 +0200, no-spam@cua.dk (Kim F. Storm) wrote:

> the bracketed (optional) args are not recognized.

I forgot about them. It's just a matter of fixing the regexp.

New iteration attached.

Thanks a lot for testing.

                                                           /L/e/k/t/u



Index: help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.40
diff -u -2 -r1.40 help-fns.el
--- help-fns.el	29 Apr 2004 18:46:13 -0000	1.40
+++ help-fns.el	30 Apr 2004 22:15:08 -0000
@@ -131,4 +131,33 @@
 ;; Functions
 
+(defun help-highlight-arguments (fun &rest args)
+  (save-excursion
+    (goto-char (point-min))
+    (let* ((case-fold-search nil)
+           (next (and (not args)
+                      (re-search-forward (concat "(" (symbol-name fun)) nil t))))
+      (save-restriction
+        (narrow-to-region (point) (re-search-forward ")\n" nil t))
+        (goto-char (point-min))
+        ;; Make a list of all arguments
+        (while next
+          (if (not (re-search-forward " \\([\\[(]?\\)\\([^] &)\.]+\\)" nil t))
+              (setq next nil)
+            (setq args (cons (match-string 2) args))
+            (when (string= (match-string 1) "(")
+              ;; A pesky CL-style optional argument with default value,
+              ;; so let's skip over it
+              (search-backward "(")
+              (goto-char (scan-sexps (point) 1))))))
+      ;; Highlight all found arguments anywhere in the *Help* buffer
+      (while args
+        (let* ((arg (car args))
+               (solo (concat "\\<\\(" arg "\\)e?s?\\>"))
+               (high (propertize arg 'face 'font-lock-variable-name-face)))
+          (setq args (cdr args))
+          (goto-char (point-min))
+          (while (re-search-forward solo nil t)
+            (replace-match high nil t nil 1)))))))
+
 ;;;###autoload
 (defun describe-function (function)
@@ -156,4 +185,6 @@
 	(print-help-return-message)
 	(with-current-buffer standard-output
+          ;; highlight argument names
+          (help-highlight-arguments function)
 	  ;; Return the text we displayed.
 	  (buffer-string))))))

Re: Improved help from minibuffer prompts

[Stefan Monnier]

> So, I'm not sure what benefit would it be (but I'm perhaps
> misunderstanding you). Could you please elaborate?

Your code assumes that the arglist has been inserted at a particular place
in the buffer, which is not necessarily a reliable way to get the info
you need.
Instead, you could hook into describe-function-1 at the place where the
corresponding text is inserted, at which point you know exactly where that
text is, without needing any heuristic.


        Stefan

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 30 Apr 2004 18:49:42 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Instead, you could hook into describe-function-1 at the place where the
> corresponding text is inserted, at which point you know exactly where that
> text is, without needing any heuristic.

I agree, in principle, and as I said that's what I first tried.

The problem is, describe-function-1 is a big hairy function with a
complex program flow. For starters, there's not a single place where
help-split-fundoc is called inside describe-function-1, but two. There's
also a call to help-make-usage, which, to add fun, does not return a
string but a list which must be first converted. Additionally,
describe-function-1 uses princ to output data to the current buffer,
which must be changed to (with-current-buffer standard-output (insert...))
or otherwise the text attributes are lost...

All in all, I really doubt the result is easier to understand or
maintain. For example, there's a case I've been unable to test, the one
corresponding to ((stringp arglist) arglist) in the cond, because I
don't know of any such function.

AFAICS, the benefits from doing it your way are small:

 - No heuristics to determine what's a usage doc and what's simply doc.

   OK, but the format of docs is something we control so we can be
   reasonably sure it's working, and we can always adapt
   help-highlight-arguments if necessary.

 - All functions that use describe-function-1 are automatically
   highlighted.

   The fact is that describe-function-1 is not a public function (it has
   no docstring and it's not included on the Emacs Lisp reference
   manual); it's only used in describe-function and describe-key. Adding
   my initial implementation to both is a matter of adding one line to
   describe-function and two lines to describe-key.

I've included below a patch doing it your style (it's a bit weird
because I've had to used diff -b to avoid the effects of a reindent of
some code). I honestly don't find it more robust or better that the
other implementation, but I'll be happy to pursue whatever one is deemed
more acceptable.



                                                           /L/e/k/t/u



Index: help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.40
diff -u -2 -b -r1.40 help-fns.el
--- help-fns.el	29 Apr 2004 18:46:13 -0000	1.40
+++ help-fns.el	1 May 2004 01:59:08 -0000
@@ -131,4 +131,39 @@
 ;; Functions
 
+(defun help-do-arg-highlight (doc args)
+  (while args
+    (let ((arg (car args)))
+      (setq args (cdr args))
+      (setq doc (replace-regexp-in-string (concat "\\<\\(" arg "\\)e?s?\\>")
+                                          (propertize arg 'face 'font-lock-variable-name-face)
+                                          doc))))
+  doc)
+
+(defun help-highlight-arguments (usage &rest args)
+  (when usage
+    (let* ((case-fold-search nil)
+           (use (car usage))
+           (doc (cdr usage))
+           (next (not args)))
+      ;; Make a list of all arguments
+      (with-temp-buffer
+        (insert use)
+        (goto-char (point-min))
+        ;; Make a list of all arguments
+        (while next
+          (if (not (re-search-forward " \\([\\[(]?\\)\\([^] &)\.]+\\)" nil t))
+              (setq next nil)
+            (setq args (cons (match-string 2) args))
+            (when (string= (match-string 1) "(")
+              ;; A pesky CL-style optional argument with default value,
+              ;; so let's skip over it
+              (search-backward "(")
+              (goto-char (scan-sexps (point) 1)))))
+        ;; Highlight aguments in the USE string
+        (setq use (help-do-arg-highlight (buffer-string) args)))
+      ;; Highlight arguments in the DOC string
+      (setq doc (and doc (help-do-arg-highlight doc args)))
+      (cons use doc))))
+
 ;;;###autoload
 (defun describe-function (function)
@@ -353,10 +390,14 @@
     (let* ((arglist (help-function-arglist def))
 	   (doc (documentation function))
-	   (usage (help-split-fundoc doc function)))
+	   (usage (help-highlight-arguments (help-split-fundoc doc function))))
       ;; If definition is a keymap, skip arglist note.
       (unless (keymapp def)
-	(princ (cond
+        (with-current-buffer standard-output
+          (insert (cond
 		(usage (setq doc (cdr usage)) (car usage))
-		((listp arglist) (help-make-usage function arglist))
+                    ((listp arglist)
+                     (setq doc (help-highlight-arguments (cons (format "%s" (help-make-usage function arglist))
+                                                               doc)))
+                     (prog1 (car doc) (setq doc (cdr doc))))
 		((stringp arglist) arglist)
 		;; Maybe the arglist is in the docstring of the alias.
@@ -367,10 +408,10 @@
 						 (documentation fun)
 						 function)))))
-		   usage)
+                       (setq usage (help-highlight-arguments usage)))
 		 (car usage))
  		((or (stringp def)
  		     (vectorp def))
 		 (format "\nMacro: %s" (format-kbd-macro def)))
-		(t "[Missing arglist.  Please make a bug report.]")))
+                    (t "[Missing arglist.  Please make a bug report.]"))))
 	(terpri))
       (let ((obsolete (and
@@ -387,5 +428,6 @@
 	  (terpri)))
       (terpri)
-      (princ (or doc "Not documented.")))))
+      (with-current-buffer standard-output
+        (insert (or doc "Not documented."))))))
 
 \f

Re: Improved help from minibuffer prompts

[Richard Stallman]

    BTW, my implementation does not grok yet CL-style "&optional (variable
    default)" arglists.  I'm working on it.

Emacs Lisp does not support them, and I believe it is better
not to add that feature.

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On Sat, 01 May 2004 13:51:44 -0400, Richard Stallman <rms@gnu.org> wrote:

> Emacs Lisp does not support them, and I believe it is better
> not to add that feature.

`defun*' is a macro in emacs-lisp/cl-macs.el which allows creating
defuns with (almost-)full CL-style arglists. In fact, there are at least
two modules in Emacs which already define functions with such arglists:

  net/quickurl.el: (quickurl, quickurl-read, quickurl-browse-url)
  progmodes/ebrowse.el: (ebrowse-draw-file-member-info)

There is also machinery (help-make-usage, from help-fns.el) to support
them in describe-function. So it's better if help-highlight-arguments
also supports them. Even if we were to expurge such functions from the
sources, the user can make use of defun*... I don't think we're going to
remove functionality from cl-macs.el, aren't we?

                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Stefan Monnier]

> The problem is, describe-function-1 is a big hairy function with a
> complex program flow.

Yes.  I'd just call it ugly.

> describe-function-1 uses princ to output data to the current buffer,

Yup and there's only one place where this happens, so despite the ugly
control flow there's clearly just one place where you can insert a call to
your function, knowing that the arglist has just been inserted at point.

Maybe the best way is not to call your new function right then and there.
Maybe it's better to just remember the buffer position of start&end of
arglist and do the highlighting later.

> All in all, I really doubt the result is easier to understand or
> maintain.

It's more robust since it does not assume the arglist is printed
and it does not make assumption about where it's printed, etc...

>  - No heuristics to determine what's a usage doc and what's simply doc.
>    OK, but the format of docs is something we control so we can be
>    reasonably sure it's working, and we can always adapt
>    help-highlight-arguments if necessary.

I'm reasonably sure I can already come up with an example where your
code ends up doing funny things.

>  - All functions that use describe-function-1 are automatically
>    highlighted.

Irrelevant indeed.


        Stefan

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 01 May 2004 16:23:07 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Yes.  I'd just call it ugly.

:)

> Yup and there's only one place where this happens, so despite the ugly
> control flow there's clearly just one place where you can insert a call to
> your function, knowing that the arglist has just been inserted at point.

Aha! Now I understand you. I don't know why I was looping over the idea
of getting hold of (usage . doc) at the point the docstring was splitted,
instead of at the point where usage is inserted...

Please try this (hopefully near-to-last) patch, and let's see what do
you think of it.

The change seems bigger than it is because I've opted to change all
`princ's and `terpri's of the last section of `describe-function-1' to
`insert's inside a big (with-current-buffer standard-output ...). It
seems cleaner than having

 (with-current-buffer standard-output
   (insert usage)
    ...))
 (princ ...)
 (terpri)
 (princ ...)
 (terpri)
 ...
 (terpri)
 (with-current-buffer standard-output
   (insert (or doc "No documentation available.")))

I'll be happy to do a refactoring of describe-function-1 some day,
splitting it into manageable chunks and doing all output through insert
(instead of the current mix insert/princ), but I don't think this is an
appropriate time, with the proposed freeze, etc.

Supposing help-highlight-arguments is accepted, I think the only things
left to do are deciding which face to use (I'm using a new
help-argument-name face which inherits from font-lock-variable-face, but
I have no real preference), and whether the argument highlighting should
be always on, or user-configurable. Again, no preference.

                                                           /L/e/k/t/u



Index: help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.41
diff -u -2 -r1.41 help-fns.el
--- help-fns.el	1 May 2004 13:52:53 -0000	1.41
+++ help-fns.el	2 May 2004 01:39:22 -0000
@@ -238,5 +238,42 @@
 	  file)))))
 
-;;;###autoload
+(defface help-argument-name '((t (:inherit font-lock-variable-name-face)))
+  "Face to highlight function arguments in docstrings.")
+
+(defun help-do-arg-highlight (doc args)
+  (while args
+    (let ((arg (prog1 (car args) (setq args (cdr args)))))
+      (setq doc (replace-regexp-in-string
+                 (concat "\\<\\(" arg "\\)\\(?:es\\|s\\)?\\>")
+                 (propertize arg 'face 'help-argument-name)
+                 doc t t 1))))
+  doc)
+
+(defun help-highlight-arguments (usage doc &rest args)
+  (when usage
+    (let ((case-fold-search nil)
+          (next (not args)))
+      ;; Make a list of all arguments
+      (with-temp-buffer
+        (insert usage)
+        (goto-char (point-min))
+        ;; Make a list of all arguments
+        (while next
+          (if (not (re-search-forward " \\([\\[(]?\\)\\([^] &)\.]+\\)" nil t))
+              (setq next nil)
+            (setq args (cons (match-string 2) args))
+            (when (string= (match-string 1) "(")
+              ;; A pesky CL-style optional argument with default value,
+              ;; so let's skip over it
+              (search-backward "(")
+              (goto-char (scan-sexps (point) 1)))))
+        ;; Highlight aguments in the USAGE string
+        (setq usage (help-do-arg-highlight (buffer-string) args)))
+      ;; Highlight arguments in the DOC string
+      (setq doc (and doc (help-do-arg-highlight doc args)))
+      ;; Return value is like the one from help-split-fundoc, but highlighted
+      (cons usage doc))))
+
+;;###autoload
 (defun describe-function-1 (function)
   (let* ((def (if (symbolp function)
@@ -354,38 +391,42 @@
 	   (doc (documentation function))
 	   (usage (help-split-fundoc doc function)))
-      ;; If definition is a keymap, skip arglist note.
-      (unless (keymapp def)
-	(princ (cond
-		(usage (setq doc (cdr usage)) (car usage))
-		((listp arglist) (help-make-usage function arglist))
-		((stringp arglist) arglist)
-		;; Maybe the arglist is in the docstring of the alias.
-		((let ((fun function))
-		   (while (and (symbolp fun)
-			       (setq fun (symbol-function fun))
-			       (not (setq usage (help-split-fundoc
-						 (documentation fun)
-						 function)))))
-		   usage)
-		 (car usage))
- 		((or (stringp def)
- 		     (vectorp def))
-		 (format "\nMacro: %s" (format-kbd-macro def)))
-		(t "[Missing arglist.  Please make a bug report.]")))
-	(terpri))
-      (let ((obsolete (and
-		       ;; function might be a lambda construct.
-		       (symbolp function)
-		       (get function 'byte-obsolete-info))))
-	(when obsolete
-	  (terpri)
-	  (princ "This function is obsolete")
-	  (if (nth 2 obsolete) (princ (format " since %s" (nth 2 obsolete))))
-	  (princ ";") (terpri)
-	  (princ (if (stringp (car obsolete)) (car obsolete)
-		   (format "use `%s' instead." (car obsolete))))
-	  (terpri)))
-      (terpri)
-      (princ (or doc "Not documented.")))))
+      (with-current-buffer standard-output
+        ;; If definition is a keymap, skip arglist note.
+        (unless (keymapp def)
+          (let* ((use (cond
+                        (usage (setq doc (cdr usage)) (car usage))
+                        ((listp arglist)
+                         (format "%S" (help-make-usage function arglist)))
+                        ((stringp arglist) arglist)
+                        ;; Maybe the arglist is in the docstring of the alias.
+                        ((let ((fun function))
+                           (while (and (symbolp fun)
+                                       (setq fun (symbol-function fun))
+                                       (not (setq usage (help-split-fundoc
+                                                         (documentation fun)
+                                                         function)))))
+                           usage)
+                         (car usage))
+                        ((or (stringp def)
+                             (vectorp def))
+                         (format "\nMacro: %s" (format-kbd-macro def)))
+                        (t "[Missing arglist.  Please make a bug report.]")))
+                 (high (help-highlight-arguments use doc)))
+            (insert (car high) "\n")
+            (setq doc (cdr high))))
+        (let ((obsolete (and
+                         ;; function might be a lambda construct.
+                         (symbolp function)
+                         (get function 'byte-obsolete-info))))
+          (when obsolete
+            (princ "\nThis function is obsolete")
+            (when (nth 2 obsolete)
+              (insert (format " since %s" (nth 2 obsolete))))
+            (insert ";\n"
+                    (if (stringp (car obsolete)) (car obsolete)
+                      (format "use `%s' instead." (car obsolete)))
+                    "\n"))
+          (insert "\n"
+                  (or doc "Not documented.")))))))
 
 \f

Re: Improved help from minibuffer prompts

[Richard Stallman]

    `defun*' is a macro in emacs-lisp/cl-macs.el which allows creating
    defuns with (almost-)full CL-style arglists.

We don't consider CL as an official part of Emacs.

     In fact, there are at least
    two modules in Emacs which already define functions with such arglists:

      net/quickurl.el: (quickurl, quickurl-read, quickurl-browse-url)
      progmodes/ebrowse.el: (ebrowse-draw-file-member-info)

It might be a mistake to use defun* to define functions that are
advertised for Emacs, simply because it is misleading to use an
arglist syntax that isn't the usual Emacs syntax.  Also, it is
inconsistent with normal Emacs practice to have arguments whose
default value is not nil.  So I think we should change these
functions.

    There is also machinery (help-make-usage, from help-fns.el) to support
    them in describe-function. So it's better if help-highlight-arguments
    also supports them. Even if we were to expurge such functions from the
    sources, the user can make use of defun*...

Ok, I see no harm in having that machinery in case users use CL
to define such functions.

Will someone else offer to change quickurl, etc?

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On Sun, 02 May 2004 15:52:05 -0400, Richard Stallman <rms@gnu.org> wrote:

> We don't consider CL as an official part of Emacs.

I'm not sure what do you mean by "official". It's included with Emacs
since long ago, and also in XEmacs, and it's used by third-party code 
(at least, macros are). I know you object to it being loaded by modules
(although I'm not sure I believe in the namespace pollution issue, given
that XEmacs loads it by default), but in my view is as official as VC or
Calendar.

> Ok, I see no harm in having that machinery in case users use CL
> to define such functions.

Great.

> Will someone else offer to change quickurl, etc?

I can take a look.


                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Richard Stallman]

The CL features are not an official part of Emacs Lisp.
People can load CL and use it, but you don't need to know
anything about CL to do Emacs Lisp programming, and the
CL function names are not reserved.

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On Sun, 02 May 2004 03:52:48 +0200, Juanma Barranquero <lektu@mi.madritel.es> wrote:

> [...] I think the only things
> left to do are deciding which face to use (I'm using a new
> help-argument-name face which inherits from font-lock-variable-face, but
> I have no real preference), and whether the argument highlighting should
> be always on, or user-configurable. Again, no preference.

What I said.

I've now installed the change so everybody can try it by h??self.
There's no direct way to deactivate it right now, but is easy enough by
setting the help-argument-name face to default.

I've been using this patch for several days and it works fine. There's a
little problem with docstrings like the one for define-key, because they
use:

 (define-key KEYMAP KEY DEF)

and, in the description below:

 or a cons (KEYMAP . CHAR), meaning use definition of CHAR in map KEYMAP

This second KEYMAP gets highlighted because it's also an argument, even
if the docstring is using KEYMAP also to define a part of another
argument (DEF, in this case). IMO, this is an ambiguity in such
docstrings and should be fixed.

                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Richard Stallman]

    and, in the description below:

     or a cons (KEYMAP . CHAR), meaning use definition of CHAR in map KEYMAP

    This second KEYMAP gets highlighted because it's also an argument, even
    if the docstring is using KEYMAP also to define a part of another
    argument (DEF, in this case). IMO, this is an ambiguity in such
    docstrings and should be fixed.

I agree, that metavariable should be renamed.
If people want to make such changes, that would be useful.

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On Tue, 04 May 2004 16:07:58 -0400, Richard Stallman <rms@gnu.org> wrote:

> I agree, that metavariable should be renamed.
> If people want to make such changes, that would be useful.

I'll fix them as I find them.

But there are cases, like the one shown, that it's necessary to look at
once at the docstrings of a bunch of functions, to maintain consistency
among them.

                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On Sun, 02 May 2004 15:52:05 -0400, Richard Stallman <rms@gnu.org> wrote:

> Will someone else offer to change quickurl, etc?

Changing uses of &optional (var default) is easy enough, but, what about
"defun*"s or "defmacro*"s that use &key args?

There are a few:

 pcvs.el           (cvs-cmd-do, cvs-mode-marked, cvs-mode-run,
                    cvs-mode-do)
 progmodes/ebrowse (ebrowse-view/find-class-declaration,
                    ebrowse-tags-view/find-member-decl/defn)
 ibuf-macs.el      (define-ibuffer-column, define-ibuffer-sorter,
                    define-ibuffer-op, define-ibuffer-filter)

And functions that use defun* to be able to return-from?

 mh-e/mh-index     (mh-index-search)
 progmodes/ebrowse (ebrowse-marked-classes-p)

etc.

It seems like much change for no gain...

                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Stefan Monnier]

>> Will someone else offer to change quickurl, etc?

> Changing uses of &optional (var default) is easy enough, but, what about
> "defun*"s or "defmacro*"s that use &key args?

Please don't change those functions which are internal to a package.


        Stefan

Re: Improved help from minibuffer prompts

[Richard Stallman]

    Changing uses of &optional (var default) is easy enough, but, what about
    "defun*"s or "defmacro*"s that use &key args?

Using defun* is not in itself a problem.  Using keyword args
would be somewhat strange in the Help buffer since it will
show syntax that is not meaningful in Emacs Lisp, but if
users don't get confused by this, it isn't a problem.

The specific problem I want to avoid is arguments whose
default is not nil; that is to say, for which omitting an arg
is not equivalent to using nil for it.

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 06 May 2004 10:13:29 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Please don't change those functions which are internal to a package.

I'm a Common Lisp and cl*.el fan. I'd rather not change any of them.

That's why I'm asking. I want confirmation about which ones, if any,
should be changed.

                                                           /L/e/k/t/u

Re: Improved help from minibuffer prompts

[Juanma Barranquero]

On 06 May 2004 10:13:29 -0400, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Please don't change those functions which are internal to a package.

Is cvs-mode-run internal? (I think so.)

More questions about docstrings:

 - Is internal ebrowse-draw-file-member-info? (BTW, I don't understand
   the docstring:

   "Display a line in an the members per file info buffer.  [...]"

 - cvs-mode-marked doesn't document keyword argument noquery. Should it?

 - cvs-mode-do doesn't document keyword argument postproc.

 - insert-buffer-substring (and -as-yank, -no-properties) refer to START
   and END with:

   "Arguments START and END are character numbers specifying the substring."

   but "character numbers" is not an usual Emacs terminology.


                                                           /L/e/k/t/u