From 1d4d4ebfd874d99d5e2d29078f3316f49dcf3136 Mon Sep 17 00:00:00 2001
From: Earl Hyatt <okamsn@protonmail.com>
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