GNU bug report logs - #60418
[PATCH] Add :vc keyword to use-package

Previous Next

Full log

Message #94 received at 60418 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tony Zorman <soliditsallgood <at> mailbox.org>
Cc: philipk <at> posteo.net, felician.nemeth <at> gmail.com, 60418 <at> debbugs.gnu.org,
 stefankangas <at> gmail.com
Subject: Re: bug#60418: [PATCH] Add :vc keyword to use-package
Date: Tue, 02 May 2023 15:40:14 +0300

> From: Tony Zorman <soliditsallgood <at> mailbox.org>
> Cc: Eli Zaretskii <eliz <at> gnu.org>, 60418 <at> debbugs.gnu.org,
>  felician.nemeth <at> gmail.com, stefankangas <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.