Subject: Re: bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

From: Dmitry Gutov <[email-masked]>
Date: Sat, 4 Jun 2022 03:37:21 +0300

Version: 29.1

On 03.06.2022 08:44, Eli Zaretskii wrote:
>> Date: Fri, 3 Jun 2022 02:45:19 +0300
>> Cc: [email-masked], [email-masked]
>> From: Dmitry Gutov <[email-masked]>
>>
>> On 02.06.2022 22:19, Eli Zaretskii wrote:
>>> Can we please tell more about what does "include untracked files"
>>> mean?  Include where and in what sense?
>>
>> Has them considered to be part of the project. Which in practice means
>> including them in a project's list of files. For the purposes for
>> project-find-file, project-find-regexp, and all other commands that
>> build on top of 'project-files'.
>>
>> How would you phrase that better?
> 
> Something like this:
> 
>    If non-nil, files untracked by a VCS are considered to be part of
>    the project by a VC project based on that VCS.

A bit unwieldy IMHO, but I don't mind. As long as you only objected to 
the NEWS entry.

The addition to the manual, which is also usually considered user-level 
text, only continues the style of the preceding sentence. And the 
docstring has to be precise either way.

>>> Bonus points for explaining
>>> this without ever alluding to "backend", as that is not necessarily a
>>> user-level concept in this case.
>>
>> The variable only affects a particular backend. It's only meaningful
>> when there is a VCS anyway.
> 
> I understand.  My point was to avoid using the word "backend" in
> user-level documentation, as much as possible.
> 
>>> Also, is it "VC project backend" or "Project's VC backend"?
>>
>> I would say both mean the same thing, but the latter seems to be more
>> unambiguous.
> 
> Well, if you are okay with my alternative wording above, it solves
> this problem as well.

Amended and pushed, thank you both.