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

[Dmitry Gutov]

Hi Eli,

Thanks for these examples. Commends below.

On 21.06.2020 18:08, Eli Zaretskii wrote:
> >     And project-switch-to-buffer should work with all kinds of projects.
> >
> >      Yes.  And one such kind is an ad-hoc collection of files and buffers,
> >      where only the user knows which ones he/she is interested in and which
> >      ones he/she isn't.  Every IDE I saw supports something like that, so
> >      we should do that as well, IMO.
> >
> > I'm curious about those "every IDE". I don't recall such a feature in ones I 
> > tried. Perhaps I just didn't use it, of course.
> Few examples below:
>
>    Code::Blocks:
>    
> https://www.cs.odu.edu/~zeil/FAQs/Public/newIDEProject/index.html#creating-a-project-from-existing-code

Going by "Navigate to the directory where you already have your code.", 
it seems to expect that all project code resides in the directory the 
user specifies. Although, for some reason or other, it decides to 
default to not listing existing source code in there in the "sources" 
section. Perhaps that has to do with build configuration.

Note A: Being able to tell "source files" from the rest of the project 
files is a concern that we haven't looked into yet (nor into its 
applications). In the default backend, though, I would like to have it 
work automatically as well (probably by having a configurable list of 
globs/file extensions/etc).

Note B: If you only meant this as an illustration of including certain 
files in the directory, this setup should be supportable when we add 
support for whitelisting entries (as opposed to just blacklisting ones, 
through in project-ignores). That would still require all files to be 
contained inside the directory that is designated as "project root 
directory".

>    Visual Studio:
>    
> https://docs.microsoft.com/en-us/visualstudio/ide/creating-solutions-and-projects?view=vs-2019
>    Look under "Create a project from existing code files", "Add files
>    to a solution", "Create empty solutions"

"Create a project from existing code files" actually makes VS pick up 
all the source files in the chosen directory, from what I can tell. In 
that, it's closer to our project-vc backend than to Code::Blocks.

"Add files to a solution" talks about having a file that "applies to 
multiple projects". Which talks about a case of spreading the current 
work contents across multiple root directories. Which is what its 
"solutions" are.

As far as how to support a notion similar to solutions best, I'm not 
sure. Perhaps it indeed would be a separate thing (package/feature/etc), 
with a file-based configuration, that points at projects included in it. 
That way, project-vc backend (and others) could be reused for included 
projects. And we could have solution-level commands (e.g. 
solution-find-file, which scans across all included projects). I don't 
understand the level of demand for this among our users, and as such, 
the necessary features.

We're not at the level of complexity that Visual Studio has (WRT build 
configurations support, etc), and most other text editors I know don't 
have this feature, so perhaps it's a bit premature. The good news here, 
however, is that implementing solutions as a separate feature on top of 
project.el should be relatively simple. And people are welcome to 
experiment.

>    QNX:
>    https://www.qnx.com/developers/docs/6.4.1/ide_en/user_guide/tutorials.html

It seems to describe a situation similar to MS VS, except "solutions" 
are called "workspaces" here.

Otherwise, you don't select individual files inside a project to be added.

>    Netbeans:
>    
> https://netbeans.apache.org/kb/docs/cnd/quickstart.html#_adding_existing_files_to_your_project

"Creating a Project With Existing Sources" seems to import all source 
files within a project directory automatically.

I wonder what "Adding Existing Files to Your Project" does. Perhaps it 
copies files from elsewhere into the project directory, if it's not 
there yet.

>    TI's Code Composer:
>    
> http://software-dl.ti.com/ccs/esd/documents/users_guide/ccs_project-management.html#adding-or-linking-source-files-to-project

The "physically copied" case is obvious.

Regarding "When you link a file/folder to a project ...", does it create 
a symlink, maybe? That wouldn't require a configuration change.

To sum up, what I saw here is mostly what I'm already used to anyway: a 
project is basically a directory with some files in it (the set is 
generally based on the principle of exclusion, but some subviews can be 
based on inclusion/whitelist as well), and not an arbitrary set of files 
from random places on disk.

Not to discourage alternative workflows, but this is the concept we 
should work on supporting well first.

I should also note that these other editors have no concept of 
"buffers", and thus no way to configure their inclusion of exclusion. 
Thus, any entity that might correspond to our non-file-visiting buffers 
(such as a search window, or a compilation output window) is likely 
implicitly considered to just be part of the current project or 
solution. Please feel free to correct me here.

(To be continued, to address the rest of the email.)