From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eshel Yaron via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#65386: [PATCH] ; Refine some 'package-vc' docstrings Date: Sat, 19 Aug 2023 22:42:57 +0200 Message-ID: References: <83msymyfun.fsf@gnu.org> Reply-To: Eshel Yaron 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="15948"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: philipk@posteo.net, 65386@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Aug 19 22:44:21 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 1qXSo0-0003yR-PX for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 19 Aug 2023 22:44:20 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qXSni-0006pn-Pl; Sat, 19 Aug 2023 16:44:02 -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 1qXSnh-0006pf-CO for bug-gnu-emacs@gnu.org; Sat, 19 Aug 2023 16:44:01 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qXSnh-0002Ay-4A for bug-gnu-emacs@gnu.org; Sat, 19 Aug 2023 16:44:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qXSni-00026u-9E for bug-gnu-emacs@gnu.org; Sat, 19 Aug 2023 16:44:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eshel Yaron Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 19 Aug 2023 20:44:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 65386 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 65386-submit@debbugs.gnu.org id=B65386.16924777888045 (code B ref 65386); Sat, 19 Aug 2023 20:44:02 +0000 Original-Received: (at 65386) by debbugs.gnu.org; 19 Aug 2023 20:43:08 +0000 Original-Received: from localhost ([127.0.0.1]:52369 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qXSmo-00025g-Ee for submit@debbugs.gnu.org; Sat, 19 Aug 2023 16:43:07 -0400 Original-Received: from mail.eshelyaron.com ([107.175.124.16]:34364 helo=eshelyaron.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qXSmj-00025D-42 for 65386@debbugs.gnu.org; Sat, 19 Aug 2023 16:43:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1692477779; bh=MPl/oFnC76pNj/yMFjzJLsx7XxCOkm+hZ0X1RZ8jsXs=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=j3HTFu+dcidP3UPFt+/MO0z11mvWOdV8JU1ViN/9VDWlxX0zQ+5AIKNUCF+OD1CMP ykou2k9Xkrtlp3N2fzgspT4f9wlFvr0vQV2o87CR7dIXt83b1ULCVbqD6BVdcsHrxP SPutVxTudNP+c0UBe6EafSNMqH19sz9RKXLqOnmvy7Rr/unJJqGwHOlAi1m85/vh1t ejokW3/UPprnoRRnL+4QUHHmOPQZ+/eOlyos2aERMQAVzX50K+fAYG4SkBstYSPdFw 1dwBk8Z/7btYK8uJbHWY47hIL+ckITQpg3ML/r+wpUai67kkN9Qve7HIYxmKZDjTxz uH7LvjAJkjrcA== In-Reply-To: <83msymyfun.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 19 Aug 2023 22:47:12 +0300") 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:267916 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> Cc: Philip Kaludercic >> Date: Sat, 19 Aug 2023 20:07:07 +0200 >> From: Eshel Yaron via "Bug reports for GNU Emacs, >> the Swiss army knife of text editors" >> >> This patch includes improvement suggestions for the docstrings of some >> of the functions and user options in package-vc.el. > > Thanks. Allow me a few comments: > Thank you, I've attached an updated patch below. >> @@ -94,7 +94,10 @@ package-vc-heuristic-alist >> (+ (or alnum "-" "." "_")) (? "/"))) >> eos) >> . Bzr)) >> - "Heuristic mapping URL regular expressions to VC backends." >> + "Alist mapping regular expressions to VC backends. > > The first line loses information by omitting the "URL" part, which I > think is important, more important than the "regular expressions" > part. How about > > Alist mapping repository URLs to VC backends. > Sure, done. >> +`package-vc-install' tries to match each regular expression in >> +this alist to the repository URL you give it, and uses the VC >> +backend corresponding to the first matching regular expression." > > This tends to describe the implementation, not the purpose. I would > rephrase > > `package-vc-install' consults this alist to determine the VC backend > from the repository URL. Each element of the alist has the form > (URL-REGEXP . BACKEND). `package-vc-install' will use BACKEND of > the first association for which the URL of the repository matches > the URL-REGEXP of the association. > Done. >> (defcustom package-vc-default-backend 'Git >> - "Default VC backend used when cloning a package repository. >> -If no repository type was specified or could be guessed by >> -`package-vc-heuristic-alist', this is the default VC backend >> -used as fallback. The value must be a member of >> -`vc-handled-backends' and the named backend must implement >> -the `clone' function." >> - :type `(choice ,@(mapcar (lambda (b) (list 'const b)) >> - vc-handled-backends)) >> + "Default VC backend to use for cloning package repositories. >> +`package-vc-install' uses this backend when you don't specify a >> +backend and give it a URL that doesn't match any regular >> +expression in `package-vc-heuristic-alist'. > > I guess you mean > > `package-vc-install' uses this backend when you specify neither the > backend nor a repository URL to map via `package-vc-heuristic-alist'. > I went with a variation of your phrasing that I think is a little more precise. LMK what you think. >> + >> +The value must be a member of `vc-handled-backends' that supports >> +the `clone' VC function." >> + :type `(choice ,@(seq-keep >> + (lambda (be) >> + (when (or (vc-find-backend-function be 'clone) >> + (alist-get 'clone (get be 'vc-functions))) >> + (list 'const be))) >> + vc-handled-backends)) >> :version "29.1") >> >> (defcustom package-vc-register-as-project t >> @@ -140,20 +148,21 @@ package-vc-install-selected-packages >> (package-desc-create :name name :kind 'vc)) >> spec))))))) >> >> -(defcustom package-vc-selected-packages '() >> - "List of packages that must be installed. >> -Each member of the list is of the form (NAME . SPEC), where NAME >> -is a symbol designating the package and SPEC is one of: >> + >> +(defcustom package-vc-selected-packages nil >> + "List of packages to install from source. > > What is the significance of "from source" here? > It's just for indicating that we're talking about VC packages specifically. Does that make sense? >> +The command `package-vc-install' updates the value of this user >> +option to store package specifications for packages that are not >> +specified in any archive." > > I question the wisdom of having commands modify values of user > options. I think it is better to have a separate variable whose > initial value is taken from the user option, and then have the > commands add to that separate variable, leaving the user option > intact. > Yes, this patch only updates the documentation, but I agree that this behavior may deserve another look as well. >> (defcustom package-vc-allow-side-effects nil >> - "Whether to process :make and :shell-command spec arguments. >> + "Whether to run extra build commands when installing VC packages. > > The name of this variable is very far from what it means. Running > commands and "side effects" are barely related to each other. Please > consider renaming the variable. How about > package-vc-allow-build-commands? > I agree. Philip, any objections to renaming this variable? I don't know if people already use it. >> + When >> +this option is nil, Emacs ignores these keywords when installing >> +and upgrading VC packages. If it's a list of package >> +names (symbols), Emacs only runs these extra build commands for >> +those packages. > > "By default, Emacs ignores these keywords [...], but if the value is a > list of package names (symbols), the build commands will be run for > those packages." > Done. >> (defun package-vc-install-dependencies (requirements) >> - "Install missing dependencies, and return missing ones. >> -The return value will be nil if everything was found, or a list >> -of (NAME VERSION) pairs of all packages that couldn't be found. >> - >> -REQUIREMENTS should be a list of additional requirements; each >> -element in this list should have the form (PACKAGE VERSION-LIST), >> -where PACKAGE is a package name and VERSION-LIST is the required >> -version of that package." >> + "Install missing dependencies according to REQUIREMENTS. >> + >> +REQUIREMENTS is a list of elements (PACKAGE VERSION-LIST), where >> +PACKAGE is a package name and VERSION-LIST is the required >> +version of that package. > > This seems to indicate that REQUIREMENTS should be renamed to > DEPENDENCIES. > Alright, I went with DEPS for brevity. >> +Return a list of requirements that couldn't be met (or nil, when >> +this function successfully installs all given requirements)." > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > "Installs requirements"? that's why "dependencies" would be better. > Updated. >> (defun package-vc-upgrade (pkg-desc) >> - "Attempt to upgrade the package PKG-DESC." >> + "Upgrade the VC package that PKG-DESC describes." > > "Upgrade the package described by PKG-DESC from the package's VC repository." > Done. >> (defun package-vc-install (package &optional rev backend name) >> "Fetch a PACKAGE and set it up for using with Emacs. > > "Fetch a package described by PACKAGE and set it up for use with Emacs." > > (The point being that PACKAGE is not just a name, it's a description > that can have several forms.) > Updated. >> -If PACKAGE is a string containing an URL, download the package >> -from the repository at that URL; the function will try to guess >> -the name of the package from the URL. This can be overridden by >> -passing the optional argument NAME. If PACKAGE is a cons-cell, >> -it should have the form (NAME . SPEC), where NAME is a symbol >> -indicating the package name and SPEC is a plist as described in >> -`package-vc-selected-packages'. Otherwise PACKAGE should be a >> -symbol whose name is the package name, and the URL for the >> -package will be taken from the package's metadata. >> +PACKAGE specifies which package to install, where to find its >> +source repository and how to build it. >> >> By default, this function installs the last revision of the >> package available from its repository. If REV is a string, it >> -describes the revision to install, as interpreted by the VC >> -backend. The special value `:last-release' (interactively, the >> -prefix argument), will use the commit of the latest release, if >> -it exists. The last release is the latest revision which changed >> -the \"Version:\" header of the package's main Lisp file. >> - >> -Optional argument BACKEND specifies the VC backend to use for cloning >> -the package's repository; this is only possible if NAME-OR-URL is a URL, >> -a string. If BACKEND is omitted or nil, the function >> -uses `package-vc-heuristic-alist' to guess the backend. >> -Note that by default, a VC package will be prioritized over a >> -regular package, but it will not remove a VC package. >> - >> -\(fn PACKAGE &optional REV BACKEND)" >> +describes the revision to install, as interpreted by the relevant >> +VC backend. The special value `:last-release' (interactively, >> +the prefix argument), says to use the commit of the latest >> +release, if it exists. The last release is the latest revision >> +which changed the \"Version:\" header of the package's main Lisp >> +file. >> + >> +If PACKAGE is a symbol, install the package with that name >> +according to metadata that package archives provide for it. This >> +is the simplest way to call this function, but it only works if >> +the package you want to install is listed in a package archive >> +you have configured. >> + >> +If PACKAGE is a string, it specifies the URL of the package >> +repository. In this case, optional argument BACKEND specifies >> +the VC backend to use for cloning the repository; if it's nil, >> +this function tries to infer which backend to use according to >> +the value of `package-vc-heuristic-alist' and if that fails it >> +uses `package-vc-default-backend'. Optional argument NAME >> +specifies the package name in this case; if it's nil, this >> +package uses `file-name-base' on the URL to obtain the package >> +name, otherwise NAME is the package name as a symbol. >> + >> +PACKAGE can also be a cons cell (PNAME . SPEC) where PNAME is the >> +package name as a symbol, and SPEC is a plist that specifes how >> +to fetch and build the package. For possible values, see the >> +subsection \"Specifying Package Sources\" in the Info >> +node `(emacs)Fetching Package Sources'. > > I think the doc string should describe PACKAGE before REV. > Sure, done. >> +If you use this function to install a package that you also have >> +installed from a package archive, the version this function >> +installs is takes precedence." > > "is takes"? something's wrong here. > Good catch, thanks. I've removed the "is" in the updated patch. >> (defun package-vc-prepare-patch (pkg-desc subject revisions) >> - "Send patch for REVISIONS to maintainer of the package PKG using SUBJECT. >> + "Send patch for REVISIONS to maintainer of the package PKG-DESC using SUBJECT. > > This should mention email, otherwise SUBJECT is confusing. Maybe use > "Email" instead of "Send". Alright, I made a couple more changes to this one. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=v2-0001-Refine-some-package-vc-docstrings.patch >From 213675085fd77246fcbf6ad0cc5134081e4a66d4 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Fri, 18 Aug 2023 21:59:10 +0200 Subject: [PATCH v2] ; Refine some 'package-vc' docstrings * lisp/emacs-lisp/package-vc.el (package-vc-heuristic-alist) (package-vc-install-dependencies, package-vc-upgrade) (package-vc-install, package-vc-install-from-checkout) (package-vc-prepare-patch, package-vc-upgrade-all) (package-vc-allow-side-effects): Refine docstrings. (package-vc-default-backend): Refine docstring and custom type. --- lisp/emacs-lisp/package-vc.el | 167 ++++++++++++++++++++-------------- 1 file changed, 100 insertions(+), 67 deletions(-) diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el index db8b41aee6a..bf0e024ec19 100644 --- a/lisp/emacs-lisp/package-vc.el +++ b/lisp/emacs-lisp/package-vc.el @@ -94,7 +94,12 @@ package-vc-heuristic-alist (+ (or alnum "-" "." "_")) (? "/"))) eos) . Bzr)) - "Heuristic mapping URL regular expressions to VC backends." + "Alist mapping repository URLs to VC backends. +`package-vc-install' consults this alist to determine the VC backend +from the repository URL. Each element of the alist has the form +(URL-REGEXP . BACKEND). `package-vc-install' will use BACKEND of +the first association for which the URL of the repository matches +the URL-REGEXP of the association." :type `(alist :key-type (regexp :tag "Regular expression matching URLs") :value-type (choice :tag "VC Backend" ,@(mapcar (lambda (b) `(const ,b)) @@ -102,14 +107,19 @@ package-vc-heuristic-alist :version "29.1") (defcustom package-vc-default-backend 'Git - "Default VC backend used when cloning a package repository. -If no repository type was specified or could be guessed by -`package-vc-heuristic-alist', this is the default VC backend -used as fallback. The value must be a member of -`vc-handled-backends' and the named backend must implement -the `clone' function." - :type `(choice ,@(mapcar (lambda (b) (list 'const b)) - vc-handled-backends)) + "Default VC backend to use for cloning package repositories. +`package-vc-install' uses this backend when you specify neither +the backend nor a repository URL that's recognized via +`package-vc-heuristic-alist'. + +The value must be a member of `vc-handled-backends' that supports +the `clone' VC function." + :type `(choice ,@(seq-keep + (lambda (be) + (when (or (vc-find-backend-function be 'clone) + (alist-get 'clone (get be 'vc-functions))) + (list 'const be))) + vc-handled-backends)) :version "29.1") (defcustom package-vc-register-as-project t @@ -140,20 +150,21 @@ package-vc-install-selected-packages (package-desc-create :name name :kind 'vc)) spec))))))) -(defcustom package-vc-selected-packages '() - "List of packages that must be installed. -Each member of the list is of the form (NAME . SPEC), where NAME -is a symbol designating the package and SPEC is one of: + +(defcustom package-vc-selected-packages nil + "List of packages to install from source. +Each element is of the form (NAME . SPEC), where NAME is a symbol +designating the package and SPEC is one of: - nil, if any package version can be installed; - a version string, if that specific revision is to be installed; -- a property list, describing a package specification. For more - details, please consult the subsection \"Specifying Package - Sources\" in the Info node `(emacs)Fetching Package Sources'. +- a property list, describing a package specification. For possible + values, see the subsection \"Specifying Package Sources\" in the + Info node `(emacs)Fetching Package Sources'. -This user option will be automatically updated to store package -specifications for packages that are not specified in any -archive." +The command `package-vc-install' updates the value of this user +option to store package specifications for packages that are not +specified in any archive." :type '(alist :tag "List of packages you want to be installed" :key-type (symbol :tag "Package") :value-type @@ -345,19 +356,26 @@ package-vc--generate-description-file nil pkg-file nil 'silent)))) (defcustom package-vc-allow-side-effects nil - "Whether to process :make and :shell-command spec arguments. + "Whether to run extra build commands when installing VC packages. + +Some packages specify \"make\" targets or other shell commands +that should run prior to building the package, by including the +:make or :shell-command keywords in their specification. By +default, Emacs ignores these keywords when installing and +upgrading VC packages, but if the value is a list of package +names (symbols), the build commands will be run for those +packages. A non-nil non-list value says to always respect :make +and :shell-command keywords. It may be necessary to run :make and :shell-command arguments in order to initialize a package or build its documentation, but please be careful when changing this option, as installing and updating a package can run potentially harmful code. -When set to a list of symbols (packages), run commands for only -packages in the list. When nil, never run commands. Otherwise -when non-nil, run commands for any package with :make or -:shell-command specified. - -Package specs are loaded from trusted package archives." +This applies to package specifications that come from your +configured package archives, as well as from entries in +`package-vc-selected-packages' and specifications that you give +to `package-vc-install' directly." :type '(choice (const :tag "Run for all packages" t) (repeat :tag "Run only for selected packages" (symbol :tag "Package name")) (const :tag "Never run" nil)) @@ -414,15 +432,15 @@ package-vc--build-documentation (when clean-up (delete-file file)))) -(defun package-vc-install-dependencies (requirements) - "Install missing dependencies, and return missing ones. -The return value will be nil if everything was found, or a list -of (NAME VERSION) pairs of all packages that couldn't be found. +(defun package-vc-install-dependencies (deps) + "Install missing dependencies according to DEPS. + +DEPS is a list of elements (PACKAGE VERSION-LIST), where +PACKAGE is a package name and VERSION-LIST is the required +version of that package. -REQUIREMENTS should be a list of additional requirements; each -element in this list should have the form (PACKAGE VERSION-LIST), -where PACKAGE is a package name and VERSION-LIST is the required -version of that package." +Return a list of dependencies that couldn't be met (or nil, when +this function successfully installs all given dependencies)." (let ((to-install '()) (missing '())) (cl-labels ((search (pkg) "Attempt to find all dependencies for PKG." @@ -458,7 +476,7 @@ package-vc-install-dependencies (or (not desc-a) (not desc-b) (not (depends-on-p desc-b desc-a)) (depends-on-p desc-a desc-b))))) - (mapc #'search requirements) + (mapc #'search deps) (cl-callf sort to-install #'version-order) (cl-callf seq-uniq to-install #'duplicate-p) (cl-callf sort to-install #'dependent-order)) @@ -719,7 +737,7 @@ package-vc--read-package-desc ;;;###autoload (defun package-vc-upgrade-all () - "Attempt to upgrade all installed VC packages." + "Upgrade all installed VC packages." (interactive) (dolist (package package-alist) (dolist (pkg-desc (cdr package)) @@ -729,7 +747,7 @@ package-vc-upgrade-all ;;;###autoload (defun package-vc-upgrade (pkg-desc) - "Attempt to upgrade the package PKG-DESC." + "Upgrade the package described by PKG-DESC from package's VC repository." (interactive (list (package-vc--read-package-desc "Upgrade VC package: " t))) ;; HACK: To run `package-vc--unpack-1' after checking out the new ;; revision, we insert a hook into `vc-post-command-functions', and @@ -792,34 +810,45 @@ package-vc--release-rev ;;;###autoload (defun package-vc-install (package &optional rev backend name) - "Fetch a PACKAGE and set it up for using with Emacs. - -If PACKAGE is a string containing an URL, download the package -from the repository at that URL; the function will try to guess -the name of the package from the URL. This can be overridden by -passing the optional argument NAME. If PACKAGE is a cons-cell, -it should have the form (NAME . SPEC), where NAME is a symbol -indicating the package name and SPEC is a plist as described in -`package-vc-selected-packages'. Otherwise PACKAGE should be a -symbol whose name is the package name, and the URL for the -package will be taken from the package's metadata. + "Fetch a package described by PACKAGE and set it up for use with Emacs. + +PACKAGE specifies which package to install, where to find its +source repository and how to build it. + +If PACKAGE is a symbol, install the package with that name +according to metadata that package archives provide for it. This +is the simplest way to call this function, but it only works if +the package you want to install is listed in a package archive +you have configured. + +If PACKAGE is a string, it specifies the URL of the package +repository. In this case, optional argument BACKEND specifies +the VC backend to use for cloning the repository; if it's nil, +this function tries to infer which backend to use according to +the value of `package-vc-heuristic-alist' and if that fails it +uses `package-vc-default-backend'. Optional argument NAME +specifies the package name in this case; if it's nil, this +package uses `file-name-base' on the URL to obtain the package +name, otherwise NAME is the package name as a symbol. + +PACKAGE can also be a cons cell (PNAME . SPEC) where PNAME is the +package name as a symbol, and SPEC is a plist that specifes how +to fetch and build the package. For possible values, see the +subsection \"Specifying Package Sources\" in the Info +node `(emacs)Fetching Package Sources'. By default, this function installs the last revision of the package available from its repository. If REV is a string, it -describes the revision to install, as interpreted by the VC -backend. The special value `:last-release' (interactively, the -prefix argument), will use the commit of the latest release, if -it exists. The last release is the latest revision which changed -the \"Version:\" header of the package's main Lisp file. - -Optional argument BACKEND specifies the VC backend to use for cloning -the package's repository; this is only possible if NAME-OR-URL is a URL, -a string. If BACKEND is omitted or nil, the function -uses `package-vc-heuristic-alist' to guess the backend. -Note that by default, a VC package will be prioritized over a -regular package, but it will not remove a VC package. - -\(fn PACKAGE &optional REV BACKEND)" +describes the revision to install, as interpreted by the relevant +VC backend. The special value `:last-release' (interactively, +the prefix argument), says to use the commit of the latest +release, if it exists. The last release is the latest revision +which changed the \"Version:\" header of the package's main Lisp +file. + +If you use this function to install a package that you also have +installed from a package archive, the version this function +installs takes precedence." (interactive (progn ;; Initialize the package system to get the list of package @@ -895,7 +924,7 @@ package-vc-checkout ;;;###autoload (defun package-vc-install-from-checkout (dir name) - "Set up the package NAME in DIR by linking it into the ELPA directory. + "Install the package NAME from its source directory DIR. Interactively, prompt the user for DIR, which should be a directory under version control, typically one created by `package-vc-checkout'. If invoked interactively with a prefix argument, prompt the user @@ -937,13 +966,17 @@ package-vc-rebuild ;;;###autoload (defun package-vc-prepare-patch (pkg-desc subject revisions) - "Send patch for REVISIONS to maintainer of the package PKG using SUBJECT. -The function uses `vc-prepare-patch', passing SUBJECT and -REVISIONS directly. PKG-DESC must be a package description. + "Email patches for REVISIONS to the maintainer of the package PKG-DESC. + +PKG-DESC is a package description and SUBJECT is the subject of +the message. + Interactively, prompt for PKG-DESC, SUBJECT, and REVISIONS. When invoked with a numerical prefix argument, use the last N revisions. When invoked interactively in a Log View buffer with -marked revisions, use those." +marked revisions, use those. + +See also `vc-prepare-patch'." (interactive (list (package-vc--read-package-desc "Package to prepare a patch for: " t) (and (not vc-prepare-patches-separately) -- 2.41.0 --=-=-=--