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.