Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

Multiple readings of the manual, and also the Customization Types section of the Emacs Lisp manual, are a requirement. The library isn't easy to use, which is not it's fault. It hides incredible power. However, the library's manual could use improvement.

I searched and read the Customize mailing list. It has more spam than it does messages from Custom.el or Widget.el users.

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? Every non-trivial example I've seen in other source code is poorly commented, which I think is a reflection of frustrated hackers simply wanting to get away from that library because they've finally managed to get it to work and don't want to think about it anymore.

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.

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.

---

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?

Regards,

An ape riding a gnu.