Re: Community improvements to the Emacs Widget Library manual?

[Bryce <bovine@cyberscientist.ca>]

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