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

[Okamsn <okamsn@protonmail.com>]

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

On 2023-03-16 08:44 UTC, Philip Kaludercic wrote:
>> Are the keys used by the ELPA package specification documented in the
>> manual? If not, I would like to list the keys accepted at the end of the
>> Package VC manual page, take from here:
>> https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README
>
> Yes, exactly.
>
>> I will write a patch for this, unless there is a reason to not do so.
>> What do you think?
>
> If you think it can be clarified, why not?

I have tried to write a patch doing this (attached).  I think that each
of the keys supported by Package VC should be listed in the
documentation, but I'm still not sure which keys those are.
In the patch, these are currently listed:

- `:url`
- `:branch`
- `:lisp-dir`
- `:main-file`
- `:doc`
- `:vc-backend`

I did not see any others. Are there others?

I have listed these keys at the end of the Texi file, based on what was
in the documentation string. For the information in the manual, should
the data type be included?

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

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