Re: master 1e3b0f2: Improve doc strings of project.el

[Dmitry Gutov <dgutov@yandex.ru>]

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.