all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Re: Community improvements to the Emacs Widget Library manual?
@ 2023-07-09 12:17 Mauro Aranda
  2023-07-09 14:59 ` [External] : " Drew Adams
  2023-07-12  4:07 ` Bryce
  0 siblings, 2 replies; 35+ messages in thread
From: Mauro Aranda @ 2023-07-09 12:17 UTC (permalink / raw)
  To: Bryce Carson; +Cc: emacs-devel

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.




^ permalink raw reply	[flat|nested] 35+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
@ 2023-07-12 11:43 Mauro Aranda
  2023-07-12 20:17 ` Bryce
  2023-07-14  6:32 ` Bryce Carson
  0 siblings, 2 replies; 35+ messages in thread
From: Mauro Aranda @ 2023-07-12 11:43 UTC (permalink / raw)
  To: Bryce Carson; +Cc: emacs-devel

Bryce <bovine@cyberscientist.ca> writes:

 > An example of something that would make a good edition, not a tutorial
 > or example, is indicating in §5.12 (info "(widget)checkbox") that the
 > :format value must contain %[ %], to "buttonize" the checkbox (otherwise
 > you cannot interact with it).

I think that's clear from the :format description.  %[ and %] are the
first escapes described.

What might need to be added is the default value for the :format in
most described widgets.  That way, it's more clear that if you override
the :format value, it is your responsibility to add %[ and %] around
whatever text you want.





^ permalink raw reply	[flat|nested] 35+ messages in thread
* Community improvements to the Emacs Widget Library manual?
@ 2023-07-08 20:18 Bryce Carson
  2023-07-09  5:26 ` Eli Zaretskii
                   ` (2 more replies)
  0 siblings, 3 replies; 35+ messages in thread
From: Bryce Carson @ 2023-07-08 20:18 UTC (permalink / raw)
  To: emacs-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 35+ messages in thread

end of thread, other threads:[~2023-07-24 11:37 UTC | newest]

Thread overview: 35+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-07-09 12:17 Community improvements to the Emacs Widget Library manual? Mauro Aranda
2023-07-09 14:59 ` [External] : " Drew Adams
2023-07-09 23: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
  -- strict thread matches above, loose matches on Subject: below --
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
2023-07-08 20:18 Bryce Carson
2023-07-09  5:26 ` 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-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

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.