[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Dmitry Gutov
Subject: Re: master 1e3b0f2: Improve doc strings of project.el
Date: Sun, 21 Jun 2020 02:11:18 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.8.0

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

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

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]