Re: New Eglot release

[João Távora]

On Fri, Mar 10, 2023 at 1:06 PM Eli Zaretskii <eliz@gnu.org> wrote:

> > Yes, it's quite different and this is in big part why I opted for
> > a separate file, so hopefully these idiosyncrasies could be
> > at least tolerated.
>
> You wanted my opinion; I don't like the style.

I asked if this is "good to push" ;-)

But I'm interested in your opinion, not necessarily in changing it.

> > > > +(github#29)
> > > > +
> > > > +** Handle experimental/unknown server methods gracefully.
> > >
> > > This doesn't say enough about the change, so why mention it?  And why
> > > the GitHub reference there?
> >
> > For readers to get access to the original context.
>
> That's IMNSHO is a disservice for the readers.  We should not force
> them to go places and read there about the changes, we should provide
> enough information for them to understand what has been changed
> without going anywhere.  In the few cases where a change is too
> complex to describe, we direct to the manual (which is party of the
> distribution, and thus at the reader's fingertips).

I've maintained this project for 5 years and interacted with many
of its users.  My understanding  of what this particular project's
audience is different (but it is not set in stone).

Also users can read the Eglot's (and other ELPA :core packages')
NEWS from other outlets, such as https://elpa.gnu.org/ or even
from links to the Git repo directly.

I think you have a very different understanding of how NEWS
is consumed partly because of how Emacs releases work.  They
follow a release schedule that is one order of magnitude slower
than Eglot's (I'm not criticizing, just stating).

> > > > +** Hierarchical symbols are supported in Imenu.
> > > > +Thanks to Ingo Lohmar for the original implementation (github#303).
> > >
> > > We don't mention individual contributors in NEWS.  They are mentioned
> > > in AUTHORS instead (and if you want, also in doc/emacs/ack.texi).
> >
> > Yeah, again pre-merge.  At the time I didn't have an AUTHORS file and
> > I wanted to thank certain contributors specially for certain
> > contributions.  Shall I remove these mentions? (Sorry Ingo :-) )
>
> AUTHORS are generated from ChangeLog files, so they will catch all the
> contributions in Git.  Since AFAIU the Eglot history was preserved in
> Emacs, those contributions will be caught as well, I think?

Yes, they are there.  I'll remove the mentions to individuals then,
it's no problem.

> > > > +(github#196)
> > > > +
> > > > +** Completion sorting fixed.
> > >
> > > This (and other similar entries) are not very useful, IMNSHO.
> > >
> > > Moreover, I don't think I see why mentioning past versions of Eglot
> > > that were never parts of Emacs would be useful to someone.
> > > It might be okay to have that on ELPA,
> >
> > Eglot is a :core GNU ELPA package, meaning its source files and its
> > documentation lives in the Emacs.git repo.
>
> Does that mean the ELPA tarball cannot include files that are not in
> the Emacs Git repository?

No idea.  But I would like to keep all Eglot's files in one Git
repository, if possible.

> > > but I don't see why we'd want this in Emacs core.
> >
> > I think it's quite nice to have a historical record of Eglot's
> > evolution, to see how far it has come, how certain decisions were
> > taken and adjusted over the years.
>
> NEWS is not about evolution, it's about changes in specific versions.

If you take those together, it maps the evolution of program
in terms of user visible behaviour.

> Since Emacs will not come with past versions of Eglot, mentioning
> those doesn't seem useful.

But gnu.elpa.org allows access to old version, and this
etc/EGLOT-NEWS file is supposed to be imported into there (that's
what F. Jason Park mentioned some email ago).  So I think it
makes sense.

etc/ERC-NEWS also uses a freer style

> > > > +mode: outline
> > > > +mode: bug-reference-mode
> > >
> > > Why not emacs-news-mode?
> >
> > Because, for some reason I didn't investigate, it erases my
> > bug-reference-bug-regexp and the links stop working.
>
> You mean emacs-news-mode and bug-reference-mode are incompatible?
> Then perhaps we should fix emacs-news-mode?

Maybe, and then etc/EGLOT-NEWS can use it.  It's nicer indeed.

> > AFAIK, the only place where an up-to-date version is published
> > for users to read is that link (I'm happy to be shown otherwise, so
> > I don't have to do this periodic chore anymore).
>
> It makes no sense to me to point to the outdated manual on GitHub.
> I'm not aware of any other bundled package which does something like
> that.

It's not outdated, it's the opposite!  As I wrote, it's the most
up-to-date version available,  AFAICT.  I render the doc/misc/eglot.texi file
manually to HTML and update it. Updated it yesterday, for example.

João