From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sat, 11 Jul 2020 09:58:23 +0300 Message-ID: <831rlipmgg.fsf@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <83imfnxgt3.fsf@gnu.org> <626efe11-0f9c-081b-11dd-0d61cee8168d@yandex.ru> <83h7v7xf7w.fsf@gnu.org> <831rmayj55.fsf@gnu.org> <6dc2c2ac-8e17-f044-dc78-8c109f936ad2@yandex.ru> <83wo42w83e.fsf@gnu.org> <6762abf5-71c1-aa54-1bac-d4c90c20870b@yandex.ru> <831rmavsuq.fsf@gnu.org> <83a70wv4mj.fsf@gnu.org> <5542db0c-cc0d-2743-87ae-7728a0cc94bb@yandex.ru> <83ftaf2rj2.fsf@gnu.org> <43a8f8d4-83fb-f012-8e1d-c1a618b0ef59@yandex.ru> <83mu4m0vub.fsf@gnu.org> <44f2f1f4-ae34-f0bf-b153-f33b8ee6069f@yandex.ru> <83mu4fvjh3.fsf@gnu.org> <7c2e93d4-8d86-bbbb-77a0-bf5d73051907@yandex.ru> <83imf2t4w4.fsf@gnu.org> <95fd893e-0da5-4cdc-a3e8-3c22af750aae@yandex.ru> <837dvfs6wg.fsf@gnu.org> <8bc1f381-248f-5cee-c3c6-a29d411a2f74@yandex.ru> <837dvbphs0.fsf@gnu.org> <83365zp78d.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="13942"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 11 08:59:03 2020 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 1ju9TT-0003Wp-Co for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jul 2020 08:59:03 +0200 Original-Received: from localhost ([::1]:43098 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ju9TS-0002ju-BC for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jul 2020 02:59:02 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46384) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ju9T2-0002L9-Bo for emacs-devel@gnu.org; Sat, 11 Jul 2020 02:58:36 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:52195) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ju9T1-00054e-GW; Sat, 11 Jul 2020 02:58:35 -0400 Original-Received: from [176.228.60.248] (port=4976 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1ju9T0-0004ar-KM; Sat, 11 Jul 2020 02:58:35 -0400 In-Reply-To: (message from Dmitry Gutov on Fri, 10 Jul 2020 22:36:48 +0300) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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" Xref: news.gmane.io gmane.emacs.devel:252855 Archived-At: > Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org > From: Dmitry Gutov > Date: Fri, 10 Jul 2020 22:36:48 +0300 > > >> Which is most likely a plus for Tramp, we don't need to make buffer > >> opening even slower there. > > > > We could have a defcustom to disable that for those who will seldom > > if ever use project.el. And again, we do that for VC. > > Tramp has extra-special handling for VC. It probably wouldn't be able to > do that for all possible project backends. Why assume the worse? The situation is no different from that with VC, so I see no reason to assume Tramp will do something similar for supporting project.el. > >> Removal also happens through different venues (removal in Dired, on 'rm' > >> in the terminal, or changing the project configuration to ignore the > >> said file). > > > > Why should we care about adding or removing a file that are not > > visited in Emacs? > > A file already opened in Emacs might be added to some project this way > (by editing project config, or doing 'git init'). Then, ideally, two > things need to happen: > > - The "current project" cache of said buffer (if it is already visited) > needs to be invalidated. > - The "project-files" cache (currently not cached) of said project needs > to be invalidated as well. > > When a file is removed from project, the latter needs to happen. Having commands to add or remove files from the project would allow us to advertise those commands as the supported means of doing so. We could also have a command to "refresh" the project, for those who for some reasons will prefer doing that externally. But even without such a command, we could say that users will have to go the project.el way to have their project always up to date with the files it consists of, and discourage doing that by external means. > >>> . it makes the doc string of project-switch-to-buffer intentionally > >>> obfuscated by "explaining" stuff in terms of the implementation, > >>> which makes it not very useful (as I already tried to explain in > >>> the past) > >> > >> What are you suggesting? > > > > Explain what project-current does, most probably, right in that doc > > string. > > project-current finds the current project of the buffer. Or the project > to which the current buffer is related. Would that explanation make > things better? No, because that's not enough detail. > The exact logic of project-current depends on the configuration of > project-find-functions. Exactly. Then mentioning that as well would also help. > >>> . the new doc string is confusing: "if 'project-current' returns the > >>> same (equal) value" is incomplete, because it doesn't say the same > >>> as what > >> > >> Same as the current project value, if any (otherwise, same as the value > >> returned by the project selection prompt). > > > > Please fix the sentence, then. > > I'll do my best. I see you simply reverted to the original wording, more or less, which is what prompted me to improve it. If you are still working on improving that, I will wait; but if this is what you think the doc string should say, then I will fix it again to be better. > >>> So that commit looks like a step backwards to me. > >> > >> Just because you don't like the new docstring? > >> > >> That's harsh. > > > > I didn't see any other significant changes, sorry. > > You asked for the buffer-matching logic not to depend on > default-directory anymore. It doesn't. > > Now project-switch-to-buffer and project-kill-buffers should work with > Stephen's backend, as well as any "manually managed project" backend you > might choose to write. Yes, and that's good. Thanks.