GNU bug report logs - #77974
Manual updates for the VC-aware project backend

Previous Next

Full log

Message #17 received at 77974 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77974 <at> debbugs.gnu.org
Subject: Re: bug#77974: Manual updates for the VC-aware project backend
Date: Fri, 25 Apr 2025 03:27:29 +0300

On 23/04/2025 14:17, Eli Zaretskii wrote:
>> Date: Tue, 22 Apr 2025 20:04:12 +0300
>> Cc: 77974 <at> debbugs.gnu.org
>> From: Dmitry Gutov <dmitry <at> gutov.dev>
>>
>>>> +@node VC-Aware Project Backend
>>>
>>> Index entry leading to this node is missing here.  Think about a
>>> reader who wants to find this quickly without knowing the exact name
>>> of the node.
>>
>> Any suggestions for what it should say?
> 
> Something simple and obvious.  I'd start with
> 
>    @cindex VC-aware project backend
>    @cindex project backend, VC-aware

Very good.

>>>> +This backend is used by default.
>>>
>>> This sentence confused me.  What does it mean for a backend to be used
>>> by default?  This should be explained, I think, if we consider this
>>> backend important enough to be described.
>>
>> Used out of the box.
> 
> Aren't other backends available out of the box?

We have EDE as well, which adds itself to project-find-functions, but 
with lower priority and only when the ede package is loaded. So... 
however you want to phrase it.

> If not, I'd say
> 
>    This backend is part of Emacs and is enabled by default.  (Other
>    backend may need installation of add-on packages and their proper
>    configuration.)

"Installation of add-on packages and/or additional setup" perhaps would 
be more correct. After all some users create their own small backends 
(which isn't always advised, but still).

>>>> +@defopt project-vc-include-untracked
>>>> +``untracked'' files are considered to be part of the project.  To change
>>>        ^^^^^^^^^^^
>>> Sentences should start with capital letters.
>>>
>>> Also, when you introduce new terminology, it is best to use @dfn
>>> instead of literal quotes, and also have an indexing command for that
>>> terminology.
>>
>> "Untracked" is a fairly common term to the VC subsystem and VC systems
>> in general.
> 
> That's beside the point (you don't explain what it means, presumably
> because that is known well enough).  The important part is that this
> is the first (or only) place where it is mentioned in the Emacs
> manual.

Okay. Do we provide a definition inline? Or link to another node? Here's 
what Git says about it:

  Untracked files in Git are files that exist in your working directory
  but are not being tracked by Git, meaning they haven't been added to
  version control.

>>> Since these are file names, it is better to use @file markup and lose
>>> the quotes.
>>
>> Not exactly file names -- they are globs. The last one contains a
>> wildcard, for example.
>>
>> Should @file still be used?
> 
> Yes.  Glob patterns are file-name specifications, so @file is still
> the best markup.

Great.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.