From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Mauro Aranda Newsgroups: gmane.emacs.devel Subject: Re: Community improvements to the Emacs Widget Library manual? Date: Sun, 9 Jul 2023 09:17:25 -0300 Message-ID: <1fd4b379-90a9-549e-b0fc-55d5bd4ff042@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27348"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.11.0 Cc: emacs-devel To: Bryce Carson Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 09 14:18:12 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 1qITMh-0006sA-SK for ged-emacs-devel@m.gmane-mx.org; Sun, 09 Jul 2023 14:18:11 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qITM8-00016y-M5; Sun, 09 Jul 2023 08:17:36 -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 1qITM3-00013o-1P for emacs-devel@gnu.org; Sun, 09 Jul 2023 08:17:35 -0400 Original-Received: from mail-oo1-xc36.google.com ([2607:f8b0:4864:20::c36]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qITM1-00061W-Gr for emacs-devel@gnu.org; Sun, 09 Jul 2023 08:17:30 -0400 Original-Received: by mail-oo1-xc36.google.com with SMTP id 006d021491bc7-560b56b638eso2238344eaf.0 for ; Sun, 09 Jul 2023 05:17:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1688905048; x=1691497048; h=content-transfer-encoding:subject:from:cc:to:content-language :user-agent:mime-version:date:message-id:from:to:cc:subject:date :message-id:reply-to; bh=ScUjXAaMKL7vY51+LuN1Wz8YChGOmXDxSM2Tho7eOA8=; b=jkKARpYGUZp7B5zpvBLPGJ81spdCgG5QbffWhfbySBuLjUDqj9FEDmzwBGYbfrI0F9 B586nyqBUIe4esRCFd7rui1pjOkswBCFsEKyJU81ykdPRjg+7klHT9F/umIFMTT6EhU4 CJCB/KPkd7EzDQcZaYxR7L2Xwss8PA93xABNQzSq1BJPcuquRMwUO0Y8ZyCs0X/Zrwsn Y3Z5Q85zzTiyL/BMlATSCgZyv+9JZ/buwIvgcyZVjTxdgip6/etd0FIimu9nQpD/FTO6 LjezYk9I69z5uy8PymIoABcMxqfzIoZB/lKwisroUJVLIC/vwDDsPNDeNGzmviMRCIEy kWag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1688905048; x=1691497048; h=content-transfer-encoding:subject:from:cc:to:content-language :user-agent:mime-version:date:message-id:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to; bh=ScUjXAaMKL7vY51+LuN1Wz8YChGOmXDxSM2Tho7eOA8=; b=Tveau1AxV+6qBTsSfFaP55gHeFXfROZ2t+6/nGqXmAtgLA4iGHSa2W4oxlG56ddv82 sawxGkwZAxOqoBAYMsKooL4l52Yr8e1JAbHkUcHwTuk1deHzx20goOdJrhKofLxCY/AF 00yUiYT4++GIn6G7YNvHeGJcaX8709h2aW4tkG1HKHJrrcaZ9ARlQI1B8NKPtKIR76J0 tZeY0JbQcZIwnxoInUtxf8cNyoX7A/NbueUX3myncIXZELpJBL864kDlvI6gwsue0ymE weyB2FrJMEowr4zALEQPZ/8rvLI9bd+6yXWkfzAsKCnCEO8waU4gXeXr9Xy8lND9AVR+ rk2Q== X-Gm-Message-State: ABy/qLbxvXAQy58qcbLpZsZsPbHG6ytuDGzNAoVI8AYp+7UVcsEW3BbT PbGwPwWpRCEG6tDZupcAwGF1WAEz0hVRzA== X-Google-Smtp-Source: APBJJlFJgmSgjwjN5btL4aJeks59DtpDuv/aGQfzWI+dqAJsxgpIXf3JSerjU1ys85nd3mdhrxNhZA== X-Received: by 2002:a4a:4f53:0:b0:562:ff8a:75b7 with SMTP id c80-20020a4a4f53000000b00562ff8a75b7mr5501676oob.3.1688905048281; Sun, 09 Jul 2023 05:17:28 -0700 (PDT) Original-Received: from [192.168.0.234] ([186.127.128.249]) by smtp.gmail.com with ESMTPSA id u18-20020a4a8c12000000b0055e3dd89c12sm3402889ooj.1.2023.07.09.05.17.27 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sun, 09 Jul 2023 05:17:27 -0700 (PDT) Content-Language: en-US Received-SPF: pass client-ip=2607:f8b0:4864:20::c36; envelope-from=maurooaranda@gmail.com; helo=mail-oo1-xc36.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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:307670 Archived-At: Bryce Carson 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.