GNU bug report logs - #9452
24.0.50; doc string of `constrain-to-field'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9452 in the body.
You can then email your comments to 9452 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc string of `constrain-to-field'
Date: Tue, 6 Sep 2011 11:51:59 -0700

1. The doc for this, and for all things concerning fields, is quite
complex - not simple to read.  Dunno whether it could be made simpler
and still be complete and correct.  It seems clear, but you must read it
carefully, and probably more than once.
 
2. The elisp manual's description of `constrain-to-field' is better than
the doc string's.  In particular, the fact that a nil NEW-POS has the
side effect of (possibly) moving point is clearer.  The manual says:
 
 "If NEW-POS is `nil', then `constrain-to-field'...moves point to the
  resulting position as well as returning it."
 
(The English is not really correct, however: It should say "moves"..."
and returns", not "moves"...and "returning".)
 
The doc string is not as clear about point moving.  It says:
 
 "If NEW-POS is nil, then the current point is used instead, and set to
  the constrained position if that is different."
 
We do not "set" point, for one thing.  And the passive voice ("is used",
"is set to") waters meaning down here.
 
But the real problem is that users reading this might not catch the fact
that _point is moved_.  Use language similar to the manual's: "moves" is
an active verb and makes clear that there is a side effect of (possibly)
moving point.
 
Even in the manual this important difference in behavior when NEW-POS is
nil is not so noticeable.  We should emphasize to users that null
NEW-POS means point might move.  This is an important use case for
`constrain-to-field', and it almost gets lost in the verbiage about the
args.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-09-05 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt'
 

Message #8 received at 9452 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 9452 <at> debbugs.gnu.org
Subject: Re: bug#9452: 24.0.50; doc string of `constrain-to-field'
Date: Mon, 12 Mar 2012 00:28:01 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> But the real problem is that users reading this might not catch the fact
> that _point is moved_.  Use language similar to the manual's: "moves" is
> an active verb and makes clear that there is a side effect of (possibly)
> moving point.

Fair enough.  Fixed.

Previous Next

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