From: Bryce Carson <bovine@cyberscientist.ca>
To: emacs-devel@gnu.org
Subject: Community improvements to the Emacs Widget Library manual?
Date: Sat, 8 Jul 2023 14:18:21 -0600 [thread overview]
Message-ID: <1e042c59-9baf-ee4f-4726-26aba36847d4@cyberscientist.ca> (raw)
[-- Attachment #1: Type: text/plain, Size: 1746 bytes --]
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.
[-- Attachment #2: Type: text/html, Size: 2115 bytes --]
next reply other threads:[~2023-07-08 20:18 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-08 20:18 Bryce Carson [this message]
2023-07-09 5:26 ` Community improvements to the Emacs Widget Library manual? Eli Zaretskii
2023-07-09 12:02 ` Mauro Aranda
2023-07-09 12:16 ` Eli Zaretskii
2023-07-11 0:52 ` Bryce
2023-07-12 12:30 ` Eli Zaretskii
2023-07-12 16:42 ` Corwin Brust
2023-07-13 23:05 ` Bryce Carson
2023-07-13 23:27 ` [External] : " Drew Adams
2023-07-13 23:57 ` Bryce Carson
2023-07-10 3:38 ` Michael Heerdegen
2023-07-11 23:17 ` Bryce
2023-07-12 5:18 ` Michael Heerdegen
2023-07-12 7:21 ` Bryce
2023-07-13 2:59 ` Michael Heerdegen
2023-07-11 11:04 ` Kjartan Oli Agustsson
2023-07-14 2:02 ` Richard Stallman
2023-07-14 5:28 ` Bryce Carson
-- strict thread matches above, loose matches on Subject: below --
2023-07-09 12:17 Mauro Aranda
2023-07-12 4:07 ` Bryce
2023-07-12 11:34 ` Mauro Aranda
2023-07-13 3:30 ` Michael Heerdegen
2023-07-23 23:06 ` Bryce
2023-07-24 11:37 ` Eli Zaretskii
2023-07-12 11:43 Mauro Aranda
2023-07-12 20:17 ` Bryce
2023-07-14 6:32 ` Bryce Carson
2023-07-14 6:52 ` Bryce Carson
2023-07-14 6:56 ` Bryce Carson
2023-07-14 6:59 ` Bryce Carson
2023-07-14 7:07 ` Bryce Carson
2023-07-14 14:41 ` Mauro Aranda
2023-07-14 18:50 ` bovine
2023-07-15 0:08 ` Mauro Aranda
2023-07-14 10:48 ` Mauro Aranda
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1e042c59-9baf-ee4f-4726-26aba36847d4@cyberscientist.ca \
--to=bovine@cyberscientist.ca \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.