Subject: bug#12492: Acknowledgement (24.2.50; Open vc-dir buffer easier and faster)

From: Eli Zaretskii <[email-masked]>
Date: Sat, 07 Mar 2020 09:37:09 +0200

> Cc: [email-masked], [email-masked], [email-masked]
> From: Dmitry Gutov <[email-masked]>
> Date: Sat, 7 Mar 2020 00:34:36 +0200
> 
> On 06.03.2020 19:12, Eli Zaretskii wrote:
> > For starters, how do you explain what a "project" is, when
> > the only example we can give is a repository?
> 
> The way we should either way: with a higher level description.
> 
> Something like:
> 
> A project is set of files. Which we usually define through a list of 
> directories where the files reside, and a list of ignore rules that 
> exclude some files within said directories from being considered a part 
> of the project.

This is too abstract: it doesn't tell the reader how to "create a
project".  Without knowing that, all the rest of the information about
the commands is mostly useless, because the commands cannot be used in
practice.

> The above information is provided by the project backend that is in use. 
> The main backend supplied with Emacs is based on VC, and it uses 
> repository markers and associated ignore files (as well as the 
> `project-vc-ignores` variable).

Still falls short of clarifying the above.

We are talking about the Emacs User manual.  The project API is
extensible on the Lisp programmer level, not on the user level.  So
the user-level information should describe what is available to users;
too much abstractions is inappropriate.

> > I see nothing wrong with having this in the VC chapter for now; we can
> > always move it out later, when there are other back-ends.  The
> > placement of sections in chapters of the manual is neither sacred nor
> > final.
> 
> As long as it doesn't say that a project is a VC repository.

But with the VC back-end, it really is, isn't it?  Then why not say
that the type of project supported by Emacs OOTB is a VCS repository?