From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel 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 Message-ID: References: <83h6zyye3f.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33705"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Oct 20 13:44:39 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1olTyZ-0008af-Li for ged-emacs-devel@m.gmane-mx.org; Thu, 20 Oct 2022 13:44:39 +0200 Original-Received: from localhost ([::1]:45480 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1olTyW-0001qX-Iq for ged-emacs-devel@m.gmane-mx.org; Thu, 20 Oct 2022 07:44:36 -0400 Original-Received: from [::1] (helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1olTbB-0003w5-Hy for ged-emacs-devel@m.gmane-mx.org; Thu, 20 Oct 2022 07:20:29 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48796) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1olTGZ-0002Lo-Qk for emacs-devel@gnu.org; Thu, 20 Oct 2022 06:59:12 -0400 Original-Received: from mail-oi1-x232.google.com ([2607:f8b0:4864:20::232]:45720) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1olTGT-0000Bo-Em; Thu, 20 Oct 2022 06:59:11 -0400 Original-Received: by mail-oi1-x232.google.com with SMTP id o64so22386784oib.12; Thu, 20 Oct 2022 03:59:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:from:to:cc:subject:date:message-id:reply-to; bh=YiP5Zxr+//IjfZDl4W4yOT9K4F/HLPTT3okDBBb/pZo=; b=giaiTmBLYMSs4JC/myN0tbfKsQeGDWHKzoEUuf6dM85Cbeo4Uhjxv+54c35cw0V8rf VY8XYJIAdMyABpugR5YSCQZhNvoUjSaFXcccwHYx8HRp76rB/117LkSILDJijejbdBFm cBns2G7+FU87iu5lSRUsmgwZR3DrUOeKseM7/58NkmSPm4r8tI1SNeTHQM/odV5XHXW3 oJLEZYdg/aRdF14TKP8iawNiFUwiQsY3SeYh1513NFL6H7/tE4EUz/qrvlfxMogkS4v5 TLk0snwcjDsNo4p3Q9h+EtsdKvvCW5UMK75BrXQQHIhYbbbzLxz3KwqHCDmVbQJch0nu fSnw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=YiP5Zxr+//IjfZDl4W4yOT9K4F/HLPTT3okDBBb/pZo=; b=ayl+FaCQfQ4uKPsbv37HL7jgNKcicg2D0Ov6fC7LkF4cTG/TKtiC3MUWz3CgBv3naW +ORq2ENej/bjo6ZKd1N4TBB+bWGw+oCeNJNHTMcNC9TjJlIEVhGrvLyBTDtwZClh9KTO 8B68xJN0WO0+re6nPidulta7oVLlxzn3uH7GJiuZDHbkXwtv1lUT/bqT0m6KSiMxlKUb +KCoiu/2VRG1bRonqTWPFpnJkfe4ZB6d5d3IjPXlDNEmUFzofUBT3Wf6biztePk2qozm Ng/iD8oxZRBlL52Q2Sv8sUnrfLkj/zzGBFojljH8crA7A4Vki35iEq9POZV+QIArwYy1 6pdg== X-Gm-Message-State: ACrzQf2cTDdWxtqvnNBA0u6lBAOTrVAZtxZFEMQUNFK+Pf94KPLDJ8VG ITzWTqzIxi74z38LfsyS7K+BrKMGs7HhxYGotofjOSzU X-Google-Smtp-Source: AMsMyM6btP9dsYeHkRT7qaLQBe1z5RgAWOHTceBLBWat0+CEGB1vs7dWjV8eXPsAsVJtGT93Y8d1SWxX5TMGSQ7GiJQ= X-Received: by 2002:a05:6808:1186:b0:353:b77a:a481 with SMTP id j6-20020a056808118600b00353b77aa481mr21318026oil.199.1666263542561; Thu, 20 Oct 2022 03:59:02 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Thu, 20 Oct 2022 03:59:01 -0700 In-Reply-To: <83h6zyye3f.fsf@gnu.org> X-Hashcash: 1:20:221020:emacs-devel@gnu.org::OsPDHaThHKkIWgbU:4pOk Received-SPF: pass client-ip=2607:f8b0:4864:20::232; envelope-from=stefankangas@gmail.com; helo=mail-oi1-x232.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:298143 Archived-At: Eli Zaretskii 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.