X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/7ac1c664547ca88fd6c0ff65ef5e780b1c5efcb0..f6d6298639ae43539581c2079666d76a54f1557e:/doc/lispref/commands.texi

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index d22cfd955c..eb42ddb11a 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1,7 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c   2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/commands
@@ -92,8 +91,9 @@ and also when the command loop is first entered.  At that time,
 
   Quitting is suppressed while running @code{pre-command-hook} and
 @code{post-command-hook}.  If an error happens while executing one of
-these hooks, it terminates execution of the hook, and clears the hook
-variable to @code{nil} so as to prevent an infinite loop of errors.
+these hooks, it does not terminate execution of the hook; instead
+the error is silenced and the function in which the error occurred
+is removed from the hook.
 
   A request coming into the Emacs server (@pxref{Emacs Server,,,
 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
@@ -1285,8 +1285,12 @@ input stream.  @xref{Key Sequence Input}.
 @item @var{x}, @var{y}
 These are the pixel coordinates of the click, relative to
 the top left corner of @var{window}, which is @code{(0 . 0)}.
-For the mode or header line, @var{y} does not have meaningful data.
-For the vertical line, @var{x} does not have meaningful data.
+For a click on text, these are relative to the top left corner of
+the window's text area.  For the mode or header line, they are
+relative to the top left window edge.  For fringes, margins, and the
+vertical border, @var{x} does not have meaningful data.  For fringes
+and margins, @var{y} is relative to the bottom edge of the header
+line.
 
 @item @var{timestamp}
 This is the time at which the event occurred, in milliseconds.
@@ -1316,7 +1320,12 @@ the window.
 @item @var{col}, @var{row}
 These are the actual coordinates of the glyph under the @var{x},
 @var{y} position, possibly padded with default character width
-glyphs if @var{x} is beyond the last glyph on the line.
+glyphs if @var{x} is beyond the last glyph on the line.  For clicks on
+the header or mode line, these are measured from the top left edge of
+the header or mode line.  For clicks on the fringes and on the
+vertical border, these have no meaningful data.  For clicks on the
+margins, @var{col} is measured from the left edge of the margin area
+and @var{row} is measured from the top of the margin area.
 
 @item @var{image}
 This is the image object on which the click occurred.  It is either
@@ -1333,7 +1342,7 @@ left corner of the character glyph clicked on.
 These are the pixel width and height of @var{object} or, if this is
 @code{nil}, those of the character glyph clicked on.
 @end table
- 
+
 @sp 1
 For mouse clicks on a scroll-bar, @var{position} has this form:
 
@@ -1616,7 +1625,8 @@ These kinds of event are generated by moving a mouse wheel.  Their
 usual meaning is a kind of scroll or zoom.
 
 The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event.
+event, in the same format as used in a mouse-click event (@pxref{Click
+Events}).
 
 @vindex mouse-wheel-up-event
 @vindex mouse-wheel-down-event
@@ -1633,9 +1643,10 @@ selected in an application outside of Emacs, and then dragged and
 dropped onto an Emacs frame.
 
 The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event, and
-@var{files} is the list of file names that were dragged and dropped.
-The usual way to handle this event is by visiting these files.
+event, in the same format as used in a mouse-click event (@pxref{Click
+Events}), and @var{files} is the list of file names that were dragged
+and dropped.  The usual way to handle this event is by visiting these
+files.
 
 This kind of event is generated, at present, only on some kinds of
 systems.
@@ -1917,10 +1928,17 @@ into frame-relative coordinates:
 @end defun
 
 @defun posn-col-row position
-Return the row and column (in units of the frame's default character
-height and width) of @var{position}, as a cons cell @code{(@var{col} .
-@var{row})}.  These are computed from the @var{x} and @var{y} values
-actually found in @var{position}.
+This function returns a cons cell @code{(@var{col} .  @var{row})},
+containing the estimated column and row corresponding to buffer
+position @var{position}.  The return value is given in units of the
+frame's default character width and height, as computed from the
+@var{x} and @var{y} values corresponding to @var{position}.  (So, if
+the actual characters have non-default sizes, the actual row and
+column may differ from these computed values.)
+
+Note that @var{row} is counted from the top of the text area.  If the
+window possesses a header line (@pxref{Header Lines}), it is
+@emph{not} counted as the first line.
 @end defun
 
 @defun posn-actual-col-row position
@@ -3375,7 +3393,3 @@ This normal hook (@pxref{Standard Hooks}) is run when a keyboard
 macro terminates, regardless of what caused it to terminate (reaching
 the macro end or an error which ended the macro prematurely).
 @end defvar
-
-@ignore
-   arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
-@end ignore