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

From: Dmitry Gutov <[email-masked]>
Date: Sun, 31 Dec 2023 00:50:42 +0200

On 30/12/2023 22:31, Stefan Kangas wrote:

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

.dir-locals.el already usually hosts per-project settings. And most 
users of this feature probably aren't going to read Emacs's one.

I've added another sentence to the docstring, let's see if it helps.

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

You might be right. The file/feature only contains the automatic 
indexing part, though.

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

Yeah, it's hardly an innovation, more like in the "why don't we have 
this yet" department. But while automatic indexing has been around for a 
while, having it OOtB in lightweight editors wasn't commonplace. So as I 
recall it for ST3 (first beta in 2013, release in 2017) it was a 
meaningful step forward. The complex IDEs already had this for a long 
time, of course (but each was more specialized, and worked with a 
smaller number of languages).

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

Suggestions welcome. I'm not sure how to phrase that without mentioning 
etags, tags files, and xref backends (in general and the names of 
specific ones).

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

All right, I've replaced the two "e.g."'s in user-facing text.