From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#9452: 24.0.50; doc string of `constrain-to-field' Date: Tue, 6 Sep 2011 11:51:59 -0700 Message-ID: <1A73BA9F32054BCDABC84307BE3C8494@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1315335209 13075 80.91.229.12 (6 Sep 2011 18:53:29 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 6 Sep 2011 18:53:29 +0000 (UTC) To: 9452@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Sep 06 20:53:21 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1R10lr-0005nL-5A for geb-bug-gnu-emacs@m.gmane.org; Tue, 06 Sep 2011 20:53:19 +0200 Original-Received: from localhost ([::1]:54100 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R10lq-0005yu-Ol for geb-bug-gnu-emacs@m.gmane.org; Tue, 06 Sep 2011 14:53:18 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:36527) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R10lo-0005yo-1e for bug-gnu-emacs@gnu.org; Tue, 06 Sep 2011 14:53:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1R10lm-0005G9-FO for bug-gnu-emacs@gnu.org; Tue, 06 Sep 2011 14:53:15 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:53147) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R10lm-0005G4-CR for bug-gnu-emacs@gnu.org; Tue, 06 Sep 2011 14:53:14 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1R10pS-00028m-Ai; Tue, 06 Sep 2011 14:57:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 06 Sep 2011 18:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 9452 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.13153353778175 (code B ref -1); Tue, 06 Sep 2011 18:57:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 6 Sep 2011 18:56:17 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R10oj-00027n-5C for submit@debbugs.gnu.org; Tue, 06 Sep 2011 14:56:17 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1R10og-00027g-OI for submit@debbugs.gnu.org; Tue, 06 Sep 2011 14:56:15 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1R10kz-0005Bb-3R for submit@debbugs.gnu.org; Tue, 06 Sep 2011 14:52:25 -0400 Original-Received: from lists.gnu.org ([140.186.70.17]:51504) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R10ky-0005BW-T3 for submit@debbugs.gnu.org; Tue, 06 Sep 2011 14:52:24 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:36336) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R10ku-0005xV-FT for bug-gnu-emacs@gnu.org; Tue, 06 Sep 2011 14:52:24 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1R10kt-0005AZ-I9 for bug-gnu-emacs@gnu.org; Tue, 06 Sep 2011 14:52:20 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]:43857) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R10kt-0005AS-9S for bug-gnu-emacs@gnu.org; Tue, 06 Sep 2011 14:52:19 -0400 Original-Received: from rtcsinet21.oracle.com (rtcsinet21.oracle.com [66.248.204.29]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p86IqGvW016561 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 6 Sep 2011 18:52:18 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by rtcsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p86IqFY0016185 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 6 Sep 2011 18:52:15 GMT Original-Received: from abhmt104.oracle.com (abhmt104.oracle.com [141.146.116.56]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p86Iq9WM003112 for ; Tue, 6 Sep 2011 13:52:09 -0500 Original-Received: from dradamslap1 (/10.159.62.133) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 06 Sep 2011 11:52:09 -0700 X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 Thread-Index: Acxsxg6wFTTWrr3CRGC4B6eUfZc3Pg== X-Source-IP: rtcsinet21.oracle.com [66.248.204.29] X-CT-RefId: str=0001.0A090202.4E666BE2.00BF,ss=1,re=0.000,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 06 Sep 2011 14:57:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-Received-From: 140.186.70.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.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:50643 Archived-At: 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'