From: Stefan Kangas <stefankangas@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: 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
Date: Thu, 20 Oct 2022 03:59:01 -0700 [thread overview]
Message-ID: <CADwFkm=BahC=a0tNR7pY7NWv1a9=trT0C-FozGN3iRgU48=syQ@mail.gmail.com> (raw)
In-Reply-To: <83h6zyye3f.fsf@gnu.org>
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.
next prev parent reply other threads:[~2022-10-20 10:59 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-10-20 10:38 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
2022-10-20 10:59 ` Stefan Kangas [this message]
2022-10-20 13:51 ` Eli Zaretskii
2022-10-20 11:35 ` Robert Pluim
2022-10-20 12:24 ` Stefan Kangas
[not found] ` <87a65qty8a.fsf@gmail.com>
2022-10-20 13:50 ` Eli Zaretskii
2022-10-22 19:59 ` Richard Stallman
2022-10-23 5:13 ` Eli Zaretskii
2022-10-23 13:19 ` Stefan Kangas
2022-10-23 16:18 ` Eli Zaretskii
2022-10-20 15:02 ` Stefan Kangas
2022-10-20 16:18 ` Eli Zaretskii
2022-10-20 20:34 ` Gregory Heytings
2022-10-20 22:35 ` Tim Cross
2022-10-21 6:04 ` Eli Zaretskii
2022-10-21 8:41 ` Gregory Heytings
2022-10-23 19:14 ` Richard Stallman
2022-10-23 19:21 ` Eli Zaretskii
2022-10-23 19:13 ` Richard Stallman
2022-10-20 15:11 ` Rudolf Adamkovič
2022-10-20 16:20 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CADwFkm=BahC=a0tNR7pY7NWv1a9=trT0C-FozGN3iRgU48=syQ@mail.gmail.com' \
--to=stefankangas@gmail.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.