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: Tue, 10 Mar 2020 14:54:25 +0100 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="6949"; mail-complaints-to="usenet@ciao.gmane.io" Cc: richard stallman To: 40011@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Mar 10 14:55:18 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 1jBfLq-0001gP-Nl for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 10 Mar 2020 14:55:18 +0100 Original-Received: from localhost ([::1]:33674 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBfLp-0005EX-QA for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 10 Mar 2020 09:55:17 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35609) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBfLc-0005EF-4w for bug-gnu-emacs@gnu.org; Tue, 10 Mar 2020 09:55:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBfLa-0006OS-Vs for bug-gnu-emacs@gnu.org; Tue, 10 Mar 2020 09:55:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46067) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBfLa-0006LV-S8; Tue, 10 Mar 2020 09:55:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jBfLZ-0006aQ-P4; Tue, 10 Mar 2020 09:55:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: rms@gnu.org, bug-gnu-emacs@gnu.org Resent-Date: Tue, 10 Mar 2020 13:55:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 40011 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org X-Debbugs-Original-Xcc: richard stallman Original-Received: via spool by submit@debbugs.gnu.org id=B.158384848225282 (code B ref -1); Tue, 10 Mar 2020 13:55:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 10 Mar 2020 13:54:42 +0000 Original-Received: from localhost ([127.0.0.1]:52038 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jBfLG-0006Zh-Aw for submit@debbugs.gnu.org; Tue, 10 Mar 2020 09:54:42 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:41725) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jBfLE-0006ZY-ND for submit@debbugs.gnu.org; Tue, 10 Mar 2020 09:54:41 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34849) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBfLD-0004yN-EF for bug-gnu-emacs@gnu.org; Tue, 10 Mar 2020 09:54:40 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBfLC-0004B1-B4 for bug-gnu-emacs@gnu.org; Tue, 10 Mar 2020 09:54:39 -0400 Original-Received: from mail-yw1-f45.google.com ([209.85.161.45]:43031) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBfLC-00046K-6j for bug-gnu-emacs@gnu.org; Tue, 10 Mar 2020 09:54:38 -0400 Original-Received: by mail-yw1-f45.google.com with SMTP id p69so13633668ywh.10 for ; Tue, 10 Mar 2020 06:54:37 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; bh=+TNcqkxfKAbGfKnIEr2t5UoypqnNxCUYpBexaNUEOnU=; b=CWAVl5phfwYhdrugGUe56FQ/v5CcAb/Pdpu5NHZZ8NDJBghPLoTAqzVHvEivMV1Hsf N1E1qmCMD5r3sg0n1JND/ZOmiIivvU6hLf3QnxHdCbRREYzf9XCj6op0iPHqRTAh1Hvj r1WYucRFUwYg645RQ1+nBmI1im2MQL+0Z5txVmKzYkppUlSDuHTxfC2NoSInzFAoknZ2 B1YoLnIPbrRTnfMUfxLIxayQV+juwBHh6EO3CCAgS3w/j0VYloAw0oIkk5+sEd62hmkq wzeVk3VDzkwuimcYU+CYxl7op5M4bcfT6Wdli5V7+vcWVBEToBi8U9QTFYGN1/uWuPp2 mBEA== X-Gm-Message-State: ANhLgQ11yvvWE5ne4tfY5rIRYY2CS2CjHa2+x9gCVZwBZAGRPHsr6TXQ eWoBy9cgWqtmX8hGUI426ImSDxIVhlywEfYKTIMcx0gHp4Y= X-Google-Smtp-Source: ADFU+vt32evT8kgrSI999ZgJr8RdpCWytsBMamU8lkxZ/hLYwr3OKCyvjopGgG0dMsuaI8ofarUsgwk1DvcqpUzQWw8= X-Received: by 2002:a25:d3d0:: with SMTP id e199mr25187827ybf.43.1583848476174; Tue, 10 Mar 2020 06:54:36 -0700 (PDT) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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:177133 Archived-At: X-Debbugs-CC: Richard Stallman Writing for Computer Science (2004) by Justin Zobel says: "It is often tempting to use abbreviations such as 'no.', 'i.e.', 'e.g.' 'c.f.' and 'w.r.t.' These save little space on the page, but slow readers down. It is almost always desirable to expand these abbreviations, to 'number', 'that is', 'for example', 'compared with' (or more accurately 'in contrast to', since that is the sense in which 'c.f.' should be used), and 'with respect to', or synonyms of these expressions. Where such abbreviations are used, the punctuation should be as if the expanded form were used. Also consider expanding abbreviations such as 'Fig.' and 'Alg.' and don't use concoctions such as '1st' or '2nd'. Months should not be abbreviated. Make sure that all abbreviations and acronyms are explained when they are first used." (page 57) 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") Please also consider adding a guideline to avoid them where possible. I think we should not do this in a blanket fashion, however, but treat each case individually. For example, it seems to me that it's a good idea to be much more lenient in tables, where space may be a serious concern. If anyone has any suggestions for other abbreviations that could perhaps be avoided, please add them to the list. Any comments? Best regards, Stefan Kangas PS. For further background, see Bug#39778: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=39778