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

[Dmitry Gutov]

On 22/04/2025 14:58, Eli Zaretskii wrote:
> > Date: Tue, 22 Apr 2025 00:51:30 +0300
> > From: Dmitry Gutov <dmitry@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.