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

[Dmitry Gutov <dgutov@yandex.ru>]

On 22.03.2020 16:18, Eli Zaretskii wrote:
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> 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,

Regardless of how we define a project, this heading can say "Commands 
for handling files in a project" without a loss of clarify, I believe.

> 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.

You're probably responding to my second quote here. But why not say 
"Command for handling files in a project"? Again, no real loss of 
clarity, this sentence is not a definition.

But later, we could say something like:

   A project is a collection of files united by common purpose (for 
example, used for producing one or more programs)

Maybe no one uses project-find-file currently for other purposes, but 
they surely can. And people do use Emacs for other purposes. And the 
manual is the way we tell people about what's possible, isn't it?

>>> 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.

Um, not really. All built-in commands should work with multi-root 
projects fine. We don't have any such project backends, though.

> Especially if the multiple-roots alternative will be going away.

True.

>> 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?

This choice of words gives me a somewhat more complicated mental image, 
like a sparse collection of subdirectories, where some are included, and 
some are not. Which kind of comes out to the same thing, but in a more 
complex way.

>> 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.

Fair enough.