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