Getting help for a widget

Getting help for a widget

[Lennart Borgman]

I think it is too difficult to get help for a widget. As an example try 
`recent-open-files'. This will create a buffer where each file is shown 
with a widget. If you press

    C-h k

on a file you get help for `widget-button-press'. But what does the 
button do? Do find out this you have to know there is an interactive 
function you can use:

    M-x widget-browse-at

I would suggest for now that `widget-button-press' mentions this. Maybe 
it is also simple enough to make the :action in the *Browse Widget* 
buffer a help-link?

After the release I would suggest that help for widgets are enhanced.

RE: Getting help for a widget

[Drew Adams]

    I think it is too difficult to get help for a widget.

Amen!

This is perhaps the main difficulty of working with or even talking about
widgets (and, so, with Customize too) as either a user or a casual
developer: understanding what the &^!@% is going on. It is different from
the rest of Emacs, where you can start with, say, `C-h k' and drill down
easily to see exactly what is happening at any level of detail (and perhaps
modify the behavior).

In a word, Widget World is opaque, at least to the uninitiated (which I
think is 99.999% of us). I doubt there's much that can be done about that
without an overhaul, but I could be wrong - after all, I can't figure it
out!

If the code could be more transparent or user-friendly, that would be great.
If not, how about a tutorial or a Widget-World map?

Re: Getting help for a widget

[Richard Stallman]

    This is perhaps the main difficulty of working with or even talking about
    widgets (and, so, with Customize too) as either a user or a casual
    developer: understanding what the &^!@% is going on.

I agree.  I find it very hard to understand that code.

But what does it mean to "get help for a widget"?
It is not clear to me, and maybe there is more than one
kind we need.

    If you press

	C-h k

    on a file you get help for `widget-button-press'. But what does the 
    button do?

I don't really follow that, but it seems to be a request
for a better answer to the question, "What happens if i click here"?

That could be useful, and perhaps C-h k ought to make a special
case for the function widget-button-press.  That would not be hard.
But where can it get the useful doc string to display?

Meanwhile, this would not help people who are doing programming with
widgets.  They need a different kind of help.

In other words, it will take some real thought and study to figure out
what "good help for widgets" would mean.  It would be useful for
people to start exploring this now.

Re: Getting help for a widget

[Lennart Borgman]

Richard Stallman wrote:
>     This is perhaps the main difficulty of working with or even talking about
>     widgets (and, so, with Customize too) as either a user or a casual
>     developer: understanding what the &^!@% is going on.
>
> I agree.  I find it very hard to understand that code.
>
> But what does it mean to "get help for a widget"?
> It is not clear to me, and maybe there is more than one
> kind we need.
>
>     If you press
>
> 	C-h k
>
>     on a file you get help for `widget-button-press'. But what does the 
>     button do?
>
> I don't really follow that, but it seems to be a request
> for a better answer to the question, "What happens if i click here"?
>
> That could be useful, and perhaps C-h k ought to make a special
> case for the function widget-button-press.  That would not be hard.
> But where can it get the useful doc string to display?
>
> Meanwhile, this would not help people who are doing programming with
> widgets.  They need a different kind of help.
>
> In other words, it will take some real thought and study to figure out
> what "good help for widgets" would mean.  It would be useful for
> people to start exploring this now.
>   

As a little starter the two functions below can be used. The first one 
is new. Pub point over a widget or button and do

    M-x describe-field

This will open the widget browser. Badly needed in this are back and 
forward buttons (widgets of course ;-). Also badly needed IMHO are links 
to where widget-create are called. Can anyone explain how to add this? 
The information is available to the debugger, but is there a fast and 
simple way to get this information in `widget-create'?

The second function just makes links out of descriptions that are 
function names.

(defun describe-field(pos &optional use-mouse-action)
  (interactive (list (point)))
  ;; widget-browse-at
  (let* ((field (get-char-property pos 'field))
     (wbutton (get-char-property pos 'button))
     (doc (get-char-property pos 'widget-doc))
     (widget (or field wbutton doc)))
    ;;(message "widget=%s" widget)(sit-for 1)
    (if (and widget
             (if (symbolp widget)
                 (get widget 'widget-type)
               (and (consp widget)
                    (get (widget-type widget) 'widget-type))))
        (widget-browse-at pos)
      ;; push-button
      (let ((button (button-at pos)))
        ;;(message "button=%s" button)(sit-for 1)
        (if button
            (let ((action (or (and use-mouse-action
                                   (button-get button 'mouse-action))
                              (button-get button 'action))))
              (message "action=%s" action)(sit-for 1)
              (describe-function (intern-soft action)))
          (message "No widget or button at point"))))))

(defun widget-browse-sexp (widget key value)
  "Insert description of WIDGET's KEY VALUE.
Nothing is assumed about value."
  (let ((pp (condition-case signal
        (pp-to-string value)
          (error (prin1-to-string signal)))))
    (when (string-match "\n\\'" pp)
      (setq pp (substring pp 0 (1- (length pp)))))
    (if (cond ((string-match "\n" pp)
           nil)
          ((> (length pp) (- (window-width) (current-column)))
           nil)
          (t t))
        (progn
          ;;(message "pp=<%s>" pp) (sit-for 1)
          (let ((pp-sym (intern-soft pp)))
          (if (and pp-sym
                   (fboundp pp-sym))
              (widget-create 'push-button
                             :tag pp
                             :value pp
                             :action '(lambda (widget &optional event)
                                        (let ((pp-symf (intern-soft 
(widget-get widget :value))))
                                          (describe-function pp-symf)))
                             pp)
            (widget-insert pp))))
      (widget-create 'push-button
             :tag "show"
             :action (lambda (widget &optional event)
                   (with-output-to-temp-buffer
                   "*Pp Eval Output*"
                 (princ (widget-get widget :value))))
             pp))))

RE: Getting help for a widget

[Drew Adams]

    As a little starter the two functions below can be used. The first one
    is new. Pub point over a widget or button and do M-x describe-field
    This will open the widget browser.

That's an interesting beginning of a widget browser. What I was thinking of
was a way to get to the appropriate part of the widget (or customize) Lisp
code that carries out the action when you click a widget button.

IOW, with a menu item, mouse click or keyboard sequence, I can use `C-h k'
and then click on the *Help* buffer command-name link to get to the
command's source code. I'd like to be able to do that with a widget button
also.

Another problem is of course that even if you arrive at the code that
carries out the button action it is difficult to understand what's going on.
Things are much simpler in widgetless code: get to a command definition;
read its code; read the code of the functions it calls - clear as a bell
usually.

Re: Getting help for a widget

[Richard Stallman]

I tried describe-field.  It seems useful.

Does a widget class have a doc string?  If so, showing the doc string
would make it more useful.

Re: Getting help for a widget

[Lennart Borgman]

Richard Stallman wrote:
> I tried describe-field.  It seems useful.
>
> Does a widget class have a doc string?  If so, showing the doc string
> would make it more useful.
>   
I am trying to make this a bit more useful. I am not ready yet, but if 
someone is interested then there is a bit of this in the file whelp.el at

    http://ourcomments.org/Emacs/DL/elisp/test/

Re: Getting help for a widget

[Lennart Borgman]

Lennart Borgman wrote:
> Richard Stallman wrote:
>> I tried describe-field.  It seems useful.
>>
>> Does a widget class have a doc string?  If so, showing the doc string
>> would make it more useful.
>>   
> I am trying to make this a bit more useful. I am not ready yet, but if 
> someone is interested then there is a bit of this in the file whelp.el at
>
>    http://ourcomments.org/Emacs/DL/elisp/test/

I think this is ready for testing now. So please, if you are interested 
in how and where widgets and buttons are implemented, then test this. I 
need some feedback, of course.

Unfortunately in this stage of the testing it is not possible to collect 
information on where a button or widget type is defined since this is 
done before the module above is loaded now. (I have also not added 
collecting of this information to the functions that creates button 
objects yet.)