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

[Dmitry Gutov]

On 20.06.2020 09:43, Eli Zaretskii wrote:

> So all you want to add to the current doc string is "...and doesn't
> belong to some other project"?

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". The 
implication being that if it's inside a nested project, it doesn't 
belong to the outer one.

> > > But the default-directory of these buffers is a very weak evidence of
> > > them being relevant to some project.  E.g., I could (and many times
> > > do) grep some other project when I need to see how it solves some
> > > problem which is relevant to what I'm working on now.
> >
> > That is a case of working on multiple projects at once.
>
> 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?

> > And whatever your purpose of grepping it, wouldn't you agree that
> > that grep buffer is probably closer to the "other" project rather
> > that to the current one?
>
> No.  And that "other" project doesn't even have to be a "project" in
> the project.el sense of the word.

Here's one direction how it could be resolved:

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.

Then create a new command, project-or-external-switch-to-buffer. Which 
would check for default-directory belonging not only to the project 
root, but for belonging the external roots as well.

> > 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?

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. Because exceptions and edge cases tend to pile up, if we 
just start adding exceptions here and there.

> 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.

In my work, having Grep buffer's default-directory belong to the current 
project is also a string indicator.

> > So default-directory is not the worst indicator.
>
> I'm saying it isn't the best, either.  We have just discovered at
> least 2 problems with it.  We should try to find a better one.

One might interpret your request essentially as "I want any buffer, 
arbitrarily, based on my current intention, be associated with the 
current project". It's probably not as arbitrary, so you're welcome to 
suggest an alternative indicator.

> > But we should also try the new command out and document our experiences.
>
> IMNSHO, some thought is required even before we hope the experience
> will teach us in due time.  Doing this only by trial and error runs
> the risk of converging on a design that is found later to be
> restrictive, or one that cannot be easily extended to support
> behaviors not accounted for or envisioned originally.

I'm not suggesting trying it for a few years. The command is here 
already, so the process has started.

> > So far Theodor agreed too. And myself as well. You alone have voiced
> > disagreement. With this distribution of votes, it seems the default
> > behavior should default to including non-file-visiting buffers (with
> > some agreed-upon exceptions).
>
> For an opinion to "count", it doesn't have to _replace_ the other
> opinions.  It could be taken into consideration by augmenting the
> design so that it supports both kinds of behaviors.  This is IME
> better than flatly discarding the dissenting opinions.

Sure.

> > And, of course, we can add a user option that would allow to tweak
> > the choosing logic.
>
> Sub-optimal selection of the "belongs to a project" criteria will make
> any such user options cumbersome and hard to use.  IOW, user options
> shouldn't be considered as means to "fix" sub-optimal design.  We are
> at a point where we can make the design better, if we consider a wider
> variety of project-related activities.

Also agree.