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

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: 77974 <at> debbugs.gnu.org
Subject: Re: bug#77974: Manual updates for the VC-aware project backend
Date: Wed, 23 Apr 2025 14:17:43 +0300

> 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

> >> +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?  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.)

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

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

Yes.  Glob patterns are file-name specifications, so @file is still
the best markup.

Previous Next

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