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

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

[Okamsn]

Hello,

I am trying to install a package I wrote using Package VC from Github:
https://github.com/okamsn/loopy/tree/fix-comp-warnings

The lisp files, which are in the root of the project, are installed, but
the documentation file "loopy.texi" is in a subfolder "doc":
https://github.com/okamsn/loopy/tree/fix-comp-warnings/doc

The presence of this file does not trigger the call to makeinfo.
The function `package-vc--unpack-1` seems to look for the keyword ":doc"
in the package description or package spec, which I have tried adding to
the file "loopy-pkg.el" and to the list passed to `package-vc-install`
as `:doc "doc/loopy.texi"`.

What is the correct way to make Package VC install the documentation
contained in the sub-folder?

Thank you.

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

[Philip Kaludercic]

Okamsn <okamsn@protonmail.com> writes:

> Hello,
>
> I am trying to install a package I wrote using Package VC from Github:
> https://github.com/okamsn/loopy/tree/fix-comp-warnings
>
> The lisp files, which are in the root of the project, are installed, but
> the documentation file "loopy.texi" is in a subfolder "doc":
> https://github.com/okamsn/loopy/tree/fix-comp-warnings/doc
>
> The presence of this file does not trigger the call to makeinfo.
> The function `package-vc--unpack-1` seems to look for the keyword ":doc"
> in the package description or package spec, which I have tried adding to
> the file "loopy-pkg.el" and to the list passed to `package-vc-install`
> as `:doc "doc/loopy.texi"`.

Note that the -pkg.el file is overwritten (as does elpa-admin.el for all
packages on GNU and NonGNU ELPA), as the package metadata is taken from
the main file.

The other issue is that -pkg.el files are used to generate package
descriptors, while :doc is part of the package specification.

> What is the correct way to make Package VC install the documentation
> contained in the sub-folder?

Package-vc uses ELPA package specifications, which you can also pass to
`package-vc-install':

        (package-vc-install '(loopy :url "https://github.com/okamsn/loopy"
                                    :doc "doc/loopy.texi"))

That being said I have found a bug in `package-vc--unpack-1' and
`package-vc--desc->spec' in that it fails to re-locate the
specification.  This is a general problem, whenever packages are
installed with a provided specification.  One trick might be to also
consult `package-vc-selected-packages', but that wouldn't solve the
issue we have here.

I believe a general fix would involve storing new or custom package
specifications in a user option, which probably cannot be
'package-vc-selected-packages', similarly to
`package-selected-packages'.

It is imaginable that we add support for a special file, sort of like
.elpaignore (say .elpaspec.eld), that could also be used to consult this
file.

> Thank you.

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

[Philip Kaludercic]

Philip Kaludercic <philipk@posteo.net> writes:

>> What is the correct way to make Package VC install the documentation
>> contained in the sub-folder?
>
> Package-vc uses ELPA package specifications, which you can also pass to
> `package-vc-install':
>
>         (package-vc-install '(loopy :url "https://github.com/okamsn/loopy"
>                                     :doc "doc/loopy.texi"))
>
> That being said I have found a bug in `package-vc--unpack-1' and
> `package-vc--desc->spec' in that it fails to re-locate the
> specification.  This is a general problem, whenever packages are
> installed with a provided specification.  One trick might be to also
> consult `package-vc-selected-packages', but that wouldn't solve the
> issue we have here.
>
> I believe a general fix would involve storing new or custom package
> specifications in a user option, which probably cannot be
> 'package-vc-selected-packages', similarly to
> `package-selected-packages'.

I have made the change alluded to here, in the commit
168165178f32fb4e20aea32858407921baf079f0, which has been pushed to the
emacs-29 branch.  This has also allowed for some other simplifications
to be made, which is nice.

The above `package-vc-install' now works on my end, and I see the Loopy
manual listed under (dir)Top.

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

[Okamsn]

On 2023-03-15 09:41 UTC, Philip Kaludercic wrote:
> Philip Kaludercic <philipk@posteo.net> writes:
 >
>> I believe a general fix would involve storing new or custom package
>> specifications in a user option, which probably cannot be
>> 'package-vc-selected-packages', similarly to
>> `package-selected-packages'.
>
> I have made the change alluded to here, in the commit
> 168165178f32fb4e20aea32858407921baf079f0, which has been pushed to the
> emacs-29 branch.  This has also allowed for some other simplifications
> to be made, which is nice.
>
> The above `package-vc-install' now works on my end, and I see the Loopy
> manual listed under (dir)Top.
>

Thank you for making this change. With it, I see that the Info
documentation was installed.

When you write that "package-vc uses ELPA package specifications, which
you can also pass to `package-vc-install'", does that disagree with the
documentation of `package-vc-selected-packages', which states that for
its arguments "all other keys are ignored"?

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

I will write a patch for this, unless there is a reason to not do so.
What do you think?

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

[Philip Kaludercic]

Okamsn <okamsn@protonmail.com> writes:

> On 2023-03-15 09:41 UTC, Philip Kaludercic wrote:
>> Philip Kaludercic <philipk@posteo.net> writes:
>  >
>>> I believe a general fix would involve storing new or custom package
>>> specifications in a user option, which probably cannot be
>>> 'package-vc-selected-packages', similarly to
>>> `package-selected-packages'.
>>
>> I have made the change alluded to here, in the commit
>> 168165178f32fb4e20aea32858407921baf079f0, which has been pushed to the
>> emacs-29 branch.  This has also allowed for some other simplifications
>> to be made, which is nice.
>>
>> The above `package-vc-install' now works on my end, and I see the Loopy
>> manual listed under (dir)Top.
>>
>
> Thank you for making this change. With it, I see that the Info
> documentation was installed.
>
> When you write that "package-vc uses ELPA package specifications, which
> you can also pass to `package-vc-install'", does that disagree with the
> documentation of `package-vc-selected-packages', which states that for
> its arguments "all other keys are ignored"?

The "all other keys are ignored" is to be understood in the sense of
package-vc uses a subset of the keys that elpa-admin uses.  After
loading and initialising package-vc, you should in fact see a plist of
package specifications fetched from {Non,}GNU ELPA in
`package-vc--archive-spec-alist', which are used by package-vc if you
attempt to install a package using just a symbol.

> 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?

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

[Okamsn]

[-- 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

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

[Philip Kaludercic]

Okamsn <okamsn@protonmail.com> writes:

> 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?

Those should be it for now.

> 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?

We might as well.  A related matter I wonder about is if we should just
link to this section from `package-vc-selected-packages', instead of
documenting the same information twice?

> 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?

> +
> +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.

> +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.

> +@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').

> +@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?

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

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

> +@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.

I guess it will be good to also add :doc to the user option type.

>     `: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,

-- 
Philip Kaludercic

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

[Okamsn]

[-- 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

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

[Eli Zaretskii]

> Date: Sun, 02 Apr 2023 00:41:43 +0000
> From: Okamsn <okamsn@protonmail.com>
> Cc: emacs-devel@gnu.org
> 
> +For definitions of basic terms for working with code repositories and
> +version control systems, see @xref{VCS Concepts,,,emacs, The GNU Emacs
                                ^^^^^
This should be @ref.  @xref is only valid at the beginning of a
sentence, since it produces a capitalized "See".

> +@table @code
> +@item :url
> +A string containing the URL that specifies the repository from which
   ^^^^^^^^^^^^^^^^^^^
Here and elsewhere, please say "A string providing", not "A string
containing".  "Containing" can be misinterpreted to mean there's
something else in the string in addition URL etc.

Thanks.

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

[Philip Kaludercic]

Okamsn <okamsn@protonmail.com> writes:

>>> +@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?

I think it is fine now.  Thanks.

[...]

> 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
                                 ^
                                 a bit informal?  I think you can just
                                 drop the word and still convey the same
                                 information.
> +@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.

Not sure if this might be confusing.  package-vc has heuristics to try
and guess how to install a package, so it is /possible/ but not
/reliable/ to install a package from a third-party archive like MELPA.
Then again, perhaps we don't have to mention that at all in the manual,
so as to not promote an unreliable trick.

> +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}.

Should this paragraph be moved down below the table?  Otherwise the "any
of the following" reads funnily.

> +@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.

(This is true most of the time, but if you check out what
`package-vc--main-file' does, then you will see that this is not
necessary.  Again, I don't think this implementation detail is worth
documenting publicly.)

> +@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'.

I believe I mentioned this before, but what do you think about just
linking to the manual, and not duplicating the information here and
there?  It would make maintenance easier, but might not be nice for
users on systems that do not come installed with documentation like
Debian...  Then again, this wouldn't be the only place where this would
affect users.

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

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

[Okamsn]

On 2023-04-05 07:30 UTC, Philip Kaludercic wrote:
>> +  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
>                                   ^
>                                   a bit informal?  I think you can just
>                                   drop the word and still convey the same
>                                   information.

I acknowledge that "things" is unspecific, but I do think that the
paragraph flows better with a noun there.  What if "things" was swapped
out for "properties"? I think that it would work well with the use of
"property list" a few sentences later.


>> +  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.
>
> Not sure if this might be confusing.  package-vc has heuristics to try
> and guess how to install a package, so it is /possible/ but not
> /reliable/ to install a package from a third-party archive like MELPA.
> Then again, perhaps we don't have to mention that at all in the manual,
> so as to not promote an unreliable trick.

I wasn't aware of these heuristics.  In this paragraph, I was trying to
describe where the known specifications come from, as in the
"elpa-package.eld" file.

>> +@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.
>
> (This is true most of the time, but if you check out what
> `package-vc--main-file' does, then you will see that this is not
> necessary.  Again, I don't think this implementation detail is worth
> documenting publicly.)

Are you saying that you don't want to describe the heuristic, or that
you don't want to describe the default behavior? I would like to keep
the mention of the default behavior.

>> +  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}.
>
> Should this paragraph be moved down below the table?  Otherwise the "any
> of the following" reads funnily.

I don't think that this paragraph should be moved to after the table. In
my opinion, it is better to have the link, which defines the terms,
placed before the using of the terms.

Instead, what if the sentence ended like "using any of the keys in the
table below"?


>> 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
>
> I believe I mentioned this before, but what do you think about just
> linking to the manual, and not duplicating the information here and
> there?  It would make maintenance easier, but might not be nice for
> users on systems that do not come installed with documentation like
> Debian...  Then again, this wouldn't be the only place where this would
> affect users.

Some of the information in the documentation string is probably not
relevant for users wishing to give their own specification. For example,
the information about a package archive's default VC backend that Eli
Zaretskii pointed out.  Would you like to limit the information in the
table to what is relevant for giving a manual specification, or should
the table be a description of the behavior for all specifications?

If it is made more general, then I have no strong reason to disagree
with keeping the information in only one place. However, I will defer to
others on this.

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

[Philip Kaludercic]

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

Okamsn <okamsn@protonmail.com> writes:

> On 2023-04-05 07:30 UTC, Philip Kaludercic wrote:
>>> +  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
>>                                   ^
>>                                   a bit informal?  I think you can just
>>                                   drop the word and still convey the same
>>                                   information.
>
> I acknowledge that "things" is unspecific, but I do think that the
> paragraph flows better with a noun there.  What if "things" was swapped
> out for "properties"? I think that it would work well with the use of
> "property list" a few sentences later.

That sounds good!

>
>>> +  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.
>>
>> Not sure if this might be confusing.  package-vc has heuristics to try
>> and guess how to install a package, so it is /possible/ but not
>> /reliable/ to install a package from a third-party archive like MELPA.
>> Then again, perhaps we don't have to mention that at all in the manual,
>> so as to not promote an unreliable trick.
>
> I wasn't aware of these heuristics.  In this paragraph, I was trying to
> describe where the known specifications come from, as in the
> "elpa-package.eld" file.

The point here is that you can install a package listed in an archive,
even though the archive doesn't generate a  elpa-package.eld.  It works
most of the time, in the remaining cases the heuristics help but it is
not ideal.  Should this be explained?

>>> +@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.
>>
>> (This is true most of the time, but if you check out what
>> `package-vc--main-file' does, then you will see that this is not
>> necessary.  Again, I don't think this implementation detail is worth
>> documenting publicly.)
>
> Are you saying that you don't want to describe the heuristic, or that
> you don't want to describe the default behavior? I would like to keep
> the mention of the default behavior.

I don't want to document the heuristic, as IMO this is an implementation
detail.  Lets keep this the way it is.

>>> +  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}.
>>
>> Should this paragraph be moved down below the table?  Otherwise the "any
>> of the following" reads funnily.
>
> I don't think that this paragraph should be moved to after the table. In
> my opinion, it is better to have the link, which defines the terms,
> placed before the using of the terms.

Another idea would be to mark the paragraph up using @quotation,
@cartouche or a Footnote?

> Instead, what if the sentence ended like "using any of the keys in the
> table below"?

That would also be fine.

>>> 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
>>
>> I believe I mentioned this before, but what do you think about just
>> linking to the manual, and not duplicating the information here and
>> there?  It would make maintenance easier, but might not be nice for
>> users on systems that do not come installed with documentation like
>> Debian...  Then again, this wouldn't be the only place where this would
>> affect users.
>
> Some of the information in the documentation string is probably not
> relevant for users wishing to give their own specification. For example,
> the information about a package archive's default VC backend that Eli
> Zaretskii pointed out.  Would you like to limit the information in the
> table to what is relevant for giving a manual specification, or should
> the table be a description of the behavior for all specifications?

What I had in mind was just replace the ad-hoc list in the docstring
with a reference to the new section in the manual:


[-- Attachment #2: Type: text/plain, Size: 1664 bytes --]

diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
index ddc7ec4679b..6fe30e08830 100644
--- a/lisp/emacs-lisp/package-vc.el
+++ b/lisp/emacs-lisp/package-vc.el
@@ -147,32 +147,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 \"Package specification\" subsection
+  under 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

[-- Attachment #3: Type: text/plain, Size: 277 bytes --]


> If it is made more general, then I have no strong reason to disagree
> with keeping the information in only one place. However, I will defer to
> others on this.

I am just making suggestions here and am interested in what you think.
My opinion isn't worth more than yours.

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

[Philip Kaludercic]

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.

Philip Kaludercic <philipk@posteo.net> writes:

> Okamsn <okamsn@protonmail.com> writes:
>
>> On 2023-04-05 07:30 UTC, Philip Kaludercic wrote:
>>>> +  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
>>>                                   ^
>>>                                   a bit informal?  I think you can just
>>>                                   drop the word and still convey the same
>>>                                   information.
>>
>> I acknowledge that "things" is unspecific, but I do think that the
>> paragraph flows better with a noun there.  What if "things" was swapped
>> out for "properties"? I think that it would work well with the use of
>> "property list" a few sentences later.
>
> That sounds good!
>
>>
>>>> +  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.
>>>
>>> Not sure if this might be confusing.  package-vc has heuristics to try
>>> and guess how to install a package, so it is /possible/ but not
>>> /reliable/ to install a package from a third-party archive like MELPA.
>>> Then again, perhaps we don't have to mention that at all in the manual,
>>> so as to not promote an unreliable trick.
>>
>> I wasn't aware of these heuristics.  In this paragraph, I was trying to
>> describe where the known specifications come from, as in the
>> "elpa-package.eld" file.
>
> The point here is that you can install a package listed in an archive,
> even though the archive doesn't generate a  elpa-package.eld.  It works
> most of the time, in the remaining cases the heuristics help but it is
> not ideal.  Should this be explained?
>
>>>> +@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.
>>>
>>> (This is true most of the time, but if you check out what
>>> `package-vc--main-file' does, then you will see that this is not
>>> necessary.  Again, I don't think this implementation detail is worth
>>> documenting publicly.)
>>
>> Are you saying that you don't want to describe the heuristic, or that
>> you don't want to describe the default behavior? I would like to keep
>> the mention of the default behavior.
>
> I don't want to document the heuristic, as IMO this is an implementation
> detail.  Lets keep this the way it is.
>
>>>> +  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}.
>>>
>>> Should this paragraph be moved down below the table?  Otherwise the "any
>>> of the following" reads funnily.
>>
>> I don't think that this paragraph should be moved to after the table. In
>> my opinion, it is better to have the link, which defines the terms,
>> placed before the using of the terms.
>
> Another idea would be to mark the paragraph up using @quotation,
> @cartouche or a Footnote?
>
>> Instead, what if the sentence ended like "using any of the keys in the
>> table below"?
>
> That would also be fine.
>
>>>> 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
>>>
>>> I believe I mentioned this before, but what do you think about just
>>> linking to the manual, and not duplicating the information here and
>>> there?  It would make maintenance easier, but might not be nice for
>>> users on systems that do not come installed with documentation like
>>> Debian...  Then again, this wouldn't be the only place where this would
>>> affect users.
>>
>> Some of the information in the documentation string is probably not
>> relevant for users wishing to give their own specification. For example,
>> the information about a package archive's default VC backend that Eli
>> Zaretskii pointed out.  Would you like to limit the information in the
>> table to what is relevant for giving a manual specification, or should
>> the table be a description of the behavior for all specifications?
>
> What I had in mind was just replace the ad-hoc list in the docstring
> with a reference to the new section in the manual:
>
> diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
> index ddc7ec4679b..6fe30e08830 100644
> --- a/lisp/emacs-lisp/package-vc.el
> +++ b/lisp/emacs-lisp/package-vc.el
> @@ -147,32 +147,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 \"Package specification\" subsection
> +  under 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
>
>
>> If it is made more general, then I have no strong reason to disagree
>> with keeping the information in only one place. However, I will defer to
>> others on this.
>
> I am just making suggestions here and am interested in what you think.
> My opinion isn't worth more than yours.

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

[Okamsn]

[-- 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

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

[Philip Kaludercic]

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

Okamsn <okamsn@protonmail.com> writes:

> 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.

This looks good to me.  Eli would you be ok with me pushing this to
emacs-29?  There are no functional changes.

I found a few more passive phrases, which I attempted to reformulate.
In case you think this is worth addressing, how does this sound:


[-- Attachment #2: Type: text/plain, Size: 2758 bytes --]

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 205a14c6c4d..2b03399b0a7 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -586,8 +586,8 @@ Fetching Package Sources
   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}.
+a multi-file package).  A @dfn{package specification} describes these
+properties.
 
   When supported by a package archive (@pxref{Package
 Archives,,,elisp, The Emacs Lisp Reference Manual}), Emacs can
@@ -603,12 +603,12 @@ Fetching Package Sources
 @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.
+  The first argument to @code{package-vc-install} may also be a
+package specification.  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
@@ -620,8 +620,8 @@ Fetching Package Sources
 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.
+A string providing the revision of the code to install.  Do not
+confuse this with a package's version number.
 
 @item :lisp-dir
 A string providing the repository-relative name of the directory to
@@ -641,9 +641,9 @@ Fetching Package Sources
 @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}.
+Emacs Manual}).  If omitted, Emacs will attempt to make a guess 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

[-- Attachment #3: Type: text/plain, Size: 6424 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")

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

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Wed, 12 Apr 2023 07:27:23 +0000
> 
> Okamsn <okamsn@protonmail.com> writes:
> 
> > 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.
> 
> This looks good to me.  Eli would you be ok with me pushing this to
> emacs-29?  There are no functional changes.

Documentation changes are always okay on the release branch.

> I found a few more passive phrases, which I attempted to reformulate.
> In case you think this is worth addressing, how does this sound:

LGTM, thanks.

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

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Wed, 12 Apr 2023 07:27:23 +0000
>> 
>> Okamsn <okamsn@protonmail.com> writes:
>> 
>> > 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.
>> 
>> This looks good to me.  Eli would you be ok with me pushing this to
>> emacs-29?  There are no functional changes.
>
> Documentation changes are always okay on the release branch.

Great, done so.

>> I found a few more passive phrases, which I attempted to reformulate.
>> In case you think this is worth addressing, how does this sound:
>
> LGTM, thanks.

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

[Jonas Bernoulli]

Philip Kaludercic <philipk@posteo.net> writes:

>> - `:url`
>> - `:branch`
>> - `:lisp-dir`
>> - `:main-file`
>> - `:doc`
>> - `:vc-backend`
>>
>> I did not see any others. Are there others?
>
> Those should be it for now.

For what it's worth, since [1] MELPA generates a "elpa-packages.eld".
We only provide :url, and where appropriate :branch, :vc-backend and
:maintainer.  :main-file shouldn't be required because we don't accept
packages for which that would be necessary.  We don't set :doc or
:lisp-dir (yet?).

[1] https://github.com/melpa/package-build/commit/0cfcc5ce30186a5d1b92c1d

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

[Philip Kaludercic]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>>> - `:url`
>>> - `:branch`
>>> - `:lisp-dir`
>>> - `:main-file`
>>> - `:doc`
>>> - `:vc-backend`
>>>
>>> I did not see any others. Are there others?
>>
>> Those should be it for now.
>
> For what it's worth, since [1] MELPA generates a "elpa-packages.eld".

That is great!  I was planning to look at how this could be done for
MELPA, but as I am not familiar with the build-system I have been
deferring this for a while.

> We only provide :url, and where appropriate :branch, :vc-backend and
> :maintainer.  

:maintainer is currently not used (TBH I am not sure what the point of
it is in elpa-admin to begin with), so I guess you don't have to insert
that if you want to reduce the file size.

>               :main-file shouldn't be required because we don't accept
> packages for which that would be necessary.  We don't set :doc or
> :lisp-dir (yet?).

Do you think it could be possible to support :doc and :lisp-dir.  IIUC
the issue is that MELPA only accepts a list of files to include when
bundling a package (:files) and the build system would have to infer
what what is?

> [1] https://github.com/melpa/package-build/commit/0cfcc5ce30186a5d1b92c1d

-- 
Philip Kaludercic

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

[Jonas Bernoulli]

Philip Kaludercic <philipk@posteo.net> writes:

>> We only provide :url, and where appropriate :branch, :vc-backend and
>> :maintainer.  
>
> :maintainer is currently not used

Removed.

Could you please ping me when you add new properties?

> (TBH I am not sure what the point of it is in elpa-admin to begin
> with),

Sending emails to a package's maintainer.  It is used to send every
pushed commit for example.

>> We don't set :doc or :lisp-dir (yet?).
>
> Do you think it could be possible to support :doc and :lisp-dir.  IIUC
> the issue is that MELPA only accepts a list of files to include when
> bundling a package (:files) and the build system would have to infer
> what what is?

Why is :doc needed?  I think package-install simply runs makeinfo on all
texi files, but of course it can rely on them being at the top-level.
It might end up trying (and failing) to directly process gpl.texi and
similar.  But still, cannot package-vc simply do that too?

The value of :doc can also be an org file and we cannot just blindly try
to transcode *all* org files to texi.  But Melpa doesn't support
exporting ort to texi, so packages distributed there cannot assume that
that happens.  (I wish Melpa supported this and I actually implemented
it, but the main Melpa maintainers didn't want to merge it for security
reasons.)

I am not sure determining :lisp-dir from :files on the archive's side,
is easier and/or more reliable than package-vc doing it itself based
solely on what it finds in the latest commit.  In Borg I use "if lisp/
exists, then use that, else use ./" and that works for 99% of all
packages.

I think it would be better to first try to add some heuristics to
package-vc.  If that doesn't work well enough, we can still later
make package-build generate more elpa-admin-style metadata.

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

[Lynn Winebarger]

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

On Sun, Apr 9, 2023, 3:11 PM Jonas Bernoulli <jonas@bernoul.li> wrote:

> Philip Kaludercic <philipk@posteo.net> writes:
> Why is :doc needed?  I think package-install simply runs makeinfo on all
> texi files, but of course it can rely on them being at the top-level.
> It might end up trying (and failing) to directly process gpl.texi and
> similar.  But still, cannot package-vc simply do that too?
>
> The value of :doc can also be an org file and we cannot just blindly try
> to transcode *all* org files to texi.


Is there anything like the info top-level directory node for org files?

My draft of unboxed (package management) has a provision for handling info
files found in an unpacked package, and dealing with texi files when there
is no info file is straightforward.  I have no idea what to do with a
random org file used for documenting a package to make it systematically
accessible to the package's user.

Lynn

[-- Attachment #2: Type: text/html, Size: 1561 bytes --]

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

[Philip Kaludercic]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>>> We only provide :url, and where appropriate :branch, :vc-backend and
>>> :maintainer.  
>>
>> :maintainer is currently not used
>
> Removed.
>
> Could you please ping me when you add new properties?

I don't see the point of adding support for it to package-vc, that is to
say that I don't know what would want to make use of it.

>> (TBH I am not sure what the point of it is in elpa-admin to begin
>> with),
>
> Sending emails to a package's maintainer.  It is used to send every
> pushed commit for example.

Every commit?  From what it see being done in elpa-admin.el it is
invoked when a package fails to build and on releases (as is the case
when a maintainer is listed in the package header).

>>> We don't set :doc or :lisp-dir (yet?).
>>
>> Do you think it could be possible to support :doc and :lisp-dir.  IIUC
>> the issue is that MELPA only accepts a list of files to include when
>> bundling a package (:files) and the build system would have to infer
>> what what is?
>
> Why is :doc needed?  I think package-install simply runs makeinfo on all
> texi files, but of course it can rely on them being at the top-level.

I don't see that package-install attempts anything like that.

> It might end up trying (and failing) to directly process gpl.texi and
> similar.  But still, cannot package-vc simply do that too?

Sure, that can be done.  There was just no need for that up until now
considering that ELPA added :doc provides the information.

> The value of :doc can also be an org file and we cannot just blindly try
> to transcode *all* org files to texi.  But Melpa doesn't support
> exporting ort to texi, so packages distributed there cannot assume that
> that happens.  (I wish Melpa supported this and I actually implemented
> it, but the main Melpa maintainers didn't want to merge it for security
> reasons.)

Hmm, understandable.  As long as MELPA wouldn't install a manual in
these cases, I think it is tolerable if package-vc doesn't do so either.

> I am not sure determining :lisp-dir from :files on the archive's side,
> is easier and/or more reliable than package-vc doing it itself based
> solely on what it finds in the latest commit.  In Borg I use "if lisp/
> exists, then use that, else use ./" and that works for 99% of all
> packages.

What package-vc does is check both "lisp" and "src" checking if they
contain .el files.  Good to know that this works well enough.

> I think it would be better to first try to add some heuristics to
> package-vc.  If that doesn't work well enough, we can still later
> make package-build generate more elpa-admin-style metadata.

Yeah, it should all work well enough for now, I guess the only way to
improve this is to deal with real-world edge-cases that are discovered
over time.

-- 
Philip Kaludercic

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

[Eli Zaretskii]

> Date: Tue, 28 Mar 2023 01:50:04 +0000
> From: Okamsn <okamsn@protonmail.com>
> Cc: emacs-devel@gnu.org
> 
> I have tried to write a patch doing this (attached).

Thanks.

> +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?

> +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.

> +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.

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

> +@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.

> +@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.

> +@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".

> +@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.

> +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"?

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