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

[Okamsn <okamsn@protonmail.com>]

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

On 2023-03-28 07:41 UTC, Philip Kaludercic wrote:
>>  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.
>
> Should a sub-heading inside the same node be added here?

I have added one.

>
>> +
>> +There are two ways for Emacs to learn how and whence to install a
>> +package from source.  The first way, when supported, is to
>                                          ^
>
> The phrasing "when supported" doesn't sound clear.  The user doesn't
> know what this depends on.

I have tried to make it clear that it depends on the archive.

>> +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.
>
> I have the feeling the phrase "package specification" should be
> mentioned somewhere here.


I added this phrase.

>> +@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.
>
> At the risk of being pedantic, we check out the right branch /while/
> cloning, not /after/ cloning and I don't know if that matters.  (I also
> just now noticed that I used the same phrasing in the documentation
> string for `package-vc-selected-packages').

I tried to do as Eli Zaretskii asked and changed it to be less Git
specific.  Does it still convey what you want?

>> +@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}.
>
> Should we link to (emacs) Version Control here?

Linked to the VC Concepts above the list.

>> +;; Specifying information manually:
>> +(package-vc-install
>> +  '(csv-mode :url "https://git.sv.gnu.org/git/emacs/elpa.git"
>> +             :branch "externals/csv-mode"))
>
> I worry that this example might be confusing, for those people who don't
> know how ELPA works.  It would either be worth mentioning that elpa.git
> is a mirror with different packages on different branches, or to take
> some other example (like AucTeX).

I switched it to BBDB, which uses several keys.
> I guess it will be good to also add :doc to the user option type.

Done.

On 2023-03-28 11:48 UTC, Eli Zaretskii wrote:
 >> +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.
 >     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 > Passive voice alert!  Could you perhaps rephrase this avoiding the
 > passive voice?

I have reworded it.  Please check again.

 >> +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
 >
 > This should be @code, not @samp.

Done.

 >> +list using any of the following keys:
 >> +
 >> +@itemize @bullet
 >
 > This should be "@table @code", not @itemize.  The result is more
 > readable.  @itemize is for free text, not for systematic description
 > of several optional features and attributes.

Done.

 >> +@item @code{:branch}
 >> +The name of the branch to checkout after cloning the directory.
 >         ^^^^^^^^^^^^^^^^^^    ^^^^^^^^       ^^^^^^^
 > Can we make this less Git-specific?

Attempted, but I have only used Git.  I linked to the VCS Concepts
section above the list.

 >> +@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.
 >
 > The "if not" part is confusing.  I suggest ", which defaults to the
 > root directory of the repository" instead.

Done.

 >> +@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.
 >
 > I'd drop the "assumed" part.  It adds nothing to the description.

Done.

 >> +@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.
 >                       ^^
 > Two spaces there, please.  Also, the spelling is "Texinfo", not
 > "TexInfo".

Done.

 >> +@item @code{:vc-backend}
 >> +The VC backend to use for cloning the package.  If omitted,
 >
 > A cross-reference here to the place where VC backends are described
 > would be good.

Done.

 >> +the process will fall back onto the archive default or onto
 >> +the value of @code{package-vc-default-backend}.
 >
 > What does it mean to "fall back onto the archive default"?

Each archive has a default backend.  As that's not relevant to
specifying the information manually, I've removed it.

 >> +   `:doc' (string)
 >> +      The documentation file from which to build an Info file.
 >> +      This can be a TexInfo file or an Org file.
 >                         ^^^^^^^
 > Spelling again.

Fixed.

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

From 0024726c24f16976f1b472afe8e079e5892517b5 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 | 25 ++++++++----
 2 files changed, 93 insertions(+), 9 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 7a2bc11d03c..7ad4143d3cb 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 things 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 following keys.
+
+For definitions of basic terms for working with code repositories and
+version control systems, see @xref{VCS Concepts,,,emacs, The GNU Emacs
+Manual}.
+
+@table @code
+@item :url
+A string containing the URL that specifies the repository from which
+to fetch the package's source code.
+
+@item :branch
+A string containing the revision of the code to install.  This is not
+to be confused with a package's version number.
+
+@item :lisp-dir
+A string containing 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 containing 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 containing 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..cbc9a1ecece 100644
--- a/lisp/emacs-lisp/package-vc.el
+++ b/lisp/emacs-lisp/package-vc.el
@@ -152,25 +152,31 @@ package-vc-selected-packages
       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.
+      The repository-specific revision of the code to install.
+      This is not to be confused with a package's version number.
 
    `: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.
+      sources, which 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\"
+      If not given, the 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,
-      `vc-clone' will fall back onto the archive default or on
-      `package-vc-default-backend'.
+      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, a guess will be made based on the provided URL,
+      or, failing that, `vc-clone' will fall back onto the
+      archive default or on `package-vc-default-backend'.
 
-  All other keys are ignored.
+  All other keys are ignored.  Package specifications are further
+  described 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 +190,7 @@ package-vc-selected-packages
                                          (:branch string)
                                          (:lisp-dir string)
                                          (:main-file string)
+                                         (:doc string)
                                          (:vc-backend symbol)))))
   :version "29.1")
 
-- 
2.34.1