* 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; 20+ 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] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-08 20:18 Community improvements to the Emacs Widget Library manual? Bryce Carson
@ 2023-07-09 5:26 ` Eli Zaretskii
2023-07-09 12:02 ` Mauro Aranda
2023-07-11 0:52 ` Bryce
2023-07-10 3:38 ` Michael Heerdegen
2023-07-11 11:04 ` Kjartan Oli Agustsson
2 siblings, 2 replies; 20+ messages in thread
From: Eli Zaretskii @ 2023-07-09 5:26 UTC (permalink / raw)
To: Bryce Carson, Mauro Aranda; +Cc: emacs-devel
> Date: Sat, 8 Jul 2023 14:18:21 -0600
> From: Bryce Carson <bovine@cyberscientist.ca>
>
> 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 think Mauro (CC'ed) is our widget expert.
> 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 don't think I understand the plan in this aspect. If important
information is missing from the manual, it can and should be added.
If you want to add tutorial-style sections, that could also be a good
idea, provided that the subject is so complex that reading the main
description is too hard without first reading a tutorial introduction.
If this is what you mean here, it is, of course, very welcome. But
the general idea of the existing manual, which is to describe both the
user-facing UI and the Lisp-level reference, is correct, IMO.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
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
1 sibling, 1 reply; 20+ messages in thread
From: Mauro Aranda @ 2023-07-09 12:02 UTC (permalink / raw)
To: Eli Zaretskii, Bryce Carson; +Cc: emacs-devel
Eli Zaretskii <eliz@gnu.org> writes:
>> Date: Sat, 8 Jul 2023 14:18:21 -0600
>> From: Bryce Carson <bovine@cyberscientist.ca>
>>
>> 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 think Mauro (CC'ed) is our widget expert.
Thank you for CCing me, Eli, although I'm pretty sure I'm far from an
expert.
>> 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 don't think I understand the plan in this aspect. If important
> information is missing from the manual, it can and should be added.
> If you want to add tutorial-style sections, that could also be a good
> idea, provided that the subject is so complex that reading the main
> description is too hard without first reading a tutorial introduction.
I think the manual lacks more information about how to do more
"advanced" stuff. It's not hard, but I feel like some ideas about
what one can do with widgets only pop up after reading the code. Which
of course is really useful, but the manual could do a better job so it
isn't as required as of now.
That would fall in the category of adding tutorial-style sections, I
think. I'd love to help with that, but I don't have much time available
to do it on my own.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-09 12:02 ` Mauro Aranda
@ 2023-07-09 12:16 ` Eli Zaretskii
0 siblings, 0 replies; 20+ messages in thread
From: Eli Zaretskii @ 2023-07-09 12:16 UTC (permalink / raw)
To: Mauro Aranda; +Cc: bovine, emacs-devel
> Date: Sun, 9 Jul 2023 09:02:38 -0300
> Cc: emacs-devel@gnu.org
> From: Mauro Aranda <maurooaranda@gmail.com>
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> > I think Mauro (CC'ed) is our widget expert.
>
> Thank you for CCing me, Eli, although I'm pretty sure I'm far from an
> expert.
Well, as the quotation from one immortal movie goes, you are an expert
"compared to some". Certainly compared to myself.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-09 5:26 ` Eli Zaretskii
2023-07-09 12:02 ` Mauro Aranda
@ 2023-07-11 0:52 ` Bryce
2023-07-12 12:30 ` Eli Zaretskii
1 sibling, 1 reply; 20+ messages in thread
From: Bryce @ 2023-07-11 0:52 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: maurooaranda, emacs-devel
>> Date: Sat, 8 Jul 2023 14:18:21 -0600 From: Bryce Carson
>> <bovine@cyberscientist.ca>
>>
>> The Emacs Widget Library manual could use a re-write, preferably
>> following the Diataxis documentation framework if possible.
> I don't think I understand the plan in this aspect.
I don't have plans for the manual, not really. I pondered the draft of
the message I sent for two or three nights, but I was never satisfied
with how I asked about the library's manual. I spoke quickly, especially
in regard re-writing the manual in some given prescribed documentation
style.
In some ways, I expected others to be as frustrated with the library as
I was becoming, and as presumably frustrated as the authors of the
poorly commented code that I have read which uses the library.
The manual as a whole certainly does not need to be re-written. It is
useful, and I have learned how to use the library at a fundamental level
from it.
> If important information is missing from the manual, it can and should
> be added.
There are definite improvements to be made through editing, I believe.
For the amount of code behind the library, it has a small amount of
documentation compared to other areas of Emacs. It could be considerably
longer, in my opionion.
> If you want to add tutorial-style sections, that could also be a good
> idea, provided that the subject is so complex that reading the main
> description is too hard without first reading a tutorial introduction.
Should any tutorial content, inserted or appended to the manual, only
cover content that would likewise be too complex to understand? Would
example content be more appropriate in cases where the manual may not be
clear in some reader's opinions? Would further tutorial content (like
the example in §2 and §3) be rejected for being too simple or
"long-winded"?
I have spent a lot of time with the manual, but I find it a bit awkward
when I want to know how to do something and the reference is less than
exhaustive and doesn't have an example of the proper usage. It begs a
lot of inferences that I find make using the library more difficult than
it needs to be. Perhaps the library's documentation begets users that
are a tad more self-sufficient and exploratory than I, but I've been
using it some time in the project I'm working on. That's why I may have
been bold enough to speak quickly and say it "The Emacs Widget Library
manual could use a re-write". Diataxis is something I recently learned
of, and I figured it would be a good application to the various
objectives I was considering (What's the syntax of Z widget type? How do
I…? Why X? What is Y?).
> If this is what you mean here, it is, of course, very welcome.
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 became a bit paranoid after writing the above paragraph. I read over
the manual again. There is no explicit mention that for _any_ button
field, it should contain the same escape codes in it's :format value. I
used the Widget Browser tool as a sanity check, and lo that it would
show that each of the "button" types is formatted like this.
> But the general idea of the existing manual, which is to describe both
> the user-facing UI and the Lisp-level reference, is correct, IMO.
Are you referring to something other than the Customize interface in
this sentence? If so, I'm confused by the reference unless you're
talking about a developer's experience with the library (DX?). As a Lisp
library reference it is fine, mostly. I have some opinions on it, but
I'll talk that over with Mauro.
\f
I'm new to mailing lists, and I'm trying to participate as best I can.
Let me know if some parts of my reply would've been better–formatted in
another way or if I'm not as courteous as I could be.
Regards,
Bryce.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-11 0:52 ` Bryce
@ 2023-07-12 12:30 ` Eli Zaretskii
2023-07-12 16:42 ` Corwin Brust
0 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2023-07-12 12:30 UTC (permalink / raw)
To: Bryce; +Cc: maurooaranda, emacs-devel
> From: Bryce <bovine@cyberscientist.ca>
> Cc: maurooaranda@gmail.com, emacs-devel@gnu.org
> Date: Mon, 10 Jul 2023 18:52:59 -0600
>
> > If you want to add tutorial-style sections, that could also be a good
> > idea, provided that the subject is so complex that reading the main
> > description is too hard without first reading a tutorial introduction.
>
> Should any tutorial content, inserted or appended to the manual, only
> cover content that would likewise be too complex to understand? Would
> example content be more appropriate in cases where the manual may not be
> clear in some reader's opinions? Would further tutorial content (like
> the example in §2 and §3) be rejected for being too simple or
> "long-winded"?
I don't know the answers, and probably won't know until I see a
proposal for adding such a tutorial. The devil is in the details!
> Diataxis is something I recently learned of, and I figured it would
> be a good application to the various objectives I was considering
> (What's the syntax of Z widget type? How do I…? Why X? What is Y?).
A good manual should answer all those questions, yes.
> > But the general idea of the existing manual, which is to describe both
> > the user-facing UI and the Lisp-level reference, is correct, IMO.
>
> Are you referring to something other than the Customize interface in
> this sentence?
I refer to the fact that the manual has a chapter names "User
Interface", which describes how widgets look and are used, and it also
has chapters that describe how to program widgets.
> I'm new to mailing lists, and I'm trying to participate as best I can.
> Let me know if some parts of my reply would've been better–formatted in
> another way or if I'm not as courteous as I could be.
I see absolutely no problems with your responses.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-12 12:30 ` Eli Zaretskii
@ 2023-07-12 16:42 ` Corwin Brust
2023-07-13 23:05 ` Bryce Carson
0 siblings, 1 reply; 20+ messages in thread
From: Corwin Brust @ 2023-07-12 16:42 UTC (permalink / raw)
To: Bryce; +Cc: maurooaranda, emacs-devel
Thanks for your interest and work on this!
On Wed, Jul 12, 2023 at 7:30 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
>
> > I'm new to mailing lists, and I'm trying to participate as best I can.
> > Let me know if some parts of my reply would've been better–formatted in
> > another way or if I'm not as courteous as I could be.
>
> I see absolutely no problems with your responses.
As someone who's been following the list for some time now (who often
doubts the value of my own messages sent here): I think you are doing
great!
I too will be happy to help. I suspect my experience level is similar
to others': I have generally been able to make customize do what I
wished, but I've struggled to do it and wondered how to make it easier
to understand/use.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-12 16:42 ` Corwin Brust
@ 2023-07-13 23:05 ` Bryce Carson
2023-07-13 23:27 ` [External] : " Drew Adams
0 siblings, 1 reply; 20+ messages in thread
From: Bryce Carson @ 2023-07-13 23:05 UTC (permalink / raw)
To: emacs-devel
[-- Attachment #1: Type: text/plain, Size: 2712 bytes --]
On 7/12/23 10:42, Corwin Brust wrote:
> Thanks for your interest and work on this!
>
> On Wed, Jul 12, 2023 at 7:30 AM Eli Zaretskii<eliz@gnu.org> wrote:
>>> I'm new to mailing lists, and I'm trying to participate as best I can.
>>> Let me know if some parts of my reply would've been better–formatted in
>>> another way or if I'm not as courteous as I could be.
>> I see absolutely no problems with your responses.
> As someone who's been following the list for some time now (who often
> doubts the value of my own messages sent here): I think you are doing
> great!
I'm fairly confused because I haven't used Email in this way before. I
have always used it in a conversational, threaded manner that the Gmail
web client has always handled in a particular way (quoting entire
threads and only prepending new content.
I like this "literate" style, however, with more quotations and
different levels thereof.
On 7/12/23 10:42, Corwin Brust wrote:
> I too will be happy to help. I suspect my experience level is similar
> to others': I have generally been able to make customize do what I
> wished, but I've struggled to do it and wondered how to make it easier
> to understand/use.
I'm not sure if I'm managing my email incorrectly, or using the mailing
list in a weird way.
I did accidentally send out multiple copies of draft replies I had
saved; I had a rough start with Rmail and my mail server on my web host,
but it's working properly now.
At the moment, I'm experiencing an effect where I receive two copies of
a message from some respondents, while I only receive one copy of a
message from others. In Thunderbird, one message has a button whose
label states that I can "Reply [to] all", which is a familiar concept,
while the other message has a button for "Reply[ing to the] List".
I'm not sure if the issue arises because of other's email client, the
mailing list "echoing" messages it is CC'd in when it is not the
recipient, when myself or other respondents are CC'd, etc.
I've also noticed that I have three separate threads of emails related
to this subject, some with [External] and others not, and some which are
in regard to the external email and others which are only in regard to
the original message. It's pretty confusing.
I'm /hoping/ that this email is only going to the list, so that it is
public and that subscribers will see it. For parity, the message is
going to emacs-devel, with no CC or BCC, and the subject is regarding
the original message I sent to the list. We'll see, and hopefully I'm
not making more trouble in my own and other's Inbox.
😕 Mailing lists are new to me, but I'm liking it so far despite
confusion and some hurdles!
[-- Attachment #2: Type: text/html, Size: 3870 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-08 20:18 Community improvements to the Emacs Widget Library manual? Bryce Carson
2023-07-09 5:26 ` Eli Zaretskii
@ 2023-07-10 3:38 ` Michael Heerdegen
2023-07-11 23:17 ` Bryce
2023-07-11 11:04 ` Kjartan Oli Agustsson
2 siblings, 1 reply; 20+ messages in thread
From: Michael Heerdegen @ 2023-07-10 3:38 UTC (permalink / raw)
To: Bryce Carson; +Cc: emacs-devel
Bryce Carson <bovine@cyberscientist.ca> writes:
> 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.
What keyword handling do you mean, exactly (example)? I ask because AFAIR,
`widget-create' works fine for user-defined widget types. Then either
these are used implicitly (by the widget type you are deriving from) -
or you can refer to the values using `widget-get' in the functions
implementing the widget behavior (in `define-widget').
What I missed in the documentation most of all was an explanation of the
meaning of the keywords. There are a lot, and I recall that some widget
types totally ignore some keywords and one has to use another one with a
similar name instead, etc. I.e. it would be good to document which
keywords are meaningful for which builtin widget types.
Michael.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-10 3:38 ` Michael Heerdegen
@ 2023-07-11 23:17 ` Bryce
2023-07-12 5:18 ` Michael Heerdegen
0 siblings, 1 reply; 20+ messages in thread
From: Bryce @ 2023-07-11 23:17 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: emacs-devel
Michael Heerdegen <michael_heerdegen@web.de> writes:
> Bryce Carson <bovine@cyberscientist.ca> writes:
>
>> 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.
>
> What keyword handling do you mean, exactly (example)? I ask because
> AFAIR, `widget-create' works fine for user-defined widget types.
Writing :widget-create functions works, but there are no examples in the
manual. Using a function which specially handles arguments (I do not
mean the :args keyword [though in some cases, this would be what I do
mean (Widget is strange like that)]) is only suggested as possible by
the manual stating some built-in widgets do this. An example is the ITEM
widget, which has the following type definitionf:
ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
This type definition syntax shows that after all of the
keyword-argument/keyword-value pairs that a VALUE must be supplied, but
that it does not need to be supplied as in the first form in the example
below.
(widget-create 'item "Example item VALUE")
(widget-create 'item :value "Example item :value ARGUMENT")
In the second form, I used ARGUMENT to match the type definition syntax
quoted above. Normally when writing about widgets, I will say
"Keyword-value pairs," because in most cases the :args keyword is simply
the list of arguments supplied to widget-create after the type argument,
like below.
(widget-create 'TYPE ARGUMENTS...)
=> ()
> Then either these are used implicitly (by the widget type you are
> deriving from) - or you can refer to the values using `widget-get' in
> the functions implementing the widget behavior (in `define-widget').
The widget-get function will retrieve values of properties (which are
defined with keyword-argument and value pairs [:keyword-argument
value]). Perhaps I simply did not think long enough about how to write a
function which will access the elements of a list after exhausting any
keyword value pairs. The widget-put function can be used to set the
value of an arbitrary property, which yes, can then be retrieved with
widget-get.
Perhaps a new macro should be introduced into the library which
facilitates accessing the nth argument _past the keyword-argument value
pairs_ in a reproducible way. The function widget-convert loops over the
arguments, assessing if they are keywords and makes them part of the
value of the :args property of the widget being created (if it is using
the default widget-convert functionality).
> What I missed in the documentation most of all was an explanation of
> the meaning of the keywords. There are a lot, and I recall that some
> widget types totally ignore some keywords and one has to use another
> one with a similar name instead, etc. I.e. it would be good to
> document which keywords are meaningful for which builtin widget types.
>
> Michael.
Regards, Michael. Thanks for asking the pointed question, it did guide
my thinking a bit.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-11 23:17 ` Bryce
@ 2023-07-12 5:18 ` Michael Heerdegen
2023-07-12 7:21 ` Bryce
0 siblings, 1 reply; 20+ messages in thread
From: Michael Heerdegen @ 2023-07-12 5:18 UTC (permalink / raw)
To: emacs-devel
Bryce <bovine@cyberscientist.ca> writes:
> > What keyword handling do you mean, exactly (example)? I ask because
> > AFAIR, `widget-create' works fine for user-defined widget types.
>
> Writing :widget-create functions works, but there are no examples in the
> manual.
I meant `widget-create', not :widget-create.
> Perhaps a new macro should be introduced into the library which
> facilitates accessing the nth argument _past the keyword-argument value
> pairs_ in a reproducible way. The function widget-convert loops over the
> arguments, assessing if they are keywords and makes them part of the
> value of the :args property of the widget being created (if it is using
> the default widget-convert functionality).
But normally it should also set all of the given keywords - in this
part:
;; Finally set the keyword args.
(while keys
(let ((next (nth 0 keys)))
(if (keywordp next)
(progn
(widget-put widget next (nth 1 keys))
(setq keys (nthcdr 2 keys)))
(setq keys nil))))
Maybe you just have found a case where this doesn't work correctly
(Bug)? After creating a widget with `widget-create' I expect that all
keywords are set and can be referred to using `widget-get'. The code
above seems to fail when the arguments don't start with a keyword.
Maybe this is not appropriate.
AFAIR there are some bugs hiding in the code. We must be careful not to
document bugs and unintended behavior. Not sure in this case (it's late
here), but what I understand from what you are describing doesn't
sound like desirable behavior.
Michael.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-12 5:18 ` Michael Heerdegen
@ 2023-07-12 7:21 ` Bryce
2023-07-13 2:59 ` Michael Heerdegen
0 siblings, 1 reply; 20+ messages in thread
From: Bryce @ 2023-07-12 7:21 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: emacs-devel
Michael Heerdegen <michael_heerdegen@web.de> writes:
> Bryce <bovine@cyberscientist.ca> writes:
>
>> > What keyword handling do you mean, exactly (example)? I ask because
>> > AFAIR, `widget-create' works fine for user-defined widget types.
>>
>> Writing :widget-create functions works, but there are no examples in the
>> manual.
>
> I meant `widget-create', not :widget-create.
Okay. I have not tried to insert one of my own widgets into a plain
buffer since I began properly defining one, but the argument
initialization code should indeed work to the same effect and if you can
define a widget, you can create it at point with `widget-create'. I'll
try this some time soon as a sanity check, however.
I am tired, it is also late here. I did manage to catch myself, and what
I've been talking about is the function value for the :create keyword. I
have been calling it :widget-create mistakenly. Pardon the confusion.
>> Perhaps a new macro should be introduced into the library which
>> facilitates accessing the nth argument _past the keyword-argument value
>> pairs_ in a reproducible way. The function widget-convert loops over the
>> arguments, assessing if they are keywords and makes them part of the
>> value of the :args property of the widget being created (if it is using
>> the default widget-convert functionality).
>
> But normally it should also set all of the given keywords - in this
> part:
>
> ;; Finally set the keyword args.
> (while keys
> (let ((next (nth 0 keys)))
> (if (keywordp next)
> (progn
> (widget-put widget next (nth 1 keys))
> (setq keys (nthcdr 2 keys)))
> (setq keys nil))))
Yes, for all arguments given to `create' after TYPE, they are
used to initialize values of properties (including user-defined
properties).
> After creating a widget with `widget-create' I expect that all
> keywords are set and can be referred to using `widget-get'. The code
> above seems to fail when the arguments don't start with a keyword.
> Maybe this is not appropriate.
It should fail, but it should be refactored to provide an error message.
When an argument is not a keyword or the value corresponding to that
keyword (the loop iterates over pairs) it _must_ be handled "in a
widget-specific way." This is what should be improved in the library.
> AFAIR there are some bugs hiding in the code. We must be careful not to
> document bugs and unintended behavior. Not sure in this case (it's late
> here), but what I understand from what you are describing doesn't
> sound like desirable behavior.
I hope I've cleared up the confusion, but if I haven't, here's an
example of what I'm really trying to get at. It isn't valid syntax and
won't run, but the point is to /consume/ non-keyword arguments to
`widget-create' in a widget-specific way (for property initialization or
side-effects).
| (define-widget 'matchbox 'checkbox
| "A cousin-level radiobutton, styled as a checkbox.
|
| The BNF for this widget is:
|
| matchbox := (matchbox VALUE)
| | matchbox
|
| VALUE is used to initialize :value.
|
| It operates like a radio-button, but at the cousin-level (however
| removed) rather than the sibling-level."
| :value nil
| :create
| (lambda (widget-type)
| (let (value)
| (widget-create 'checkbox :value value))))
Granted, the manual doesn't explicity advertise this functionality (see
next quote; either no arguments, one keyword-argument pair, or multiple
keyword-argument pairs), but it feels implied by writing elsewhere in
the manual.
| -- Function: widget-create type [ keyword argument ]...
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-12 7:21 ` Bryce
@ 2023-07-13 2:59 ` Michael Heerdegen
0 siblings, 0 replies; 20+ messages in thread
From: Michael Heerdegen @ 2023-07-13 2:59 UTC (permalink / raw)
To: emacs-devel
Bryce <bovine@cyberscientist.ca> writes:
> [...] but the point is to /consume/ non-keyword arguments to
> `widget-create' in a widget-specific way (for property initialization
> or side-effects).
>
> | (define-widget 'matchbox 'checkbox
> | "A cousin-level radiobutton, styled as a checkbox.
> |
> | The BNF for this widget is:
> |
> | matchbox := (matchbox VALUE)
> | | matchbox
> |
> | VALUE is used to initialize :value.
> |
> | It operates like a radio-button, but at the cousin-level (however
> | removed) rather than the sibling-level."
> | :value nil
> | :create
> | (lambda (widget-type)
> | (let (value)
> | (widget-create 'checkbox :value value))))
>
> Granted, the manual doesn't explicity advertise this functionality (see
> next quote; either no arguments, one keyword-argument pair, or multiple
> keyword-argument pairs), but it feels implied by writing elsewhere in
> the manual.
>
> | -- Function: widget-create type [ keyword argument ]...
Not sure I understand the example (especially what the :create function
is supposed to do). But specifying the value as first argument (to
`widget-create' or `widget-convert') works here for checkbox widgets,
e.g.
(let ((w (widget-convert 'checkbox t :help-echo "A help echo.")))
(message "Value is: %S" (widget-value w)))
If you want something non-standard, you can provide a :widget-convert
argument (it is called in the middle of `widget-convert'). Some
built-in widgets use it, `item' for example.
I'm probably still missing something.
Michael.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-08 20:18 Community improvements to the Emacs Widget Library manual? Bryce Carson
2023-07-09 5:26 ` Eli Zaretskii
2023-07-10 3:38 ` Michael Heerdegen
@ 2023-07-11 11:04 ` Kjartan Oli Agustsson
2023-07-14 2:02 ` Richard Stallman
2 siblings, 1 reply; 20+ messages in thread
From: Kjartan Oli Agustsson @ 2023-07-11 11:04 UTC (permalink / raw)
To: Bryce Carson; +Cc: emacs-devel
[-- Attachment #1: Type: text/plain, Size: 634 bytes --]
Bryce Carson <bovine@cyberscientist.ca> writes:
> 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?
Count me as someone interested. I am very far from an expert on
widget.el but I have used it, expect to use it more in the future, and
would very much like to understand it better.
--
Kjartan Oli Agustsson
GPG Key fingerprint: 4801 0D71 49C0 1DD6 E5FD 6AC9 D757 2FE3 605E E6B0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 691 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-11 11:04 ` Kjartan Oli Agustsson
@ 2023-07-14 2:02 ` Richard Stallman
2023-07-14 5:28 ` Bryce Carson
0 siblings, 1 reply; 20+ messages in thread
From: Richard Stallman @ 2023-07-14 2:02 UTC (permalink / raw)
To: Kjartan Oli Agustsson; +Cc: bovine, emacs-devel
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> > 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?
> Count me as someone interested.
People who are interested can help, but what we need in order for this
to get anywhere is someone willing to start the project, lead it,
and push to get it done.
I hope someone will steo forward.
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
2023-07-14 2:02 ` Richard Stallman
@ 2023-07-14 5:28 ` Bryce Carson
0 siblings, 0 replies; 20+ messages in thread
From: Bryce Carson @ 2023-07-14 5:28 UTC (permalink / raw)
To: emacs-devel
On 7/13/23 20:02, Richard Stallman wrote:
> People who are interested can help, but what we need in order for this
> to get anywhere is someone willing to start the project, lead it,
> and push to get it done.
>
> I hope someone will steo forward.
Do you mean just for an edition of the manual to be successful, or do
you disagree with Eli and think that there is room for rewriting the
entire manual?
In either case, I've downloaded and printed the TexInfo reference card,
the texi source file for the Widget Library, and I'm reading the
manual--again--while working on my project which uses widgets.
Regards,
Bryce.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Community improvements to the Emacs Widget Library manual?
@ 2023-07-09 12:17 Mauro Aranda
2023-07-09 14:59 ` [External] : " Drew Adams
0 siblings, 1 reply; 20+ 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] 20+ messages in thread
* RE: [External] : Re: Community improvements to the Emacs Widget Library manual?
2023-07-09 12:17 Mauro Aranda
@ 2023-07-09 14:59 ` Drew Adams
2023-07-09 23:17 ` Mauro Aranda
0 siblings, 1 reply; 20+ messages in thread
From: Drew Adams @ 2023-07-09 14:59 UTC (permalink / raw)
To: Mauro Aranda, Bryce Carson; +Cc: emacs-devel
1. You _are_ the resident expert, Mauro.
Maybe, and hopefully, there will be some
more to come someday. A public thread
about this effort might just encourage
people to learn and expertize themselves.
Progress encourages participation and
invites more progress.
2. I can't guarantee I'll have time to
help, and any such help would likely be
limited to (hopefully) helpful questions
and some text editing/suggestions. But
if you think that could help more than
hinder, please cc me in whatever threads
you like.
Thanks for working on this, both of you.
It would sure be great to give Customize
a boost in general understanding and
perhaps usability, by way of its doc (at
least).
I know you're talking here about _widget_
(not Customize) doc, but it's mainly the
Widgetry (TM) that makes Customize code
difficult for many of us.
I've long felt that more users, including
Lispers of all levels, could benefit by
using and leveraging Customize more.
But when trying to encourage that, the
response is often either or both (1) the
UI needs improvement (usually stated less
politely) and (2) the Lisp code behind
widgets is obtuse.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [External] : Re: Community improvements to the Emacs Widget Library manual?
2023-07-09 14:59 ` [External] : " Drew Adams
@ 2023-07-09 23:17 ` Mauro Aranda
0 siblings, 0 replies; 20+ messages in thread
From: Mauro Aranda @ 2023-07-09 23:17 UTC (permalink / raw)
To: Drew Adams; +Cc: emacs-devel, Bryce Carson
Drew Adams <drew.adams@oracle.com> writes:
> 2. I can't guarantee I'll have time to
> help, and any such help would likely be
> limited to (hopefully) helpful questions
> and some text editing/suggestions. But
> if you think that could help more than
> hinder, please cc me in whatever threads
> you like.
Will do :-). Your comments have always been helpful to me to spot
weirdness (or plain bugs) in the Widget code.
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2023-07-14 5:28 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-07-08 20:18 Community improvements to the Emacs Widget Library manual? 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-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-09 14:59 ` [External] : " Drew Adams
2023-07-09 23:17 ` Mauro Aranda
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.