Re: project.el semantics

[Dmitry Gutov]

On 11/10/2015 07:36 PM, Stephen Leake wrote:

> > Although again, what will the project dependencies be used for, is
> > still an open question for me.
>
> The general rule is: if we don't have a good use case, don't add code.

So I'm not adding it. Just keeping that possibility in mind, and hence 
keeping the word "dependency" free.

> > Another thing you might want to do - replace some term across the
> > project (using M-x project-find-regexp and then M-x
> > xref-query-replace). If we were to show its occurrences in library
> > files as well, that would be a waste of user's and computer's time.
>
> You can't allow for all possible user desires by providing different
> path functions at this level.

Indeed, I can't account for every variation. So I service just the ones 
that seem most important to me at this point.

> Instead, there should just be one path, that includes all files that the
> user might want to do anything with. Then, when the user actually
> invokes a function to do something, they can provide a predicate if they
> want a subset of that.

How would they provide the predicate when calling the command 
interactively? Especially a predicate that would distinguish between 
project roots and library roots.

> You have to rely on common definitions; "dependency" is one (although
> apparently not for you, sigh).

"outside" is definitely a more common word for me than "dependency". *shrug*

> "outside" is a common English word, but "outside the project" is very
> fuzzy.

You're free to suggest another word that means "not inside of any of the 
project roots".

> > Since we're discussing project-library-roots here, I'm not sure which
> > improvement you mean. How about simply replacing "the list of
> > directories outside of the project" with "the list of directories
> > outside of the project roots"?
>
> I suggest "not included in" rather than "outside".

That implies the (not (member ...)) semantics, rather than (not 
(file-in-directory-p ...)), which is what `project-subtract-directories' 
actually does.

And "not member" semantics seems pointless to me here; we might as well 
allow project-library-roots to include project-roots element, if the 
consumer will have to call `project-combine-directories' on them together.

Having "library roots" entirely outside the project roots, however, 
makes a lot of sense to me intuitively: if they're inside, they are a 
part of the project anyway. What kind of use would we have for such 
elements?

> > Because if we describe it in terms of dependencies, a dependency might
> > be checked out inside a project root subdirectory in certain
> > configurations (maybe with an appropriate .gitignore entry, maybe
> > not). In that case, though, we probably don't want to have
> > project-library-roots include it.
>
> Why not? We allow subdirectories in the same path in general (ie
> `load-path'); that's what project-prune-directories is for.

Note that neither `elisp--xref-find-references', not 
`etags--xref-find-references' call `project-prune-directories' (or 
`project-combine-directories', as it's called now).

> > We can add "So if the project has dependencies which should be edited
> > together with it, they should go here as well." to the third paragraph
> > of the project-roots docstring.
>
> That would be good.

Would you be able to give an example of a project file that lists 
dependencies like that, that "should be edited together" with the 
current project? It would fit the manual well.

> > Guess that might go into the manual instead. I've seen someone state
> > that it's okay for the manual to have redundancies.
>
> Ok, please start the manual. That would help a lot.

If you're waiting for me to start, you might have to wait a while. I 
haven't written a manual in my life (not in Texinfo, or in English).

If you or someone else add the file with structure outline some 
placeholders a la <write XX here>, that would speed the process 
considerably.

> > It's a... semantic-symref-tool implementation of it, actually. Which
> > has no relation to Semantic grammars, its tags, or etc.
>
> Ok, so xref-semantic-symref-find-references, or
> xref-symref-find-references.

semantic-symref is a command that displays references in a tree-like UI, 
and it uses Semantic on the way to do that. xref-collect-references doesn't.

I don't really know a good name for it. 
xref-collect-references-using-any-cedet-indexing-tool-we-can-find?

It's not a user-level command, though, so we can get away with just a 
mediocre name.

> But if I normally use global, I want xref to use it. And I know how to
> deal with all those issues. Although some details in the manual would
> help.

Yes, the manual could be the answer.

> I could write a new global xref backend, but it's better to reuse
> existing code.

Does lisp/cedet/cedet-global.el have code that will help us with 
implementing "find definitions" using Global?

> Unless you are proposing to rewrite symref to be more consistent with
> xref.

Maybe. Depending on what you exactly mean by that. I'd rather rewrite 
the "tools" CEDET code to be more flexible, for different uses.

> > IMO, it's more important to have the distinction between "project
> > roots" and "project library roots" in "find regexp" than in "find
> > references".
>
> But you don't provide any code that allows the user to take advantage of
> that distinction. So it how important can it be?

What code?

We have both project-find-regexp and project-or-libraries-find-regexp 
already, and I find the difference between them useful in practice.

> No, I would not expect vc-project to know anything about project files.
>
> I would write a new project backend that knows about some set of project
> files.

Again, how many project backends will that be? One for every distinct 
language combination?

Basically, you position eliminates the need for 
project-library-roots-function, as it's used now. I think that we should 
create a better use for it, and do teach vc-project about library-roots 
for different project files, through it.