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

[Philip Kaludercic <philipk@posteo.net>]

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