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: Tue, 02 May 2023 15:40:14 +0300 Message-ID: <831qjyoqj5.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> <835y9vbyfr.fsf@gnu.org> <87mt36uwl8.fsf@hyperspace> <83ttxd8k1z.fsf@gnu.org> <87v8hrn56l.fsf@hyperspace> <87cz3w2lvb.fsf@posteo.net> <87jzy3ku6u.fsf@hyperspace> <87bkje93ou.fsf@posteo.net> <87y1mhihhy.fsf@hyperspace> <87ildbet2d.fsf@hyperspace> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15948"; 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 Tue May 02 14:40:29 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 1ptpIz-0003xA-22 for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 02 May 2023 14:40:29 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ptpIh-0005mo-Vt; Tue, 02 May 2023 08:40:12 -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 1ptpIZ-0005kD-M2 for bug-gnu-emacs@gnu.org; Tue, 02 May 2023 08:40:05 -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 1ptpIY-0004Xv-Mr for bug-gnu-emacs@gnu.org; Tue, 02 May 2023 08:40:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ptpIX-0001ru-UO for bug-gnu-emacs@gnu.org; Tue, 02 May 2023 08:40:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 02 May 2023 12:40:01 +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.16830311997169 (code B ref 60418); Tue, 02 May 2023 12:40:01 +0000 Original-Received: (at 60418) by debbugs.gnu.org; 2 May 2023 12:39:59 +0000 Original-Received: from localhost ([127.0.0.1]:41903 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ptpIU-0001rY-Co for submit@debbugs.gnu.org; Tue, 02 May 2023 08:39:58 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:39880) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ptpIQ-0001rF-ER for 60418@debbugs.gnu.org; Tue, 02 May 2023 08:39:57 -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 1ptpII-0004Li-8Y; Tue, 02 May 2023 08:39:47 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=H9IVhy+zLidGDxPBFRXsuNE5iklHpNbW9avijWhLXhM=; b=mnbIh85F7gu7 cykIYhGhGZpP6W/EhkjX6bF6EhxBrx8GFKhdGk3zl/vlgTBc7WhW1j+VTSbDfXDH13tuKsJ/AuymT moEsjuKTPK3DaB3/KmykAMvFfbrj3NkARJuI91Ssicf5WXw9XtEIWcrfnVsGVLcbDif58bQtgLRpA zj7Azkb0rIkN7miIM23tl+vbI7ddOTCCFmQghMkKMk/kz1WxJ8T3oR8K8g2R51ccktVR4fwUdK0TU NC6ZOXf9xSNnm8owGm7F8aEwgndoQCuA6F2KTnvUKuZRDsuY6VoR00m27KZCL2HYmZK8LG1yCsYWm 2SclK4ypBXW1b5+I5luAcg==; 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 1ptpI1-0003ac-Us; Tue, 02 May 2023 08:39:45 -0400 In-Reply-To: <87ildbet2d.fsf@hyperspace> (message from Tony Zorman on Mon, 01 May 2023 21:43:22 +0200) 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:260920 Archived-At: > From: Tony Zorman > Cc: Eli Zaretskii , 60418@debbugs.gnu.org, > felician.nemeth@gmail.com, stefankangas@gmail.com > Date: Mon, 01 May 2023 21:43:22 +0200 > > +@findex :vc > +The @code{:vc} keyword can be used to control how packages are > +downloaded and/or installed. More specifically, it allows one to fetch > +and update packages directly from a version control system. This is > +especially convenient when wanting to install a package that is not on > +any package archive. This paragraph uses just one space between sentences; please use two of them, per our conventions. > +The keyword accepts the same arguments as specified in > +@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}, except Please don't use @pxref this way: it only looks well in HTML output, but in all other outputs it looks awkward, if not incorrect. Instead, please use the more traditional and less "sexy" way: The keyword accepts the same form of specifications as @code{package-vc-install} (@pxref{Fetching Package Sources,,, emacs, GNU Emacs Manual}), except that... > +declaration. 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}. Instead of @code{REV}, please use @var{rev}: @var markup and lower-case "rev". This is the markup suitable for formal arguments to functions in Texinfo sources. > +@code{package-vc-install}. Notably -- even when not specified -- > +@code{:rev} defaults to checking out the last release of the package. > +You can use @code{:rev :newest} to check out the latest commit. > + > +For example, > + > +@example > +@group > +(use-package bbdb > + :vc (:url "https://git.savannah.nongnu.org/git/bbdb.git" > + :rev :newest)) > +@end group > +@end example > + > +would try -- by invoking @code{package-vc-install} -- to install the > +latest commit of the package @code{foo} from the specified remote. ^^^ A typo there. Also, you say above "the latest release", but then "the latest commit". These two are not the same, and in fact I think talking about "release" here is misleading, since you actually mean "commit". For the same reason, I think the text should explain how to indicate a commit that is not the latest one, because that is also not self-evident, especially since the upstream VCS is not necessarily Git. > +*** New ':vc' keyword. "*** New keyword ':vc'." > +This keyword enables the user to control how packages are fetched by > +utilising 'package-vc.el'. By default, it relays its arguments to We use US English spelling: "utilizing". But I would actually suggest to say "using" instead: there's no need to use overly-complicated words when simpler ones will do. > +'package-vc-install', but -- when combined with the ':load-path' > +keyword -- it can also call upon 'package-vc-install-from-checkout' > +instead. If no revision is given via the ':rev' argument, use-package > +falls back to the last release (via 'package-vc-install's > +':last-release' argument). To check out the last commit, use ':rev > +:newest'. Here, again, you mix up "release", "revision", and "commit". It is always better to use consistent terminology, and in this case I think only "commit" is accurate. Thanks.