From 07c00d430a3b213a0b8a8e4f107b8b6e4d54a9fd 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 (Specifying Package Sources): List the accepted keys in a new subsection of Fetching Package Sources. * lisp/emacs-lisp/package-vc.el (package-vc-selected-packages): - Mention the `:doc` key. Add the `:doc` key to the Customize form. - Mention the new Info node. - Correct "TexInfo" to "Texinfo". - Avoid Git-specific terms for the description of `:branch`. - Mention guessing `:vc-backend` based on the URL. --- doc/emacs/package.texi | 77 +++++++++++++++++++++++++++++++++++ lisp/emacs-lisp/package-vc.el | 30 ++------------ 2 files changed, 81 insertions(+), 26 deletions(-) diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 7a2bc11d03c..205a14c6c4d 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -578,3 +578,80 @@ 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. + +@subsection Specifying Package Sources +@cindex package specification +@cindex specification, for source packages + + To install a package from source, Emacs must know where to get the +package's source code (such as a code repository) and basic +information about the structure of the code (such as the main file in +a multi-file package). These properties are described by a package's +@dfn{specification}. + + When supported by a package archive (@pxref{Package +Archives,,,elisp, The Emacs Lisp Reference Manual}), Emacs can +automatically download a package's specification from said archive. +If the first argument passed to @code{package-vc-install} is a symbol +naming a package, then Emacs will use the specification provided by +the archive for that package. + +@example +@group +;; Emacs will download BBDB's specification from GNU ELPA: +(package-vc-install 'bbdb) +@end group +@end example + + A package's specification can also be given manually as the first +argument to @code{package-vc-install}. This allows you to install +source packages from locations other than the known archives listed in +the user option @code{package-archives}. A package specification is a +list of the form @code{(@var{name} . @var{spec})}, in which @var{spec} +should be a property list using any of the keys in the table below. + +For definitions of basic terms for working with code repositories and +version control systems, see @ref{VCS Concepts,,,emacs, The GNU Emacs +Manual}. + +@table @code +@item :url +A string providing the URL that specifies the repository from which to +fetch the package's source code. + +@item :branch +A string providing the revision of the code to install. This is not +to be confused with a package's version number. + +@item :lisp-dir +A string providing the repository-relative name of the directory to +use for loading the Lisp sources, which defaults to the root directory +of the repository. + +@item :main-file +A string providing the main file of the project, from which to gather +package metadata. If not given, the default is the package name with +".el" appended to it. + +@item :doc +A string providing 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 :vc-backend +A symbol naming the VC backend to use for downloading a copy of the +package's repository (@pxref{Version Control Systems,,,emacs, The GNU +Emacs Manual}). If omitted, a guess will be made based on the +provided URL, or, failing that, the process will fall back onto the +value of @code{package-vc-default-backend}. +@end table + +@example +@group +;; Specifying information manually: +(package-vc-install + '(bbdb :url "https://git.savannah.nongnu.org/git/bbdb.git" + :lisp-dir "lisp" + :doc "doc/bbdb.texi")) +@end group +@end example diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el index 253b35f1f1a..1d29f8dbbd1 100644 --- a/lisp/emacs-lisp/package-vc.el +++ b/lisp/emacs-lisp/package-vc.el @@ -145,32 +145,9 @@ package-vc-selected-packages - 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. Valid - key/value pairs are - - `:url' (string) - The URL of the repository used to fetch the package source. - - `:branch' (string) - If given, the name of the branch to checkout after cloning the directory. - - `:lisp-dir' (string) - The repository-relative name of the directory to use for loading the Lisp - sources. If not given, the value defaults to the root directory - of the repository. - - `:main-file' (string) - The main file of the project, relevant to gather package metadata. - If not given, the assumed default is the package name with \".el\" - appended to it. - - `: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, - `vc-clone' will fall back onto the archive default or on - `package-vc-default-backend'. - - All other keys are ignored. +- 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'. This user option will be automatically updated to store package specifications for packages that are not specified in any @@ -184,6 +161,7 @@ package-vc-selected-packages (:branch string) (:lisp-dir string) (:main-file string) + (:doc string) (:vc-backend symbol))))) :version "29.1") -- 2.34.1