eglot manual suggestions

eglot manual suggestions

[Robert Pluim]

Normally, Iʼd just commit this, but I feel the Grammar Dragon has been
poked enough for one week. I care not a whit if these are
characterised as 'style changes' or 'grammar corrections', but I feel
they are improvements.

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 0d82239c58..c90de7b84d 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -525,7 +525,7 @@ Eglot and Buffers
 Manual}).
 @end itemize
 
-Eglot uses the Emacs's project management infrastructure to figure out
+Eglot uses the Emacs project management infrastructure to figure out
 which files and buffers belong to what project, so any kind of project
 supported by that infrastructure is automatically supported by Eglot.
 
@@ -588,8 +588,8 @@ Eglot and Buffers
 (@pxref{Eglot Features}) to receive information from the language
 server, by changing the settings of these features.  Unlike other
 minor-modes, this special minor mode is not activated manually by the
-user, but automatically as result of starting an Eglot session for the
-buffer.  However, this minor mode provides a hook variable
+user, but automatically, as the result of starting an Eglot session
+for the buffer.  However, this minor mode provides a hook variable
 @code{eglot-managed-mode-hook} that can be used to customize the Eglot
 management of the buffer.  This hook is run both when the minor mode
 is turned on and when it's turned off; use the variable
@@ -614,7 +614,7 @@ Eglot Commands
 @section Eglot Commands
 @cindex commands, Eglot
 
-This section provides a reference of the most commonly used Eglot
+This section provides a reference for the most commonly used Eglot
 commands:
 
 @ftable @code
@@ -672,7 +672,7 @@ Eglot Commands
 @item M-x eglot-rename
 This command renames the program symbol (a.k.a.@: @dfn{identifier}) at
 point to another name.  It prompts for the new name of the symbol, and
-then modifies all the files in the project which arte managed by the
+then modifies all the files in the project which are managed by the
 language server of the current buffer to implement the renaming.
 
 @item M-x eglot-format
@@ -775,13 +775,13 @@ Eglot Variables
 @section Eglot Variables
 @cindex variables, Eglot
 
-This section provides a reference of the Eglot' user options.
+This section provides a reference for the Eglot user options.
 
 @vtable @code
 @item eglot-autoreconnect
 This option controls the ability to reconnect automatically to the
 language server when Eglot detects that the server process terminated
-unexpectedly.  The default value 3 means to attempt reconnection only
+unexpectedly.  The default value @code{3} means to attempt reconnection only
 if the previous successful connection lasted for more than that number
 of seconds; a different positive value changes the minimal length of
 the connection to trigger reconnection.  A value of @code{t} means
@@ -798,7 +798,7 @@ Eglot Variables
 This setting is mainly important for connections which are slow to
 establish.  Whereas the variable @code{eglot-connect-timeout} controls
 how long to wait for, this variable controls whether to block Emacs's
-user interface while waiting.  The default value is 3; a positive
+user interface while waiting.  The default value is @code{3}; a positive
 value means block for that many seconds, then wait for the connection
 in the background.  The value of @code{t} means block during the whole
 waiting period.  The value of @code{nil} or zero means don't block at
@@ -885,7 +885,7 @@ Customizing Eglot
 @code{eldoc-display-functions}.
 @end itemize
 
-For this reason, this manual describes only how to customize the
+For this reason, this manual describes only how to customize
 Eglot's own operation, which mainly has to do with the server
 connections and the server features to be used by Eglot.
 
@@ -919,12 +919,12 @@ Customizing Eglot
 @vindex eglot-stay-out-of
 @item eglot-stay-out-of
 This variable's value lists Emacs features that Eglot shouldn't
-automatically try to manage on user's behalf.  It is useful, for
+automatically try to manage on the user's behalf.  It is useful, for
 example, when you need to use non-LSP Flymake or Company back-ends.
-To have Eglot stay away of some Emacs feature, add that feature's
+To have Eglot stay away from some Emacs feature, add that feature's
 symbol or a regexp that will match a symbol's name to the list: for
 example, the symbol @code{xref} to leave Xref alone, or the string
-@samp{company} to stay away of your Company customizations.  Here's an
+@samp{company} to stay away from your Company customizations.  Here's an
 example:
 
 @lisp
@@ -949,7 +949,7 @@ Customizing Eglot
 settings contained in this variable to each server for which such
 settings were defined in the variable.  These settings are
 communicated to the server initially (upon establishing the
-connection) or when the settings are changed, or in response to the
+connection) or when the settings are changed, or in response to a
 configuration request from the server.
 
 In many cases, servers can be configured globally using a
@@ -958,12 +958,12 @@ Customizing Eglot
 @command{pylsp} server for Python reads the file
 @file{~/.config/pycodestyle} and the @command{clangd} server reads the
 file @file{.clangd} anywhere in the current project's directory tree.
-If possible, we recommend to use these configuration files that are
+If possible, we recommend to use those configuration files that are
 independent of Eglot and Emacs; they have the advantage that they will
 work with other LSP clients as well.
 
 If you do need to provide Emacs-specific configuration for a language
-server, we recommend to define the appropriate value in the
+server, we recommend defining the appropriate value in the
 @file{.dir-locals.el} file in the project's directory.  The value of
 this variable should be a property list of the following format:
 
@@ -1104,9 +1104,9 @@ Troubleshooting Eglot
 backtrace of the error that should also be attached to the bug report.
 
 @item
-An explanation how to obtain and install the language server you used.
-If possible, try to replicate the problem with the C/C@t{++} or Python
-servers, as these are very easy to install.
+An explanation of how to obtain, install, and configure the language
+server you used.  If possible, try to replicate the problem with the
+C/C@t{++} or Python servers, as these are very easy to install.
 
 @item
 A description of how to setup the @emph{minimal} project (one or two

Re: eglot manual suggestions

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Mon, 24 Oct 2022 18:00:35 +0200
> 
> Normally, Iʼd just commit this, but I feel the Grammar Dragon has been
> poked enough for one week. I care not a whit if these are
> characterised as 'style changes' or 'grammar corrections', but I feel
> they are improvements.

In general, LGTM, thanks.  However, ...

> -Eglot uses the Emacs's project management infrastructure to figure out
> +Eglot uses the Emacs project management infrastructure to figure out

Is "Emacs's" really wrong?

> -This section provides a reference of the most commonly used Eglot
> +This section provides a reference for the most commonly used Eglot

Is "reference of" incorrect?

> -To have Eglot stay away of some Emacs feature, add that feature's
> +To have Eglot stay away from some Emacs feature, add that feature's

"Stay away of" is incorrect?

> -If possible, we recommend to use these configuration files that are
> +If possible, we recommend to use those configuration files that are
>  independent of Eglot and Emacs; they have the advantage that they will
>  work with other LSP clients as well.
>  
>  If you do need to provide Emacs-specific configuration for a language
> -server, we recommend to define the appropriate value in the
> +server, we recommend defining the appropriate value in the

Here, you contradict yourself: if "recommend to use" is OK, then why
"recommend to define" isn't?

And AFAIU, both forms are correct English.

Also, why "those" in preference to "these"?

Re: eglot manual suggestions

[Robert Pluim]

>>>>> On Mon, 24 Oct 2022 20:03:23 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Date: Mon, 24 Oct 2022 18:00:35 +0200
    >> 
    >> Normally, Iʼd just commit this, but I feel the Grammar Dragon has been
    >> poked enough for one week. I care not a whit if these are
    >> characterised as 'style changes' or 'grammar corrections', but I feel
    >> they are improvements.

    Eli> In general, LGTM, thanks.  However, ...

    >> -Eglot uses the Emacs's project management infrastructure to figure out
    >> +Eglot uses the Emacs project management infrastructure to figure out

    Eli> Is "Emacs's" really wrong?

"Emacsʼs" is not, but "the Emacsʼs" is. We can drop the "the" and
retain "Emacsʼs" if you prefer

    >> -This section provides a reference of the most commonly used Eglot
    >> +This section provides a reference for the most commonly used Eglot

    Eli> Is "reference of" incorrect?

Itʼs unusual. Here "reference" is used as "a list that you can refer
to", which to me implies "for". But Iʼm not wedded to it

    >> -To have Eglot stay away of some Emacs feature, add that feature's
    >> +To have Eglot stay away from some Emacs feature, add that feature's

    Eli> "Stay away of" is incorrect?

Yes

    >> -If possible, we recommend to use these configuration files that are
    >> +If possible, we recommend to use those configuration files that are
    >> independent of Eglot and Emacs; they have the advantage that they will
    >> work with other LSP clients as well.
    >> 
    >> If you do need to provide Emacs-specific configuration for a language
    >> -server, we recommend to define the appropriate value in the
    >> +server, we recommend defining the appropriate value in the

    Eli> Here, you contradict yourself: if "recommend to use" is OK, then why
    Eli> "recommend to define" isn't?

That just means I missed the first one :-)

    Eli> And AFAIU, both forms are correct English.

Possibly, but verb + gerund is more common and reads better.

    Eli> Also, why "those" in preference to "these"?

Because weʼre referring to files that are not Emacs configuration
files, hence "those" emphasises their otherness: "Donʼt use these, use
*those*"

Robert
-- 

Re: eglot manual suggestions

[Mark H. David]

Native English speaker and grammar nerd here. Wow, these are some interesting English fine points. FWIW, Robert is 100% right on with all these changes IMHO.
-mhd

----- Original message -----
From: Robert Pluim <rpluim@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: eglot manual suggestions
Date: Monday, October 24, 2022 10:56 AM

>>>>> On Mon, 24 Oct 2022 20:03:23 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Date: Mon, 24 Oct 2022 18:00:35 +0200
    >> 
    >> Normally, Iʼd just commit this, but I feel the Grammar Dragon has been
    >> poked enough for one week. I care not a whit if these are
    >> characterised as 'style changes' or 'grammar corrections', but I feel
    >> they are improvements.

    Eli> In general, LGTM, thanks.  However, ...

    >> -Eglot uses the Emacs's project management infrastructure to figure out
    >> +Eglot uses the Emacs project management infrastructure to figure out

    Eli> Is "Emacs's" really wrong?

"Emacsʼs" is not, but "the Emacsʼs" is. We can drop the "the" and
retain "Emacsʼs" if you prefer

    >> -This section provides a reference of the most commonly used Eglot
    >> +This section provides a reference for the most commonly used Eglot

    Eli> Is "reference of" incorrect?

Itʼs unusual. Here "reference" is used as "a list that you can refer
to", which to me implies "for". But Iʼm not wedded to it

    >> -To have Eglot stay away of some Emacs feature, add that feature's
    >> +To have Eglot stay away from some Emacs feature, add that feature's

    Eli> "Stay away of" is incorrect?

Yes

    >> -If possible, we recommend to use these configuration files that are
    >> +If possible, we recommend to use those configuration files that are
    >> independent of Eglot and Emacs; they have the advantage that they will
    >> work with other LSP clients as well.
    >> 
    >> If you do need to provide Emacs-specific configuration for a language
    >> -server, we recommend to define the appropriate value in the
    >> +server, we recommend defining the appropriate value in the

    Eli> Here, you contradict yourself: if "recommend to use" is OK, then why
    Eli> "recommend to define" isn't?

That just means I missed the first one :-)

    Eli> And AFAIU, both forms are correct English.

Possibly, but verb + gerund is more common and reads better.

    Eli> Also, why "those" in preference to "these"?

Because weʼre referring to files that are not Emacs configuration
files, hence "those" emphasises their otherness: "Donʼt use these, use
*those*"

Robert
-- 

Re: eglot manual suggestions

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Is "Emacs's" really wrong?

"the Emacs's" is definitely wrong.

Re: eglot manual suggestions

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 350 bytes --]

Let's push the changes, then, they look good to me as well. Thanks Robert.
Prefer "Emacs's" for consistency with other users in the manual (i think).

João

On Tue, Oct 25, 2022, 01:34 Po Lu <luangruo@yahoo.com> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> > Is "Emacs's" really wrong?
>
> "the Emacs's" is definitely wrong.
>
>

[-- Attachment #2: Type: text/html, Size: 783 bytes --]

Re: eglot manual suggestions

[Robert Pluim]

>>>>> On Tue, 25 Oct 2022 09:29:38 +0100, João Távora <joaotavora@gmail.com> said:

    João> Let's push the changes, then, they look good to me as well. Thanks Robert.
    João> Prefer "Emacs's" for consistency with other users in the manual (i think).

Sure. Done as 72a94f91fd

Robert
--