Re: feature/eglot-texi-manual 4725c123f3 2/5: ; eglot.texi: Fix typos and minor inconsistenciesfeature/eglot-texi-manual 4725c123f3 2/5: ; eglot.texi: Fix typos and minor inconsistencies

[Eli Zaretskii <eliz@gnu.org>]

> From: Richard Stallman <rms@gnu.org>
> Cc: rpluim@gmail.com, stefankangas@gmail.com, emacs-devel@gnu.org
> Date: Sat, 22 Oct 2022 15:59:51 -0400
> 
>   > Exactly.  We should always err on that side, out of respect to the
>   > original author(s) if for no other reasons.  Please try following this
>   > principle.
> 
> Nothing about Eglot is "existing text" as far as Emacs is concerned.
> All of it is proposed to add.  If we see ways to improve it before we
> add it, we should do so.  Better now than later.

That manual was written by yours truly.  I welcome any improvements to
it and corrections of any mistakes I might have made.  But replacing
my style preferences by someone else's is not going to improve the
manual.

> Consistency of style is a virtue in documentation, and so is
> consistency of terminology.  These are important reasons to make
> documentation text more uniform when installing it.

Exactly.

> We are not all equally skilled in writing clear English text.
> We should improve the writing that contributors submit.

Agreed.

> Documemtation shuld be structured according to the concepts of use,
> not based on implementation.  THe basic question here is, should we
> ask users to think in terms of "documenting hwo to use Eglot" or in
> terms of "documenting various features" (which happen to be provided
> by Eglot)?

We do both, please take a look at the recent changes to the Emacs user
manual, which mention capabilities provided by Eglot, and at the Eglot
manual itself.

> People seem to have assumed the former, but we ought to consider the
> latter too, and see which approach will be easiest to understand.

No such assumptions are being made.  And this discussion is not about
that anyway, it is about minor stylistic changes to the manual.

> Would someone please show me the documentation about Eglot?

There's doc/misc/eglot.texi in the Git repository on the master
branch.  And then there are references to capabilities backed up by
Eglot in the Emacs user manual, mainly in programs.texi and
maintaining.texi.