Re: Community improvements to the Emacs Widget Library manual?

[Bryce <bovine@cyberscientist.ca>]

Mauro Aranda <maurooaranda@gmail.com> writes:

> Bryce Carson <bovine@cyberscientist.ca> writes:
>
>  > I searched and read the Customize mailing list. It has more spam than it
>  > does messages from Custom.el or Widget.el users.
>
> I didn't know about that mailing list.  I don't feel like it's relevant
> as of today.

It is definitely defunct. I wanted to find some help for using Widget,
so I began subscribing to all sorts of mailing lists related to Emacs
and Lisp with Thunderbird. At the moment I am attempting to get
comfortable with Rmail, but I need to send a message to the Emacs Help
list for an issue I'm having with it (feel free to read it there! I'm
just letting you know that getting up to speed with how mailing lists
work is one of the reasons I haven't replied sooner).

>  > Would anyone like to collaborate to improve The Emacs Widget Library
>  > manual? Are there any active Emacs Lisp hackers that actually
>  > understand this library at a deep level?
>
> I do think I understand it quite a bit.  I've fixed some bugs, in the
> code and in the documentation, and I have some techniques for debugging
> the code which sometimes turns out to be a mess of nested widgets
> creation.

I'd love to hear about that debugging technique. Twice I've witnessed
debug (not edebug) get itself into a circle of evaluating the commands
that pertain to evaluating commands that pertain to evaluating
commands... sorry, I'm sure you understand. Do you know if that may have
had anything to do with Widget's recursive bits? I am not good at using
the debugger, I could do with more practice.

I let debug walk into a recursive loop when trying to debug an error
which occured when I wanted to save the value of a custom variable using
the widget type I defined. (I settled on _merely_ defining a custom type
and using Customize to handle all user interaction for my application,
rather than setting up a buffer using Widgets myself and managing
_everything_).

If I encounter the same error (I have shiny new ones now) I will ask for
specific help resolving it.

> And sure, I'd love to collaborate on improving the documentation, be it
> the info manual that gets shipped with Emacs or with tutorials about how
> to use it to get the most out of it, without starting to hate the
> library.

I'd like to see as much as possible end up in the Widget manual itself.
The manuals that ship with Emacs for some modes are gargantuan, there is
no reason other than politics to not ship any tutorials we write (if
they are quality).

The most one could get out of the library is making a Widgetry RAD
(WidgeTRY™?), I imagine. I can see the possibility for that when I read
the manual and consider the command/event loop of Emacs, and the global
keymap mentioned in the manual.

>  > I'm writing a package using the library, and I'm still quite lost while
>  > reading the manual. It's been days that I've spent with the manual, so it is
>  > not one or two quick readings. I have studied it, yet I am bewildered at
>  > times.
>
> I'm absolutely willing to help.  If you have the code somewhere, or if
> you want to tell me what are the things you're finding difficult, I can
> try to help you out.  And maybe that can give me some ideas about what
> to improve in the Widget documentation.

I haven't made any code public yet because I am still deciding on how I
want to publish it. I may provide the code on my GitHub, or I might
provide it on my personal website to churn up some traffic.

The biggest issue I've had with the library is creating a working SEXP
widget. I wanted to match _any_ symoblic expression that would create an
object of a specific type (using :validate). I have settled on something
much more reasonable (a choice-menu) instead, especially while I dogfood
and bootstrap the application.

The application is a literate programming interface. It's closing in on
0.1.0, but because I am writing the interface using Noweb (I am writing
it literately) it is taking longer, because I am nothing more than a
would-be acolyte of LaTeX. I will ask for help soon once I have a
specific question; before I was not making any notes of errors or where
the project was at, and I also lost some Git history of the project due
to accidentally deleteing it (however, I recovered it with some handy
libre software; I can recall the amusing story, if wanted, but don't
fret I aliased rm to remind me to use trash instead).

>  > One aspect that is confusing is widget definition with widget-specific
>  > argument handling. Built-in widgets handle arguments after the
>  > keyword-value pairs in widget-specific ways. How do end users create
>  > such behaviour in their own widgets? The answer is a function value for
>  > the widget-create keyword, but this is a difficult thing to implement.
>
> Please tell more about the difficulties you have encountered. If you
> can show a piece of code to show what you expected and what really
> happens, then better yet.

I responded to Michael in detail concerning :widget-create and the
handling of further (non-keyword) arguments.

To quote the library,

    | This is the general syntax of a type specification:
    |
    |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
    |           |   NAME
    |
    |    Where, NAME is a widget name, KEYWORD is the name of a
    | property, ARGUMENT is the value of the property, and ARGS are
    | interpreted in a widget specific way.

ARGS in the general type specification is not one of the pairs of
:keyword value pairs, it is anything else. I forget where it is stated,
but I believe the manual says that any non-keyword value pair arguments
must follow the pairs (if any pairs exist). How to define the handling
of such ARGS in a custom widget is never exampled in the manual; it
certainly isn't a simple (widget-args) function call away.

When replying to Michael, I gave the example of the ITEM widget, which
doesn't handle any of the §5 keyword arguments in a special way, but
will initialize :value on behalf of the user with VALUE (see §5.9).

The description of the ITEM widget, while on the topic, should probably
be expanded to elaborate on what last sentence means. When matching
against widgets, is a (widget-find type) function being used? It would
be nice if there was a Widget Object Model, where all widgets are rooted
in the buffer they belong to, but that's a lofty, far off goal like a
WidgeTRY™ RAD for the Emacs Widget Library.

>  > The Emacs Widget Library manual could use a re-write [...]
>
> I'm not sure about a re-write.  But yes, I feel like there's more room
> for improvement.  And count me in as one possible collaborator to
> improve it.

Great! I hope the possibility is realized.

Considering the age of the library (twenty-three years! [if the
earlier copyright year is correct]), and the support for embedded
graphics like GTK+ widgets (so far only WebkitGTK…) _has_ improved,
perhaps this statement could be removed or edited in some way? At least
the part about the _automatic_ improvement in graphical appearance. I
feel like that is not correct, but I could easily be wrong (if these are
merely _goals_ for the library, not the state of affairs).

    7. As support for embedded graphics improve, the widget library will
       be extended to use the GUI features.  This means that your code
       using the widget library will also use the new graphic features
       automatically.