From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Bryce Carson Newsgroups: gmane.emacs.devel Subject: Community improvements to the Emacs Widget Library manual? Date: Sat, 8 Jul 2023 14:18:21 -0600 Message-ID: <1e042c59-9baf-ee4f-4726-26aba36847d4@cyberscientist.ca> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="------------5hoFMR0So67Jc0XjPMhleOwV" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11629"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.12.0 To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 08 22:19:25 2023 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qIEOq-0002sO-Kr for ged-emacs-devel@m.gmane-mx.org; Sat, 08 Jul 2023 22:19:24 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qIEO5-0007QY-0x; Sat, 08 Jul 2023 16:18:37 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qIEO2-0007OM-Kc for emacs-devel@gnu.org; Sat, 08 Jul 2023 16:18:34 -0400 Original-Received: from seout10.web-dns1.com ([68.168.119.164]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qIEO0-0006b2-QN for emacs-devel@gnu.org; Sat, 08 Jul 2023 16:18:34 -0400 Original-Received: from beaudry.whc.ca ([72.10.170.194]) by se3.web-dns1.com with esmtps (TLSv1.2:AES128-GCM-SHA256:128) (Exim 4.92) (envelope-from ) id 1qIENx-0001ku-7Z for emacs-devel@gnu.org; Sat, 08 Jul 2023 16:18:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=cyberscientist.ca; s=default; h=To:Subject:From:MIME-Version:Date: Message-ID:Content-Type:Sender:Reply-To:Cc:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=WpGgRu7CYarHTLsI0NopM7Srh9uupwXWdSiPnUkJOg4=; b=ZPPPR1kvHEyuUFEQaHVDcRXNgA mEUoyC/zad3jkLyP8ejPeZmkgnttMf4obkSlNX91wl2v9pnqNvm83HDhP3Gv86qAVK4Tl8D8UwOOW gUdYxTEsp63pRDY97vaRWIKcW+73Tcr4Dgr4HPpbKkqORnl5+hkyLjUKBm5iQGxm+SPg2C+/YPPoX ADoU+aQ/sKrITSHf0jWB9z2Qq4D+qh/zPHJiecaHtj2LUhQSVLrFdOV3fVdVQvqtBEC+PeIcR3QoZ OfRyArYpHERaG0F78NGOW0cuTGuC2gVJz31XeUlZMjzzbomOmmVgbtkW9BcZiv2HTJbTvlb3f/Cpp e0wvBgHg==; Original-Received: from s01063cb74b7279b2.cg.shawcable.net ([174.0.57.221]:42410 helo=[10.0.0.120]) by beaudry.whc.ca with esmtpsa (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.96) (envelope-from ) id 1qIENq-0008HU-0E for emacs-devel@gnu.org; Sat, 08 Jul 2023 16:18:28 -0400 Content-Language: en-US X-Originating-IP: 72.10.170.194 X-SpamExperts-Domain: out.beaudry.whc.ca X-SpamExperts-Username: 72.10.170.194 Authentication-Results: web-dns1.com; auth=pass smtp.auth=72.10.170.194@out.beaudry.whc.ca X-SpamExperts-Outgoing-Class: ham X-SpamExperts-Outgoing-Evidence: Combined (0.16) X-Recommended-Action: accept X-Filter-ID: Pt3MvcO5N4iKaDQ5O6lkdGlMVN6RH8bjRMzItlySaT8sbVD8zWKPzsfJnigLWTTWPUtbdvnXkggZ 3YnVId/Y5jcf0yeVQAvfjHznO7+bT5yIihPVXVFAYa+LPll+F2R2qA/pdxL9H6My4aKblWy1swqF ip2pFIziVH9hPQl4JJ5aa40DxZPJuLUk3zkVKd8pdqDuc9lS3Nx+9iKFZ9qooJJVRKyFCRrxWkR6 oZhlSr1PyJCkrfCv5qYfIiHO9mkciFKfD1jKgYfH+6S5qDVYoDFgY9NSkYzvwZKlNZIeZZVkrQQy Z/c/nQCN/+0hfTQW67Zt5GqKWaOBDqMDdTBiCeNwxuyQxxpFBZS72lACfRLGYP/Zj29Dpz4JZGFu 9hfz+sPa00WfFmZwEM/0Zmjjnqj1X9RXdFvDp6YyTercuCQcW7Ptgw8P5bot6S/5Bxld/Zf+w/GO 0z491YCixzZA+xsM51Mye8eo6Y/hXEFbc9MIm4qZ5/UkJuZ+By/rOgnAFLpsLfgjUziXfqTeC+RW OFXdu+Bu1/ZYyHlEMbJGF24ksVlXZWxasRfFjM8m8h7IISdVKyA8/8yCpIYzH3apf78hv/eAPXF2 /g6Nh7EU3uLxMm9NJj5srenHTGoLJ89XcJ+oe7cNV02XS3Fiuz6lWJXD+DTsICZ03NLhC+umx/Zi 7wLmYnntkb2D1B9sGkgX4k/PTJHTWXgV7ZP/74ue6NEC7IIKJQB0YZshkxULck7TPpuFqUUQz+mM 8JAD4ECWE1bVWE1COYFlQnbcJ6lOo9mtq1s3s2IsYujArm9fJMqpr2p5LV0JU8Z8kSNqOLz/ECG2 c1N1RYG47ky4EWw5cbDOSq/9nUdep X-Report-Abuse-To: spam@se1.web-dns1.com Received-SPF: pass client-ip=68.168.119.164; envelope-from=bovine@cyberscientist.ca; helo=seout10.web-dns1.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:307629 Archived-At: This is a multi-part message in MIME format. --------------5hoFMR0So67Jc0XjPMhleOwV Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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. --------------5hoFMR0So67Jc0XjPMhleOwV Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 7bit

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.

--------------5hoFMR0So67Jc0XjPMhleOwV--