From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#60418: [PATCH] Add :vc keyword to use-package Date: Sun, 16 Apr 2023 19:10:16 +0300 Message-ID: <835y9vbyfr.fsf@gnu.org> References: <87zgb6uk2r.fsf@hyperspace> <87tu0tl1s4.fsf@hyperspace> <87a5zt2emd.fsf@betli.tmit.bme.hu> <87fs9l9bim.fsf@posteo.net> <87y1n3zsro.fsf@posteo.net> <871qku220f.fsf@betli.tmit.bme.hu> <874jpq920b.fsf@posteo.net> <87cz4ezpwi.fsf@betli.tmit.bme.hu> <87h6tlinft.fsf@hyperspace> <87r0spa712.fsf@posteo.net> <87edopiif5.fsf@hyperspace> <87wn2bzvcp.fsf@hyperspace> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="24581"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philipk@posteo.net, felician.nemeth@gmail.com, 60418@debbugs.gnu.org, stefankangas@gmail.com To: Tony Zorman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Apr 16 18:11:14 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1po4y9-0006HS-RJ for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 16 Apr 2023 18:11:13 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1po4y0-00072O-Gv; Sun, 16 Apr 2023 12:11:04 -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 1po4xy-00072F-Qs for bug-gnu-emacs@gnu.org; Sun, 16 Apr 2023 12:11:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1po4xy-0003jv-It for bug-gnu-emacs@gnu.org; Sun, 16 Apr 2023 12:11:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1po4xy-0001aU-9r for bug-gnu-emacs@gnu.org; Sun, 16 Apr 2023 12:11:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 16 Apr 2023 16:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60418 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 60418-submit@debbugs.gnu.org id=B60418.16816614246056 (code B ref 60418); Sun, 16 Apr 2023 16:11:02 +0000 Original-Received: (at 60418) by debbugs.gnu.org; 16 Apr 2023 16:10:24 +0000 Original-Received: from localhost ([127.0.0.1]:52393 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1po4xL-0001Zc-Gq for submit@debbugs.gnu.org; Sun, 16 Apr 2023 12:10:23 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:54322) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1po4xJ-0001ZN-44 for 60418@debbugs.gnu.org; Sun, 16 Apr 2023 12:10:22 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1po4xC-0003Z3-D7; Sun, 16 Apr 2023 12:10:14 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=T9y5YiLuppBV/K0y2uCChp6w2eeplArGDAW/q+qqL58=; b=Gdp1qMovffVSKO1w0VKg cWgWqsciqs1dGjoqxhwonMd+N+4z3ja6TuQEpHLva4lND0VXu71zwkb4qCCbFBhzmr+dHsYViByxT VYlzwKgMGL8ZNoLUmTM9TaeNglrkYdhTfaM572mmp1RIVdOqfzj44FM2vuGMl3hkVzewpC7HcCgsF a609ty62kA0ifkr0bgvMTXfj55+6+KrTHxjQSeKWHY4V/mM3Ue+N0y0IsIUVXqA3XT+k3BW8IKpBk 89h97oVX2yUrTRk3J3RaFJ8IDjJx7qKTuI8Ytowyd4UsCy8UKpRQylQ15xq3cKAyYWA/RP8fnjFwc fDNBtATW395udg==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1po4xB-0003Zo-BW; Sun, 16 Apr 2023 12:10:13 -0400 In-Reply-To: <87wn2bzvcp.fsf@hyperspace> (bug-gnu-emacs@gnu.org) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:260139 Archived-At: > Cc: 60418@debbugs.gnu.org, Felician Nemeth , > stefankangas@gmail.com > Date: Sun, 16 Apr 2023 17:43:02 +0200 > From: Tony Zorman via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > Alright, attached are patches that contain the requested change: we now > default to :last-release. Thanks, please see below a few minor comments. > +(defun use-package-vc-install (arg &optional local-path) > + "ARG is a list of the form (NAME OPTIONS REVISION). This should tell what the function does, not just what the arguments look like. > +The optional LOCAL-PATH boolean decides whether > +`package-vc-install-from-checkout' or `package-vc-install' will > +end up being called." This should tell explicitly which of the two is called when LOCAL-PATH is nil and when it's non-nil. > +(defun use-package-handler/:vc (name _keyword arg rest state) > + "Generate code for the :vc keyword." I don't think this is an accurate description of what the function does. Also, we try very hard to mention at least the mandatory arguments in the first line of the doc strings. > @@ -1666,7 +1744,8 @@ use-package > (compare with `custom-set-variables'). > :custom-face Call `custom-set-faces' with each face definition. > :ensure Loads the package using package.el if necessary. > -:pin Pin the package to an archive." > +:pin Pin the package to an archive. > +:vc Integration with `package-vc.el'." The description of other keywords say what is the effect of each one; the description of :vc doesn't. "Integration with package.el" is not a useful description, it says nothing about what this keyword does. > +@findex :vc > +The @code{:vc} keyword can be used to control how packages are fetched. Without saying more regarding what "fetched" is about, this description is not as useful as it could have been. You should give some context which would explain how "fetching" is related to use-package. My suggestion, btw, is to use a more descriptive "downloading", not "fetching". > +It accepts the same arguments as @code{package-vc-selected-packages}, There should be a cross-reference here to the Emacs manual where it describes package-vc-selected-packages. > +except that a name need not explicitly given: it is inferred from the ^ "be" is missing there. > +declaration. Further, the accepted property list is augmented by a > +@code{:rev} keyword, which has the same shape as the @code{REV} argument > +to @code{package-vc-install}. Notably—even when not specified—@code{:rev} ^ Please don't use non-ASCII characters in Texinfo sources, that is usually unnecessary. In this case, to produce an em-dash, use two dashes in a row -- they will be converted to em-dash on output. > +would try—by invoking @code{package-vc-install}—to install the latest Same here. > +The above dispatches to @code{package-vc-install-from-checkout}. A cross-reference here would be beneficial, again. > +** use-package > + > +*** New ':vc' keyword Heading lines in NEWS should end in a period. Also, this entry should be marked with "+++", as the necessary changes in the manuals are included. > +This keyword enables the user to control how packages are fetched by > +utilising 'package-vc.el'. By default, it relays its arguments to > +'package-vc-install', but—when combined with the ':load-path' > +keyword—it can also call upon 'package-vc-install-from-checkout' > +instead. Please also avoid non-ASCII characters in NEWS. > Further, if no revision is given via the ':rev' argument, we > +fall back to the last release (via 'package-vc-install's > +':last-release' argument). To check out the last commit, use ':rev You seem to like to say "Further," at the beginning of sentences, but please be aware that this word usually adds no useful information, so you can easily drop it in most cases. For example, in the text above: the sentence will be as informative without "Further" as with it. Also, "we fall back" is not our style in documentation (who is "we"?). We say "use-package will fall back" instead. Thanks for working on this.