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

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]

I don't understand many of these changes.  They seem to be personal
stylistic preferences, in which case please revert them: there's
nothing wrong with alternative stylistic preferences.

> -on.  @xref{Eglot and Buffers}, for more details of what does Eglot
> -management of a buffer entail.
> +on.  @xref{Eglot and Buffers}, for more details of what Eglot
> +management of a buffer entails.

Why this change?

> -packages.  Here are the main features Eglot enables and provides:
> +packages.  These are the main features that Eglot enables and provides:

And this?

> -languages which are only supported by the @code{etags} backend.
> +languages that are only supported by the @code{etags} backend.

And this one?  What's wrong with using "which" in that case?

> -3rd-party completion package, is installed, Eglot enhances it by
> +third-party completion package, is installed, Eglot enhances it by

And what's the problem here?

> -i.e.@: a VCS repository (@pxref{Version Control,,, emacs, GNU Emacs
> +e.g.@: a Git repository (@pxref{Version Control,,, emacs, GNU Emacs
>  Manual}).

This change is for the worse: project.el supports more than just Git.

> -with @kbd{C-u}, it always prompts for the server program, and if
> -invoked with @kbd{C-u C-u}, also prompt for the major mode.
> +with a prefix argument @kbd{C-u}, it always prompts for the server
> +program, and if invoked with @kbd{C-u C-u}, also prompt for the major
> +mode.

What was wrong with the original text here?

>  @item M-x eglot-shutdown
> -Shut down a language server.  This commands prompts for a language
> +Shuts down a language server.  This commands prompts for a language

This is a change for the worst: the first sentence is now incomplete.

>     eglot.texi: Make example more realistic
>     
>     * doc/misc/eglot.texi (Eglot and Buffers): Prefer more realistic
>     *.c instead of *.foo in example.

Why do you think it is "more realistic"?  The whole point of Eglot is
that it's almost agnostic to the source language, so why do we have to
talk about C sources in particular?

>     eglot.texi: Move sentence on LSP Servers earlier
>     
>     * doc/misc/eglot.texi (Setting Up LSP Servers): Move explanation
>     on the (lack of) need for customizing servers earlier.

Please revert that: I see no need to move the description to another
place.  The current text was well thought-of.

Thanks.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> -on.  @xref{Eglot and Buffers}, for more details of what does Eglot
>> -management of a buffer entail.
>> +on.  @xref{Eglot and Buffers}, for more details of what Eglot
>> +management of a buffer entails.
>
> Why this change?

It reads better (and is shorter).

I'm not a native English speaker, but I did consult one about this
change, FWIW.  The changed version "just reads better", according to
them.

>> -packages.  Here are the main features Eglot enables and provides:
>> +packages.  These are the main features that Eglot enables and provides:
>
> And this?

I believe "that" is needed above.  I might be wrong.

>> -languages which are only supported by the @code{etags} backend.
>> +languages that are only supported by the @code{etags} backend.
>
> And this one?  What's wrong with using "which" in that

Please see:

https://prowritingaid.com/art/438/-Which--or--That-%3A-Know-When-to-Use-Each.aspx

>> -3rd-party completion package, is installed, Eglot enhances it by
>> +third-party completion package, is installed, Eglot enhances it by
>
> And what's the problem here?

The spelling is wrong: https://www.merriam-webster.com/dictionary/third-party

>> -i.e.@: a VCS repository (@pxref{Version Control,,, emacs, GNU Emacs
>> +e.g.@: a Git repository (@pxref{Version Control,,, emacs, GNU Emacs
>>  Manual}).
>
> This change is for the worse: project.el supports more than just Git.

That's why it says "e.g."; users are likely to be more familiar with Git
than the term VCS.  We could mention both, but I think a reference to
Git is good there.

>> -with @kbd{C-u}, it always prompts for the server program, and if
>> -invoked with @kbd{C-u C-u}, also prompt for the major mode.
>> +with a prefix argument @kbd{C-u}, it always prompts for the server
>> +program, and if invoked with @kbd{C-u C-u}, also prompt for the major
>> +mode.
>
> What was wrong with the original text here?

It doesn't say "prefix argument", so it is less didactic.

>>  @item M-x eglot-shutdown
>> -Shut down a language server.  This commands prompts for a language
>> +Shuts down a language server.  This commands prompts for a language
>
> This is a change for the worst: the first sentence is now incomplete.

It is more consistent with the preceding paragraph, so if you change it
again then please change both.

>>     eglot.texi: Make example more realistic
>>
>>     * doc/misc/eglot.texi (Eglot and Buffers): Prefer more realistic
>>     *.c instead of *.foo in example.
>
> Why do you think it is "more realistic"?  The whole point of Eglot is
> that it's almost agnostic to the source language, so why do we have to
> talk about C sources in particular?

Because it is an example, and there is no language named "foo".  Better
use a language that everyone knows exists than one that will confuse.

>>     eglot.texi: Move sentence on LSP Servers earlier
>>
>>     * doc/misc/eglot.texi (Setting Up LSP Servers): Move explanation
>>     on the (lack of) need for customizing servers earlier.
>
> Please revert that: I see no need to move the description to another
> place.  The current text was well thought-of.

It moves the important information up-front, so I think this is an
important improvement.  Please put the important information at the
beginning and not the end of this section.

> I don't understand many of these changes.  They seem to be personal
> stylistic preferences, in which case please revert them: there's
> nothing wrong with alternative stylistic preferences.

I don't think your objections have managed to convince me here, sorry.

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

[Robert Pluim]

>>>>> On Thu, 20 Oct 2022 13:38:28 +0300, Eli Zaretskii <eliz@gnu.org> said:

    Eli> I don't understand many of these changes.  They seem to be personal
    Eli> stylistic preferences, in which case please revert them: there's
    Eli> nothing wrong with alternative stylistic preferences.

Most of them are preferences, but this one:

    >> -on.  @xref{Eglot and Buffers}, for more details of what does Eglot
    >> -management of a buffer entail.
    >> +on.  @xref{Eglot and Buffers}, for more details of what Eglot
    >> +management of a buffer entails.

The original is not wrong, it just scans somewhat awkwardly.

    >> -languages which are only supported by the @code{etags} backend.
    >> +languages that are only supported by the @code{etags} backend.

    Eli> And this one?  What's wrong with using "which" in that case?

Nothing, except that there are some grammarians who believe that there
is an iron-clad infallible rule which governs when to use 'which'
versus 'that', which most of us donʼt care about [1] (and Iʼve yet to
see an example where using the 'wrong' one was unclear).

Robert

Footnotes:
[1]  Please nobody try to explain this rule. Itʼs been done, it
     doesnʼt need to be done again.

-- 

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

[Stefan Kangas]

Robert Pluim <rpluim@gmail.com> writes:

>     >> -languages which are only supported by the @code{etags} backend.
>     >> +languages that are only supported by the @code{etags} backend.
>
>     Eli> And this one?  What's wrong with using "which" in that case?
>
> Nothing, except that there are some grammarians who believe that there
> is an iron-clad infallible rule which governs when to use 'which'
> versus 'that', which most of us donʼt care about [1] (and Iʼve yet to
> see an example where using the 'wrong' one was unclear).

I generally try to follow the most authoritative recommendations I can
find, but if there is a particular reason to be more progressive here,
then please go for it.

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]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Thu, 20 Oct 2022 15:34:45 +0200
> 
> >>>>> On Thu, 20 Oct 2022 05:24:58 -0700, Stefan Kangas <stefankangas@gmail.com> said:
> 
>     Stefan> I generally try to follow the most authoritative recommendations I can
>     Stefan> find, but if there is a particular reason to be more progressive here,
>     Stefan> then please go for it.
> 
> You donʼt want progressive, you want conservative: if the existing
> text is not clearly incorrect, donʼt change it, even if thereʼs some
> guide that says itʼs 'wrong'.

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.

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]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 20 Oct 2022 03:59:01 -0700
> Cc: emacs-devel@gnu.org
> 
> I don't think your objections have managed to convince me here, sorry.

That's fine, I can take care of this myself.  Here, done.

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

[Stefan Kangas]

Robert Pluim <rpluim@gmail.com> writes:

> You donʼt want progressive, you want conservative:

No, I just had no idea that this particular rule was contentious:

1. I first learned about the difference between "which" or "that" on
   this list (or bug-gnu-emacs), and no one protested against the advice
   given to me at the time.

2. Any reference I could find recommended it (admittedly, I only checked
   the top 1-2 hits on the web).

> if the existing text is not clearly incorrect, donʼt change it, even
> if thereʼs some guide that says itʼs 'wrong'.

You could be a bit more generous here, perhaps.

From the advice given to me, and the sources I found, I drew the
conclusion precisely that using "that" is "clearly incorrect".  I did
not have any reason to think this advice was wrong, or stylistic
preference, or personal, or conservative, or anything of the kind.

I'm sure there are hundreds or even thousands of these pitfalls in the
English language.  When people try to improve the documentation, I think
we can point out such pitfalls.

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

[Rudolf Adamkovič]

Eli Zaretskii <eliz@gnu.org> writes:

> They [the changes] seem to be personal stylistic preferences, in which
> case please revert them: there's nothing wrong with alternative
> stylistic preferences.

Yes, there is nothing "wrong" with the text, but style matters greatly
in writing, and the new version reads better.  Thus, as a reader, and
also a non-native speaker, I prefer the patched version.

For instance, "of what does Eglot management of a buffer entail" makes
me re-parse the sentence, whereas "of what Eglot management of a buffer
entails" reads naturally.

Rudy
-- 
"The whole science is nothing more than a refinement of everyday
thinking."
-- Albert Einstein, 1879-1955

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

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]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 20 Oct 2022 08:02:12 -0700
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> From the advice given to me, and the sources I found, I drew the
> conclusion precisely that using "that" is "clearly incorrect".

It isn't.  Whoever gave that advice was wrong.

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]

> From: Rudolf Adamkovič <salutis@me.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 20 Oct 2022 17:11:57 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > They [the changes] seem to be personal stylistic preferences, in which
> > case please revert them: there's nothing wrong with alternative
> > stylistic preferences.
> 
> Yes, there is nothing "wrong" with the text, but style matters greatly
> in writing, and the new version reads better.

Not to me.  And we shouldn't argue about this, because that's what
personal stylistic preferences are about: they are personal.

> Thus, as a reader, and also a non-native speaker, I prefer the
> patched version.

As a person who wrote the original text, I prefer that version.

> For instance, "of what does Eglot management of a buffer entail" makes
> me re-parse the sentence, whereas "of what Eglot management of a buffer
> entails" reads naturally.

I didn't revert that part.

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

[Gregory Heytings]

>
> if the existing text is not clearly incorrect, don't change it, even if 
> there's some guide that says it's 'wrong'. 'which' vs 'that' falls in 
> that camp
>

IMHO, it doesn't.  And, FWIW, here's what the CMOS says:

that; which.  These are both relative pronouns.  In polished American 
prose, _that_ is used restrictively to narrow a category or identify a 
particular item being talked about {any building that is taller must be 
outside the state}; _which_ is used nonrestrictively---not to narrow a 
class or identify a particular item but to add something about an item 
already identified {alongside the officer trotted a toy poodle, which is 
hardly a typical police dog}.  _Which_ is best used restrictively only 
when it is preceded by a preposition {the situation in which we find 
ourselves}. Nonrestrictively, it is almost always preceded by a comma, a 
parenthesis, or a dash. (In British English, writers and editors seldom 
observe the distinction between the two words.)  Is it a useful 
distinction?  Yes.  The language inarguably benefits from having a 
terminological as well as a punctuational means of telling a restrictive 
from a nonrestrictive relative pronoun.

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

[Tim Cross]

Gregory Heytings <gregory@heytings.org> writes:

>>
>> if the existing text is not clearly incorrect, don't change it, even if there's some
>> guide that says it's 'wrong'. 'which' vs 'that' falls in that camp
>>
>
> IMHO, it doesn't.  And, FWIW, here's what the CMOS says:
>
> that; which.  These are both relative pronouns.  In polished American prose, _that_ is
> used restrictively to narrow a category or identify a particular item being talked about
> {any building that is taller must be outside the state}; _which_ is used
> nonrestrictively---not to narrow a class or identify a particular item but to add
> something about an item already identified {alongside the officer trotted a toy poodle,
> which is hardly a typical police dog}.  _Which_ is best used restrictively only when it is
> preceded by a preposition {the situation in which we find ourselves}. Nonrestrictively, it
> is almost always preceded by a comma, a parenthesis, or a dash. (In British English,
> writers and editors seldom observe the distinction between the two words.)  Is it a useful
> distinction?  Yes.  The language inarguably benefits from having a terminological as well
> as a punctuational means of telling a restrictive from a nonrestrictive relative pronoun.

“We have really everything in common with America nowadays, except, of
course, language.” -- Oscar Wilde

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]

> Date: Thu, 20 Oct 2022 20:34:00 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: Stefan Kangas <stefankangas@gmail.com>, Eli Zaretskii <eliz@gnu.org>, 
>  emacs-devel@gnu.org
> 
> IMHO, it doesn't.  And, FWIW, here's what the CMOS says:

Please don't care too much about what the CMOS says.  There are enough
native English speakers here to offer advice on good technical English
(I personally have always benefited from excellent advice from RMS,
whenever I had any such problems).  Besides, we have our own
"micro-language", in that we use certain styles and practices peculiar
to Emacs and more generally GNU documentation.  Stuff like "value is"
at the beginning of a sentence, which is not exactly 110% normative
English.  But we use it consistently across the board, and for good
reasons.

The important part here is not to make stylistic changes unless the
original is clearly wrong or unclear.  When in doubt, please ask.

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

[Gregory Heytings]

>> IMHO, it doesn't.  And, FWIW, here's what the CMOS says:
>
> Please don't care too much about what the CMOS says.  There are enough 
> native English speakers here to offer advice on good technical English 
> (I personally have always benefited from excellent advice from RMS, 
> whenever I had any such problems).
>

I'd be curious to hear RMS' opinion on the matter.  Note that CMOS (and 
other style guides) are also, and primarily, meant for native speakers. 
Also note that Strunk & White say the same:

_That_ is the defining, or restrictive, pronoun, _which_ the nondefining, 
or nonrestrictive.

The lawn mower that is broken is in the garage. (Tells which one.)

The lawn mower, which is broken, is in the garage. (Adds a fact about the 
only mower in question.)

[...] Careful writers, watchful for small conveniences, go 
_which_-hunting, remove the defining _whiches_, and by so doing improve 
their work.

CONTRIBUTE says that "We prefer American English both in doc strings and 
in the manuals", so it seems to me that this rule should be used.

>
> The important part here is not to make stylistic changes unless the 
> original is clearly wrong or unclear.  When in doubt, please ask.
>

With that I agree, of course.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > You donʼt want progressive, you want conservative: if the existing
  > > text is not clearly incorrect, donʼt change it, even if thereʼs some
  > > guide that says itʼs 'wrong'.

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

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.

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

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

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

Would someone please show me the documentation about Eglot?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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]

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

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

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

(For the record, I have no desire to make gratuitous changes, or impose
my stylistic preferences on anyone.)

We are discussing some changes I made after proofreading the manual.
You have claimed that these changes were merely "personal preferences".
That description is not just imprecise, but wrong, and can only serve to
muddy the waters.  In particular, it does not help us think about the
changes concretely.

But even if a wrong or imperfect edit goes in, it is not a big deal.
We review it, improve upon it, and move on.  For example, I note that
your so-called "undo" of my commit actually kept several of my fixes,
and improved further on others.[1]  This is expected, and IME exactly
how collaborative editing must work.

The other thing is the idea to only change things that are "clearly
wrong".  As this thread demonstrates, it is not trivial to ascertain
what is "clearly wrong", not least because, in several cases, opinions
abound.  The discussion about "that"/"which" is one example.

I must also ask whether the many changes you have made to our
documentation recently really qualifies as fixing things that are
"clearly wrong".  I think they do _not_.  For example:

    -Shuts down an the current connection to the language server
    +This command shuts down the current connection to the language
    +server

You fix such stylistic issues routinely.  And not just you.  It is
actually a good thing.  If we disagree about something, we revert, fix,
discuss, and improve.  In all cases, we are making progress.

So what's the problem?  Overall, the documentation is slowly getting
better over time.  AFAICT, it got better from my proofreading too, as
much as you don't like to admit it.  The proof is all there in the git
diff.  So this thread is a storm in a tea cup, as far as I'm concerned.

Proofreading is thankless enough as it is.  We should do everything in
our power to encourage and facilitate such work, and not be quick to
shoot it down.  I can only hope that this thread has not served to
discourage anyone from proofreading our manuals in the future.

Footnotes:
[1] Unfortunately, you also threw away some improvements, for some
     inexplicable reason.  So be it.

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]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sun, 23 Oct 2022 06:19:56 -0700
> Cc: rpluim@gmail.com, emacs-devel@gnu.org
> 
> So what's the problem?  Overall, the documentation is slowly getting
> better over time.  AFAICT, it got better from my proofreading too, as
> much as you don't like to admit it.  The proof is all there in the git
> diff.  So this thread is a storm in a tea cup, as far as I'm concerned.

It is unfortunate that you dismiss this thread as meaningless and
insignificant, because there were useful observations and advice
posted as part of it.  I hope people will take some of that out of
this discussion.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

For me as a speaker of English, "which" is ok for both restrictive and
nonrestrictive clauses.  But since some people do make that
distinction, I generally do go along with that distinction when people
point it out to me.  It might help some readers understand, and it
does not hurt.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > IMHO, it doesn't.  And, FWIW, here's what the CMOS says:

  > Please don't care too much about what the CMOS says.  There are enough
  > native English speakers here to offer advice on good technical English
  > (I personally have always benefited from excellent advice from RMS,
  > whenever I had any such problems).

My advice, nowadays, is to avoid the old English erudite Latin
abbreviations.  They offer no advantage over the plain English
expressions that everyone will understand.

In the GNU C Language Introduction and Reference Manual, I have
avoided them completely. That was easy and had no downside.

We have made overall style changes many times in GNU manuals.  To do
so for the whole Emacs Manual would be a big job, so we might not
decide to do it, but it's not unreasonable in principle.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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]

> From: Richard Stallman <rms@gnu.org>
> Cc: gregory@heytings.org, rpluim@gmail.com, stefankangas@gmail.com,
> 	emacs-devel@gnu.org
> Date: Sun, 23 Oct 2022 15:14:07 -0400
> 
> We have made overall style changes many times in GNU manuals.  To do
> so for the whole Emacs Manual would be a big job, so we might not
> decide to do it, but it's not unreasonable in principle.

Such stylistic changes are at times a risky business: people don't
always understand the fine points of what the author wanted to express
or emphasize, and make changes for the worse.  This actually happened
in the past, and is not always easy to catch in time.  This is
exacerbated by the fact that the number of people we have who are both
native English speakers and are willing to invest a significant
portion of their free time in working on our documentation -- that
number is very small.

For this reason, my advice is to avoid stylistic changes, or at least
ask before making them.  It should be low priority anyway, since most
of our documentation problems are not of stylistic nature.