GNU bug report logs - #6958
Documentation: `posn-actual-col-row' is unclear

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 6958 <at> debbugs.gnu.org
Subject: Re: bug#6958: Documentation: `posn-actual-col-row' is unclear
Date: Wed, 01 Sep 2010 04:59:13 -0400

> Date: Tue, 31 Aug 2010 16:58:09 -0400
> From: MON KEY <monkey <at> sandpframing.com>
> 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.

Previous Next

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