Re: project.el semantics

[Dmitry Gutov]

On 11/12/2015 12:30 AM, John Wiegley wrote:

> > I meant "external to the project" instead of "outside the project", of
> > course.
>
> What is the difference between these two? To my ears, they mean exactly the
> same thing.

Not much. You didn't like one word, so I suggested another, to described 
the same thing.

> I think we're too focused on "projects" having to do with code, where code
> uses libraries. A "library-root" presumes things about the content of the
> project which I suggest we don't need to presume.

"Project libraries" paint a quick and simple picture. Which, I imagine, 
might be good for the first adopters of the API. I'm not going to hold 
on tight to it, but please keep in mind that simple is often good.

> The filesets idea was not meant to complicate the API, but to step back and
> reassess the API we really want. I understand now why you chose "root" as a
> suffix, and that much makes sense.
>
> Here's where I'm coming from:
>
> When I'm sitting at a buffer in Emacs, that buffer is usually related to
> something. It could be just a buffer (like *scratch*) with no relation at all,
> but that's pretty rare.

In the current concept, the file, or the non-file-visiting buffer, is 
related to its default-directory. Then `project-current' takes that 
directory and determines the current project based on it, using 
project-find-functions.

project-find-functions being explicitly documented to depend only on the 
directory, but not on the contents of the current buffer, is a conscious 
decision: I don't want to see foo.el belong to one project, and 
README.md lying nearby in the same dir, to another, from the standpoint 
of this API. Do you disagree?

> Typically, the only relationship it has is to a file. But it may have other
> relationships:
>
>    - To other buffers

Other buffers also often have a default-directory set. So we can extend 
to them the relations that the original buffer has to their directories.

>    - To other files
>    - To other directories
>    - To other directories trees

If you intend to keep the tree/no-tree distinction, please keep in mind 
my comment from the previous email.

> The selection of these "other" things can be based on many, many different
> criteria: same file type, same directory, same "project" in the version
> control sense, same modification day, etc., etc.
>
> Why confine ourselves to thinking about code projects that use libraries, when
> we can imagine a larger picture, where the original idea is just a particular
> set of choices?

The API clients need to have an idea of the kinds of relations the API 
is dealing with. Otherwise, how would they ask the API anything?

For instance, what will project-find-regexp do? Will it query the API 
for a list of directories related to the current buffer/file/directory? 
What kind of directories? What kind of relations will it ask for?

Will we have anything like project-or-libraries-find-regexp? What will 
it change to?

What will the project-find-file command (current not implemented) look like?

> I'd love to have a programmatic API for associating files and buffers, and a
> set of commands able to take these associations into account. I'd use them for
> lots of things that have nothing to do with source code.

Why don't we save altering operations for the project backends? The API 
should work with existing backends as well (such as Projectile and EDE), 
and I'm not sure if they can support what you're describing.

> When I'm editing a
> Markdown file, for example, I might have a preview buffer showing me a PNG of
> the rendered result. These buffers are all related to my current "project",
> and I'd like a way to "save all files in project", or "close all buffers in
> project".

That's a very simple example, which can be served by the current API 
just as well. Do you have any example that will show off the difference?

> This is one of the "IDE features" I mentioned several weeks ago, which is why
> I want us to spend more time thinking about it. Why start out with a smaller
> API that does a very focused thing, when we can imagine something much more
> capable?

More capable is better than less, provided everything else is equal. But 
carefully considered limitations are also valuable, because they protect 
from misuse and other surprises by both backends and consumers.

I don't really see the end result from your description. Judging from 
just that message, you either want to remove project-library-roots and 
add a bunch of some other accessors instead, or remove all current 
cl-defgeneric declarations and declare each project to be a hash-table, 
using some sets of keys, both predefined (?) and not, and documented to 
have files and directories as values. The first option is simply vague, 
the second one, well, writing code for it would definitely be more 
error-prone: currently, if you mistype the name of a generic function, 
at least you get a warning.

You'll have to give more specifics either way.