From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: Re: Adding use-package to core Date: Sat, 12 Nov 2022 02:17:08 -0800 Message-ID: References: <87lep4jeeb.fsf@gmail.com> <875yg4144y.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; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="8147"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Payas Relekar , Stefan Monnier , emacs-devel , John Wiegley To: Philip Kaludercic Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Nov 12 11:18:04 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 1otnaM-0001nR-TW for ged-emacs-devel@m.gmane-mx.org; Sat, 12 Nov 2022 11:18:03 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1otnZi-0001c1-3d; Sat, 12 Nov 2022 05:17:22 -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 1otnZY-0001bP-En for emacs-devel@gnu.org; Sat, 12 Nov 2022 05:17:14 -0500 Original-Received: from mail-oi1-x233.google.com ([2607:f8b0:4864:20::233]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1otnZW-0005kg-Cx; Sat, 12 Nov 2022 05:17:12 -0500 Original-Received: by mail-oi1-x233.google.com with SMTP id s206so7083781oie.3; Sat, 12 Nov 2022 02:17:09 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:from:to:cc:subject:date:message-id:reply-to; bh=ORHVuUMZva6ucddLXhCCH162hwFIH9URPKqU5GZRUKU=; b=SnqnGwhKOt6EXYbfD76GiBKhY9o+jY/CnSI71N6+dYxefBr1qn2f3iLCj4aknvROJl str6h9vFDNg2y2/Xl0F7ug5YGa/GxFpRi54tr/G9p+dO8/CYEMiew0qdk9gB/dDmTmbZ Y0ZJ1vOwy7IRLqxEDZP1OkgFKEPRdSycNASTUHNXeTMJhYa0mLazz7pRthD5Ggblg1CH FHmk+yNuxPI//ns0Wmax7q+bg4MeCV58peQfrGZMpHts6jFYpvoYieiWlI7hS/1xcG8C wj7rngO1jmzIDj/eOggiJc3eRJxlHtMfJavkXY2+05znvpXE7Yx13bcBkWXS8vYOfB3C RPEA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=ORHVuUMZva6ucddLXhCCH162hwFIH9URPKqU5GZRUKU=; b=NwW+KKl8KJA+5tKuVtn22fFyPji3kvg/oXQgqgrwk7+X56I27MKqeXuz8qvbhb9mMU PdtDvmD07qeT7Kb+zuydXLNWsFq7TgcCLBpj18LOr61sbywXgc0kGNvI7Xq6y7GnpHhX 4irvhTWAV3Qw6fpyLBCEgt/OcV8KFiXRGQ2zDTHj4VPq5xYV7is707S36Z6qj5xKXEL4 ERBOPhyWN9KMNjAsr7CS9FrFi20OAPiES781Dnwszp4cCKNwJPRsFUx8X9aKVmgzsHaR LfkpXewMKS9L3YxCbOMT7r9m9UwejS4oygwALXPpDb/NKVOL6H3dfrioPHw8Au8IfOZt DORQ== X-Gm-Message-State: ANoB5pmhLfcWJy9KcCdwaLiWStXQlaoTAtpwFhxaaH9RpzUdnV4+LuIy 2mH2ORzazP9z3sA6a3IMTUEUdF8skMpegDX+fm4= X-Google-Smtp-Source: AA0mqf7E3EvkX/ZS8+fL3+a3Ce2CWSRLRyl/Zb2TLY96KC2ZRiN5lfSo2N2wyWNeAXUiqdsZgOA/A/Nt6xqBUD/XBg0= X-Received: by 2002:a54:4889:0:b0:359:dc32:4f9e with SMTP id r9-20020a544889000000b00359dc324f9emr2380120oic.92.1668248228468; Sat, 12 Nov 2022 02:17:08 -0800 (PST) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 12 Nov 2022 02:17:08 -0800 In-Reply-To: <87iljk1voy.fsf@posteo.net> X-Hashcash: 1:20:221112:johnw@gnu.org::hJMltjBCI0lGfD4K:0Zh3 Received-SPF: pass client-ip=2607:f8b0:4864:20::233; envelope-from=stefankangas@gmail.com; helo=mail-oi1-x233.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 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:299639 Archived-At: 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. But I think one question remains, unless I missed some important part of the discussion (and please forgive me if I did): 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. 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'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. 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. 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. So all in all, the documentation will take some work, but nothing too crazy. 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. Footnotes: [1] https://gohugo.io/