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

Previous Next

Full log

View this message in rfc822 format

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

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

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

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

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

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

> +that, you can customize this variable to nil.
> +@end defopt
> +
> +@defopt project-vc-ignores
> +Using this variable you can add more ignore patterns to the project, to
> +exclude more files from the project's file listing.  The value is a list
> +of glob strings.  They can match both regular files and directories.  To
> +anchor an entry to the project root, start it with @code{./}.  To match
> +directories only, end it with @code{/}.
> +@end defopt
> +
> +@defopt project-vc-merge-submodules
> +By default all submodules inside a Git project are considered to be part
> +of the parent repository's project.  Customize this to nil to make them
> +separate projects.
> +@end defopt
> +
> +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.

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

Previous Next

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