Community improvements to the Emacs Widget Library manual?

Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

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

Re: Community improvements to the Emacs Widget Library manual?

[Eli Zaretskii]

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

Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Eli Zaretskii]

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

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.

Re: Community improvements to the Emacs Widget Library manual?

[Michael Heerdegen]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

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

Re: Community improvements to the Emacs Widget Library manual?

[Kjartan Oli Agustsson]

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

Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

Mauro Aranda <maurooaranda@gmail.com> writes:

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

It is definitely defunct. I wanted to find some help for using Widget,
so I began subscribing to all sorts of mailing lists related to Emacs
and Lisp with Thunderbird. At the moment I am attempting to get
comfortable with Rmail, but I need to send a message to the Emacs Help
list for an issue I'm having with it (feel free to read it there! I'm
just letting you know that getting up to speed with how mailing lists
work is one of the reasons I haven't replied sooner).

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

I'd love to hear about that debugging technique. Twice I've witnessed
debug (not edebug) get itself into a circle of evaluating the commands
that pertain to evaluating commands that pertain to evaluating
commands... sorry, I'm sure you understand. Do you know if that may have
had anything to do with Widget's recursive bits? I am not good at using
the debugger, I could do with more practice.

I let debug walk into a recursive loop when trying to debug an error
which occured when I wanted to save the value of a custom variable using
the widget type I defined. (I settled on _merely_ defining a custom type
and using Customize to handle all user interaction for my application,
rather than setting up a buffer using Widgets myself and managing
_everything_).

If I encounter the same error (I have shiny new ones now) I will ask for
specific help resolving it.

> 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'd like to see as much as possible end up in the Widget manual itself.
The manuals that ship with Emacs for some modes are gargantuan, there is
no reason other than politics to not ship any tutorials we write (if
they are quality).

The most one could get out of the library is making a Widgetry RAD
(WidgeTRY™?), I imagine. I can see the possibility for that when I read
the manual and consider the command/event loop of Emacs, and the global
keymap mentioned in the manual.

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

I haven't made any code public yet because I am still deciding on how I
want to publish it. I may provide the code on my GitHub, or I might
provide it on my personal website to churn up some traffic.

The biggest issue I've had with the library is creating a working SEXP
widget. I wanted to match _any_ symoblic expression that would create an
object of a specific type (using :validate). I have settled on something
much more reasonable (a choice-menu) instead, especially while I dogfood
and bootstrap the application.

The application is a literate programming interface. It's closing in on
0.1.0, but because I am writing the interface using Noweb (I am writing
it literately) it is taking longer, because I am nothing more than a
would-be acolyte of LaTeX. I will ask for help soon once I have a
specific question; before I was not making any notes of errors or where
the project was at, and I also lost some Git history of the project due
to accidentally deleteing it (however, I recovered it with some handy
libre software; I can recall the amusing story, if wanted, but don't
fret I aliased rm to remind me to use trash instead).

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

I responded to Michael in detail concerning :widget-create and the
handling of further (non-keyword) arguments.

To quote the library,

    | This is the general syntax of a type specification:
    |
    |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
    |           |   NAME
    |
    |    Where, NAME is a widget name, KEYWORD is the name of a
    | property, ARGUMENT is the value of the property, and ARGS are
    | interpreted in a widget specific way.

ARGS in the general type specification is not one of the pairs of
:keyword value pairs, it is anything else. I forget where it is stated,
but I believe the manual says that any non-keyword value pair arguments
must follow the pairs (if any pairs exist). How to define the handling
of such ARGS in a custom widget is never exampled in the manual; it
certainly isn't a simple (widget-args) function call away.

When replying to Michael, I gave the example of the ITEM widget, which
doesn't handle any of the §5 keyword arguments in a special way, but
will initialize :value on behalf of the user with VALUE (see §5.9).

The description of the ITEM widget, while on the topic, should probably
be expanded to elaborate on what last sentence means. When matching
against widgets, is a (widget-find type) function being used? It would
be nice if there was a Widget Object Model, where all widgets are rooted
in the buffer they belong to, but that's a lofty, far off goal like a
WidgeTRY™ RAD for the Emacs Widget Library.

>  > The Emacs Widget Library manual could use a re-write [...]
>
> 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.

Great! I hope the possibility is realized.

Considering the age of the library (twenty-three years! [if the
earlier copyright year is correct]), and the support for embedded
graphics like GTK+ widgets (so far only WebkitGTK…) _has_ improved,
perhaps this statement could be removed or edited in some way? At least
the part about the _automatic_ improvement in graphical appearance. I
feel like that is not correct, but I could easily be wrong (if these are
merely _goals_ for the library, not the state of affairs).

    7. As support for embedded graphics improve, the widget library will
       be extended to use the GUI features.  This means that your code
       using the widget library will also use the new graphic features
       automatically.

Re: Community improvements to the Emacs Widget Library manual?

[Michael Heerdegen]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

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

Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

Bryce <bovine@cyberscientist.ca> writes:

 > Mauro Aranda <maurooaranda@gmail.com> writes:
 >
 >> Bryce Carson <bovine@cyberscientist.ca> writes:

 >> 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.
 >
 > I haven't made any code public yet because I am still deciding on how I
 > want to publish it. I may provide the code on my GitHub, or I might
 > provide it on my personal website to churn up some traffic.
 >
 > The biggest issue I've had with the library is creating a working SEXP
 > widget. I wanted to match _any_ symoblic expression that would create an
 > object of a specific type (using :validate). I have settled on something
 > much more reasonable (a choice-menu) instead, especially while I dogfood
 > and bootstrap the application.

It sounds to me like you want to use a custom widget type whose parent
is the 'restricted-sexp widget, and define a :match function to do the
matching.   Do you recall if you tried to use that widget, or what
widget did you try to use? If you did, do you recall what problems you
ran into?

 >>  > 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.
 >
 > I responded to Michael in detail concerning :widget-create and the
 > handling of further (non-keyword) arguments.
 >
 > To quote the library,
 >
 >     | This is the general syntax of a type specification:
 >     |
 >     |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
 >     |           |   NAME
 >     |
 >     |    Where, NAME is a widget name, KEYWORD is the name of a
 >     | property, ARGUMENT is the value of the property, and ARGS are
 >     | interpreted in a widget specific way.
 >
 > ARGS in the general type specification is not one of the pairs of
 > :keyword value pairs, it is anything else. I forget where it is stated,
 > but I believe the manual says that any non-keyword value pair arguments
 > must follow the pairs (if any pairs exist). How to define the handling
 > of such ARGS in a custom widget is never exampled in the manual; it
 > certainly isn't a simple (widget-args) function call away.

The widget specific way is handled via a :convert-widget function.

Creation of a widget takes two steps: conversion and creation.

Conversion means to take a specification of the widget to be created
(type and properties) and convert that specification into another one,
suitable for creating the widget.  So if you want to handle those extra
args in a specific way, or to manipulate the widget before creation, you
need a :convert-widget function, that widget-convert (which is
undocumented in the manual) will make sure to call.  It will call the
most specific :convert-widget function first, and then the
:convert-widget of the parents.

You can see an example of this in the following code:

(defun completion--update-styles-options (widget)
   "Function to keep updated the options in 
`completion-category-overrides'."
   (let ((lst (mapcar (lambda (x)
                        (list 'const (car x)))
              completion-styles-alist)))
     (widget-put widget :args (mapcar #'widget-convert lst))
     widget))

(defconst completion--styles-type
   `(repeat :tag "insert a new menu to add more styles"
            (choice :convert-widget completion--update-styles-options)))

Here completion--styles-type holds a type definition for a defcustom,
and the idea is to make the choices available build dynamically.
Without a custom :convert-widget function, the :args would've been
defined in a static way as soon as the type gets defined.  So we use a
:convert-widget function that builds the choices, and puts them into the
:args property, as required by the choice widget.  Then, when creating
it, all the choices in :args show up in the buffer.

 > When replying to Michael, I gave the example of the ITEM widget, which
 > doesn't handle any of the §5 keyword arguments in a special way, but
 > will initialize :value on behalf of the user with VALUE (see §5.9).

Yes.  And that's another undocumented thing.  The :convert-widget
function for the 'item widget is widget-value-convert-widget, which is
documented.

 > The description of the ITEM widget, while on the topic, should probably
 > be expanded to elaborate on what last sentence means. When matching
 > against widgets, is a (widget-find type) function being used?

No, the last sentence "This widget will only match the specified value."
means that the :match function will return non-nil if the value passed
to it is equal to the :value upon creation.

 > It would be nice if there was a Widget Object Model, where all widgets
 > are rooted in the buffer they belong to, but that's a lofty, far off
 > goal like a WidgeTRY™ RAD for the Emacs Widget Library.

Yes, it'd be nice if we could show the hierarchy.  For now, all we have
is widget-browse, and navigate through the super widgets.

 >>  > The Emacs Widget Library manual could use a re-write [...]
 >>
 >> 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.
 >
 > Great! I hope the possibility is realized.
 >
 > Considering the age of the library (twenty-three years! [if the
 > earlier copyright year is correct]), and the support for embedded
 > graphics like GTK+ widgets (so far only WebkitGTK…) _has_ improved,
 > perhaps this statement could be removed or edited in some way? At least
 > the part about the _automatic_ improvement in graphical appearance. I
 > feel like that is not correct, but I could easily be wrong (if these are
 > merely _goals_ for the library, not the state of affairs).
 >
 >     7. As support for embedded graphics improve, the widget library will
 >        be extended to use the GUI features.  This means that your code
 >        using the widget library will also use the new graphic features
 >        automatically.

I don't know if that item is relevant anymore.  Maybe should be moved to
the Wishlist section, which surely needs an update.

Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Eli Zaretskii]

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

Re: Community improvements to the Emacs Widget Library manual?

[Corwin Brust]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

Mauro Aranda <maurooaranda@gmail.com> writes:

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

What about adding links which will call `widget-browse' for the type in
each section of basic types and the sexp types? That way, it is more
clear that you _should_ really be using `widget-browse' to have an
overview of the currently defined types.

Adding the default values for every widget type to the section of each
widget may be more than is necessary.

Re: Community improvements to the Emacs Widget Library manual?

[Michael Heerdegen]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Michael Heerdegen]

Mauro Aranda <maurooaranda@gmail.com> writes:

> Creation of a widget takes two steps: conversion and creation.
>
> Conversion means to take a specification of the widget to be created
> (type and properties) and convert that specification into another one,
> suitable for creating the widget.  So if you want to handle those extra
> args in a specific way, or to manipulate the widget before creation, you
> need a :convert-widget function, that widget-convert (which is
> undocumented in the manual) will make sure to call.  It will call the
> most specific :convert-widget function first, and then the
> :convert-widget of the parents.

This would be a nice paragraph to add to the manual I think.

> You can see an example of this in the following code:
>
> (defun completion--update-styles-options (widget)
>   "Function to keep updated the options in
> `completion-category-overrides'."
>   (let ((lst (mapcar (lambda (x)
>                        (list 'const (car x)))
>              completion-styles-alist)))
>     (widget-put widget :args (mapcar #'widget-convert lst))
>     widget))
>
> (defconst completion--styles-type
>   `(repeat :tag "insert a new menu to add more styles"
>            (choice :convert-widget completion--update-styles-options)))
>
> Here completion--styles-type holds a type definition for a defcustom,
> and the idea is to make the choices available build dynamically.
> Without a custom :convert-widget function, the :args would've been
> defined in a static way as soon as the type gets defined.  So we use a
> :convert-widget function that builds the choices, and puts them into the
> :args property, as required by the choice widget.  Then, when creating
> it, all the choices in :args show up in the buffer.

And this is a nice example for it!



BTW, one thing I often wondered about (I think it's missing in the
manual): one often sees code using list values like

`(widget-type :keyword1 ,(lambda ...) ...)

What is that?  Already a widget?  A widget definition?  What functions
accept such list values, and how do I create a real widget using such
values?


Michael.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

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

RE: [External] : Re: Community improvements to the Emacs Widget Library manual?

[Drew Adams]

> I've also noticed that I have three separate threads
> of emails related to this subject, some with [External]

That "[External]" is my fault, or rather the
fault of my (company's) mail server.  It gets
added automatically for any msgs that are
outside the company.  Sorry about that.  

Re: [External] : Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

On 7/13/23 17:27, Drew Adams wrote:

>> I've also noticed that I have three separate threads
>> of emails related to this subject, some with [External]
> That "[External]" is my fault, or rather the
> fault of my (company's) mail server.  It gets
> added automatically for any msgs that are
> outside the company.  Sorry about that.
I see! No worries, my university does similar things.

Re: Community improvements to the Emacs Widget Library manual?

[Richard Stallman]

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

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

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.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

[-- Attachment #1: Type: text/plain, Size: 1374 bytes --]

In the section /Defining New Widgets/, the following quotation reveals a 
bug, I believe. I added emphasis for the last sentence of each 
description of the keywords. I believe that for the :value-to-external 
function, the last sentence is not supposed to be present.

:value-to-internal
	Function to convert the value to the internal format. The function takes two
	arguments, a widget and an external value, and returns the internal value./The function is called on the present :value when the widget is 
created, and on any value set later with widget-value-set./
:value-to-external
	Function to convert the value to the external format. The function takes two
	arguments, a widget and an internal value, and returns the external value./The function is called on the present :value when the widget is 
created, and on any value set later with widget-value-set./

It looks like the author or editor of the descriptions coped them, which 
is fine. It doesn't make sense that :value-to-external would be called 
when the widget is created, nor when new values are set with 
widget-value-set.

Other places in the manual state that the value of the :value keyword, 
when creating or defining widget, should be in the external form, more 
evidence that the last sentence is a bug.

-- 
"It's a GNU system, I don't know this!"
||--- Mirror universe Lex Murphy, in Cenozoic Zoo

[-- Attachment #2: Type: text/html, Size: 1898 bytes --]

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

[-- Attachment #1: Type: text/plain, Size: 3027 bytes --]

Further, I can't seem to get these functions to work /as documented/ or 
expected.

Without these defined when I'm creating a widget with the following 
code, I do get a button but the internal value is displayed in the 
clickable button. I'd like the external value to be displayed in the 
button %v, just as the menu-tag is is "externally facing".

<<widget>>=
(define-widget 'project-widget 'list
   :tag (let ((s "\n\tProject"))
          (put-text-property 0 (length s) 'face 'bold s) s)
   :format "%t\n%v "
   :offset 0
   :indent 0
   :convert-widget 'widget-types-convert-widget
   :args '((menu-choice
            :tag "EmacSQL-supported backend"
            :format "%[%t%]: %[%v%]"
            :value "sqlite"
            :value-to-external <<menu-choice internal value to external lambda>>
            :value-to-internal <<menu-choice external value to internal lambda>>
            (choice-item :menu-tag "MySQL" :value "mysql")
            (choice-item :menu-tag "PostgreSQL" :value "postgresql")
            (choice-item :menu-tag "SQLite" :value "sqlite"))))
<<menu-choice internal value to external lambda>>=
(lambda (widget internal-value)
   "Converts lowercase, internal values to the casing of trademarks."
   (pcase internal-value
     ("mysql" "MySQL")
     ("sqlite" "SQLite")
     ("postgresql" "PostgreSQL")))
<<menu-choice external value to internal lambda>>=
(lambda (widget external-value)
   "Converts the casing of trademarked names to lowercase, internal values."
   (pcase external-value
     ("MySQL" "mysql")
     ("SQLite" "sqlite")

On 7/14/23 00:32, Bryce Carson wrote:
>
> In the section /Defining New Widgets/, the following quotation reveals 
> a bug, I believe. I added emphasis for the last sentence of each 
> description of the keywords. I believe that for the :value-to-external 
> function, the last sentence is not supposed to be present.
>
> :value-to-internal
> 	Function to convert the value to the internal format. The function takes two
> 	arguments, a widget and an external value, and returns the internal value./The function is called on the present :value when the widget is 
> created, and on any value set later with widget-value-set./
> :value-to-external
> 	Function to convert the value to the external format. The function takes two
> 	arguments, a widget and an internal value, and returns the external value./The function is called on the present :value when the widget is 
> created, and on any value set later with widget-value-set./
>
> It looks like the author or editor of the descriptions coped them, 
> which is fine. It doesn't make sense that :value-to-external would be 
> called when the widget is created, nor when new values are set with 
> widget-value-set.
>
> Other places in the manual state that the value of the :value keyword, 
> when creating or defining widget, should be in the external form, more 
> evidence that the last sentence is a bug.
>
-- 
"It's a GNU system, I don't know this!"
||--- Mirror universe Lex Murphy, in Cenozoic Zoo

[-- Attachment #2: Type: text/html, Size: 3926 bytes --]

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

[-- Attachment #1.1: Type: text/plain, Size: 3716 bytes --]

I forgot to attach the screenshot of the in-error appearance in the 
customize buffer when using these lambdas to convert betwixt internal 
and internal values.

In the customize buffer, the button appears as invalid (nil). Perhaps my 
pcase is incorrect, but it's rather simple matching so I don't see why 
it'd be the cause (though it /would/ not match any of the choice-items 
if none of the patterns are matching [nil would be returned]).

On 7/14/23 00:52, Bryce Carson wrote:
>
> Further, I can't seem to get these functions to work /as documented/ 
> or expected.
>
> Without these defined when I'm creating a widget with the following 
> code, I do get a button but the internal value is displayed in the 
> clickable button. I'd like the external value to be displayed in the 
> button %v, just as the menu-tag is is "externally facing".
>
> <<widget>>=
> (define-widget 'project-widget 'list
>    :tag (let ((s "\n\tProject"))
>           (put-text-property 0 (length s) 'face 'bold s) s)
>    :format "%t\n%v "
>    :offset 0
>    :indent 0
>    :convert-widget 'widget-types-convert-widget
>    :args '((menu-choice
>             :tag "EmacSQL-supported backend"
>             :format "%[%t%]: %[%v%]"
>             :value "sqlite"
>             :value-to-external <<menu-choice internal value to external lambda>>
>             :value-to-internal <<menu-choice external value to internal lambda>>
>             (choice-item :menu-tag "MySQL" :value "mysql")
>             (choice-item :menu-tag "PostgreSQL" :value "postgresql")
>             (choice-item :menu-tag "SQLite" :value "sqlite"))))
> <<menu-choice internal value to external lambda>>=
> (lambda (widget internal-value)
>    "Converts lowercase, internal values to the casing of trademarks."
>    (pcase internal-value
>      ("mysql" "MySQL")
>      ("sqlite" "SQLite")
>      ("postgresql" "PostgreSQL")))
> <<menu-choice external value to internal lambda>>=
> (lambda (widget external-value)
>    "Converts the casing of trademarked names to lowercase, internal values."
>    (pcase external-value
>      ("MySQL" "mysql")
>      ("SQLite" "sqlite")
>
> On 7/14/23 00:32, Bryce Carson wrote:
>>
>> In the section /Defining New Widgets/, the following quotation 
>> reveals a bug, I believe. I added emphasis for the last sentence of 
>> each description of the keywords. I believe that for the 
>> :value-to-external function, the last sentence is not supposed to be 
>> present.
>>
>> :value-to-internal
>> 	Function to convert the value to the internal format. The function takes two
>> 	arguments, a widget and an external value, and returns the internal value./The function is called on the present :value when the widget is 
>> created, and on any value set later with widget-value-set./
>> :value-to-external
>> 	Function to convert the value to the external format. The function takes two
>> 	arguments, a widget and an internal value, and returns the external value./The function is called on the present :value when the widget is 
>> created, and on any value set later with widget-value-set./
>>
>> It looks like the author or editor of the descriptions coped them, 
>> which is fine. It doesn't make sense that :value-to-external would be 
>> called when the widget is created, nor when new values are set with 
>> widget-value-set.
>>
>> Other places in the manual state that the value of the :value 
>> keyword, when creating or defining widget, should be in the external 
>> form, more evidence that the last sentence is a bug.
>>
> -- 
> "It's a GNU system, I don't know this!"
> ||--- Mirror universe Lex Murphy, in Cenozoic Zoo
-- 
"It's a GNU system, I don't know this!"
||--- Mirror universe Lex Murphy, in Cenozoic Zoo

[-- Attachment #1.2: Type: text/html, Size: 5096 bytes --]

[-- Attachment #2: Screenshot from 2023-07-14 00-45-48.png --]
[-- Type: image/png, Size: 33024 bytes --]

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

[-- Attachment #1: Type: text/plain, Size: 4101 bytes --]

Silly me... I put a (debug) in each lambda and I could see that my pcase 
is indeed incorrectly matching.

The keyword documentation is strange, however.

On 7/14/23 00:56, Bryce Carson wrote:
>
> I forgot to attach the screenshot of the in-error appearance in the 
> customize buffer when using these lambdas to convert betwixt internal 
> and internal values.
>
> In the customize buffer, the button appears as invalid (nil). Perhaps 
> my pcase is incorrect, but it's rather simple matching so I don't see 
> why it'd be the cause (though it /would/ not match any of the 
> choice-items if none of the patterns are matching [nil would be 
> returned]).
>
> On 7/14/23 00:52, Bryce Carson wrote:
>>
>> Further, I can't seem to get these functions to work /as documented/ 
>> or expected.
>>
>> Without these defined when I'm creating a widget with the following 
>> code, I do get a button but the internal value is displayed in the 
>> clickable button. I'd like the external value to be displayed in the 
>> button %v, just as the menu-tag is is "externally facing".
>>
>> <<widget>>=
>> (define-widget 'project-widget 'list
>>    :tag (let ((s "\n\tProject"))
>>           (put-text-property 0 (length s) 'face 'bold s) s)
>>    :format "%t\n%v "
>>    :offset 0
>>    :indent 0
>>    :convert-widget 'widget-types-convert-widget
>>    :args '((menu-choice
>>             :tag "EmacSQL-supported backend"
>>             :format "%[%t%]: %[%v%]"
>>             :value "sqlite"
>>             :value-to-external <<menu-choice internal value to external lambda>>
>>             :value-to-internal <<menu-choice external value to internal lambda>>
>>             (choice-item :menu-tag "MySQL" :value "mysql")
>>             (choice-item :menu-tag "PostgreSQL" :value "postgresql")
>>             (choice-item :menu-tag "SQLite" :value "sqlite"))))
>> <<menu-choice internal value to external lambda>>=
>> (lambda (widget internal-value)
>>    "Converts lowercase, internal values to the casing of trademarks."
>>    (pcase internal-value
>>      ("mysql" "MySQL")
>>      ("sqlite" "SQLite")
>>      ("postgresql" "PostgreSQL")))
>> <<menu-choice external value to internal lambda>>=
>> (lambda (widget external-value)
>>    "Converts the casing of trademarked names to lowercase, internal values."
>>    (pcase external-value
>>      ("MySQL" "mysql")
>>      ("SQLite" "sqlite")
>>
>> On 7/14/23 00:32, Bryce Carson wrote:
>>>
>>> In the section /Defining New Widgets/, the following quotation 
>>> reveals a bug, I believe. I added emphasis for the last sentence of 
>>> each description of the keywords. I believe that for the 
>>> :value-to-external function, the last sentence is not supposed to be 
>>> present.
>>>
>>> :value-to-internal
>>> 	Function to convert the value to the internal format. The function takes two
>>> 	arguments, a widget and an external value, and returns the internal value./The function is called on the present :value when the widget is 
>>> created, and on any value set later with widget-value-set./
>>> :value-to-external
>>> 	Function to convert the value to the external format. The function takes two
>>> 	arguments, a widget and an internal value, and returns the external value./The function is called on the present :value when the widget is 
>>> created, and on any value set later with widget-value-set./
>>>
>>> It looks like the author or editor of the descriptions coped them, 
>>> which is fine. It doesn't make sense that :value-to-external would 
>>> be called when the widget is created, nor when new values are set 
>>> with widget-value-set.
>>>
>>> Other places in the manual state that the value of the :value 
>>> keyword, when creating or defining widget, should be in the external 
>>> form, more evidence that the last sentence is a bug.
>>>
>> -- 
>> "It's a GNU system, I don't know this!"
>> ||--- Mirror universe Lex Murphy, in Cenozoic Zoo
> -- 
> "It's a GNU system, I don't know this!"
> ||--- Mirror universe Lex Murphy, in Cenozoic Zoo
-- 
"It's a GNU system, I don't know this!"
||--- Mirror universe Lex Murphy, in Cenozoic Zoo

[-- Attachment #2: Type: text/html, Size: 5996 bytes --]

Re: Community improvements to the Emacs Widget Library manual?

[Bryce Carson]

[-- Attachment #1: Type: text/plain, Size: 4389 bytes --]

...that was a lie. They do work... Now I'm confused.

On 7/14/23 00:59, Bryce Carson wrote:
>
> Silly me... I put a (debug) in each lambda and I could see that my 
> pcase is indeed incorrectly matching.
>
> The keyword documentation is strange, however.
>
> On 7/14/23 00:56, Bryce Carson wrote:
>>
>> I forgot to attach the screenshot of the in-error appearance in the 
>> customize buffer when using these lambdas to convert betwixt internal 
>> and internal values.
>>
>> In the customize buffer, the button appears as invalid (nil). Perhaps 
>> my pcase is incorrect, but it's rather simple matching so I don't see 
>> why it'd be the cause (though it /would/ not match any of the 
>> choice-items if none of the patterns are matching [nil would be 
>> returned]).
>>
>> On 7/14/23 00:52, Bryce Carson wrote:
>>>
>>> Further, I can't seem to get these functions to work /as documented/ 
>>> or expected.
>>>
>>> Without these defined when I'm creating a widget with the following 
>>> code, I do get a button but the internal value is displayed in the 
>>> clickable button. I'd like the external value to be displayed in the 
>>> button %v, just as the menu-tag is is "externally facing".
>>>
>>> <<widget>>=
>>> (define-widget 'project-widget 'list
>>>    :tag (let ((s "\n\tProject"))
>>>           (put-text-property 0 (length s) 'face 'bold s) s)
>>>    :format "%t\n%v "
>>>    :offset 0
>>>    :indent 0
>>>    :convert-widget 'widget-types-convert-widget
>>>    :args '((menu-choice
>>>             :tag "EmacSQL-supported backend"
>>>             :format "%[%t%]: %[%v%]"
>>>             :value "sqlite"
>>>             :value-to-external <<menu-choice internal value to external lambda>>
>>>             :value-to-internal <<menu-choice external value to internal lambda>>
>>>             (choice-item :menu-tag "MySQL" :value "mysql")
>>>             (choice-item :menu-tag "PostgreSQL" :value "postgresql")
>>>             (choice-item :menu-tag "SQLite" :value "sqlite"))))
>>> <<menu-choice internal value to external lambda>>=
>>> (lambda (widget internal-value)
>>>    "Converts lowercase, internal values to the casing of trademarks."
>>>    (pcase internal-value
>>>      ("mysql" "MySQL")
>>>      ("sqlite" "SQLite")
>>>      ("postgresql" "PostgreSQL")))
>>> <<menu-choice external value to internal lambda>>=
>>> (lambda (widget external-value)
>>>    "Converts the casing of trademarked names to lowercase, internal values."
>>>    (pcase external-value
>>>      ("MySQL" "mysql")
>>>      ("SQLite" "sqlite")
>>>
>>> On 7/14/23 00:32, Bryce Carson wrote:
>>>>
>>>> In the section /Defining New Widgets/, the following quotation 
>>>> reveals a bug, I believe. I added emphasis for the last sentence of 
>>>> each description of the keywords. I believe that for the 
>>>> :value-to-external function, the last sentence is not supposed to 
>>>> be present.
>>>>
>>>> :value-to-internal
>>>> 	Function to convert the value to the internal format. The function takes two
>>>> 	arguments, a widget and an external value, and returns the internal value./The function is called on the present :value when the widget is 
>>>> created, and on any value set later with widget-value-set./
>>>> :value-to-external
>>>> 	Function to convert the value to the external format. The function takes two
>>>> 	arguments, a widget and an internal value, and returns the external value./The function is called on the present :value when the widget is 
>>>> created, and on any value set later with widget-value-set./
>>>>
>>>> It looks like the author or editor of the descriptions coped them, 
>>>> which is fine. It doesn't make sense that :value-to-external would 
>>>> be called when the widget is created, nor when new values are set 
>>>> with widget-value-set.
>>>>
>>>> Other places in the manual state that the value of the :value 
>>>> keyword, when creating or defining widget, should be in the 
>>>> external form, more evidence that the last sentence is a bug.
>>>>
>>> -- 
>>> "It's a GNU system, I don't know this!"
>>> ||--- Mirror universe Lex Murphy, in Cenozoic Zoo
>> -- 
>> "It's a GNU system, I don't know this!"
>> ||--- Mirror universe Lex Murphy, in Cenozoic Zoo
> -- 
> "It's a GNU system, I don't know this!"
> ||--- Mirror universe Lex Murphy, in Cenozoic Zoo
-- 
"It's a GNU system, I don't know this!"
||--- Mirror universe Lex Murphy, in Cenozoic Zoo

[-- Attachment #2: Type: text/html, Size: 6750 bytes --]

Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

Bryce Carson <bovine@cyberscientist.ca> writes:

 > In the section Defining New Widgets, the following quotation reveals a
 > bug, I believe. I added emphasis for the last sentence of each
 > description of the keywords. I believe that for the :value-to-external
 > function, the last sentence is not supposed to be present.
 >
 > :value-to-internal Function to convert the value to the internal
 >     format. The function takes two arguments, a widget and an
 >     external value, and returns the internal value. The function is
 >     called on the present :value when the widget is created, and on
 >     any value set later with widget-value-set. :value-to-external
 >     Function to convert the value to the external format. The
 >     function takes two arguments, a widget and an internal value,
 >     and returns the external value. The function is called on the
 >     present :value when the widget is created, and on any value set
 >     later with widget-value-set.
 >
 > It looks like the author or editor of the descriptions coped them,
 > which is fine. It doesn't make sense that :value-to-external would be
 > called when the widget is created, nor when new values are set with
 > widget-value-set.
 >
 > Other places in the manual state that the value of the :value keyword,
 > when creating or defining widget, should be in the external form, more
 > evidence that the last sentence is a bug.

Thanks.  I filed a report at:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64610

Please, if you find new bugs, report them with M-x report-emacs-bug

Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

Bryce Carson <bovine@cyberscientist.ca> writes:

 > Further, I can't seem to get these functions to work as documented or
 > expected.
 >
 > Without these defined when I'm creating a widget with the following
 > code, I do get a button but the internal value is displayed in the 
clickable
 > button. I'd like the external value to be displayed in the button %v, 
just
 > as the menu-tag is is "externally facing".
 >
 > <<widget>>=
 > (define-widget 'project-widget 'list
 >   :tag (let ((s "\n\tProject"))
 >          (put-text-property 0 (length s) 'face 'bold s) s)
 >   :format "%t\n%v "
 >   :offset 0
 >   :indent 0
 >   :convert-widget 'widget-types-convert-widget
 >   :args '((menu-choice
 >            :tag "EmacSQL-supported backend"
 >            :format "%[%t%]: %[%v%]"
 >            :value "sqlite"
 >            :value-to-external <<menu-choice internal value to 
external lambda>>
 >            :value-to-internal <<menu-choice external value to 
internal lambda>>
 >            (choice-item :menu-tag "MySQL" :value "mysql")
 >            (choice-item :menu-tag "PostgreSQL" :value "postgresql")
 >            (choice-item :menu-tag "SQLite" :value "sqlite"))))
 > <<menu-choice internal value to external lambda>>=
 > (lambda (widget internal-value)
 >   "Converts lowercase, internal values to the casing of trademarks."
 >   (pcase internal-value
 >     ("mysql" "MySQL")
 >     ("sqlite" "SQLite")
 >     ("postgresql" "PostgreSQL")))
 > <<menu-choice external value to internal lambda>>=
 > (lambda (widget external-value)
 >   "Converts the casing of trademarked names to lowercase, internal 
values."
 >   (pcase external-value
 >     ("MySQL" "mysql")
 >     ("SQLite" "sqlite")

When possible, please post code that can be evaled without making
tweaks.

Some things I noted:

- Since the super is a list widget, then you don't need to specify
:convert-widget.  The :convert-widget function is one of the few that
gets called for all supers, so you end up converting twice the widget.
In this case, it doesn't seem you want that.

- You're specifying a value in the internal format for the menu-choice.
The manual specifies that when creating a widget or defining a new
one, the ‘:value’ should be in the external format.

- I think you should give similar conversion functions to all
choice-item, and also pass the :value in external format.

Let me know if you still find problems after fixing these things.

Re: Community improvements to the Emacs Widget Library manual?

[bovine]

On 2023-07-14 10:41, Mauro Aranda wrote:
> Bryce Carson <bovine@cyberscientist.ca> writes:
> 
>> Further, I can't seem to get these functions to work as documented or
>> expected.
>> 
>> Without these defined when I'm creating a widget with the following
>> code, I do get a button but the internal value is displayed in the 
>> clickable
>> button. I'd like the external value to be displayed in the button %v, 
>> just
>> as the menu-tag is is "externally facing".
>> 
>> <<widget>>=
>> (define-widget 'project-widget 'list
>>   :tag (let ((s "\n\tProject"))
>>          (put-text-property 0 (length s) 'face 'bold s) s)
>>   :format "%t\n%v "
>>   :offset 0
>>   :indent 0
>>   :convert-widget 'widget-types-convert-widget
>>   :args '((menu-choice
>>            :tag "EmacSQL-supported backend"
>>            :format "%[%t%]: %[%v%]"
>>            :value "sqlite"
>>            :value-to-external <<menu-choice internal value to external 
>> lambda>>
>>            :value-to-internal <<menu-choice external value to internal 
>> lambda>>
>>            (choice-item :menu-tag "MySQL" :value "mysql")
>>            (choice-item :menu-tag "PostgreSQL" :value "postgresql")
>>            (choice-item :menu-tag "SQLite" :value "sqlite"))))
>> <<menu-choice internal value to external lambda>>=
>> (lambda (widget internal-value)
>>   "Converts lowercase, internal values to the casing of trademarks."
>>   (pcase internal-value
>>     ("mysql" "MySQL")
>>     ("sqlite" "SQLite")
>>     ("postgresql" "PostgreSQL")))
>> <<menu-choice external value to internal lambda>>=
>> (lambda (widget external-value)
>>   "Converts the casing of trademarked names to lowercase, internal 
>> values."
>>   (pcase external-value
>>     ("MySQL" "mysql")
>>     ("SQLite" "sqlite")
> 
> When possible, please post code that can be evaled without making
> tweaks.
> 
> Some things I noted:
> 
> - Since the super is a list widget, then you don't need to specify
> :convert-widget.  The :convert-widget function is one of the few that
> gets called for all supers, so you end up converting twice the widget.
> In this case, it doesn't seem you want that.
> 
> - You're specifying a value in the internal format for the menu-choice.
> The manual specifies that when creating a widget or defining a new
> one, the ‘:value’ should be in the external format.
> 
> - I think you should give similar conversion functions to all
> choice-item, and also pass the :value in external format.
> 
> Let me know if you still find problems after fixing these things.

I fixed those issues and I do not see the invalid or void state, but 
only nil is ever displayed in the buffer.
Below is the code I defined.

---

(define-widget 'project-widget 'list
   "A mimimal example to demonstrate 'styled' choice item buttons in a 
choice menu."
   :tag (let ((s "\n\tProject"))
          (put-text-property 0 (length s) 'face 'bold s) s)
   :format "%t\n%v "

   :args '((menu-choice
            :tag "EmacSQL-supported backend"
            :size 50
            :format "%[%t%]: %[%v%] \n"

            :value "SQLite"
            :choice (database-choice-item :menu-tag "SQLite" :value 
"SQLite")

            :value-to-external menu-choice-value-to-external
            :value-to-internal menu-choice-value-to-internal

            (database-choice-item :menu-tag "MySQL"      :value "MySQL")
            (database-choice-item :menu-tag "PostgreSQL" :value 
"PostgreSQL")
            (database-choice-item :menu-tag "SQLite"     :value 
"SQLite"))))

(defun menu-choice-value-to-internal (widget external-value)
   "Converts the casing of trademarked names to lowercase, internal 
values."
   (pcase external-value
     ("MySQL" "mysql")
     ("SQLite" "sqlite")
     ("PostgreSQL" "postgresql")))

(defun menu-choice-value-to-external (widget internal-value)
   "Converts lowercase, internal values to the casing of trademarks."
   (pcase internal-value
     ("mysql" "MySQL")
     ("sqlite" "SQLite")
     ("postgresql" "PostgreSQL")))

(define-widget 'database-choice-item 'choice-item
   nil
   :value-to-external #'menu-choice-value-to-external
   :value-to-internal #'menu-choice-value-to-internal)

(defun widget-value-conversion-example ()
        (interactive)
        (switch-to-buffer "*Widget Value Conversion Example*")
        (kill-all-local-variables)
        (let ((inhibit-read-only t))
          (erase-buffer))
        (remove-overlays)
        (widget-insert "Widget value conversion example.\n\n")
        (widget-create 'repeat 'project-widget)
        (use-local-map widget-keymap)
        (widget-setup))

Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

bovine@cyberscientist.ca writes:

 > On 2023-07-14 10:41, Mauro Aranda wrote:
 >> Bryce Carson <bovine@cyberscientist.ca> writes:
 >>
 >>> Further, I can't seem to get these functions to work as documented or
 >>> expected.
 >>> Without these defined when I'm creating a widget with the following
 >>> code, I do get a button but the internal value is displayed in the
 >>> clickable
 >>> button. I'd like the external value to be displayed in the button
 >>> %v, just
 >>> as the menu-tag is is "externally facing".
 >>> <<widget>>=
 >>> (define-widget 'project-widget 'list
 >>>   :tag (let ((s "\n\tProject"))
 >>>          (put-text-property 0 (length s) 'face 'bold s) s)
 >>>   :format "%t\n%v "
 >>>   :offset 0
 >>>   :indent 0
 >>>   :convert-widget 'widget-types-convert-widget
 >>>   :args '((menu-choice
 >>>            :tag "EmacSQL-supported backend"
 >>>            :format "%[%t%]: %[%v%]"
 >>>            :value "sqlite"
 >>>            :value-to-external <<menu-choice internal value to
 >>> external lambda>>
 >>>            :value-to-internal <<menu-choice external value to
 >>> internal lambda>>
 >>>            (choice-item :menu-tag "MySQL" :value "mysql")
 >>>            (choice-item :menu-tag "PostgreSQL" :value "postgresql")
 >>>            (choice-item :menu-tag "SQLite" :value "sqlite"))))
 >>> <<menu-choice internal value to external lambda>>=
 >>> (lambda (widget internal-value)
 >>>   "Converts lowercase, internal values to the casing of trademarks."
 >>>   (pcase internal-value
 >>>     ("mysql" "MySQL")
 >>>     ("sqlite" "SQLite")
 >>>     ("postgresql" "PostgreSQL")))
 >>> <<menu-choice external value to internal lambda>>=
 >>> (lambda (widget external-value)
 >>>   "Converts the casing of trademarked names to lowercase, internal
 >>> values."
 >>>   (pcase external-value
 >>>     ("MySQL" "mysql")
 >>>     ("SQLite" "sqlite")
 >> When possible, please post code that can be evaled without making
 >> tweaks.
 >> Some things I noted:
 >> - Since the super is a list widget, then you don't need to specify
 >> :convert-widget.  The :convert-widget function is one of the few that
 >> gets called for all supers, so you end up converting twice the widget.
 >> In this case, it doesn't seem you want that.
 >> - You're specifying a value in the internal format for the
 >> menu-choice.
 >> The manual specifies that when creating a widget or defining a new
 >> one, the ‘:value’ should be in the external format.
 >> - I think you should give similar conversion functions to all
 >> choice-item, and also pass the :value in external format.
 >> Let me know if you still find problems after fixing these things.
 >
 > I fixed those issues and I do not see the invalid or void state, but
 > only nil is ever displayed in the buffer.
 > Below is the code I defined.

OK, I think you ran into something that's unsupported (maybe a bug, but
I'm not quite sure).

And thank you for providing the code, it made things easier for me to
see it.

 > (define-widget 'project-widget 'list
 >   "A mimimal example to demonstrate 'styled' choice item buttons in a
 >   choice menu."
 >   :tag (let ((s "\n\tProject"))
 >          (put-text-property 0 (length s) 'face 'bold s) s)
 >   :format "%t\n%v "
 >
 >   :args '((menu-choice
 >            :tag "EmacSQL-supported backend"
 >            :size 50
 >            :format "%[%t%]: %[%v%] \n"
 >
 >            :value "SQLite"
 >            :choice (database-choice-item :menu-tag "SQLite" :value
 >            "SQLite")
 >
 >            :value-to-external menu-choice-value-to-external
 >            :value-to-internal menu-choice-value-to-internal
 >
 >            (database-choice-item :menu-tag "MySQL" :value "MySQL")
 >            (database-choice-item :menu-tag "PostgreSQL" :value
 >            "PostgreSQL")
 >            (database-choice-item :menu-tag "SQLite" :value
 >            "SQLite"))))

The menu-choice creation assumes no difference between the internal
format and external format.  So for now, try removing the
:value-to-external and :value-to-internal.  I think it does that
because there's no big reason for converting a menu-choice value, since
the menu-choice will get its value from a valid choice, and the
individual choice is responsible for the conversion between formats.

Oh, and don't use :value and :choice at the same.  Just use :value to
give it a default value.  So this widget should be:

(define-widget 'project-widget 'list
   "A mimimal example to demonstrate 'styled' choice item buttons in a
   choice menu."
   :tag (let ((s "\n\tProject"))
          (put-text-property 0 (length s) 'face 'bold s) s)
   :format "%t\n%v "
   :args '((menu-choice
            :tag "EmacSQL-supported backend"
            :size 50
            :format "%[%t%]: %[%v%] \n"
        :value "MySQL"
            (database-choice-item :menu-tag "MySQL"      :value "MySQL")
            (database-choice-item :menu-tag "PostgreSQL" :value
            "PostgreSQL")
            (database-choice-item :menu-tag "SQLite"     :value
            "SQLite"))))

 > (define-widget 'database-choice-item 'choice-item
 >   nil
 >   :value-to-external #'menu-choice-value-to-external
 >   :value-to-internal #'menu-choice-value-to-internal)

And now, you need a :match function for this widget, so that when it
gets passed an external value, such as "MySQL", it returns non-nil.

So maybe something like this:
(define-widget 'database-choice-item 'choice-item
   nil
   :match (lambda (widget value)
        (equal (widget-get widget :value) (widget-apply widget
                                :value-to-internal
                                value)))
   :value-to-external #'menu-choice-value-to-external
   :value-to-internal #'menu-choice-value-to-internal)

You need a custom :match function because otherwise the
database-choice-item would resort to matching like an item, and that's
not good when you have different internal and external formats.
Basically, if you use different formats, you should consider providing a
:match function yourself.

I think with these fixes, your code will run just as you expect it.

Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

[...]

To quote the library,

    | This is the general syntax of a type specification:
    |
    |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
    |           |   NAME
    |
    |    Where, NAME is a widget name, KEYWORD is the name of a
    | property, ARGUMENT is the value of the property, and ARGS are
    | interpreted in a widget specific way.

When I first approached the manual I had a difficult time understanding
the full meaning of this meta-language. I did not know what BNF or EBNF
are, and even after having a friend explain it to me I still struggled
to realize that NAME on the second bar is an alternative right-hand
side.

I'm a competent self-taught programmer (and I have a year of formal
education in CS under my belt), but I wasn't familialr with BNF. I now
know it is widely used when describing a formal language grammar, but we
should include something in the manual to at least make it clear that
this is what follows.

We /might/ elect to include a new manual in Emacs overall, or write a
new GNU manual to describe the concepts of Backus-Naur forms (BNF), or
Extended BNF. GNU Bison has a section (§1.1) in its manual which
describes some of the basic concepts of BNF and context-free grammars.
We might simply refer uses to that manual, or link to an external
reference document with a GPL compatible license which could be
redistributed by the FSF or another party friendly to GNU Emacs.


    | 5 Basic Types
    | *************
    |
    | This is the general syntax of a type specification:
    |
    |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
    |           |   NAME
    |
    |    Where, NAME is a widget name, KEYWORD is the name of a property,
    | ARGUMENT is the value of the property, and ARGS are interpreted in a
    | widget specific way.

I feel there is some ambiguity in the description of this syntax as
well. NAME is said to be a widget name (the symbol which refers to the
type being defined), but in every following use of the syntax the
uppercase word "TYPE" is repeated verbatim, except for ITEM in §5.9.

Shouldn't all type specifications read as follows?

    | 5.5 The ‘editable-field’ Widget
    | ===============================
    |
    | Syntax:
    |
    |      EDITABLE-FIELD ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
    |
    |    The VALUE, if present, is used to initialize the ‘:value’ property.
    | The value should be a string, which will be inserted in the field.  This
    | widget will match all string values.

TYPE is said to be a type name, so it should be the name of the type
being specified throughout the manual. If I've misunderstood the grammar
or the description, we should instead correct the description in §5
(Basic Types) and fix ITEMs type.

Re: Community improvements to the Emacs Widget Library manual?

[Eli Zaretskii]

> From: Bryce <bovine@cyberscientist.ca>
> Cc: maurooaranda@gmail.com, emacs-devel@gnu.org
> Date: Sun, 23 Jul 2023 17:06:45 -0600
> 
> [...]
> 
> To quote the library,
> 
>     | This is the general syntax of a type specification:
>     |
>     |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
>     |           |   NAME
>     |
>     |    Where, NAME is a widget name, KEYWORD is the name of a
>     | property, ARGUMENT is the value of the property, and ARGS are
>     | interpreted in a widget specific way.
> 
> When I first approached the manual I had a difficult time understanding
> the full meaning of this meta-language. I did not know what BNF or EBNF
> are, and even after having a friend explain it to me I still struggled
> to realize that NAME on the second bar is an alternative right-hand
> side.
> 
> I'm a competent self-taught programmer (and I have a year of formal
> education in CS under my belt), but I wasn't familialr with BNF. I now
> know it is widely used when describing a formal language grammar, but we
> should include something in the manual to at least make it clear that
> this is what follows.
> 
> We /might/ elect to include a new manual in Emacs overall, or write a
> new GNU manual to describe the concepts of Backus-Naur forms (BNF), or
> Extended BNF. GNU Bison has a section (§1.1) in its manual which
> describes some of the basic concepts of BNF and context-free grammars.
> We might simply refer uses to that manual, or link to an external
> reference document with a GPL compatible license which could be
> redistributed by the FSF or another party friendly to GNU Emacs.

A cross-reference to another manual where BNF is explained is TRT,
IMO.