Improve wording of documentation of click events

* doc/lispref/commands.texi (Click Events, Accessing Mouse):
Improve and clarify wording.  (Bug#36232)

1 files changed, 37 insertions, 33 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 1eb580e1e0f..ad31240beff 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1395,9 +1395,9 @@ The time at which the event occurred, as an integer number of
 milliseconds since a system-dependent initial time.
 
 @item @var{object}
-Either @code{nil} if there is no string-type text property at the
-click position, or a cons cell of the form (@var{string}
-. @var{string-pos}) if there is one:
+Either @code{nil}, which means the click occurred on buffer text, or a
+cons cell of the form @w{(@var{string} . @var{string-pos})} if there
+is a string from a text property or an overlay at the click position.
 
 @table @asis
 @item @var{string}
@@ -1428,15 +1428,15 @@ clicks on 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
-@code{nil} if there is no image at the position clicked on, or it is
-an image object as returned by @code{find-image} if click was in an image.
+If there is an image at the click location, this is the image object
+as returned by @code{find-image} (@pxref{Defining Images}); otherwise
+this is @code{nil}.
 
 @item @var{dx}, @var{dy}
-These are the pixel coordinates of the click, relative to
-the top left corner of @var{object}, which is @code{(0 . 0)}.  If
-@var{object} is @code{nil}, the coordinates are relative to the top
-left corner of the character glyph clicked on.
+These are the pixel coordinates of the click, relative to the top left
+corner of @var{object}, which is @code{(0 . 0)}.  If @var{object} is
+@code{nil}, which stands for a buffer, the coordinates are relative to
+the top left corner of the character glyph clicked on.
 
 @item @var{width}, @var{height}
 These are the pixel width and height of @var{object} or, if this is
@@ -2038,8 +2038,8 @@ position such events have.
 
 @defun posnp object
 This function returns non-@code{nil} if @var{object} is a mouse
-position list, in either of the formats documented in @ref{Click
-Events}); and @code{nil} otherwise.
+position list, in the format documented in @ref{Click Events}); and
+@code{nil} otherwise.
 @end defun
 
 @cindex mouse position list, accessing
@@ -2067,8 +2067,8 @@ is undefined.
 
 @defun posn-x-y position
 Return the pixel-based x and y coordinates in @var{position}, as a
-cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
-to the window given by @code{posn-window}.
+cons cell @w{@code{(@var{x} . @var{y})}}.  These coordinates are
+relative to the window given by @code{posn-window}.
 
 This example shows how to convert the window-relative coordinates in
 the text area of a window into frame-relative coordinates:
@@ -2086,11 +2086,11 @@ POSITION is assumed to lie in a window text area."
 @end defun
 
 @defun posn-col-row position
-This function returns a cons cell @code{(@var{col} .  @var{row})},
+This function returns a cons cell @w{@code{(@var{col} .  @var{row})}},
 containing the estimated column and row corresponding to buffer
-position in @var{position}.  The return value is given in units of the
-frame's default character width and default line height (including
-spacing), as computed from the @var{x} and @var{y} values
+position described by @var{position}.  The return value is given in
+units of the frame's default character width and default line height
+(including spacing), 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.)
@@ -2102,7 +2102,7 @@ Lines}), it is @emph{not} included in the @var{row} count.
 
 @defun posn-actual-col-row position
 Return the actual row and column in @var{position}, as a cons cell
-@code{(@var{col} . @var{row})}.  The values are the actual row and
+@w{@code{(@var{col} . @var{row})}}.  The values are the actual row and
 column numbers in the window given by @var{position}.  @xref{Click
 Events}, for details.  The function returns @code{nil} if
 @var{position} does not include actual position values; in that case
@@ -2115,33 +2115,37 @@ character units, use @code{posn-col-row} instead.
 @end defun
 
 @defun posn-string position
-Return the string object in @var{position}, either @code{nil}, or a
-cons cell @code{(@var{string} . @var{string-pos})}.
+Return the string object described by @var{position}, either
+@code{nil} (which means @var{position} describes buffer text), or a
+cons cell @w{@code{(@var{string} . @var{string-pos})}}.
 @end defun
 
 @defun posn-image position
-Return the image object in @var{position}, either @code{nil}, or an
-image @code{(image ...)}.
+Return the image object in @var{position}, either @code{nil} (if
+there's no image at @var{position}), or an image spec @w{@code{(image
+@dots{})}}.
 @end defun
 
 @defun posn-object position
-Return the image or string object in @var{position}, either
-@code{nil}, an image @code{(image ...)}, or a cons cell
-@code{(@var{string} . @var{string-pos})}.
+Return the image or string object described by @var{position}, either
+@code{nil} (which means @var{position} describes buffer text), an
+image @w{@code{(image @dots{})}}, or a cons cell
+@w{@code{(@var{string} . @var{string-pos})}}.
 @end defun
 
 @defun posn-object-x-y position
 Return the pixel-based x and y coordinates relative to the upper left
-corner of the object in @var{position} as a cons cell @code{(@var{dx}
-. @var{dy})}.  If the @var{position} is on buffer text, return the
-relative position of the buffer-text character closest to that
-position.
+corner of the object described by @var{position}, as a cons cell
+@w{@code{(@var{dx} . @var{dy})}}.  If the @var{position} describes
+buffer text, return the relative coordinates of the buffer-text character
+closest to that position.
 @end defun
 
 @defun posn-object-width-height position
-Return the pixel width and height of the object in @var{position} as a
-cons cell @code{(@var{width} . @var{height})}.  If the @var{position}
-is a buffer position, return the size of the character at that position.
+Return the pixel width and height of the object described by
+@var{position}, as a cons cell @code{(@var{width} . @var{height})}.
+If the @var{position} describes a buffer position, return the size of
+the character at that position.
 @end defun
 
 @cindex timestamp of a mouse event