> 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")