all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Philip Kaludercic <philipk@posteo.net>
To: Okamsn <okamsn@protonmail.com>
Cc: emacs-devel@gnu.org
Subject: Re: How to install documentation in sub-directory with Package VC?
Date: Tue, 28 Mar 2023 07:41:09 +0000	[thread overview]
Message-ID: <87cz4te31m.fsf@posteo.net> (raw)
In-Reply-To: <c9db7e2a-b447-f8b1-d94b-137d7df7b9ff@protonmail.com> (okamsn@protonmail.com's message of "Tue, 28 Mar 2023 01:50:04 +0000")

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



  reply	other threads:[~2023-03-28  7:41 UTC|newest]

Thread overview: 23+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-03-14  3:13 How to install documentation in sub-directory with Package VC? Okamsn
2023-03-14 15:56 ` Philip Kaludercic
2023-03-15  9:41   ` Philip Kaludercic
2023-03-16  1:37     ` Okamsn
2023-03-16  8:44       ` Philip Kaludercic
2023-03-28  1:50         ` Okamsn
2023-03-28  7:41           ` Philip Kaludercic [this message]
2023-04-02  0:41             ` Okamsn
2023-04-02  5:24               ` Eli Zaretskii
2023-04-05  7:30               ` Philip Kaludercic
2023-04-06  3:52                 ` Okamsn
2023-04-06 15:42                   ` Philip Kaludercic
2023-04-10 13:39                     ` Philip Kaludercic
2023-04-12  0:04                       ` Okamsn
2023-04-12  7:27                         ` Philip Kaludercic
2023-04-12  7:41                           ` Eli Zaretskii
2023-04-12  7:48                             ` Philip Kaludercic
2023-04-07 21:46             ` Jonas Bernoulli
2023-04-08  8:36               ` Philip Kaludercic
2023-04-09 18:39                 ` Jonas Bernoulli
2023-04-09 20:44                   ` Lynn Winebarger
2023-04-09 21:55                   ` Philip Kaludercic
2023-03-28 11:48           ` Eli Zaretskii

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87cz4te31m.fsf@posteo.net \
    --to=philipk@posteo.net \
    --cc=emacs-devel@gnu.org \
    --cc=okamsn@protonmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.