From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: Adding use-package to core Date: Sat, 12 Nov 2022 14:04:42 +0000 Message-ID: <874jv4z2th.fsf@posteo.net> References: <87lep4jeeb.fsf@gmail.com> <87h6zmj451.fsf@gmail.com> <5EE58F68-8B9E-4DE6-BA20-3A88FFDA6528@posteo.net> <871qqkjwjj.fsf@gmail.com> <87o7to2dfy.fsf@gmail.com> <87y1ssugaf.fsf@posteo.net> <875yfw6kbx.fsf@gmail.com> <87r0ykufh8.fsf@posteo.net> <87sfiyl6nb.fsf@posteo.net> <87pme1ddsn.fsf@gmail.com> <871qqhby2k.fsf@posteo.net> <87leopdbsw.fsf@gmail.com> <87tu3dagj5.fsf@posteo.net> <87eduhd7m7.fsf@gmail.com> <87iljk1voy.fsf@posteo.net> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="29499"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Payas Relekar , Stefan Monnier , emacs-devel , John Wiegley To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Nov 12 15:05:26 2022 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 1otr8Q-0007TN-CP for ged-emacs-devel@m.gmane-mx.org; Sat, 12 Nov 2022 15:05:26 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1otr7q-0008FI-SG; Sat, 12 Nov 2022 09:04:50 -0500 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 1otr7p-0008FA-Ak for emacs-devel@gnu.org; Sat, 12 Nov 2022 09:04:49 -0500 Original-Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1otr7m-00083D-IB for emacs-devel@gnu.org; Sat, 12 Nov 2022 09:04:49 -0500 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 8C25B240027 for ; Sat, 12 Nov 2022 15:04:44 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1668261884; bh=jkaTOfd99+etZVCvp6a/654BPHcoJM18dwMb1OvoUG4=; h=From:To:Cc:Subject:Date:From; b=YQ1qyUJ0SezC1VAd60k2NimpLDKXcgGM1KRX5m6ZYgrT0i41HTxivMMKX8EUQmQZB DeKr/wJdgymP0T+tAucslM6Rt+NbeJsYgOvYLhOSncFtVprczeBrD6iHMtHkjZzT9t RSTLUPTpDyNpqbOR22dH2Nn983MGl6pB+obNplx9j9fZXYHbKY8o/qvxyQLk2lQEE6 MmQp+/6THqUkyIGNJq5onXWhQgvW/OmGomMCW20OVcwHzmWR7eQ9SWijckr+ukbg6+ zPyXiUnii2S3NVsIA0mAczmJ6qrzUHeQvCLNKxQeKbJ2E3SM3w8I29gaYz3+I+2p5z 1JUyZU4kU1AuQ== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N8clH34x7z6tmQ; Sat, 12 Nov 2022 15:04:42 +0100 (CET) In-Reply-To: (Stefan Kangas's message of "Sat, 12 Nov 2022 02:17:08 -0800") Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.posteo.de 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, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable 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:299652 Archived-At: Stefan Kangas writes: > Philip Kaludercic writes: > >> Payas and I can up with the following list >> >> 1. Get use-package in ELPA >> 2. Complete all documentation >> 3. Prepare documentation in texinfo >> Will cross that bridge when 2 is done. >> 4. Add all relevant files to emacs.git >> TBD when 3 is done. >> 5. Ensure everything loads properly >> >> The first point has been done, but hasn't been finalised. > > I didn't follow the discussion, but it seems like adding it to GNU ELPA > is being worked on. That is good. Actually it is done, but I advised Payas to postpone it until the documentation is ready, which makes the package more useful. Even if use-package isn't added in time for 29, working on the issue would still be useful for the ELPA initiative. > But I think one question remains, unless I missed some important part of > the discussion (and please forgive me if I did): (None of this was discussed, to my recollection) > We need to figure out how development will proceed after adding it to > emacs.git. I see three options: > > 1. Development will continue as before, in the old repository and forge > (currently GitHub). This case is different from Eglot, and AFAIU > more like cc-mode, org-mode (or previously Gnus): > > - Development mainly takes place externally. > - When a new version of use-package is released, it is manually > synched (a.k.a. copied) to emacs.git and committed as basically > "new version". [So to read the full git log, one would need to > clone use-package.git -- we don't preserve it.] > - Someone needs to be in charge of (presumably manually) synching > changes in emacs.git back to use-package.git. > > 2. Development moves to emacs.git wholesale, along the same lines as we > did with eglot. This would take more work, and I guess collaboration > and active interest from John. > > 3. We wait until we can include GNU ELPA packages in the Emacs > distribution. AFAIK, this is not actively worked on, and would in > practice mean that we just wait until someone steps up to volunteer > for that (i.e. we effectively do nothing, for now). > > On balance, the first option (1) seems to me the best one here, as > use-package development is already quite established externally and it > seems smart to leverage that existing community to our advantage. The > main advantage we are looking for here is to ship use-package with > Emacs, and we already get that with option 1. FWIW I agree, and think this has worked well enough for a number of larger packages (another example are the Modus Themes). It is sad that the revision history is broken, but that is a limitation of Git IMO. > Perhaps, in this case, it also doesn't make sense to make use-package > into a :core package. We would then just need to worry about synching > the latest version of use-package to emacs.git before releasing a new > version of Emacs. We would not have to update it all the time just to > get it released on GNU ELPA. I cannot evaluate this, but isn't use-package a relatively stable package, that is mostly being bug-fixed? There really aren't that many new features being added all the time, so this might not be that important. Or am I mistaken? > I've CC:ed John in case he has anything to add. > >> Take a look at use-package.texi in the use-package repository. There >> are currently two TODO that ought to be addressed. And as the file is >> generated, the texinfo markup is probably not as idiomatic as it ought >> to be. There are at least a few instances where @code is used instead >> of @kbd, @key or @var. @ref where @xref/@pxref might be better. Content-wise >> a few sections such as how to install the package will be outdated, and >> I'd rephrase the sections that mention MELPA to use ELPA examples. I >> also notice that the spacing is inconsistent, and one should try to keep >> ensure that each full stop is followed by two spaces. > > Agreed. > >> My worry here are the TODO sections -- they either have to be removed or >> expanded: >> >> --8<---------------cut here---------------start------------->8--- >> @node Getting Started >> @chapter Getting Started >> >> TODO@. For now, see @code{README.md}. >> --8<---------------cut here---------------end--------------->8--- >> >> If the manual is pointing to the README, we might just have to convert >> the Markdown document to Texi and clean it up. My hunch is that the >> README isn't written like a good manual, so it won't be that easy. >> >> ... On the other hand, if this TODO really just wants the "Getting >> Started" section from the README, this should be trivial. All one would >> need is to clean up the following that I quickly converted using Pandoc: > > I think we should be able to just use the section "Getting started" from > README.md. I think we can just comment out the sections > "Issues/Requests" and "Debugging Tools" until they are actually written. Someone has to make that choice, and I am fine if you are the one who decides to do so. > However, the documentation seems to be currently written in Org-mode, > from where it is exported using Hugo[1] to a website: > > https://jwiegley.github.io/use-package/getting-started/ > > If it is important to continue doing that, I think we should work with > the org-mode sources rather than the texinfo ones. It would be useful > if John could let us know if he has any preferences in this regard. No, we have recently decided to scrap that documentation source in favour of the documentation generated on elpa.gnu.org -- that is if I understood everything correctly. > As for the formatting issues in the org->texinfo conversion, I believe > that Org-mode has largely solved them. With some luck, it should be a > small matter of imitating what they did. In any case, it should be > possible to find solutions and/or workarounds. Really? How does Org-mode distinguish between @key, @kbd, @code and @var? > So all in all, the documentation will take some work, but nothing too > crazy. If you think so, that is great. > The harder job going forward will be keeping use-package.{org,texi} > up-to-date with README.md, if that will continue to be an important > source of documentation. Perhaps README.md should be restricted in > scope to make that job easier. I think this is a good idea in general. Long READMEs are easy to get lost in. If a file asks you to read it, then it should at the very least be kind enough to keep it short and only focus on pointing you to the relevant information, that would ideally be found somewhere else.