bug#67687: Feature request: automatic tags management

[Stefan Kangas]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 30/12/2023 00:17, Stefan Kangas wrote:
>> Dmitry Gutov <dmitry@gutov.dev> writes:
>>
>>>>     . there are no updates for NEWS and the Emacs manual
>>>
>>> I'll certainly add something to NEWS. Not sure where and what should be
>>> in the manual.
>>
>> How about a new node describing this feature under `(emacs) Tags
>> Tables`?
>
> Good suggestion, but that still leaves the problem of organizing the text.
>
> Do you want, perchance, to give it a try yourself?
>
> Optimally, it might need a significant rewrite: we wouldn't point the
> user to 'etags' right away, or the "Create Tags Table" section.
>
> The average user taking advantage of etags-regen-mode might not even
> need to know what a "tags table" is (or only know that in very broad
> strokes), so depending on our eventual approach we might drop that node,
> or rearrange the nodes in a particular order, prefacing that one
> ("Create Tags Table") as the approach for advanced users.

Indeed, all good points.  In an ideal world, "tags tables" would be an
implementation detail, perhaps only of interest to users with highly
specific and customized workflows.

I won't have time to work on a proper patch right now, but perhaps
something along these lines (warning: a *very* rough draft):

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 0725d889747..f3d09b48f12 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2666,6 +2666,9 @@ Tags Tables
 by using one of the commands from other packages that can produce such
 tables in the same format.)

+  Instead of creating a tags table manually, you might want to have it
+created automatically for you.  @xref{Update Tags Table}.
+
   Emacs uses the tags tables via the @code{etags} package as one of
 the supported backends for @code{xref}.  Because tags tables are
 produced by the @command{etags} command that is part of an Emacs
@@ -2683,7 +2686,8 @@ Tags Tables

 @menu
 * Tag Syntax::          Tag syntax for various types of code and text files.
-* Create Tags Table::   Creating a tags table with @command{etags}.
+* Update Tags Table::   Creating a tags table automatically.
+* Create Tags Table::   Creating a tags table manually with @command{etags}.
 * Etags Regexps::       Create arbitrary tags using regular expressions.
 @end menu

@@ -2877,8 +2881,21 @@ Tag Syntax
   You can also generate tags based on regexp matching (@pxref{Etags
 Regexps}) to handle other formats and languages.

+@node Update Tags Table
+@subsubsection Keeping Tags Tables up to date
+
+   The easiest way to manage tags tables is by enabling
+@code{etags-regen-mode} (@kbd{M-x etags-regen-mode RET}).  This minor
+mode generates the tags table automatically based on the current
+project configuration, and later updates it as you edit the files and
+save the changes.
+
+Note that this feature disables itself if you have already manually
+visited a tags table (with @kbd{M-x visit-tags-table}, or through an
+explicit prompt triggered by some feature that requires tags).
+
 @node Create Tags Table
-@subsubsection Creating Tags Tables
+@subsubsection Creating Tags Tables Manually
 @cindex @command{etags} program

   The @command{etags} program is used to create a tags table file.  It knows

>>> Which brings a problem: the mode is now likely unusable over Tramp in
>>> any project of significant size. Something to improve later.
>>
>> Should this be documented somewhere?
>
> Maybe, maybe not. The previous solution using xargs and stat (as still
> implemented on the branch -- now outdated) should work for most remote
> hosts (unixy ones). So it's likely a matter of having a user interested
> in this and giving them a short enough patch to try.

Right.  I basically never use Tramp, so I'm leaving this to others.
Copying in Michael in case he has any comments.