Subject: Re: bug#67687: Feature request: automatic tags management

From: Dmitry Gutov <[email-masked]>
Date: Sun, 31 Dec 2023 01:23:52 +0200

On 30/12/2023 22:56, Stefan Kangas wrote:
> Dmitry Gutov<[email-masked]>  writes:
> 
>> On 30/12/2023 00:17, Stefan Kangas wrote:
>>> Dmitry Gutov<[email-masked]>  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

Thanks! This is already an improvement.

Regarding node names: if we call the new node "Update Tags Table", the 
users might want to visit it after "Create Tags Table" (to maybe see how 
to keep a tags table updated after creating it manually), and then read 
that this is not supported, as you note in the second paragraph.

We might implement something like that later, but it would have to be 
off by default, I think.

What if we call them "Automatic Tags Table" and "Manual Tags Table"? Or 
"Creating Tags Table Automatically" and "Creating Tags Table Manually"?