From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii 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: Sun, 23 Oct 2022 08:13:05 +0300 Message-ID: <83h6zvt95q.fsf@gnu.org> References: <83h6zyye3f.fsf@gnu.org> <87ilkeu3r1.fsf@gmail.com> <87a65qty8a.fsf@gmail.com> <83a65qy57n.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="24955"; mail-complaints-to="usenet@ciao.gmane.io" Cc: rpluim@gmail.com, stefankangas@gmail.com, emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Oct 24 02:30:43 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 1omlMZ-0006L6-L8 for ged-emacs-devel@m.gmane-mx.org; Mon, 24 Oct 2022 02:30:43 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1omkcb-0005qV-RT for ged-emacs-devel@m.gmane-mx.org; Sun, 23 Oct 2022 19:43:14 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1omTIa-0000ER-F3 for emacs-devel@gnu.org; Sun, 23 Oct 2022 01:13:24 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1omTIa-0007B5-74; Sun, 23 Oct 2022 01:13:24 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=qePn5druC2zgM7wL8VbY9RHR3W10JHXJMD8fPFk0l+g=; b=d59p0LNYfmXu tfqlrPp7rykJFQLCfCLIEPymJWKTVs27XCznSF00n4PAUFxsG+/SZHlK+r5+1G23+01ylEHhnfF/R M8qs2jLapKFgsxLNuDaIe/bJrDHpVc9oaskumoq4bPCZSzNdVtcJaKspi2sLxUbUo4yzhQoWS/SMy XoJV0sB8kpA+TZXgGrkpOLGRFbTCTIEkUPYFNxsdpsn3JX9fjHFBnl/i/8H+XYReMhwZ9Oxzo2Jla VxNSAoaQZGSsE0UXZV4VNbtJVMj3Kkau8ybVGumwtfWRyul2efPJYqutvUA1ZwksHvw0/feVaNLSa e2FAqxURNBtvLuu/jfeBGQ==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1omTIZ-00029S-1X; Sun, 23 Oct 2022 01:13:23 -0400 In-Reply-To: (message from Richard Stallman on Sat, 22 Oct 2022 15:59:51 -0400) 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:298281 Archived-At: > From: Richard Stallman > 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.