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: Thu, 06 Apr 2023 15:42:02 +0000 Message-ID: <87zg7lf25x.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> <87bkk29461.fsf@posteo.net> <2281d076-f349-cf15-a481-9aba3ce52ee0@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="19704"; 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 Thu Apr 06 17:42:49 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 1pkRlB-0004ti-20 for ged-emacs-devel@m.gmane-mx.org; Thu, 06 Apr 2023 17:42:49 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pkRkB-00059f-Kc; Thu, 06 Apr 2023 11:41:47 -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 1pkRk9-00059O-Fb for emacs-devel@gnu.org; Thu, 06 Apr 2023 11:41:45 -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 1pkRk3-0005Al-Ci for emacs-devel@gnu.org; Thu, 06 Apr 2023 11:41:45 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 036852406D1 for ; Thu, 6 Apr 2023 17:41:34 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1680795695; bh=a+lkGBz8ROn7N1lIeo8fVOG9eco0C+bX+rNqFUNvuGI=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=mergBA4QWcirzgtBRNOqFdYwT27y8FQ02cpyywQC/XYkPdxaGDTz6HKSzr6I7ET+3 YRrsRgdxMVDKeC8TBEVhR97xkO9ujdVw6/ItWs+d4dFeR0yymsvkH7gklWtxFfiHR9 rlMJ0ai4607mqYsFXkABe0pJuEi9Xw9yOVQZsAbrNn+lCh+mDpXG+HaPrseTqitatg NnoMiQMBiTmEcDP1ZLk2bcG5StVNmeyXq4rjvT9J6H3Ol+OccciXoGGL5HqQGkjf2y HEROlwAKAg0ayrwEMxqY6TmMGsqwWoLwFHJO4jMfekIEaM9vjsWQ4nA+Z0WQdB+5EP YU+xRBBuI9Wfg== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Psm262JkCz6tw3; Thu, 6 Apr 2023 17:41:34 +0200 (CEST) In-Reply-To: <2281d076-f349-cf15-a481-9aba3ce52ee0@protonmail.com> (okamsn@protonmail.com's message of "Thu, 06 Apr 2023 03:52:32 +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=unavailable 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:305144 Archived-At: --=-=-= Content-Type: text/plain Okamsn writes: > On 2023-04-05 07:30 UTC, Philip Kaludercic wrote: >>> + 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. > > I acknowledge that "things" is unspecific, but I do think that the > paragraph flows better with a noun there. What if "things" was swapped > out for "properties"? I think that it would work well with the use of > "property list" a few sentences later. That sounds good! > >>> + 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. > > I wasn't aware of these heuristics. In this paragraph, I was trying to > describe where the known specifications come from, as in the > "elpa-package.eld" file. The point here is that you can install a package listed in an archive, even though the archive doesn't generate a elpa-package.eld. It works most of the time, in the remaining cases the heuristics help but it is not ideal. Should this be explained? >>> +@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.) > > Are you saying that you don't want to describe the heuristic, or that > you don't want to describe the default behavior? I would like to keep > the mention of the default behavior. I don't want to document the heuristic, as IMO this is an implementation detail. Lets keep this the way it is. >>> + 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. > > I don't think that this paragraph should be moved to after the table. In > my opinion, it is better to have the link, which defines the terms, > placed before the using of the terms. Another idea would be to mark the paragraph up using @quotation, @cartouche or a Footnote? > Instead, what if the sentence ended like "using any of the keys in the > table below"? That would also be fine. >>> 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 >> >> 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. > > Some of the information in the documentation string is probably not > relevant for users wishing to give their own specification. For example, > the information about a package archive's default VC backend that Eli > Zaretskii pointed out. Would you like to limit the information in the > table to what is relevant for giving a manual specification, or should > the table be a description of the behavior for all specifications? What I had in mind was just replace the ad-hoc list in the docstring with a reference to the new section in the manual: --=-=-= Content-Type: text/plain Content-Disposition: inline diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el index ddc7ec4679b..6fe30e08830 100644 --- a/lisp/emacs-lisp/package-vc.el +++ b/lisp/emacs-lisp/package-vc.el @@ -147,32 +147,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 \"Package specification\" subsection + under 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 --=-=-= Content-Type: text/plain > If it is made more general, then I have no strong reason to disagree > with keeping the information in only one place. However, I will defer to > others on this. I am just making suggestions here and am interested in what you think. My opinion isn't worth more than yours. --=-=-=--