bug#35885: 25.2; Few mistakes in Emacs Manual (+ proposals)

[Drew Adams]

> > 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.