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

Previous Next

Full log

Message #11 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: Tue, 22 Apr 2025 20:04:12 +0300

On 22/04/2025 14:58, Eli Zaretskii wrote:
>> Date: Tue, 22 Apr 2025 00:51:30 +0300
>> From: Dmitry Gutov <dmitry <at> gutov.dev>
>>
>> Here are some proposed updates, which create a new node for this backend
>> and list some of the options that were until now not mentioned in the
>> manual.
>>
>> Feedback welcome on the general structure (do we want the new node in
>> that place?) and the phrasing of the new text as well.
> 
> Thanks.
> 
> This node should probably be the last in its parent node, not the
> first one, because it describes a specific project backend while the
> rest of the section describes backend-agnostic features.

All right.

> I'm also not sure why these 5 user options are deemed important enough
> to be in the manual, while the other 14 defined in project.el aren't.

These are the options for the backend, which this aims to document.

Got a request to have 'project-vc-extra-root-markers' documented: 
https://github.com/buzztaiki/project-rootfile.el/issues/17#issuecomment-2816505984

Most of the other options added affect which files are contained in a 
project. The existing manual mentions project-vc-include-untracked 
already, and it seemed to make sense to add project-vc-ignores and 
project-vc-merge-submodules which also affect the fileset (and should be 
more popular than the former, IMO).

> E.g., is project-vc-merge-submodules (which seems to be specific to
> Git, but its name doesn't say so?) really important enough to be in
> the manual?

I don't really mind dropping this one, except for the fact that it's 
also among the options that affects the fileset.

Being Git-specific seems unimportant (99% of all projects use Git), but 
being specific to submodules might make it too specialized, I don't know.

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

>> +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. Without extra configuration necessary. Before any 
third-package uses the hook variable.

Which of the explanations sounds better?

>> +@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. It doesn't seem like it has a description in the manual, though.

>> +Each element is either a base file name or a glob pattern for such.
>> +
>> +Example values: @samp{".dir-locals.el"}, @samp{"package.json"},
>> +@samp{"requirements.txt}, @samp{"*.gemspec"}.
> 
> 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?

> If you decide to install this, don't forget to update the @detailmenu
> in emacs.texi.

Thanks.

Previous Next

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