From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#40011: Remove unnecessary abbreviations from documentation Date: Mon, 27 Apr 2020 08:05:34 +0200 Message-ID: <878siha2fl.fsf@stefankangas.se> References: <83v9nc9sdk.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="87674"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: 40011@debbugs.gnu.org, rms@gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Apr 27 08:06:12 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1jSwuC-000MfB-1N for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 27 Apr 2020 08:06:12 +0200 Original-Received: from localhost ([::1]:53710 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jSwuB-0007yd-2G for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 27 Apr 2020 02:06:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57790) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jSwu2-0007yH-JU for bug-gnu-emacs@gnu.org; Mon, 27 Apr 2020 02:06:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jSwu2-0006bG-45 for bug-gnu-emacs@gnu.org; Mon, 27 Apr 2020 02:06:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52054) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jSwu1-0006bB-OC for bug-gnu-emacs@gnu.org; Mon, 27 Apr 2020 02:06:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jSwu1-0000jr-IA for bug-gnu-emacs@gnu.org; Mon, 27 Apr 2020 02:06:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 27 Apr 2020 06:06:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 40011 X-GNU-PR-Package: emacs Original-Received: via spool by 40011-submit@debbugs.gnu.org id=B40011.15879675462814 (code B ref 40011); Mon, 27 Apr 2020 06:06:01 +0000 Original-Received: (at 40011) by debbugs.gnu.org; 27 Apr 2020 06:05:46 +0000 Original-Received: from localhost ([127.0.0.1]:35367 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jSwtl-0000jJ-IP for submit@debbugs.gnu.org; Mon, 27 Apr 2020 02:05:45 -0400 Original-Received: from ted.gofardesign.uk ([67.225.143.91]:55024) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jSwtj-0000j4-GF for 40011@debbugs.gnu.org; Mon, 27 Apr 2020 02:05:43 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=marxist.se; s=default; h=Content-Type:MIME-Version:Message-ID:Date:References: In-Reply-To:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=0KGzlucgla2xk4/V7AeX6Ymk53NsRMXZu7IKC84Y3Ls=; b=ZrdT+ZzfWYQO5VtXBNr3F5Hz1P xP2WaL/uOBobRD9LMCBFy3VsCAB1b/x03Fg9sDnjt+ZFeEBSqaZuPUza6lFRcC6EXv2GloWlWAZ2n +wVvY947C4X2XEnzW+woS9ZYMvE8CHoKbPfg8hOTSH/pPeZroIRcCggJ8qlTD9GPNlyLOa9NF3ZYU HiMOjJ3GqXqC0mpNG2DEjSAUxvRYqK20/S7DzQG9dp6dqyf1hZ/fpsABIFoVxjaY08xzvu+oKg168 zcuS3IE+ZtjxS9aLodJppDpSv5JqPeD/J2fcsQGaHHOfhyJYINxBUUPMP8tyBBhmKvUUsS/e67lOj b7crllUg==; Original-Received: from h-4-70-69.a785.priv.bahnhof.se ([155.4.70.69]:55594 helo=localhost) by ted.gofardesign.uk with esmtpsa (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.93) (envelope-from ) id 1jSwtc-000tMi-TW; Mon, 27 Apr 2020 02:05:37 -0400 In-Reply-To: <83v9nc9sdk.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 10 Mar 2020 16:49:59 +0200") X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - ted.gofardesign.uk X-AntiAbuse: Original Domain - debbugs.gnu.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - marxist.se X-Get-Message-Sender-Via: ted.gofardesign.uk: authenticated_id: stefan@marxist.se X-Authenticated-Sender: ted.gofardesign.uk: stefan@marxist.se X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:179127 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> Please consider removing the following acronyms from the >> documentation, both the manual(s) and doc strings: >> >> 1. no. ("number") >> 2. e.g. ("for example") >> 3. i.e. ("that is", "namely", etc.) >> 4. c.f. ("in contrast to", "compared with", etc.) >> 5. w.r.t. ("with respect to") > > Let's not be too extreme: I'm against removing "e.g." and "i.e." at > the least. There are many such instances to get right, so maybe we can find a way forward which avoids changing all of them. How about adding something along the lines of the attached patch, and leave it at that? Would that be acceptable? Best regards, Stefan Kangas --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-Recommend-avoiding-unnecessary-abbreviations-in-doc.patch >From a44c03f6a2b2b98b34b4c7836e3291fd2c458190 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Mon, 27 Apr 2020 07:53:10 +0200 Subject: [PATCH] Recommend avoiding unnecessary abbreviations in doc * doc/lispref/tips.texi (Documentation Tips): Recommend avoiding unnecessary abbreviations. (Bug#40011)a --- doc/lispref/tips.texi | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 3b8da35b6c..382e6d7c61 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -820,6 +820,12 @@ Documentation Tips most cases, the meaning is clear with just ``if''. Otherwise, try to find an alternate phrasing that conveys the meaning. +@item +Avoid abbreviations like ``e.g.'' (for ``for example''), ``i.e.'' (for +``that is''), ``no.'' (for ``number''), ``c.f.'' (for ``in contrast +to'') and ``w.r.t.'' (for ``with respect to''). It is almost always +both more clear and easier to read the expanded version. + @item When a command is meaningful only in a certain mode or situation, do mention that in the documentation string. For example, -- 2.26.2 --=-=-=--