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, 12 Apr 2023 07:27:23 +0000 Message-ID: <87leix5zms.fsf@posteo.net> References: <875yb1gk55.fsf@posteo.net> <87cz4te31m.fsf@posteo.net> <87bkk29461.fsf@posteo.net> <2281d076-f349-cf15-a481-9aba3ce52ee0@protonmail.com> <87zg7lf25x.fsf@posteo.net> <871qkreu0u.fsf@posteo.net> <8a826e3a-d74e-fcb4-3cb2-4dbbc93cdf97@protonmail.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34529"; 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 Wed Apr 12 09:28:14 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 1pmUtp-0008ns-Cn for ged-emacs-devel@m.gmane-mx.org; Wed, 12 Apr 2023 09:28:13 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pmUsh-00083S-25; Wed, 12 Apr 2023 03:27:03 -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 1pmUse-000839-3u for emacs-devel@gnu.org; Wed, 12 Apr 2023 03:27:00 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pmUsb-0004Z7-Gv for emacs-devel@gnu.org; Wed, 12 Apr 2023 03:26:59 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id E6FD72400DE for ; Wed, 12 Apr 2023 09:26:53 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1681284413; bh=TvCh5OF+0hhhumR9npd6+66nZE9ytzCkjoWhB5bD13g=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=g8/rxMIcUHhmrK+9HrKsV/SaNbsr4pAWSIxevIxqa10u2B3d0xKNAv4VUjCOWsj4k dWGKRMrMx3srDDoujhQKiikDCr4S4AWHgBXqZpuX1XE5W9NhgeJmoMpeZzIDadbdHI 5ZaBm/d+guMQFAmKSjtB1GnwlfcQ+3sZ0Pi3fwvxvo6pDZxM1mmWuZytESLo4HWMnp q4kJMTSyuwS0XXD03cB8Cptm7sGpTxh520bN3MZ4iaxiaoom9ExYgg6Q4VIg4hsm+f 2R3KHu4hAQru0wyhwKPVdosOrZbg7/D9m5sZNwYdC03CZkc3yGWSpUK6NTzOXoh80u wF9ZFYInJFvJg== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4PxDmY2D9Sz9rxL; Wed, 12 Apr 2023 09:26:53 +0200 (CEST) In-Reply-To: <8a826e3a-d74e-fcb4-3cb2-4dbbc93cdf97@protonmail.com> (okamsn@protonmail.com's message of "Wed, 12 Apr 2023 00:04:36 +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.65; envelope-from=philipk@posteo.net; helo=mout01.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:305261 Archived-At: --=-=-= Content-Type: text/plain Okamsn 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: --=-=-= Content-Type: text/plain Content-Disposition: inline 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 --=-=-= Content-Type: text/plain > From 07c00d430a3b213a0b8a8e4f107b8b6e4d54a9fd 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 | 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") --=-=-=--