From 1d4d4ebfd874d99d5e2d29078f3316f49dcf3136 Mon Sep 17 00:00:00 2001 From: Earl Hyatt Date: Mon, 27 Mar 2023 20:57:31 -0400 Subject: [PATCH] Add more documentation for the keys of `package-vc-selected-packages`. * doc/emacs/package.texi (Fetching Package Sources): List the accepted keys. * lisp/emacs-lisp/package-vc.el (package-vc-selected-packages): Mention the `:doc` key. --- doc/emacs/package.texi | 53 +++++++++++++++++++++++++++++++++++ lisp/emacs-lisp/package-vc.el | 4 +++ 2 files changed, 57 insertions(+) diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 7a2bc11d03c..6f1fad2291a 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -578,3 +578,56 @@ Fetching Package Sources and initializes the code. Note that you might have to use @code{package-vc-refresh} to repeat the initialization and update the autoloads. + +There are two ways for Emacs to learn how and whence to install a +package from source. The first way, when supported, is to +automatically download the needed information from a package archive +(@pxref{Package Archives,,,elisp, The Emacs Lisp Reference Manual}). +This is what is done when only specifying the symbol of a package. + +@example +@group +(package-vc-install 'csv-mode) +@end group +@end example + +The second way is to specify this information manually in the first +argument of @code{package-vc-install}, in the form of +@samp{(@var{name} . @var{spec})}. @var{spec} should be a property +list using any of the following keys: + +@itemize @bullet +@item @code{:url} +A URL specifying the repository from which to fetch the package's +source code. + +@item @code{:branch} +The name of the branch to checkout after cloning the directory. + +@item @code{:lisp-dir} +The repository-relative name of the directory to use for loading the +Lisp sources, if not the root directory of the repository. + +@item @code{:main-file} +The main file of the project, from which to gather package metadata. +If not given, the assumed default is the package name with ".el" +appended to it. + +@item @code{:doc} +The repository-relative name of the documentation file from which to +build an Info file. This can be a TexInfo file or an Org file. + +@item @code{:vc-backend} +The VC backend to use for cloning the package. If omitted, +the process will fall back onto the archive default or onto +the value of @code{package-vc-default-backend}. +@end itemize + +@example +@group +;; Specifying information manually: +(package-vc-install + '(csv-mode :url "https://git.sv.gnu.org/git/emacs/elpa.git" + :branch "externals/csv-mode")) +@end group +@end example diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el index 253b35f1f1a..e75dbac3061 100644 --- a/lisp/emacs-lisp/package-vc.el +++ b/lisp/emacs-lisp/package-vc.el @@ -164,6 +164,10 @@ package-vc-selected-packages If not given, the assumed default is the package name with \".el\" appended to it. + `:doc' (string) + The documentation file from which to build an Info file. + This can be a TexInfo file or an Org file. + `:vc-backend' (symbol) A symbol of the VC backend to use for cloning the package. The value ought to be a member of `vc-handled-backends'. If omitted, -- 2.34.1