GNU bug report logs - #35885
25.2; Few mistakes in Emacs Manual (+ proposals)

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Sebastian Urban <mrsebastianurban <at> gmail.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 35885 <at> debbugs.gnu.org
Subject: bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)
Date: Wed, 12 Jun 2019 06:25:40 -0700 (PDT)

> > As for the few examples saying "if N is negative <do something> −N
> > times": sorry, I cannot see anything wrong with such wording, so
> > I left those few examples alone.
> 
> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.