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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 20 Jun 2020 14:25:50 +0300
> 
> 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".

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.

?

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

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

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

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.

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

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

> Because exceptions and edge cases tend to pile up, if we just start
> adding exceptions here and there.

The use cases I presented aren't exceptions, they are something
developers do all the time.

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

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.

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

My example was with a Grep buffer whose default-directory is NOT in
the current project.  IOW, my problem was with the false negative.

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

I already suggested one: let the user specify that with special
commands, and have other commands do that automatically where we know
the user will want that with very high probability.

Doing this means we need some indicator other than default-directory.
A buffer-local variable, perhaps, or membership in some data
structure, like a list of buffers associated with a project.  Or
anything else, really, that can support better, more accurate
decisions.  There are many alternatives; my point is that basing this
on default-directory is not the best strategy.