From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#6958: Documentation: `posn-actual-col-row' is unclear Date: Wed, 01 Sep 2010 04:59:13 -0400 Message-ID: References: Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: dough.gmane.org 1283332945 12046 80.91.229.12 (1 Sep 2010 09:22:25 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 1 Sep 2010 09:22:25 +0000 (UTC) Cc: 6958@debbugs.gnu.org To: MON KEY Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Sep 01 11:22:22 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OqjVV-0005bR-Jg for geb-bug-gnu-emacs@m.gmane.org; Wed, 01 Sep 2010 11:22:19 +0200 Original-Received: from localhost ([127.0.0.1]:37924 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OqjUj-0007Po-Du for geb-bug-gnu-emacs@m.gmane.org; Wed, 01 Sep 2010 05:20:37 -0400 Original-Received: from [140.186.70.92] (port=44721 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OqjPx-0006MQ-9o for bug-gnu-emacs@gnu.org; Wed, 01 Sep 2010 05:15:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OqjKC-0003NM-Lq for bug-gnu-emacs@gnu.org; Wed, 01 Sep 2010 05:09:46 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:59336) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OqjKC-0003NG-JE for bug-gnu-emacs@gnu.org; Wed, 01 Sep 2010 05:09:44 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1Oqj8s-0007ym-Jz; Wed, 01 Sep 2010 04:58:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 01 Sep 2010 08:58:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6958 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 6958-submit@debbugs.gnu.org id=B6958.128333145730665 (code B ref 6958); Wed, 01 Sep 2010 08:58:02 +0000 Original-Received: (at 6958) by debbugs.gnu.org; 1 Sep 2010 08:57:37 +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 1Oqj8S-0007yY-VG for submit@debbugs.gnu.org; Wed, 01 Sep 2010 04:57:37 -0400 Original-Received: from fencepost.gnu.org ([140.186.70.10]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Oqj8Q-0007yR-FB for 6958@debbugs.gnu.org; Wed, 01 Sep 2010 04:57:35 -0400 Original-Received: from eliz by fencepost.gnu.org with local (Exim 4.69) (envelope-from ) id 1OqjA1-0000uf-SI; Wed, 01 Sep 2010 04:59:13 -0400 In-reply-to: (message from MON KEY on Tue, 31 Aug 2010 16:58:09 -0400) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Wed, 01 Sep 2010 04:58:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:39879 Archived-At: > Date: Tue, 31 Aug 2010 16:58:09 -0400 > From: MON KEY > Cc: > > ,---- (documentation 'posn-actual-col-row) > | > | Return the actual column and row in position, measured in characters. > | These are the actual row number in the window and character number > in that row. > | Return nil if position does not contain the actual position; in that case > | `posn-col-row' can be used to get approximate values. > | position should be a list of the form returned by the `event-start' > | and `event-end' functions. > | > `---- > > How is a position, "measured in characters."? Not the position, the column and row numbers. The comma after "position" should have resolved the ambiguity; it did for me. > What is a, "character number in that row"? Quite simply, the ordinal number of a character. What is unclear here? > Is this equivalent to the return value of `char-to-string'? No. > At the very least the following portion of doc is poorly phrased: > "These are the actual row number in the window and character number in > that row." > ^^^^^^^^^ > > Should be something more like, > "This is the actual row number in the window and character number in that row." > ^^^^^^^ No, the original is correct: it talks about the column and row, plural, not singular. > However, even then the above definition is tautological: > ME: "What is `posn-actual-col-row'?" > DOC: "... the actual row number ..." You are confusing the function with its return value. the doc string does not describe the function, it describes its arguments and return value. > Also, there is no mention of which list element of the list returned > by the `event-start' this procedure is an accessor of e.g.: That's deliberate: the structure of the events is an implementation detail and is subject to change without notice. > Likewise, there is no indication of the order of the return value is a > cons of the form: > (COLUMN . ROW) Nitpicking: it says "column and row", so there's no reason to assume the order is not as it says.