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: Mon, 10 Apr 2023 13:39:13 +0000 Message-ID: <871qkreu0u.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> <87zg7lf25x.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="13150"; 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 Mon Apr 10 15:39: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 1plrk5-0003Gr-Jc for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Apr 2023 15:39:33 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1plrjQ-0007to-5J; Mon, 10 Apr 2023 09:38:52 -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 1plrjO-0007td-7x for emacs-devel@gnu.org; Mon, 10 Apr 2023 09:38:50 -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 1plrjL-0000wo-1b for emacs-devel@gnu.org; Mon, 10 Apr 2023 09:38:50 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 05B0B240227 for ; Mon, 10 Apr 2023 15:38:43 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1681133924; bh=OIWKX47uDsWEUghWZSzu35FJkX0l3bHtU/PtlD5Qdsg=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=JiDocqw2VEhWOVGZWJgKaVRC4j9ZiJwWlsaU3pjO/TAqt+tAfIOTDyyASdb9O36YV oybsa3EneQ9L+GD4l34H3QRne6IXZQjKDeT1KGiB/B7hyODHiA7r3b1P+gOMJQIYNU tmyVf2EiHrLOt9KpXkDtK/s/L5AYo8iqwRP4ytuXssGzMo+3BM8631TTE5Zxn44r70 OZ/t5KFcA76z1xJI90e5m9kuxu8/e8nFaODAnezvbxmpT5AFt/QTigJ05fLbETQwnT /Qt6y84pwXXMy361twilb+hBPXzzSmBJvFg22GofZUKsyHrmWkBgcqfmq/qgUppk00 WSQbAxLOenW2Q== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Pw96W3hWFz9rxN; Mon, 10 Apr 2023 15:38:43 +0200 (CEST) In-Reply-To: <87zg7lf25x.fsf@posteo.net> (Philip Kaludercic's message of "Thu, 06 Apr 2023 17:42:02 +0200") 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:305221 Archived-At: 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. Philip Kaludercic writes: > 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: > > 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 > > >> 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.