Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

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.

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

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'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.

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

> TL;DR:
>
> The Emacs Widget Library manual could use a re-write, preferably
> following the Diataxis documentation framework if possible. Does
> anyone want to collaborate over the long-term, creating a study group
> and editing the manual to a high standard to benefit the community and
> ourselves?

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.