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

From: Stefan Kangas <[email-masked]>
Date: Sat, 30 Dec 2023 12:31:57 -0800

Dmitry Gutov <[email-masked]> writes:

> As long as it's in a separate file, it should be easy to publish it to
> ELPA (as "core" package). Which is an option that's nice to have, even
> if not essential. Sometime later, when the features and implementation
> stabilize, we could merge the files, leaving the code in ELPA for older
> emacsen. Or something like that.

That overall plan sounds good to me, thanks.  We'll have to decide on
the details as we go of course, but clearly it makes sense to allow the
feature some breathing room to stabilize.

> This is only necessary for language constructs not supported by etags
> OOtB. Such as our C macros which define Elisp functions and variables.
> These are the same regexps that we have in our Makefile.
>
> So this is a per-project thing, rather than per-language. Most users and
> projects shouldn't need it, or wouldn't need it right away.

Ah, that makes more sense to me now.  Thank you.

Would it be helpful to put that explanation in the .dir-locals.el file
itself?

>>> +;;; Commentary:
>>> +
>>> +;; Simple automatic tags generation with updates on save.
>>> +;;
>>> +;; The goal of this mode is to provide a feature that should be
>>> +;; familiar to the users of certain lightweight programmer's editors,
>>> +;; such as Sublime Text.  Which is "go to definition" with automatic
>>> +;; indexing, added in ST3 (released in 2017).
>>
>> This makes it sound like we're just copying others, when we could be
>> more confident.  Emacs has had the described feature since before 2017.
>> I propose dropping all references to Sublime Text and reducing the above
>> to simply saying:
>
> But... it didn't? Otherwise you wouldn't have called it "long overdue",
> right?

Uhm, yeah, that could have been more clear.  I must have hatched a key
sentence when editing, or something.  Please let me try again.

The proposed text seemed to open up for the misunderstanding that "go to
definition" is a new feature, that Sublime text introduced in 2017 and
Emacs will now get in version 30.1.

I think we should clarify that the new feature is only "automatic
indexing".  Furthermore, doing things for the user in the background is
hardly revolutionary enough that we need to give Sublime text the credit
for the invention, or anything like that.  It's rather mundane these
days, as far as features go.  Users have learned to expect it.

This is what makes the feature long overdue.

Does that make more sense?

> Anyway, I'm not married to the above text, it's just a description of
> how I'm thinking about the problem. But I would invite you and other to
> consider how the ST users take advantage of automatic indexing without
> having to be aware of how information is stored behind the scenes (tag
> files or not), when considering the sections of the manual touching on
> etags-regen-mode.
>
>>      This library provides automatic indexing for Emacs "go to
>>      definition" feature, the `xref-go-forward' command (bound to `M-.'
>>      by default).
>
> Sure.
>
> We could also add some text that would distinguish it from the general
> notion of "automatic indexing", so that the users of Eglot, for example,
> don't consider it necessary to enable this mode. Even though they would
> also want indexing to remain automatic.

Indeed, the possible confusion with eglot could bear some documenting.
Perhaps we should add a new paragraph to the commentary explaining how
this feature will (or will not) interact with Eglot.

>>> +;; At the moment reindexing works off before/after-save-hook, but to
>>> +;; handle more complex changes (e.g. the user switching to another
>>
>> (We usually prefer "for example" to "e.g.".)
>
> No problem.
>
> Though searching across the codebase, the number of hits for these two
> options seems to be about the same (5K vs 4K).

Search for "abbreviations" in (info "(elisp) Documentation Tips").

But when we made that addition, we didn't bother changing all existing
documentation.  IIRC, most people in that discussion preferred a more
gradual approach.