Re: How to install documentation in sub-directory with Package VC?

[Okamsn <okamsn@protonmail.com>]

[-- Attachment #1: Type: text/plain, Size: 461 bytes --]

On 2023-04-10 13:39 UTC, Philip Kaludercic wrote:
> Just pinging to see if you want to finish this or if I should modify the
> patch?  Seeing as the Emacs 29 release is coming closer, I'd rather have
> this fixed sooner than later.

Sorry about that.  Please see the attached file, and please modify as
you see fit.  I am happy with it, but my only opinion is that all of the
currently supported keys should be given in the manual, which this does.



[-- Attachment #2: 0001-Add-more-documentation-for-the-keys-of-package-vc-se.patch --]
[-- Type: text/x-patch, Size: 6136 bytes --]

From 07c00d430a3b213a0b8a8e4f107b8b6e4d54a9fd 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 (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