From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail
From: Drew Adams <drew.adams@oracle.com>
Newsgroups: gmane.emacs.bugs
Subject: bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)
Date: Wed, 12 Jun 2019 06:25:40 -0700 (PDT)
Message-ID: <89e04fc0-d31b-4247-8126-0b7a7f60d661@default>
References: <cf31e2b2-3ad4-57f0-8847-e5f01ff35fc8@gmail.com>
 <f2fff09b-fc97-795b-dc3b-4175c48234db@gmail.com> <83k1e2tym6.fsf@gnu.org>
 <e083f8bd-8c77-3558-c373-a8d9d9ef6079@gmail.com> <835zpltme6.fsf@gnu.org>
 <d1695e2e-7f87-7493-fbd9-97cd6347d837@gmail.com> <83muiwrn2u.fsf@gnu.org>
 <1583c6b3-2421-794d-8c8b-86287ef3fd5a@gmail.com> <83tvczb236.fsf@gnu.org>
 <616312d4-0faf-0382-3f21-5b66327d8d8b@gmail.com> <83tvcx9xyl.fsf@gnu.org>
 <130c7584-e2ad-d521-d468-4119d462583a@gmail.com> <831s009hxa.fsf@gnu.org>
 <31ab26f7-a31e-7f4b-f6ba-c050aeeb6833@gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226";
	logging-data="27240"; mail-complaints-to="usenet@blaine.gmane.org"
Cc: 35885@debbugs.gnu.org
To: Sebastian Urban <mrsebastianurban@gmail.com>, Eli Zaretskii <eliz@gnu.org>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Jun 12 15:33:38 2019
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.89)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1hb3Nh-0006xV-FT
	for geb-bug-gnu-emacs@m.gmane.org; Wed, 12 Jun 2019 15:33:38 +0200
Original-Received: from localhost ([::1]:60488 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.86_2)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1hb3Ng-0007ld-Fa
	for geb-bug-gnu-emacs@m.gmane.org; Wed, 12 Jun 2019 09:33:36 -0400
Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36786)
 by lists.gnu.org with esmtp (Exim 4.86_2)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1hb3HL-0003DN-GH
 for bug-gnu-emacs@gnu.org; Wed, 12 Jun 2019 09:27:05 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1hb3HK-0004fM-Ff
 for bug-gnu-emacs@gnu.org; Wed, 12 Jun 2019 09:27:03 -0400
Original-Received: from debbugs.gnu.org ([209.51.188.43]:47345)
 by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
 (Exim 4.71) (envelope-from <Debian-debbugs@debbugs.gnu.org>)
 id 1hb3HK-0004fF-CK
 for bug-gnu-emacs@gnu.org; Wed, 12 Jun 2019 09:27:02 -0400
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1hb3HK-00016h-7q
 for bug-gnu-emacs@gnu.org; Wed, 12 Jun 2019 09:27:02 -0400
X-Loop: help-debbugs@gnu.org
Resent-From: Drew Adams <drew.adams@oracle.com>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Wed, 12 Jun 2019 13:27:02 +0000
Resent-Message-ID: <handler.35885.B35885.15603460024224@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 35885
X-GNU-PR-Package: emacs
Original-Received: via spool by 35885-submit@debbugs.gnu.org id=B35885.15603460024224
 (code B ref 35885); Wed, 12 Jun 2019 13:27:02 +0000
Original-Received: (at 35885) by debbugs.gnu.org; 12 Jun 2019 13:26:42 +0000
Original-Received: from localhost ([127.0.0.1]:60889 helo=debbugs.gnu.org)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
 id 1hb3H0-000164-0v
 for submit@debbugs.gnu.org; Wed, 12 Jun 2019 09:26:42 -0400
Original-Received: from aserp2130.oracle.com ([141.146.126.79]:60414)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <drew.adams@oracle.com>) id 1hb3Gx-00015q-0v
 for 35885@debbugs.gnu.org; Wed, 12 Jun 2019 09:26:40 -0400
Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1])
 by aserp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5CDIlLH188117;
 Wed, 12 Jun 2019 13:26:32 GMT
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com;
 h=mime-version :
 message-id : date : from : sender : to : cc : subject : references :
 in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02;
 bh=rcg7Q0OX50rQNHyrCe31Z0ibecOg7ATjRK3PiFURtxQ=;
 b=kXXdY8z1XTV3UcZNJsv+BAOyalQ+0NOpj0S6Q6jAXuHG/k0wZTB+pFNpbyyqqetHPedb
 zBcaEpprmfVTH5HVqXREMA9g0YA7D3jQU3BzspD/2CvbtqVr7BXpMWCEYaIAu7SZ56re
 BJ603I0M6qgZOVsFCQ6ng+FbAMjuxIec8e02bU2zy9vNVgltoF80Oaec/LPuqlhT3xwJ
 vJ4gPYt+3JHYM34h0ZTXaPJRexbHrJClQFa1CiJbNoMIHP8lzwuM1cTj5bhuyiTHIft2
 Qs4K6hN7CkovUzXthWqP27YEwh/6CPIxUPnI5ongcdkJyYlUOGVK2bUqZ+iLI+dtUBTI Xg== 
Original-Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79])
 by aserp2130.oracle.com with ESMTP id 2t02heuh6x-1
 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK);
 Wed, 12 Jun 2019 13:26:32 +0000
Original-Received: from pps.filterd (userp3020.oracle.com [127.0.0.1])
 by userp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x5CDOoSq078510;
 Wed, 12 Jun 2019 13:26:31 GMT
Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75])
 by userp3020.oracle.com with ESMTP id 2t1jpj1109-1
 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK);
 Wed, 12 Jun 2019 13:26:31 +0000
Original-Received: from abhmp0017.oracle.com (abhmp0017.oracle.com [141.146.116.23])
 by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x5CDPfD6011381;
 Wed, 12 Jun 2019 13:25:43 GMT
In-Reply-To: <31ab26f7-a31e-7f4b-f6ba-c050aeeb6833@gmail.com>
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1  (1003210) [OL
 16.0.4861.0 (x86)]
X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9285
 signatures=668687
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0
 malwarescore=0
 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999
 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1
 engine=8.0.1-1810050000 definitions=main-1906120092
X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9285
 signatures=668687
X-Proofpoint-Spam-Details: rule=notspam policy=default score=0
 priorityscore=1501 malwarescore=0
 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015
 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0
 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000
 definitions=main-1906120092
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" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/bug-gnu-emacs>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Original-Sender: "bug-gnu-emacs"
 <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.bugs:160435
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/160435>

> > As for the few examples saying "if N is negative <do something> =E2=88=
=92N
> > times": sorry, I cannot see anything wrong with such wording, so
> > I left those few examples alone.
>=20
> Well I don't think I can explain this more clearly, so I'm going to
> put this next to 'C-g C-g' "problem", i.e. we will wait for other
> opinions if they ever appear.  Until then I'll consider this thread
> closed.

"I cannot see anything wrong with such wording", versus
it could be improved a bit to avoid confusion like that
evidenced by this bug report.

A user reading "...-N..." CAN easily misread it.  Yes,
MISread.  There is not "anything wrong" with it, in the
sense that if you read it right you won't misunderstand
it.  But that's a low bar, and Emacs can do better.

To read it right you have to have grasped and recalled
that N is a placeholder for an integer value, and in
the context of that `-N' occurrence it is a placeholder
for a negative integer.

Understanding that that's the case, a reader will also
correctly interpret the `-' as a minus sign (not, e.g.,
as a dash or hyphen or whatever else in ordinary text).

MISunderstanding, a reader can easily not interpret the
math expression `-N' as math at all.  (And note that
it's not within `...', so it's likely not taken as Lisp
math.

If we instead use `(abs N)', that makes clear - yes, as
a reminder or a pay-attention note - that N is a number
and the result of that expression is its absolute value.
That clues a reader into the fact that N might be - in
fact is in this case - negative.

It's not about proving that the `-N' wording is guilty
or defending its innocence in a court case.  It's about
making things a little clearer.  It's about seeing it
from the point of view of someone who might misread it.