From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Okamsn Newsgroups: gmane.emacs.devel Subject: Re: How to install documentation in sub-directory with Package VC? Date: Thu, 06 Apr 2023 03:52:32 +0000 Message-ID: <2281d076-f349-cf15-a481-9aba3ce52ee0@protonmail.com> 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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="8741"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Eli Zaretskii , emacs-devel@gnu.org To: Philip Kaludercic Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Apr 06 08:15:40 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 1pkIuK-00023p-3q for ged-emacs-devel@m.gmane-mx.org; Thu, 06 Apr 2023 08:15:40 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pkItV-0007L7-9c; Thu, 06 Apr 2023 02:14:49 -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 1pkGgC-0002w6-P1 for emacs-devel@gnu.org; Wed, 05 Apr 2023 23:52:56 -0400 Original-Received: from mail-40134.protonmail.ch ([185.70.40.134]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pkGg8-0006yX-5X for emacs-devel@gnu.org; Wed, 05 Apr 2023 23:52:54 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail3; t=1680753156; x=1681012356; bh=RAqW4CE4H7xWq1BZD4gtpmp6YAfWbMz+kqq3JbKyMns=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=VJeGBX6Z75pap1HV6pgFoQmsyksTvnj6fHE7I4mygjBaxfUF7gzkFZz9XFnZt9O49 kseObtKEFUIgtMHCJNOznuq5z7OlMtpFqUoIIZjJ916iylIELqLqCHPs86/zwGUPt8 VZOnrHXM2IBevUrcvu7Y1KiWj9SCuxHvgpJxuyBeUZ2e5BYHqQtssHw9IxgD1yzswN CY8VvcwvcLw4w4ZJFD7vEyT/wyD3P48+alB991sZ2OL9rhrn2josb0ysuK3UMhIzFU HzfXcsBK/tIM3WQjU+Jt+akU5M6aL5VkGXPUiKWN8arBkzyN8cg3GFk1ozI++O/kvD HzlOfC7dQE0MQ== In-Reply-To: <87bkk29461.fsf@posteo.net> Feedback-ID: 25935600:user:proton Received-SPF: pass client-ip=185.70.40.134; envelope-from=okamsn@protonmail.com; helo=mail-40134.protonmail.ch X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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, FREEMAIL_FROM=0.001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Thu, 06 Apr 2023 02:14:37 -0400 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:305139 Archived-At: 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. >> + 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. >> +@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. >> + 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. Instead, what if the sentence ended like "using any of the keys in the table below"? >> 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? 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.