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: Wed, 05 Apr 2023 07:30:46 +0000 Message-ID: <87bkk29461.fsf@posteo.net> References: <87bkkvconh.fsf@posteo.net> <87o7oujqqp.fsf@posteo.net> <98f76116-4f5a-c225-3123-78c612ec64cb@protonmail.com> <875yb1gk55.fsf@posteo.net> <87cz4te31m.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="10694"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Eli Zaretskii , emacs-devel@gnu.org To: Okamsn Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Apr 05 09:31:33 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 1pjxc8-0002P0-FS for ged-emacs-devel@m.gmane-mx.org; Wed, 05 Apr 2023 09:31:28 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pjxbB-0004dV-Fk; Wed, 05 Apr 2023 03:30:29 -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 1pjxb8-0004U2-89 for emacs-devel@gnu.org; Wed, 05 Apr 2023 03:30:26 -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 1pjxb5-0004aD-Mp for emacs-devel@gnu.org; Wed, 05 Apr 2023 03:30:25 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 4D706240682 for ; Wed, 5 Apr 2023 09:30:21 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1680679821; bh=2kGOTuGHMDypy4Ve2cftUW99uL053cxe8IAg5O95aLs=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=MXdgpPPBEdRfz9GTMi58gYoAcjipl89RyUUySGqr3tiHHre/+ztdAZkh/k1E4nVqK Fjj1XRqOxTZ0nCgI8kJMNeXBf8ZckGhHkcNGMERWeZCGNPFy4Khh8b/XoX+W6KaNAX hhkvSzrupyPOIRyIOvcsCWyWaF1X0N8byjp7lnaa/s+yS70H4d1tx2jHuoxgbFxGFW y6zJnWHPfO1Mke8FluZESCDF/OqpmDhoq7ROUdLKjDGhk36n/Udy/8v1U1Ujocj8Db YndMkEPeDTFC88CxvxQjgpVGiQdGN3QOkBzmeryKmXqjBlD4AtDDwAByZXrafsElQF VTJFQMWc2Yh1g== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Prx9j6XDFz9rxT; Wed, 5 Apr 2023 09:30:17 +0200 (CEST) In-Reply-To: (okamsn@protonmail.com's message of "Sun, 02 Apr 2023 00:41:43 +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:305121 Archived-At: Okamsn 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 > 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")