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 07:25:01 +0000 Message-ID: <87iljk1voy.fsf@posteo.net> 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> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5743"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Payas Relekar , Stefan Monnier , emacs-devel To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Nov 12 08:25:39 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 1otktX-0001HI-Co for ged-emacs-devel@m.gmane-mx.org; Sat, 12 Nov 2022 08:25:39 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1otktC-0001Qx-FQ; Sat, 12 Nov 2022 02:25:18 -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 1otkt9-0001QR-VT for emacs-devel@gnu.org; Sat, 12 Nov 2022 02:25:15 -0500 Original-Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1otkt7-0000dP-ES for emacs-devel@gnu.org; Sat, 12 Nov 2022 02:25:15 -0500 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 90E72240104 for ; Sat, 12 Nov 2022 08:25:09 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1668237909; bh=5fZmaRBWxzAxobwo0468yRGe9GFVT/2IVlqOU9VTtlI=; h=From:To:Cc:Subject:Date:From; b=LqCRnK1KRdE7ZZDoAtIMm9tD/UiidWGMNQum+JfQIQ9gW5xViXDNpCGFtSQlndgKu f+9aaHMDwSAoK1bjDMnooAGLkbbEalg+YRH7aRGmOth+jO8zTBuEExyxKxicuEnEet AjksBKdgd5Ss9q15F931xnYNdrGYvSewrBFuIceL6WnC/PZpdezPCpOi4RtcxePykF rQTLZDAMfc6/xE3C8M7REGzkobQ+KwNeFvnpt03EENZ3SqXDJYI+85qHSf1F7E6T7E 8ArTPtO6D7ssOHl7dZM8ORdaGHrDnfhsYfhK98a2HavtOpVGb7IjsqX0r6z2mDvniB NAKnevdZtSDxA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N8RtD4nWHz9rxF; Sat, 12 Nov 2022 08:25:06 +0100 (CET) In-Reply-To: (Stefan Kangas's message of "Fri, 11 Nov 2022 21:42:26 -0800") Received-SPF: pass client-ip=185.67.36.66; envelope-from=philipk@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, 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:299618 Archived-At: --=-=-= Content-Type: text/plain Stefan Kangas writes: > Payas Relekar writes: > >> Philip Kaludercic writes: >> >>>>> 1. Get use-package in ELPA >>>>> 2. Complete all documentation >>>>> 3. Prepare documentation in texinfo >>>>> Will cross that bridge when 2 is done. >>> >>> While we are at it, is there a rationale for this order? I mean, there >>> is no hurry, right? My misunderstanding was that the order was 2 -> 3 -> >>> 1. Or are you planning to have use-package ready for Emacs 29? >> >> If you mean merging use-package into emacs.git, that will definitely not >> be happening (at least if I'm the only one working on it). > [...] >> From my understanding, ELPA has less stringent requirements for >> documentation and testing compared to core. Since I cannot commit enough >> time to complete all the tasks before expected 29 branch-off, ELPA is a >> good compromise IMO. > > OK, I'll bite. I have time to dedicate to this task; perhaps we can > move quickly enough for Emacs 29. Ultimately, the decision will be with > the maintainers, but it seems to me that use-package.el itself is in > shape for inclusion. That would certainly be great1 > Could you write up a summary of what needs doing before we can add > use-package to emacs.git? Is it just a matter of writing up some more > documentation, or is there more that needs doing? 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. The most tricky part IMO right now is to complete the .texi documentation. Take a look at https://raw.githubusercontent.com/jwiegley/use-package/master/use-package.texi I have previously commented on what has do be done here (<87o7v37sqh.fsf@posteo.net>, <871qqhby2k.fsf@posteo.net>): 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. 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: --=-=-= Content-Type: text/plain Content-Disposition: attachment Here is the simplest @code{use-package} declaration: @verbatim ;; This is only needed once, near the top of the file (eval-when-compile ;; Following line is not needed if use-package.el is in ~/.emacs.d (add-to-list 'load-path "") (require 'use-package)) (use-package foo) @end verbatim This loads in the package @code{foo}, but only if @code{foo} is available on your system. If not, a warning is logged to the @code{*Messages*} buffer. Use the @code{:init} keyword to execute code before a package is loaded. It accepts one or more forms, up to the next keyword: @verbatim (use-package foo :init (setq foo-variable t)) @end verbatim Similarly, @code{:config} can be used to execute code after a package is loaded. In cases where loading is done lazily (see more about autoloading below), this execution is deferred until after the autoload occurs: @verbatim (use-package foo :init (setq foo-variable t) :config (foo-mode 1)) @end verbatim As you might expect, you can use @code{:init} and @code{:config} together: @verbatim (use-package color-moccur :commands (isearch-moccur isearch-all) :bind (("M-s O" . moccur) :map isearch-mode-map ("M-o" . isearch-moccur) ("M-O" . isearch-moccur-all)) :init (setq isearch-lazy-highlight t) :config (use-package moccur-edit)) @end verbatim In this case, I want to autoload the commands @code{isearch-moccur} and @code{isearch-all} from @code{color-moccur.el}, and bind keys both at the global level and within the @code{isearch-mode-map} (see next section). When the package is actually loaded (by using one of these commands), @code{moccur-edit} is also loaded, to allow editing of the @code{moccur} buffer. If you autoload no-interactive function, please use @code{:autoload}. @verbatim (use-package org-crypt :autoload org-crypt-use-before-save-magic) @end verbatim --=-=-= Content-Type: text/plain --8<---------------cut here---------------start------------->8--- @node Debugging Tools @chapter Debugging Tools TODO --8<---------------cut here---------------end--------------->8--- This is a more technical topic that probably has to be written by someone who is knowledgeable with the internals and implementation details of use-package. Either we find someone like that -- who has time -- or the chapter is removed for now. >> As for the order rationale, getting use-package to ELPA means less >> friction and more users can try it out, more feedback, more eyeballs, >> basically. > > If we get it into core, we can make it into a :core package. Right. --=-=-=--