From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sun, 21 Jun 2020 02:11:18 +0300 Message-ID: References: <87bllfqj82.fsf@warpmail.net> <83o8pfxhzq.fsf@gnu.org> <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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="105529"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.8.0 Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jun 21 01:12:29 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 1jmmey-000RMO-4a for ged-emacs-devel@m.gmane-mx.org; Sun, 21 Jun 2020 01:12:28 +0200 Original-Received: from localhost ([::1]:42890 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmmex-0007LR-5a for ged-emacs-devel@m.gmane-mx.org; Sat, 20 Jun 2020 19:12:27 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42862) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jmmdy-0005sN-V7 for emacs-devel@gnu.org; Sat, 20 Jun 2020 19:11:29 -0400 Original-Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:39101) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jmmdv-0002xG-Rx; Sat, 20 Jun 2020 19:11:26 -0400 Original-Received: by mail-wr1-x429.google.com with SMTP id q5so759522wru.6; Sat, 20 Jun 2020 16:11:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=r0Z/d9lUSsUPfrItPy2bp/Ytt81Zb0jq760qnSEux6Y=; b=afYBGaygqqU0upi3ekrPl7ageR1NXai2x/wHenGoWhBXZc80nVr4iITKUkqdkvgxO4 jZI1Ed8zbnYHCA5xnfm154SIzhWc+2OMo3ErcOqWkk0XA4aKe8eaZkj3bni8xBAaEviJ xF1DvLJ183e3RM0nBBoJ/+kSRFyDLrFciEJBUxnwh2g7A0xHbx3mAEGkpBAlBEWPYxQJ kZf2zYI423LOnuQF9dM6JC+2sQyUxSzKVlnJgypkw6WteDUDMkGOeQ0M62FherQAtabI Hi8QWUyRYpSX+47X4xyJ7EVk9RtKHA2jwcc+e6CVJJsfbQ6dj2LiaSHbHpR6QJQQ0gEh 7fgA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=r0Z/d9lUSsUPfrItPy2bp/Ytt81Zb0jq760qnSEux6Y=; b=tY8sUK+U4VWy8BODlhIG1pMWYRoClXIwEOqhLmvguoT+7p6vs0aq5xRDrNhGQacvyV va7s3kiI71+HpHTVdI52w/ObMow9ZAquyMce5HatSoS7GeE9g5DSCgI+WFJsaaX8Dk6P wBS0NXaIlEIBJDFM2o3dA1q1lAHZed8ZiUd5gBKcRAjFNw7WKnSjHMWUgxVCTcZkF5iD yNuUUlPqdN9vtqrznHWSg2Nd/r8x/nMtwADAf9gakKzww/9gQDmWdvY3BddPYYTEzJ4z LXZBwRjj6hk0OMgs6h1ZtV7ufGtQrtz1eOJyqj6ozQTixZ5su4jzuvjMndp1a97O0Otw hItg== X-Gm-Message-State: AOAM533TKKFIgpeeea/+D1d4rnVCqh3RAJ8z4bKFQabdYnndyG7sepMV kR6LUONXG/isl9jKtJQakS93RiL7 X-Google-Smtp-Source: ABdhPJzYyeQoOZuNA7oyVaQwcEofIeO5buE+F815509Q8KNxz70+GuKIuTantdlLSdfxoA++sfaM+A== X-Received: by 2002:a5d:4286:: with SMTP id k6mr10662076wrq.140.1592694681570; Sat, 20 Jun 2020 16:11:21 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id z9sm2902335wmi.7.2020.06.20.16.11.20 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 20 Jun 2020 16:11:20 -0700 (PDT) In-Reply-To: <831rmavsuq.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=raaahh@gmail.com; helo=mail-wr1-x429.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: 0 X-Spam_score: 0.0 X-Spam_bar: / X-Spam_report: (0.0 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=_AUTOLEARN X-Spam_action: no action 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:252472 Archived-At: On 20.06.2020 15:12, Eli Zaretskii wrote: >> I don't know about that. Interpreting that literally would mean that >> such buffers would never be suggested because they "belong to some other >> project" (according to the reasoning which gave rise to this wording) no >> matter which of the projects is the current one: "the outer", or "the >> inner". >> >> So what we should say is just "belongs to the current project". > > Not sure I understand. The current doc string says > > "Switch to another buffer that is related to the current project. > A buffer is related to a project if its `default-directory' > is inside the directory hierarchy of the project's root." > > You want to change the last sentence to say > > A buffer is related to a project if it belongs to the project. > > ? It could say "A buffer is related to project PR if 'project-current', when called in it, returns a value equal to PR". But that could be considered tautological. So alternatively, the first line would just say Switch to another buffer that belongs to the current project. But only if the implementation is made more precise in this respect. >> The implication being that if it's inside a nested project, it >> doesn't belong to the outer one. > > How will this implication become apparent to the users, if the doc > string doesn't discuss the significance of being "nested"? The doc string of project-try-vc can describe that. Or the general description of VC projects, in the Commentary header and/or the manual. >>> No, it isn't. I'm working on a single project, but need to look >>> outside of its directory to find some information. A very natural >>> thing to do, and it doesn't mean I started working on another >>> project. More importantly, I do want that Grep buffer be available to >>> me as part of the current project, because I'm likely to return there >>> more than once. >> >> And bookmarks/switch-to-buffer/registers are not good options for this goal? > > The problem I raised is that such a Grep buffer will not be offered as > a completion candidate when it is definitely relevant to my work on a > project. You suggest that I don't use the project.el commands, which > is exactly what bothers me: it means that project.el commands don't > support well a very simple project-related activity, which for me is > a very frequent one. It is a possibility. But so far I don't understand very well whether your usage habits and the view of how a project should be defined are common enough, or fairly singular. In any case, we should weigh the added complexity of implementing it (using any of the proposed ways) against the added utility. For instance, you also said that you generally work on a single project at once (in an Emacs session). I could have misunderstood you there, but if that's true, the added benefit of using project-switch-to-buffer, as opposed to switch-to-buffer, would be marginal. The reason the former function was added, as I see it, is for people who switch between different projects in the same session to be able to "narrow down" their view of the buffer list, to more easily find the one they are currently looking for. >> Make sure project-vc-external-roots-function points to a function that >> returns a list which includes the "other" directory. By default, it will >> include the directories where tags tables reside. > > But I don't want all the files in that directory to be part of the > project. I want just the Grep buffer. Fair enough. > And anyway, coming up with a function that does some job is not a > user-level operation, at least not when the user needs to do it every > now and then, when the work on a project takes him/her outside of a > directory. We need easier facilities, like commands and simple-valued > variables. Alternatively, it could be a customization variable you could set in some .dir-locals.el. Or a full-blown configuration file, specific to a new project backend, that would list which files belong to which projects. Not sure if such configurations would reside in some "project roots" (the meaning of the term becomes a bit blurry when project files are allowed to reside outside of its directory tree), or inside .emacs.d. >>>> To reuse your argument, 'M-x switch-to-buffer' is still available for >>>> borderline cases. >>> >>> An argument that you dismissed previously. >> >> I dismissed it as in "people wanted to call this command less". But my >> specific wording also made provision for it being necessary at least >> sometimes. >> >> But you made this argument. So perhaps it may be good enough for your >> purposes. Am I wrong here? > > How can it be good enough for my purposes, but not good enough for > those of others? What kind of logic is this? Different usage patterns. I'm sure you're familiar with that notion. >> I don't want to dismiss your request outright, but we'll need to have >> some design which would fit the existing model and/or wouldn't be hard >> to support. > > I presented a critique of the current design, whereby the buffer's > default-directory is used to decide whether the buffer belongs to a > project. I presented several examples where this design doesn't do > what I as a user expect. If you don't want to dismiss that critique > outright, I'd expect you to come up with some changes that would > support the use cases I described. That is the expected response to a > critique such as the one I presented. I don't understand why you > expect _me_ to have some design, I'm not working on developing > project.el, I'm just a (potential) user of it. I don't want to dismiss the critique outright. Believe it or not, I really do want you, personally, to be happier and more productive as a result of things I do here. I spent several hours today just thinking about this discussion. But our workflows are different, and expectations are different as well, and it seems that your requests tend to conflict with some design choices I have originally made. One of them was to make the VC project a hands-off backend, one that immediately "just works" (or tries to), with a few possibilities for customization through local variables. Consider also that your critique might be based on a different view of what a "project" is. In my understanding, it is, roughly speaking, a directory with files. Some of them are "junk", build artefacts and the like. But the rest usually support a program, or a document, etc, and together they result in one whole. Some stuff working together. A project could have dependencies, they often reside outside of that directory (but not always), but they aren't as much a part of the said project. Consequently, if there is a regexp search across these files, I immediately consider that search (the process, and the search results) a part of that project. Because it searches in that project's files. No matter the end goal of that search. You seem to think (and this is only my guess, of course) that a project is a unit of work. And that whatever files, or activities, are pertinent to your current goal, are a part of that project. Hence, if you do a search anywhere, in any directory, but in pursuit of that goal, the search results are certainly a part of the current project. It is certainly a valid viewpoint, but one that I have never considered before. I _think_ (though I can't be sure) that the former viewpoint is more prevalent among other editors, and among our users as well. And with that definition, your example doesn't show anomalous behavior, and the outcome is something that a user would expect. Even if someone might say that they would be able to reach that Grep buffer quickly by this or other means. So I'm not sure where to go from here. If the latter viewpoint has more supporters, perhaps an new, alternative backend is the way to go. This would be a test of the API, how well it adapts to different goals. But it we were able to adopt the same language, perhaps that would be more productive after all. And we might reach the additional goals by other means. >>> I think that non file-visiting buffers are rarely related to a >>> project, an exception rather than a rule. My suggestion is therefore >>> to turn the table and come up with a list of such buffers that >>> _always_ are related to a specific project. And instead of using the >>> default-directory as evidence for the buffer's relevance, we may need >>> a command that explicitly makes a buffer related to a project. >> >> Well, Phil gave a list of examples. And in all of those cases, I think, >> default-directory worked well as an indicator. > > The same examples could be supported by having a list of buffers that > should be considered. Whether such an explicit list is a good or a > bad idea depends on how long it will have to be. That is why I > suggested to see how many such buffers are there, because I suspect > there are only a few. IMO (and I know at least some people who hold a similar view), constructing a list of buffers/files/etc that constitute the current project by hand, is not user-friendly. So I'd rather the default behavior didn't require extra hand-holding by the user. > By contrast, making a far-reaching decision that default-directory is > all we need, based on such a small sample, might produce sub-optimal > results, as I described. So far it's not a done decision, and a lot can be improved as a result of this and nearby discussions. A far-reaching decision would be to make an API change, or to add a new backend.