[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#6958: Documentation: `posn-actual-col-row' is unclear
From: |
Eli Zaretskii |
Subject: |
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@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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- bug#6958: Documentation: `posn-actual-col-row' is unclear,
Eli Zaretskii <=