bug#77974: Manual updates for the VC-aware project backend

[Dmitry Gutov]

On 23/04/2025 14:17, Eli Zaretskii wrote:
> > Date: Tue, 22 Apr 2025 20:04:12 +0300
> > Cc: 77974@debbugs.gnu.org
> > From: Dmitry Gutov <dmitry@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.