Re: emacs-27 561e9fb: Improve documentation of project.el commands

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Sat, 21 Mar 2020 23:19:25 +0200
> 
> > +* Projects::            Commands for handling source files in a project.
> 
> Not sure I like the word "source" here.
> 
> All commands listed below just as well work on documentation files, 
> build configuration files, etc. Basically anything a user might want to 
> read or edit inside the project. Pictures as well.

Yes, I was aware of that.  But since saying that a project is a
collection of arbitrary files would make the issue harder to
understand, I decided to compromise, as I believe currently no one
really uses this for non-program files.  If this ever becomes a
practical problem, we can always rephrase.

> > Files that belong to a project are typically stored in
> > +a hierarchy of directories; the top-level directory of the hierarchy
> > +is known as the @dfn{project root}.
> 
> Can we really say "the project root" (instead of "a")? The current 
> version of the API says that a project can have multiple roots. Though I 
> plan to do away with this possibility later.

Well, it looked to me that at least on the command level we rally
expect to have one root, so the current wording is still okay.
Especially if the multiple-roots alternative will be going away.

> And is "hierarchy of directories" a better term than "directory tree"?

I think it's the same thing.  Wed use both interchangeably in our
documentation.  Why, you think "directory tree" will be easier to
understand or something?

> There's also command called project-or-external-find-regexp, which I 
> sometimes find handy e.g. because it searches load-path when in 
> emacs-lisp-mode buffers. But I've been struggling with describing the 
> general semantics of "external roots", and this term is likely to change 
> in the next version.

Likewise.  I decided not to document it for now.  If it proves to be
popular, we can add it in the future.

Thanks.