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

[Philip Kaludercic <philipk@posteo.net>]

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