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

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

[MON KEY]

documentation of `posn-actual-col-row' is unclear.

,---- (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."?
What is a, "character number in that row"?

Is this equivalent to the return value of `char-to-string'?

(char-to-string
 (car
  (posn-col-row
   (posn-at-point
    (window-point (selected-window) ) (selected-window)))))
;=> ";"

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

However, even then the above definition is tautological:
 ME: "What is `posn-actual-col-row'?"
 DOC: "... the actual row number ..."

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.:
 POS (COL . ROW)

Likewise, there is no indication of the order of the return value is a
cons of the form:
 (COLUMN . ROW)

--
/s_P\

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

[Eli Zaretskii]

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