From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: How to install documentation in sub-directory with Package VC? Date: Tue, 28 Mar 2023 07:41:09 +0000 Message-ID: <87cz4te31m.fsf@posteo.net> References: <87bkkvconh.fsf@posteo.net> <87o7oujqqp.fsf@posteo.net> <98f76116-4f5a-c225-3123-78c612ec64cb@protonmail.com> <875yb1gk55.fsf@posteo.net> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2648"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Okamsn Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Mar 28 09:42:07 2023 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ph3y2-0000PI-Ot for ged-emacs-devel@m.gmane-mx.org; Tue, 28 Mar 2023 09:42:06 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ph3xG-0002L5-3A; Tue, 28 Mar 2023 03:41:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ph3xD-0002Kn-Oa for emacs-devel@gnu.org; Tue, 28 Mar 2023 03:41:15 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ph3xB-0004hU-BG for emacs-devel@gnu.org; Tue, 28 Mar 2023 03:41:15 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 44C7424042D for ; Tue, 28 Mar 2023 09:41:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1679989271; bh=ZyPNErqlXY63xizkiYjDjp/XGWWxCiCpG+wdo/ZM92o=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=FFUskJaQOmN77fedfsncsDBRONK4j77SwweldUciLzIgB6alNHdNOF3jsoUj3cYSg obrDzU1y3P4y6nWU0kuxictFxHFCFym4urnFFIJD/h/sm3stVHf7WEGV2iRR1tQHn2 udKGArDIZ9StukwtMyV6gs313A1qwcrra84soeXLEJu/p5R4xCtf/J7MGZUBA3HaQi BdSIe/fDDQI/B+nl1d9G6fmzTnNxSchic8aG33YzocLxL0tRqwUfiqaubKI6Zri0ZN NsPA0t+Et6ulDHKMUHFvRVobBYDeM4v30r5MJUbNBddTxYlUelndul/dpHBpJ1PwOy kuLmbEfZzPaYw== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Pm1ny5wlnz9rxL; Tue, 28 Mar 2023 09:41:10 +0200 (CEST) In-Reply-To: (okamsn@protonmail.com's message of "Tue, 28 Mar 2023 01:50:04 +0000") Autocrypt: addr=philipk@posteo.net; keydata= mDMEZBBQQhYJKwYBBAHaRw8BAQdAHJuofBrfqFh12uQu0Yi7mrl525F28eTmwUDflFNmdui0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiWBBMWCAA+FiEEDg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwMFCQHhM4AFCwkI BwIGFQoJCAsCBBYCAwECHgECF4AACgkQ8xYDWXahwulikAEA77hloUiSrXgFkUVJhlKBpLCHUjA0 mWZ9j9w5d08+jVwBAK6c4iGP7j+/PhbkxaEKa4V3MzIl7zJkcNNjHCXmvFcEuDgEZBBQQhIKKwYB BAGXVQEFAQEHQI5NLiLRjZy3OfSt1dhCmFyn+fN/QKELUYQetiaoe+MMAwEIB4h+BBgWCAAmFiEE Dg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwwFCQHhM4AACgkQ8xYDWXahwukm+wEA8cml4JpK NeAu65rg+auKrPOP6TP/4YWRCTIvuYDm0joBALw98AMz7/qMHvSCeU/hw9PL6u6R2EScxtpKnWof z4oM Received-SPF: pass client-ip=185.67.36.66; envelope-from=philipk@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:304796 Archived-At: Okamsn 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 > 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